diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..59a8309 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,330 @@ +# 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) diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..7751709 --- /dev/null +++ b/TODO.md @@ -0,0 +1,264 @@ +# TODO.md - Plan de développement PTT Live + +**Dernière mise à jour** : 2026-05-21 +**Phase actuelle** : PHASE 1 - Fondations + +--- + +## PHASE 1 — Fondations (MVP) + +### 🎯 Objectif +Valider la faisabilité technique : 2-4 clients, PTT basique, latence < 150ms, macOS + +--- + +### 1.1 Infrastructure projet + +- [ ] Structure dossiers (server/, client/, install/) +- [ ] package.json serveur (Node.js, Express, LiveKit SDK) +- [ ] package.json client (React, Vite, livekit-client) +- [ ] Script install/macos.sh (télécharge livekit-server binaire) +- [ ] Config YAML basique (1 groupe, 2 canaux) +- [ ] .gitignore (node_modules, binaires, .env) + +--- + +### 1.2 Serveur LiveKit + API + +- [ ] server/index.js : spawn livekit-server binaire +- [ ] Configuration LiveKit (ports, clés API) +- [ ] API REST : POST /token (génère token client) +- [ ] API REST : GET /config (infos groupes) +- [ ] Validation : LiveKit démarre sur port 7880 + +--- + +### 1.3 Bridge audio macOS + +#### Backend CoreAudio +- [ ] server/bridge/backends/CoreAudioBackend.js + - [ ] Énumération devices (entrée/sortie) + - [ ] Capture audio (48kHz, mono/stereo) + - [ ] Lecture audio (48kHz) + - [ ] Gestion buffer circulaire + +#### Codec Opus +- [ ] server/bridge/OpusCodec.js + - [ ] Encoder PCM → Opus (configurable 32-320kbps, 20ms frame) + - [ ] Decoder Opus → PCM + - [ ] Configuration bitrate (par groupe ou global) + - [ ] Tests unitaires codec (différentes qualités) + +#### Jitter Buffer +- [ ] server/bridge/JitterBuffer.js + - [ ] Buffer FIFO 40ms cible + - [ ] Détection underrun/overrun + - [ ] Statistiques latence + +#### Intégration LiveKit +- [ ] server/bridge/LiveKitClient.js + - [ ] Connexion room en tant que participant + - [ ] Publish track audio (Opus) + - [ ] Subscribe tracks autres participants + - [ ] Gestion reconnexion + +#### Classe principale +- [ ] server/bridge/AudioBridge.js + - [ ] Détection backend (CoreAudio pour macOS) + - [ ] Routing : CoreAudio → Opus → LiveKit + - [ ] Routing : LiveKit → Opus → CoreAudio + - [ ] Logs détaillés (latence, drops) + +--- + +### 1.4 Client PWA React + +#### Infrastructure +- [ ] client/vite.config.js (PWA plugin) +- [ ] client/public/manifest.json +- [ ] client/public/sw.js (Service Worker basique) +- [ ] client/src/main.jsx (setup React) + +#### Composants UI +- [ ] client/src/App.jsx + - [ ] Layout principal + - [ ] Connexion utilisateur (nom + groupe) + - [ ] Affichage état connexion + +- [ ] client/src/components/PTTButton.jsx + - [ ] Bouton PTT (maintenir pour parler) + - [ ] États : idle / talking / listening + - [ ] Feedback visuel (couleurs) + - [ ] Feedback haptique (vibration) + +- [ ] client/src/components/UserList.jsx + - [ ] Liste participants groupe actif + - [ ] Indicateur qui parle (temps réel) + +- [ ] client/src/components/AudioIndicator.jsx + - [ ] Niveau audio entrant (VU-mètre simple) + - [ ] Niveau micro sortant + +#### Hooks WebRTC +- [ ] client/src/hooks/useLiveKit.js + - [ ] Connexion room (token serveur) + - [ ] Publish microphone + - [ ] Subscribe participants + - [ ] Gestion événements (participant join/leave) + - [ ] Cleanup disconnect + +- [ ] client/src/hooks/usePTT.js + - [ ] Mode PTT : enable/disable track selon bouton + - [ ] Gestion touch events (mobile) + - [ ] Gestion mouse events (desktop) + +#### Styles +- [ ] CSS mobile-first +- [ ] Design bouton PTT (large, accessible) +- [ ] Mode sombre (défaut) + +--- + +### 1.5 Tests et validation Phase 1 + +#### Tests unitaires +- [ ] Opus encode/decode (qualité audio) +- [ ] Jitter buffer (buffer size stable) +- [ ] CoreAudio device detection + +#### Tests d'intégration +- [ ] Serveur démarre sans erreur +- [ ] Client obtient token valide +- [ ] Client rejoint room LiveKit + +#### Tests end-to-end +- [ ] **Test 1** : 2 clients, PTT alterné, audio bidirectionnel +- [ ] **Test 2** : Mesure latence (clap → réception < 150ms) +- [ ] **Test 3** : Stabilité 5min sans coupure +- [ ] **Test 4** : Reconnexion après perte WiFi + +#### Métriques +- [ ] Logger latence end-to-end moyenne +- [ ] Logger jitter buffer stats +- [ ] Logger packet loss WebRTC + +--- + +## PHASE 2 — Fonctionnalités professionnelles + +### 2.1 Groupes et routing +- [ ] Config YAML : multi-groupes, multi-canaux +- [ ] Routing dynamique serveur (groupe → canaux audio) +- [ ] Client : sélecteur groupe (dropdown) +- [ ] Client : affichage canaux groupe actif + +### 2.2 Modes PTT avancés +- [ ] PTT lock : appui long 3s → lock/unlock +- [ ] Mode continu : toggle ON/OFF +- [ ] Vibration + indicateur visuel rouge (lock actif) +- [ ] Préférences utilisateur (mode par défaut) + +### 2.3 Interface admin +- [ ] Page admin web (/admin) +- [ ] Gestion groupes (CRUD) +- [ ] Gestion utilisateurs connectés +- [ ] Monitoring temps réel (latence, qualité) +- [ ] Logs serveur (affichage live) + +### 2.4 Notifications +- [ ] Web Push : appels privés +- [ ] Service Worker : gestion notifications +- [ ] iOS : message onboarding "Installer sur écran d'accueil" +- [ ] Permissions notification au premier lancement + +--- + +## PHASE 3 — Intégrations audio pro + +### 3.1 Support Linux +- [ ] Backend JACK (server/bridge/backends/JACKBackend.js) +- [ ] Backend PipeWire (server/bridge/backends/PipeWireBackend.js) +- [ ] Script install/linux.sh +- [ ] Tests Ubuntu 22.04 LTS + Arch Linux + +### 3.2 Dante +- [ ] Documentation setup DVS macOS +- [ ] Routing JACK ↔ DVS +- [ ] Tests multi-canaux (8+) +- [ ] Guide configuration réseau Dante + +### 3.3 AES67 +- [ ] Backend RTP multicast (Linux) +- [ ] PTP sync +- [ ] Tests interop Dante (mode AES67) + +### 3.4 Production +- [ ] Script install Windows (install/windows.ps1) +- [ ] Tests charge : 30+ clients simultanés +- [ ] Optimisation réseau (QoS, DSCP) +- [ ] Documentation déploiement complet +- [ ] Guide troubleshooting + +--- + +## Prochaines actions immédiates + +1. Créer structure dossiers projet +2. Initialiser package.json serveur + client +3. Script install/macos.sh (télécharger livekit-server) +4. Serveur : lancer LiveKit binaire +5. Client : setup React + Vite + +--- + +## ⚠️ RÈGLES DE DÉVELOPPEMENT + +### 🔄 Workflow obligatoire +1. **Avant une tâche** : Cocher `[x]` dans ce fichier TODO.md +2. **Pendant le travail** : Développer la fonctionnalité +3. **Après la tâche** : + - ✅ Tester que ça fonctionne + - ✅ Valider la tâche dans TODO.md + - ✅ **COMMIT GIT** avec message descriptif + - ✅ Mettre à jour CLAUDE.md si nécessaire + +### 📝 Convention commits +```bash +feat: description # Nouvelle fonctionnalité +fix: description # Correction bug +docs: description # Documentation +refactor: description # Refactoring +test: description # Tests +``` + +**IMPORTANT** : Commiter après chaque tâche complétée, pas à la fin de la journée ! + +--- + +## Notes et décisions + +### Décisions techniques Phase 1 +- **Audio backend** : CoreAudio natif (pas de JACK Phase 1) +- **Codec Opus** : Configurable 32-320 kbps (défaut 96kbps voix standard) + - Voix économique : 32-64 kbps + - Voix standard : 96 kbps (défaut) + - Voix HD : 128-192 kbps + - Musique : 256-320 kbps +- **Sample rate** : 48kHz, 20ms frame +- **Jitter buffer** : 40ms cible +- **Client** : PWA React (pas d'app native) + +### Risques identifiés +- 🟡 Latence CoreAudio (à mesurer, cible < 50ms) +- 🟡 Permissions micro iOS (PWA) +- 🟡 Reconnexion automatique LiveKit (à tester) + +### Questions résolues +- Nombre max participants par groupe Phase 1 ? → **4 clients max** +- Qualité audio configurable ? → **Oui, 32-320 kbps selon besoin** +- HTTPS requis pour PWA local ? → **Oui, self-signed cert dev** + +--- + +**Statut** : Phase 1 prête à démarrer +**Prochaine étape** : Infrastructure projet (1.1)