benoit/PTT-Live
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add project documentation and development plan

Browse Source 
- 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
This commit is contained in:
Benoit
2026-05-21 14:10:50 +02:00
parent 55c2e41107
commit a65296221a
2 changed files with 594 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+330
View File
@@ -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)