From 3afb82355e823a7d62e4d068b792e2afdbadd253 Mon Sep 17 00:00:00 2001 From: Benoit Date: Thu, 21 May 2026 15:26:40 +0200 Subject: [PATCH] docs: add comprehensive setup guide and improve README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 102 ++++++++++++++++++++++- docs/SETUP_LIVEKIT.md | 185 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 284 insertions(+), 3 deletions(-) create mode 100644 docs/SETUP_LIVEKIT.md diff --git a/README.md b/README.md index 67a1a25..b2baf47 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,104 @@ -# Résumé Projet - Intercom WebRTC Événementiel +# PTT Live -## Concept +**Système d'intercom professionnel WebRTC pour techniciens événementiels** -Système d'intercom professionnel pour techniciens événementiels. Les utilisateurs communiquent via leur smartphone (navigateur web / PWA) en WiFi. Le serveur fait le pont avec l'installation audio professionnelle existante. +Communiquez via smartphone (PWA) en WiFi, le serveur fait le pont avec l'installation audio professionnelle. + +--- + +## 🚀 Démarrage rapide + +### Prérequis + +- Node.js 20+ ([télécharger](https://nodejs.org)) +- Compte LiveKit Cloud gratuit ([créer ici](https://cloud.livekit.io)) + +### Installation (5 minutes) + +1. **Installer les dépendances** + ```bash + cd server && npm install + cd ../client && npm install + ``` + +2. **Configurer LiveKit Cloud** + + - Créer compte sur https://cloud.livekit.io + - Créer un projet + - Copier vos clés API + + Créer `server/.env` : + ```bash + LIVEKIT_URL=wss://votre-projet.livekit.cloud + LIVEKIT_API_KEY=APIxxxxxxxxxx + LIVEKIT_API_SECRET=xxxxxxxxxxxxxxxxxx + USE_LOCAL_LIVEKIT=false + ``` + +3. **Démarrer** + + Terminal 1 : + ```bash + cd server && npm run dev + ``` + + Terminal 2 : + ```bash + cd client && npm run dev + ``` + +4. **Tester** : http://localhost:5173 + + - Se connecter avec votre nom + - Ouvrir second onglet avec autre nom + - Maintenir bouton PTT pour parler ! + +📖 **Guide complet** : [docs/SETUP_LIVEKIT.md](docs/SETUP_LIVEKIT.md) + +--- + +## 📱 Utilisation + +- **Bouton PTT** : Maintenir pour parler, relâcher pour écouter +- **Desktop** : Clic maintenu / **Mobile** : Appui tactile maintenu +- **Feedback** : Vibration + couleur rouge quand vous parlez +- **VU-mètre** : Visualisation niveau audio en temps réel + +--- + +--- + +## 🐛 Dépannage : "Connexion impossible" + +**Cause** : Clés LiveKit non configurées ou invalides. + +**Solution** : +1. Vérifier que `server/.env` existe avec vos vraies clés LiveKit Cloud +2. L'URL doit être en `wss://` (pas `ws://`) +3. Redémarrer le serveur après modification +4. Vérifier que le serveur tourne : `curl http://localhost:3000/health` + +Voir le guide complet : [docs/SETUP_LIVEKIT.md](docs/SETUP_LIVEKIT.md) + +--- + +## 📚 Documentation + +- **[docs/SETUP_LIVEKIT.md](docs/SETUP_LIVEKIT.md)** - Configuration LiveKit (Cloud + Local) +- **[CLAUDE.md](CLAUDE.md)** - Documentation développement complète +- **[TODO.md](TODO.md)** - Progression des phases + +--- + +## 🎯 État du projet + +- ✅ **Phase 1.1** : Infrastructure +- ✅ **Phase 1.2** : Serveur + API REST +- ⏳ **Phase 1.3** : Bridge audio macOS +- ✅ **Phase 1.4** : Client PWA React +- ⏳ **Phase 1.5** : Tests validation + +**Version actuelle** : 0.1.0 (Phase 1 MVP en cours) --- diff --git a/docs/SETUP_LIVEKIT.md b/docs/SETUP_LIVEKIT.md new file mode 100644 index 0000000..e269e71 --- /dev/null +++ b/docs/SETUP_LIVEKIT.md @@ -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.