docs: add comprehensive setup guide and improve README

Documentation complète pour démarrage rapide : README.md : - Section démarrage rapide en 5 minutes - Guide dépannage "Connexion impossible" - Instructions claires pour LiveKit Cloud - Liens vers documentation détaillée docs/SETUP_LIVEKIT.md : - Guide complet configuration LiveKit Cloud - Guide installation LiveKit Server local - Instructions par OS (macOS, Linux) - Section dépannage détaillée - Checklist validation tests Résout le problème de première connexion en guidant l'utilisateur vers la configuration LiveKit Cloud (gratuit). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-05-21 15:26:40 +02:00
parent 652384708e
commit 3afb82355e
2 changed files with 284 additions and 3 deletions
@@ -0,0 +1,185 @@
+# Configuration LiveKit pour PTT Live
+
+## Option 1 : LiveKit Cloud (Recommandé pour démarrer)
+
+LiveKit Cloud offre un tier gratuit parfait pour le développement et les tests.
+
+### Étapes :
+
+1. **Créer un compte LiveKit Cloud**
+   - Aller sur https://cloud.livekit.io
+   - Créer un compte gratuit
+   - Créer un nouveau projet
+
+2. **Obtenir les clés API**
+   - Dans le dashboard, aller dans "Settings" > "Keys"
+   - Copier votre `API Key` et `API Secret`
+   - Copier votre `WebSocket URL` (format: `wss://your-project.livekit.cloud`)
+
+3. **Configurer le serveur PTT Live**
+
+   Créer/éditer le fichier `server/.env` :
+   ```bash
+   # LiveKit Cloud
+   LIVEKIT_URL=wss://votre-projet.livekit.cloud
+   LIVEKIT_API_KEY=APIxxxxxxxxxx
+   LIVEKIT_API_SECRET=xxxxxxxxxxxxxxxxxx
+
+   # Mode
+   USE_LOCAL_LIVEKIT=false
+
+   # Server
+   NODE_ENV=development
+   ```
+
+4. **Redémarrer le serveur**
+   ```bash
+   cd server
+   npm run dev
+   ```
+
+5. **Tester**
+   - Le serveur devrait afficher : `✓ Mode LiveKit Cloud`
+   - Ouvrir http://localhost:5173
+   - Se connecter avec un nom et le groupe "Équipe Production"
+   - Ouvrir un second onglet/fenêtre pour tester à 2 participants
+
+### Limitations tier gratuit :
+- 10 000 minutes/mois
+- 50 participants simultanés max
+- Parfait pour développement et tests
+
+---
+
+## Option 2 : LiveKit Server Local (Auto-hébergé)
+
+Pour un déploiement en production auto-hébergé.
+
+### Prérequis :
+- macOS, Linux ou Windows
+- Port 7880 disponible
+- Ports 50000-60000 disponibles pour WebRTC
+
+### Installation :
+
+1. **Télécharger le binaire LiveKit Server**
+
+   macOS (ARM64 - Apple Silicon) :
+   ```bash
+   cd server/bin
+   curl -L -o livekit.tar.gz \
+     https://github.com/livekit/livekit/releases/download/v1.7.2/livekit_v1.7.2_darwin_arm64.tar.gz
+   tar -xzf livekit.tar.gz
+   chmod +x livekit-server
+   rm livekit.tar.gz
+   ```
+
+   macOS (AMD64 - Intel) :
+   ```bash
+   cd server/bin
+   curl -L -o livekit.tar.gz \
+     https://github.com/livekit/livekit/releases/download/v1.7.2/livekit_v1.7.2_darwin_amd64.tar.gz
+   tar -xzf livekit.tar.gz
+   chmod +x livekit-server
+   rm livekit.tar.gz
+   ```
+
+   Linux (AMD64) :
+   ```bash
+   cd server/bin
+   curl -L -o livekit.tar.gz \
+     https://github.com/livekit/livekit/releases/download/v1.7.2/livekit_v1.7.2_linux_amd64.tar.gz
+   tar -xzf livekit.tar.gz
+   chmod +x livekit-server
+   rm livekit.tar.gz
+   ```
+
+2. **Générer des clés API**
+   ```bash
+   # Génération clés aléatoires sécurisées
+   API_KEY="APIkey$(openssl rand -hex 16)"
+   API_SECRET=$(openssl rand -base64 32)
+
+   echo "API_KEY: $API_KEY"
+   echo "API_SECRET: $API_SECRET"
+   ```
+
+3. **Configurer server/.env**
+   ```bash
+   # LiveKit Local
+   LIVEKIT_URL=ws://localhost:7880
+   LIVEKIT_API_KEY=APIkey...
+   LIVEKIT_API_SECRET=...
+
+   # Mode local activé
+   USE_LOCAL_LIVEKIT=true
+
+   # Server
+   NODE_ENV=development
+   ```
+
+4. **Démarrer**
+   ```bash
+   cd server
+   npm run dev
+   ```
+
+   Le serveur lancera automatiquement LiveKit Server en local.
+
+### Production HTTPS :
+
+Pour la production, LiveKit Server doit être derrière un reverse proxy HTTPS (nginx, Caddy, Traefik).
+
+Exemple Caddy :
+```
+your-domain.com {
+    reverse_proxy localhost:7880
+}
+```
+
+---
+
+## Dépannage
+
+### "Connexion impossible. Vérifiez le serveur."
+
+1. Vérifier que le serveur Node.js tourne (`http://localhost:3000/health`)
+2. Vérifier les clés dans `server/.env`
+3. Vérifier les logs serveur pour erreurs LiveKit
+4. En mode Cloud : vérifier que l'URL est bien `wss://` (pas `ws://`)
+5. En mode Local : vérifier que le binaire `livekit-server` existe dans `server/bin/`
+
+### "Token generation failed"
+
+- Vérifier que `LIVEKIT_API_KEY` et `LIVEKIT_API_SECRET` sont corrects
+- Les clés doivent correspondre entre le serveur Node.js et LiveKit Server
+
+### Permissions microphone (navigateur)
+
+- Chrome/Edge : Aller dans Paramètres > Confidentialité > Microphone
+- Firefox : Autoriser quand demandé
+- Safari : Préférences > Sites web > Microphone
+
+### Performance réseau
+
+- LiveKit Cloud : latence dépend de votre localisation (serveurs en Europe/US)
+- Local : latence minimale sur WiFi local (~20-50ms)
+
+---
+
+## Tests de validation
+
+Checklist pour vérifier que tout fonctionne :
+
+- [ ] Serveur démarre sans erreur
+- [ ] Client se connecte (pas d'erreur "Connexion impossible")
+- [ ] 2 clients peuvent rejoindre le même groupe
+- [ ] Le bouton PTT fonctionne (maintenir pour parler)
+- [ ] L'audio est transmis entre les 2 clients
+- [ ] La liste des participants s'update en temps réel
+- [ ] Le VU-mètre affiche du niveau audio
+- [ ] Vibration haptique au press/release (mobile)
+
+---
+
+**Note** : Pour la Phase 1, LiveKit Cloud est recommandé. Le mode local sera nécessaire en Phase 3 pour l'intégration avec le bridge audio CoreAudio/JACK.