benoit
a65296221a
- Add CLAUDE.md with architecture, decisions, and workflow - Add TODO.md with detailed Phase 1-3 roadmap - Add audio quality configuration (32-320 kbps Opus) - Add strict commit workflow and validation rules
331 lines
8.8 KiB
Markdown
331 lines
8.8 KiB
Markdown
# CLAUDE.md - Documentation Développement PTT Live
|
|
|
|
## Vue d'ensemble du projet
|
|
|
|
**PTT Live** est un système d'intercom professionnel WebRTC pour techniciens événementiels. Les utilisateurs communiquent via smartphone (PWA) en WiFi, le serveur fait le pont avec l'installation audio professionnelle.
|
|
|
|
## Contexte de développement
|
|
|
|
### Environnement
|
|
- **Plateforme principale** : macOS (tests et développement)
|
|
- **Compatibilité** : Linux (implémentation rapide après macOS)
|
|
- **Infrastructure audio** : Carte son multicanaux + Dante disponible
|
|
- **Réseau** : WiFi dédié
|
|
- **Déploiement** : Auto-hébergé uniquement
|
|
- **Licence** : Open Source
|
|
|
|
### Développeur
|
|
- Développeur solo
|
|
- Gestion complète par Claude (Node.js, React, WebRTC, audio temps réel)
|
|
|
|
## Architecture technique
|
|
|
|
### Stack
|
|
```
|
|
SERVEUR (Node.js)
|
|
├── LiveKit Server (binaire Go, SFU WebRTC)
|
|
├── Bridge Audio (Node.js)
|
|
│ ├── CoreAudio (macOS natif)
|
|
│ ├── JACK (Linux/macOS)
|
|
│ ├── libopus (transcodage)
|
|
│ └── Jitter buffer
|
|
├── API REST (Express)
|
|
└── Configuration (YAML)
|
|
|
|
CLIENT (PWA React)
|
|
├── React + Vite
|
|
├── livekit-client SDK
|
|
├── Web Push API
|
|
└── Service Worker
|
|
```
|
|
|
|
### Flux audio
|
|
```
|
|
[Carte son/Dante] → CoreAudio/JACK → Opus → LiveKit → WebRTC → Client PWA
|
|
[Client PWA] → WebRTC → LiveKit → Opus → CoreAudio/JACK → [Carte son/Dante]
|
|
```
|
|
|
|
## Phases de développement
|
|
|
|
### PHASE 1 — Fondations (MVP)
|
|
**Objectif** : Valider la faisabilité technique complète
|
|
|
|
#### 1.1 Infrastructure serveur
|
|
- Installation LiveKit Server (binaire)
|
|
- Configuration basique
|
|
- API REST minimal
|
|
|
|
#### 1.2 Bridge audio macOS
|
|
- Détection CoreAudio
|
|
- Capture/lecture audio
|
|
- Encodage/décodage Opus
|
|
- Connexion LiveKit
|
|
|
|
#### 1.3 PWA React
|
|
- Interface PTT basique
|
|
- Un groupe, connexion simple
|
|
- Audio WebRTC bidirectionnel
|
|
|
|
#### 1.4 Tests validation
|
|
- Latence end-to-end < 150ms
|
|
- 2-4 clients simultanés
|
|
- Stabilité WiFi
|
|
|
|
### PHASE 2 — Fonctionnalités professionnelles
|
|
**Objectif** : Système utilisable en production
|
|
|
|
#### 2.1 Groupes et routing
|
|
- Configuration YAML (groupes, canaux)
|
|
- Routing audio dynamique
|
|
- Switch groupe côté client
|
|
|
|
#### 2.2 Modes PTT avancés
|
|
- PTT lock (appui 3s)
|
|
- Mode continu (toggle)
|
|
- Feedback visuel/vibration
|
|
|
|
#### 2.3 Interface admin
|
|
- Gestion groupes/utilisateurs
|
|
- Monitoring connexions
|
|
- Logs audio
|
|
|
|
#### 2.4 Notifications
|
|
- Web Push (appels privés)
|
|
- PWA manifest complet
|
|
- Support iOS
|
|
|
|
### PHASE 3 — Intégrations audio pro
|
|
**Objectif** : Compatibilité équipements événementiels
|
|
|
|
#### 3.1 Support Linux
|
|
- Backend JACK/PipeWire
|
|
- Script installation
|
|
- Tests compatibilité
|
|
|
|
#### 3.2 Dante
|
|
- DVS macOS/Windows
|
|
- Routing JACK ↔ Dante
|
|
- Documentation setup
|
|
|
|
#### 3.3 AES67
|
|
- RTP multicast (Linux)
|
|
- PTP sync
|
|
- Interop Dante
|
|
|
|
#### 3.4 Production
|
|
- Scripts install multi-OS
|
|
- Tests charge (30+ clients)
|
|
- Documentation déploiement
|
|
|
|
## Décisions techniques
|
|
|
|
### Pourquoi ces choix ?
|
|
|
|
#### LiveKit vs alternatives
|
|
- **Janus/Mediasoup** : trop bas niveau, complexité inutile
|
|
- **LiveKit** : SFU prêt, SDK client mature, self-hosted
|
|
|
|
#### Pas de Docker
|
|
- Latence audio critique (< 10ms jitter)
|
|
- JACK/CoreAudio nécessitent accès direct hardware
|
|
- Binaires natifs = performances optimales
|
|
|
|
#### PWA plutôt qu'app native
|
|
- Déploiement instantané (pas de stores)
|
|
- Cross-platform unifié
|
|
- Web Push suffisant pour notifications
|
|
|
|
#### Opus codec
|
|
- Standard WebRTC
|
|
- Faible latence (20-60ms frame)
|
|
- Qualité audio configurable selon besoin :
|
|
- **Voix économique** : 32-64 kbps (WiFi limité)
|
|
- **Voix standard** : 96 kbps (défaut, bon compromis)
|
|
- **Voix HD** : 128-192 kbps (qualité maximale)
|
|
- **Musique/monitoring** : 256-320 kbps (si besoin événementiel)
|
|
- Configuration par groupe ou globale (YAML)
|
|
|
|
## Structure du code
|
|
|
|
```
|
|
PTT Live/
|
|
├── server/
|
|
│ ├── index.js # Point d'entrée, lance LiveKit + Bridge
|
|
│ ├── package.json
|
|
│ ├── config/
|
|
│ │ └── config.yaml # Groupes, canaux, routes
|
|
│ ├── bridge/
|
|
│ │ ├── AudioBridge.js # Classe principale, détection backend
|
|
│ │ ├── OpusCodec.js # Wrapper libopus
|
|
│ │ ├── JitterBuffer.js # Buffer 40ms
|
|
│ │ ├── LiveKitClient.js # Connexion SFU
|
|
│ │ └── backends/
|
|
│ │ ├── CoreAudioBackend.js # macOS natif
|
|
│ │ ├── JACKBackend.js # Linux/macOS
|
|
│ │ ├── PipeWireBackend.js # Linux moderne
|
|
│ │ └── WASAPIBackend.js # Windows (futur)
|
|
│ ├── api/
|
|
│ │ ├── routes.js # REST API
|
|
│ │ └── admin.js # Interface admin
|
|
│ └── bin/
|
|
│ └── livekit-server # Binaire téléchargé à l'install
|
|
│
|
|
├── client/
|
|
│ ├── package.json
|
|
│ ├── vite.config.js
|
|
│ ├── public/
|
|
│ │ ├── manifest.json # PWA
|
|
│ │ └── sw.js # Service Worker
|
|
│ └── src/
|
|
│ ├── main.jsx
|
|
│ ├── App.jsx
|
|
│ ├── components/
|
|
│ │ ├── PTTButton.jsx # Bouton principal
|
|
│ │ ├── GroupSelector.jsx
|
|
│ │ ├── UserList.jsx
|
|
│ │ └── AudioIndicator.jsx
|
|
│ ├── hooks/
|
|
│ │ ├── useLiveKit.js # WebRTC logic
|
|
│ │ ├── usePTT.js # Modes PTT
|
|
│ │ └── usePush.js # Notifications
|
|
│ └── utils/
|
|
│ └── audio.js # Helpers WebRTC
|
|
│
|
|
├── install/
|
|
│ ├── macos.sh # Installe deps + binaire LiveKit
|
|
│ ├── linux.sh
|
|
│ └── windows.ps1
|
|
│
|
|
├── CLAUDE.md # Ce fichier
|
|
├── TODO.md # Tâches actives
|
|
└── README.md # Doc utilisateur
|
|
```
|
|
|
|
## Commandes de développement
|
|
|
|
```bash
|
|
# Installation initiale
|
|
./install/macos.sh
|
|
|
|
# Serveur (dev)
|
|
cd server
|
|
npm install
|
|
npm run dev
|
|
|
|
# Client (dev)
|
|
cd client
|
|
npm install
|
|
npm run dev
|
|
|
|
# Production
|
|
cd server
|
|
npm start
|
|
```
|
|
|
|
## Tests et validation
|
|
|
|
### Métriques critiques
|
|
- **Latence end-to-end** : < 150ms (WiFi local)
|
|
- **Jitter buffer** : 40ms cible
|
|
- **Qualité audio** : Opus configurable (32-320 kbps), 48kHz
|
|
- Défaut : 96kbps (voix standard)
|
|
- Configurable par groupe dans config.yaml
|
|
- **Clients simultanés** : 30+ (Phase 3)
|
|
|
|
### Scénarios de test Phase 1
|
|
1. ✅ 2 clients, PTT basique, même groupe
|
|
2. ✅ Latence < 150ms mesurée
|
|
3. ✅ Pas de coupures sur 5min
|
|
4. ✅ Reconnexion après perte WiFi
|
|
|
|
## Points d'attention
|
|
|
|
### macOS spécifique
|
|
- CoreAudio : permissions microphone (Info.plist si empaquété)
|
|
- Pas de JACK requis pour Phase 1 (natif CoreAudio suffit)
|
|
- JACK optionnel pour Dante/AES67
|
|
|
|
### Dante
|
|
- DVS macOS supporté officiellement
|
|
- Routing DVS → JACK → Bridge (Phase 3)
|
|
- Licence ~300€ (à budgéter)
|
|
|
|
### iOS PWA
|
|
- Support depuis iOS 16.4+
|
|
- **Impératif** : installer sur écran d'accueil pour notifications
|
|
- Message d'onboarding à implémenter
|
|
|
|
### Réseau
|
|
- QoS/DSCP recommandé pour flux audio
|
|
- VLAN dédié si possible
|
|
- Tests charge WiFi en Phase 3
|
|
|
|
## Ressources et dépendances
|
|
|
|
### NPM packages serveur
|
|
- `livekit-server-sdk` : connexion SFU
|
|
- `@opus/opusscript` ou `node-opus` : codec
|
|
- `express` : API REST
|
|
- `yaml` : config
|
|
- `node-coreaudio` : backend macOS (natif addon)
|
|
- `jack-connector` : JACK (Phase 3)
|
|
|
|
### NPM packages client
|
|
- `react` + `react-dom`
|
|
- `livekit-client` : WebRTC SDK
|
|
- `vite` : bundler
|
|
- `workbox` : Service Worker PWA
|
|
|
|
### Binaires externes
|
|
- `livekit-server` (Go) : téléchargé par script install
|
|
- JACK (optionnel macOS, requis Linux Phase 3)
|
|
|
|
## Workflow Git
|
|
|
|
### ⚠️ IMPORTANT : Commits et validation
|
|
|
|
**Règle stricte** : Commiter après chaque modification significative ou fonctionnalité complétée.
|
|
|
|
```bash
|
|
# Branches
|
|
main # Production stable
|
|
develop # Intégration continue
|
|
feature/xxx # Fonctionnalités
|
|
fix/xxx # Corrections
|
|
|
|
# Convention commits
|
|
feat: description
|
|
fix: description
|
|
docs: description
|
|
refactor: description
|
|
test: description
|
|
```
|
|
|
|
### Processus de développement
|
|
|
|
1. **Avant de coder** : Cocher la tâche en cours dans [TODO.md](TODO.md) (mettre `[x]`)
|
|
2. **Après chaque tâche complétée** :
|
|
- ✅ Valider la tâche dans [TODO.md](TODO.md)
|
|
- 🔄 Commiter avec message descriptif
|
|
- 📝 Mettre à jour CLAUDE.md si nécessaire
|
|
|
|
**Exemple workflow** :
|
|
```bash
|
|
# 1. Tâche complétée
|
|
# 2. Valider dans TODO.md
|
|
# 3. Commit
|
|
git add .
|
|
git commit -m "feat: implement CoreAudio backend for macOS"
|
|
|
|
# 4. Passer à la tâche suivante
|
|
```
|
|
|
|
## Prochaines étapes
|
|
|
|
Voir [TODO.md](TODO.md) pour le plan détaillé.
|
|
|
|
---
|
|
|
|
**Dernière mise à jour** : 2026-05-21
|
|
**Version** : 0.1.0 (Phase 1 en cours)
|