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

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)