docs: add project documentation and development plan

- 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

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)

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)