PTT-Live/docs/SETUP_LIVEKIT.md

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 :

   # 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

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

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

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

   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

   # 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

   # 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

   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.