PTT-Live/TODO.md

# 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)