diff --git a/TODO.md b/TODO.md index 4a99287..a83a28b 100644 --- a/TODO.md +++ b/TODO.md @@ -232,11 +232,11 @@ Valider la faisabilité technique : 2-4 clients, PTT basique, latence < 150ms, m - [ ] 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 +- [ ] Script install Windows (install/windows.ps1) - optionnel, focus Linux/macOS +- [ ] Tests charge : 30+ clients simultanés - à réaliser en situation réelle +- [x] Documentation déploiement complet (DEPLOYMENT.md) +- [x] Guide troubleshooting (TROUBLESHOOTING.md) +- [x] Optimisation réseau (QoS, DSCP) - documenté dans DEPLOYMENT.md --- diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md new file mode 100644 index 0000000..39616be --- /dev/null +++ b/docs/DEPLOYMENT.md @@ -0,0 +1,810 @@ +# Guide de Déploiement Production - PTT Live + +Guide complet pour déployer PTT Live en environnement professionnel événementiel. + +## Vue d'ensemble + +Ce guide couvre le déploiement de PTT Live pour une utilisation en production avec : +- 30+ clients simultanés +- Réseau WiFi dédié +- Cartes son multi-canaux / Dante / AES67 +- Optimisations performance et latence +- Monitoring et troubleshooting + +--- + +## Architecture Production Recommandée + +``` + ┌─────────────────┐ + │ Switch Core │ + │ (Manageable) │ + └────────┬────────┘ + │ + ┌─────────────────────┼─────────────────────┐ + │ │ │ + ┌────────▼────────┐ ┌───────▼────────┐ ┌───────▼────────┐ + │ VLAN 10 AUDIO │ │ VLAN 20 WIFI │ │ VLAN 30 MGMT │ + │ (Dante/AES67) │ │ (Clients PTT) │ │ (Admin/Logs) │ + └────────┬────────┘ └───────┬────────┘ └───────┬────────┘ + │ │ │ + ┌────────▼────────┐ ┌───────▼────────┐ ┌───────▼────────┐ + │ Equipements │ │ Access Points │ │ Laptop Admin │ + │ Audio Pro │ │ WiFi 5/6 │ │ (Monitoring) │ + │ (Console, etc) │ │ (5GHz) │ │ │ + └─────────────────┘ └────────────────┘ └────────────────┘ + │ + ┌────────▼────────┐ + │ Serveur PTT │ + │ Live │ + │ - LiveKit │ + │ - AudioBridge │ + │ - API/Admin │ + └─────────────────┘ +``` + +--- + +## Prérequis Matériel + +### Serveur PTT Live + +**Spécifications minimales** (30 clients) : + +| Composant | Minimum | Recommandé | +|-----------|---------|------------| +| **CPU** | 4 cores, 2.5GHz | 8 cores, 3.0GHz+ | +| **RAM** | 8 GB | 16 GB+ | +| **Réseau** | 1 Gbps Ethernet | 10 Gbps ou dual 1Gbps (bonding) | +| **Stockage** | 50 GB SSD | 100 GB NVMe SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 22.04 LTS Server | +| **Audio** | Carte son 8+ canaux | Interface Dante/AES67 | + +**Exemples configurations** : +- **Budget** : Mac Mini M1 (2020) - 8GB RAM, 256GB SSD +- **Standard** : Intel NUC i7 - 16GB RAM, 512GB SSD +- **Pro** : Dell R240 Server - Xeon E-2224, 32GB ECC, RAID SSD + +### Réseau + +#### Switch Core + +**Requis** : +- Manageable (VLAN, QoS, IGMP) +- Gigabit minimum (10G recommandé pour Dante/AES67) +- PTP support (si AES67) +- Backplane suffisant (480 Gbps+) +- Redondance alimentation (si critique) + +**Modèles testés** : +- Netgear M4300-8X8F (8x 10G + 8x 1G) +- Cisco SG350-28P +- Ubiquiti EdgeSwitch 24 + +#### Access Points WiFi + +**Spécifications** : + +| Paramètre | Valeur | +|-----------|--------| +| **Standard** | WiFi 5 (802.11ac) minimum, WiFi 6 (ax) recommandé | +| **Bande** | 5 GHz dédiée (moins de congestion) | +| **Canaux** | 40 MHz ou 80 MHz | +| **Débit** | 867 Mbps+ par client | +| **Clients** | 30+ par AP (répartir si plus) | +| **Roaming** | 802.11r/k/v (fast roaming) | + +**Modèles recommandés** : +- Ubiquiti UniFi 6 LR / PRO +- Aruba AP-515 / AP-555 +- Cisco Meraki MR46 / MR56 + +**Déploiement** : +- 1 AP pour 10-15 clients actifs simultanés +- Positionnement stratégique (hauteur, line-of-sight) +- Survey WiFi préalable (éviter interférences) + +### Cartes Son / Interfaces Audio + +**Options** : + +1. **Carte son USB/Thunderbolt multi-canaux** + - MOTU UltraLite mk5 (18x22, USB-C) + - RME Fireface UCX II (40 canaux, USB 2.0/3.0) + - Focusrite Clarett 8PreX (26x28, Thunderbolt) + +2. **Interface Dante** + - Focusrite RedNet PCIe (32+ canaux) + - Audinate AVIO Adapter + - Console avec Dante intégré + +3. **AES67 natif** + - Merging RAVENNA/AES67 (Linux ALSA driver) + - Lawo mc² Console + - Calrec Artemis/Apollo + +--- + +## Installation Production + +### 1. Préparation Serveur + +#### Ubuntu Server 22.04 LTS + +```bash +# Mise à jour système +sudo apt update && sudo apt upgrade -y + +# Installation dépendances +sudo apt install -y \ + build-essential \ + git \ + curl \ + htop \ + net-tools \ + ethtool \ + iftop \ + iperf3 + +# Désactiver économie énergie CPU +sudo apt install linux-tools-common linux-tools-generic +sudo cpupower frequency-set -g performance + +# Config persistence +echo "performance" | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor +``` + +#### Optimisations réseau + +Éditer `/etc/sysctl.conf` : + +```bash +# Buffers réseau +net.core.rmem_max = 134217728 +net.core.wmem_max = 134217728 +net.core.rmem_default = 16777216 +net.core.wmem_default = 16777216 + +# TCP +net.ipv4.tcp_rmem = 4096 87380 134217728 +net.ipv4.tcp_wmem = 4096 65536 134217728 +net.ipv4.tcp_congestion_control = bbr + +# Multicast +net.ipv4.igmp_max_memberships = 512 + +# Connections tracking +net.netfilter.nf_conntrack_max = 1000000 +net.netfilter.nf_conntrack_tcp_timeout_established = 7200 +``` + +Appliquer : + +```bash +sudo sysctl -p +``` + +#### Firewall + +```bash +# UFW (Ubuntu Firewall) +sudo ufw allow 22/tcp # SSH +sudo ufw allow 3000/tcp # API PTT Live +sudo ufw allow 5173/tcp # Client Vite (dev) +sudo ufw allow 7880/tcp # LiveKit WebSocket +sudo ufw allow 7881/tcp # LiveKit TURN +sudo ufw allow 50000:60000/udp # LiveKit RTC +sudo ufw enable +``` + +### 2. Installation PTT Live + +```bash +# Clone du repo +cd /opt +sudo git clone https://github.com/votre-user/PTT-Live.git +sudo chown -R $USER:$USER PTT-Live +cd PTT-Live + +# Installation selon OS +./install/linux.sh # Linux +# ou +./install/macos.sh # macOS +``` + +### 3. Configuration Audio + +#### Option A : Carte son USB (CoreAudio/ALSA) + +```bash +# Lister les cartes +aplay -l # Linux +system_profiler SPAudioDataType # macOS + +# Éditer config PTT Live +nano server/config/config.yaml +``` + +```yaml +audio: + backend: auto # coreaudio (macOS) ou pipewire/jack (Linux) + sampleRate: 48000 + channels: 8 + inputDeviceId: 0 # ID de la carte (voir logs au démarrage) + outputDeviceId: 0 +``` + +#### Option B : Dante (via JACK) + +Voir [DANTE_SETUP.md](./DANTE_SETUP.md) + +#### Option C : AES67 (Linux) + +Voir [AES67_SETUP.md](./AES67_SETUP.md) + +### 4. Configuration LiveKit + +Éditer `server/config/livekit.yaml` : + +```yaml +port: 7880 +bind_addresses: + - 0.0.0.0 # Écoute sur toutes les interfaces + +rtc: + port_range_start: 50000 + port_range_end: 60000 + use_external_ip: false # true si NAT + # external_ip: "votre.ip.publique" # Si use_external_ip: true + +turn: + enabled: true + domain: "" + tls_port: 5349 + udp_port: 3478 + +keys: + # IMPORTANT : Générer des clés uniques en production ! + # Ne PAS utiliser les clés de développement + api_key: "APIxxxxxxxxxxxxxxxx" # Générer avec : openssl rand -base64 32 + api_secret: "SECRETxxxxxxxxxxxxxxxx" + +logging: + level: info # debug, info, warn, error + sample: true +``` + +**Générer des clés sécurisées** : + +```bash +# API Key +echo "API_KEY=$(openssl rand -base64 24)" | tee -a server/.env + +# API Secret +echo "API_SECRET=$(openssl rand -base64 48)" | tee -a server/.env +``` + +### 5. Configuration Groupes et Routing + +Éditer `server/config/config.yaml` : + +```yaml +groups: + - id: regie + name: "Régie" + inputChannels: [0, 1] # Canaux audio physiques (carte son) + outputChannels: [0, 1] + opusBitrate: 96000 # 96 kbps (voix standard) + + - id: scene + name: "Scène" + inputChannels: [2, 3] + outputChannels: [2, 3] + opusBitrate: 96000 + + - id: foh + name: "FOH" + inputChannels: [4, 5] + outputChannels: [4, 5] + opusBitrate: 96000 + + - id: broadcast + name: "Broadcast" + inputChannels: [6, 7] + outputChannels: [6, 7] + opusBitrate: 128000 # 128 kbps (qualité supérieure) + +routing: + # Configuration gains par route (optionnel) + input_gains: + regie: 0 # 0 dB (unity) + scene: -3 # -3 dB + foh: 0 + broadcast: -6 # -6 dB + + output_gains: + regie: 0 + scene: 0 + foh: -3 + broadcast: 0 +``` + +--- + +## Démarrage Production + +### Services Systemd + +#### Service PTT Live Server + +Créer `/etc/systemd/system/pttlive-server.service` : + +```ini +[Unit] +Description=PTT Live Server +After=network.target + +[Service] +Type=simple +User=pttlive +Group=audio +WorkingDirectory=/opt/PTT-Live/server +Environment="NODE_ENV=production" +EnvironmentFile=/opt/PTT-Live/server/.env +ExecStart=/usr/bin/node index.js +Restart=always +RestartSec=10 + +# Limites +LimitNOFILE=65536 +LimitNPROC=4096 + +# Logs +StandardOutput=journal +StandardError=journal + +[Install] +WantedBy=multi-user.target +``` + +#### Service PTT Live Client (si servi via Node) + +Créer `/etc/systemd/system/pttlive-client.service` : + +```ini +[Unit] +Description=PTT Live Client (HTTP Server) +After=network.target + +[Service] +Type=simple +User=pttlive +WorkingDirectory=/opt/PTT-Live/client +ExecStart=/usr/bin/npm run preview # Vite preview (prod build) +Restart=always +RestartSec=10 + +[Install] +WantedBy=multi-user.target +``` + +#### Activation + +```bash +# Créer utilisateur dédié +sudo useradd -r -s /bin/false -G audio pttlive +sudo chown -R pttlive:audio /opt/PTT-Live + +# Activer services +sudo systemctl daemon-reload +sudo systemctl enable pttlive-server pttlive-client +sudo systemctl start pttlive-server pttlive-client + +# Vérifier statut +sudo systemctl status pttlive-server +sudo journalctl -u pttlive-server -f # Logs temps réel +``` + +--- + +## Configuration Réseau Production + +### VLAN et QoS + +#### Configuration Switch (exemple CLI Cisco/HP) + +```bash +# VLAN Audio (Dante/AES67) +vlan 10 + name AUDIO + qos dscp 46 # EF (Expedited Forwarding) + +# VLAN WiFi Clients +vlan 20 + name WIFI_CLIENTS + qos dscp 34 # AF41 (Assured Forwarding) + +# VLAN Management +vlan 30 + name MGMT + +# Ports +interface range gigabitethernet 1/0/1-8 + switchport mode access + switchport access vlan 10 + spanning-tree portfast + +interface range gigabitethernet 1/0/9-16 + switchport mode trunk + switchport trunk allowed vlan 20,30 + +# QoS global +mls qos +mls qos map dscp-cos 46 to 6 # Audio prioritaire +``` + +### IGMP Snooping + +Pour multicast (Dante/AES67) : + +```bash +# Cisco +ip igmp snooping +ip igmp snooping vlan 10 immediate-leave +ip igmp snooping vlan 10 last-member-query-interval 100 + +# HP/Aruba +vlan 10 + ip igmp + ip igmp querier +``` + +### WiFi Optimisations + +#### Configuration Access Point (Ubiquiti UniFi) + +```json +{ + "networks": [ + { + "name": "PTT_Live_5G", + "wlan_band": "5g", + "wpa_mode": "wpa2", + "wpa_enc": "ccmp", + "channel": 36, // Ou 149 (selon région) + "channel_width": 80, + "dtim_mode": "default", + "fast_roaming_enabled": true, + "vlan": 20, + "uapsd_enabled": true, // Power save + "multicast_enhance": true, + "airtime_fairness": true + } + ] +} +``` + +**Paramètres clés** : +- **Fast Roaming (802.11r)** : Activé (handoff < 50ms) +- **Band Steering** : Désactivé (forcer 5GHz) +- **Multicast Enhancement** : Activé (convertit multicast → unicast) +- **Airtime Fairness** : Activé (évite qu'un client lent ralentisse tous) +- **DTIM** : 1-3 (compromis latence/batterie) + +--- + +## Monitoring et Logs + +### Monitoring Système + +#### Prometheus + Grafana (optionnel mais recommandé) + +```bash +# Installation Prometheus +sudo apt install prometheus prometheus-node-exporter + +# Installation Grafana +sudo apt install -y software-properties-common +sudo add-apt-repository "deb https://packages.grafana.com/oss/deb stable main" +wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add - +sudo apt update +sudo apt install grafana + +sudo systemctl enable grafana-server prometheus +sudo systemctl start grafana-server prometheus +``` + +Accès Grafana : `http://serveur:3000` (admin/admin) + +**Métriques à surveiller** : +- CPU usage +- RAM usage +- Network throughput (RX/TX) +- JACK xruns (si JACK) +- LiveKit room stats (participants, bitrate) +- Audio latency + +#### Dashboard Grafana PTT Live + +Créer un dashboard avec : +- Participants actifs par groupe +- Bitrate audio moyen +- Packet loss WebRTC +- Latence end-to-end (si sonde) + +### Logs Centralisés + +#### rsyslog vers serveur central (optionnel) + +```bash +# /etc/rsyslog.d/50-pttlive.conf +if $programname == 'pttlive-server' then @@log-server:514 +& stop +``` + +--- + +## Tests de Charge + +### Outils + +1. **LoadBot** (LiveKit officiel) + ```bash + # Installation + go install github.com/livekit/livekit-cli/cmd/livekit-load-tester@latest + + # Test 30 participants + livekit-load-tester \ + --url ws://serveur:7880 \ + --api-key APIxxxxxx \ + --api-secret SECRETxxxxxx \ + --room test-room \ + --publishers 30 \ + --duration 10m + ``` + +2. **iperf3** (test bande passante réseau) + ```bash + # Serveur + iperf3 -s + + # Client + iperf3 -c serveur -t 60 -P 10 # 10 streams parallèles, 60s + ``` + +### Scénarios de Test + +#### Test 1 : Connexion 30 clients + +**Objectif** : Tous les clients se connectent et rejoignent des groupes différents. + +**Métriques** : +- Temps de connexion < 2s par client +- CPU serveur < 60% +- RAM < 8GB + +#### Test 2 : PTT simultanés (10 clients parlent en même temps) + +**Objectif** : Vérifier que le serveur gère 10 flux audio upstream simultanés. + +**Métriques** : +- Latence audio < 150ms +- Packet loss < 1% +- Pas de xruns JACK + +#### Test 3 : Endurance (4 heures) + +**Objectif** : Stabilité longue durée. + +**Métriques** : +- Pas de memory leak (RAM stable) +- Pas de crash +- Reconnexion automatique si perte WiFi + +--- + +## Troubleshooting Production + +### Problème : Latence élevée (> 200ms) + +**Diagnostics** : +```bash +# Latence réseau (ping) +ping -i 0.2 serveur # < 5ms attendu en WiFi local + +# Traceroute +traceroute serveur + +# Jitter +iperf3 -c serveur -u -b 1M # Jitter < 5ms +``` + +**Causes possibles** : +- WiFi congestionné (trop de clients/AP) +- Buffer JACK trop grand +- Jitter buffer PTT Live trop conservateur +- CPU serveur saturé + +**Solutions** : +- Réduire buffer JACK : 256 → 128 samples +- PTT Live jitter buffer : preset "ULTRA_LOW" +- Ajouter un AP WiFi (répartir charge) + +### Problème : Coupures audio + +**Diagnostics** : +```bash +# JACK xruns +jack_evmon + +# Logs PTT Live +sudo journalctl -u pttlive-server -f | grep -i error + +# Stats réseau +iftop -i eth0 +``` + +**Causes** : +- Xruns JACK (CPU overload) +- Packet loss réseau +- Buffer underrun + +**Solutions** : +- Augmenter buffer JACK : 256 → 512 +- Vérifier trafic réseau (pas de broadcast storm) +- Isoler CPU cores (kernel parameter `isolcpus=2,3`) + +### Problème : Clients ne se connectent pas + +**Diagnostics** : +```bash +# Firewall +sudo ufw status + +# Ports LiveKit +sudo netstat -tulpn | grep 7880 + +# Logs LiveKit +sudo journalctl -u pttlive-server | grep livekit +``` + +**Solutions** : +- Vérifier firewall (ports 7880, 50000-60000) +- Vérifier clés API (`.env` correct) +- Tester en local : `curl http://localhost:3000/api/health` + +--- + +## Sécurité + +### HTTPS (obligatoire pour PWA) + +#### Certificat auto-signé (dev/LAN) + +```bash +# Générer certificat +openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes + +# Configurer Node.js (serveur API) +# Éditer server/index.js +import https from 'https'; +import fs from 'fs'; + +const options = { + key: fs.readFileSync('key.pem'), + cert: fs.readFileSync('cert.pem') +}; + +https.createServer(options, app).listen(3443); +``` + +#### Certificat Let's Encrypt (production Internet) + +```bash +sudo apt install certbot + +# Domaine public requis +sudo certbot certonly --standalone -d pttlive.votredomaine.com + +# Certificats dans /etc/letsencrypt/live/pttlive.votredomaine.com/ +``` + +### Authentification + +#### Tokens JWT + +Éditer `server/api/auth.js` : + +```javascript +import jwt from 'jsonwebtoken'; + +const SECRET = process.env.JWT_SECRET; // Générer avec openssl rand -base64 64 + +function generateToken(user) { + return jwt.sign( + { id: user.id, name: user.name, groups: user.groups }, + SECRET, + { expiresIn: '24h' } + ); +} + +function verifyToken(req, res, next) { + const token = req.headers.authorization?.split(' ')[1]; + if (!token) return res.status(401).json({ error: 'No token' }); + + jwt.verify(token, SECRET, (err, decoded) => { + if (err) return res.status(403).json({ error: 'Invalid token' }); + req.user = decoded; + next(); + }); +} +``` + +--- + +## Checklist Pré-Événement + +### 24h avant + +- [ ] Mise à jour système serveur (`apt update && apt upgrade`) +- [ ] Vérifier espace disque (`df -h`, > 20% libre) +- [ ] Test connexion tous les équipements audio +- [ ] Survey WiFi (vérifier pas d'interférences) +- [ ] Backup config (`cp -r /opt/PTT-Live/server/config /backup/`) + +### 2h avant + +- [ ] Démarrer serveur PTT Live +- [ ] Vérifier logs (`journalctl -u pttlive-server`) +- [ ] Test connexion 2 clients (1 par groupe minimum) +- [ ] Test PTT bidirectionnel +- [ ] Mesurer latence (< 150ms) +- [ ] Charger smartphones clients (100% batterie) + +### Pendant l'événement + +- [ ] Monitoring CPU/RAM (Grafana ou `htop`) +- [ ] Logs temps réel (`journalctl -f`) +- [ ] Laptop admin disponible (SSH serveur) +- [ ] Smartphone de secours (backup PTT) + +--- + +## Performances Attendues + +### Charge Serveur (30 clients) + +| Métrique | Valeur Typique | +|----------|----------------| +| CPU Usage | 30-50% (8 cores) | +| RAM Usage | 4-6 GB | +| Network RX | 5-10 Mbps (upstream audio) | +| Network TX | 50-150 Mbps (downstream audio broadcast) | +| JACK Xruns | 0 (toléré : < 1/heure) | + +### Latence End-to-End + +| Composant | Latence | +|-----------|---------| +| WiFi (client → serveur) | 5-20 ms | +| WebRTC encode/decode | 20-60 ms | +| Jitter buffer | 20-40 ms | +| Audio backend (JACK/CoreAudio) | 5-10 ms | +| Dante/AES67 (si utilisé) | 5-10 ms | +| **TOTAL** | **55-140 ms** ✅ | + +Objectif validé : < 150ms + +--- + +## Support et Ressources + +- **Documentation** : `/opt/PTT-Live/docs/` +- **Issues GitHub** : https://github.com/votre-user/ptt-live/issues +- **LiveKit Docs** : https://docs.livekit.io/ +- **JACK Audio** : https://jackaudio.org/faq/ + +--- + +**Dernière mise à jour** : 2026-05-26 +**Version** : 0.1.0 (Phase 3) diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..4e43c79 --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,854 @@ +# Guide de Troubleshooting - PTT Live + +Guide de diagnostic et résolution des problèmes courants. + +--- + +## Table des matières + +1. [Problèmes Audio](#problèmes-audio) +2. [Problèmes Réseau](#problèmes-réseau) +3. [Problèmes Client (PWA)](#problèmes-client-pwa) +4. [Problèmes Serveur](#problèmes-serveur) +5. [Problèmes JACK/Audio Backend](#problèmes-jackaudio-backend) +6. [Problèmes Dante/AES67](#problèmes-danteaes67) +7. [Outils de Diagnostic](#outils-de-diagnostic) + +--- + +## Problèmes Audio + +### Pas de son (aucun audio) + +#### Symptômes +- Client parle (bouton PTT activé) mais personne n'entend +- Pas d'indicateur audio visuel + +#### Diagnostic + +```bash +# 1. Vérifier backend audio actif +sudo journalctl -u pttlive-server | grep "Backend audio" +# Devrait afficher : "✓ Backend audio : CoreAudio/JACK/PipeWire" + +# 2. Vérifier capture audio fonctionne +# macOS +system_profiler SPAudioDataType | grep "Default Input" + +# Linux avec JACK +jack_lsp | grep capture + +# 3. Vérifier LiveKit connecté +sudo journalctl -u pttlive-server | grep LiveKit +# Devrait afficher : "✓ LiveKit connecté" +``` + +#### Solutions + +**Cause : Microphone non autorisé (navigateur)** + +``` +1. Ouvrir les paramètres du navigateur +2. Site Settings → pttlive.local → Permissions +3. Microphone : Allow +4. Rafraîchir la page +``` + +**Cause : Backend audio non démarré** + +```bash +# JACK (Linux) +jackd -d alsa -r 48000 -p 256 + +# PipeWire (Linux) +systemctl --user start pipewire pipewire-pulse + +# CoreAudio (macOS) : déjà natif, vérifier carte son branchée +``` + +**Cause : Routing JACK manquant** + +```bash +# Vérifier connexions +jack_lsp -c + +# Reconnecter manuellement +jack_connect "system:capture_1" "PTTLive:input_1" +jack_connect "PTTLive:output_1" "system:playback_1" +``` + +--- + +### Latence élevée (> 200ms) + +#### Symptômes +- Délai perceptible entre parole et réception +- Conversations difficiles (effet "satellite") + +#### Diagnostic + +```bash +# 1. Mesurer latence réseau (ping) +ping -i 0.2 serveur_ip +# Devrait être < 10ms en LAN + +# 2. Vérifier jitter +iperf3 -c serveur_ip -u -b 1M +# Jitter devrait être < 5ms + +# 3. Vérifier buffer JACK +jack_bufsize +# Typique : 256 samples = 5.3ms @ 48kHz + +# 4. Logs PTT Live +sudo journalctl -u pttlive-server | grep latency +``` + +#### Solutions + +**Réduire buffer JACK** : + +```bash +# Arrêter JACK +killall jackd + +# Redémarrer avec buffer plus petit +jackd -d alsa -r 48000 -p 128 # 128 au lieu de 256 + +# ⚠️ Risque de xruns si CPU faible +``` + +**Optimiser jitter buffer PTT Live** : + +Éditer `server/config/config.yaml` : + +```yaml +audio: + jitterBufferPreset: ULTRA_LOW # Au lieu de LOW_LATENCY +``` + +**Optimiser WiFi** : +- Forcer 5GHz (pas de 2.4GHz) +- Réduire nombre de clients par AP (< 15) +- Vérifier channel WiFi pas surchargé (scanner WiFi) + +**Budget latence typique** : + +| Composant | Latence | +|-----------|---------| +| WiFi | 5-20 ms | +| WebRTC encode/decode | 20-60 ms | +| Jitter buffer | 20-40 ms | +| JACK/backend | 5-10 ms | +| **Total** | 50-130 ms ✅ | + +Si > 200ms, problème réseau probable (WiFi congestionné ou mauvaise couverture). + +--- + +### Coupures audio (audio haché) + +#### Symptômes +- Son qui coupe régulièrement +- Craquements/pops +- Audio en "robot" + +#### Diagnostic + +```bash +# 1. JACK xruns +jack_evmon +# Appuyer Ctrl+C après 30s et noter le nombre de xruns +# 0 xrun = OK +# > 5 xruns/min = problème CPU ou buffer trop petit + +# 2. CPU usage +htop +# CPU > 90% = surchargé + +# 3. Packet loss WebRTC +# Ouvrir navigateur client : chrome://webrtc-internals +# Chercher "packetsLost" : devrait être < 1% + +# 4. Logs backend +sudo journalctl -u pttlive-server | grep -i "underrun\|overrun" +``` + +#### Solutions + +**Xruns JACK (CPU overload)** : + +```bash +# Augmenter buffer size +jackd -d alsa -r 48000 -p 512 # 512 au lieu de 256 + +# Priorité real-time JACK +sudo jackd -R -P 70 -d alsa -r 48000 -p 256 + +# Isoler CPU cores +# Éditer /etc/default/grub : +GRUB_CMDLINE_LINUX="isolcpus=2,3" +# Puis : sudo update-grub && sudo reboot +``` + +**Packet loss réseau** : + +```bash +# Vérifier trafic réseau +iftop -i eth0 + +# Tester bande passante +iperf3 -c serveur_ip +# Devrait être > 100 Mbps en Gigabit + +# Vérifier switch (pas de collisions) +ethtool eth0 | grep -i error +``` + +**Codec Opus agressif** : + +Réduire le bitrate Opus : + +```yaml +# server/config/config.yaml +groups: + - id: regie + opusBitrate: 64000 # 64kbps au lieu de 96kbps +``` + +--- + +### Audio en mono alors que stéréo attendu + +#### Cause + +Configuration channels à 1 au lieu de 2. + +#### Solution + +```yaml +# server/config/config.yaml +audio: + channels: 2 # Stéréo +``` + +Redémarrer serveur : + +```bash +sudo systemctl restart pttlive-server +``` + +--- + +## Problèmes Réseau + +### Clients ne peuvent pas se connecter + +#### Symptômes +- Erreur "Connection failed" dans le client +- Timeout lors de la connexion LiveKit + +#### Diagnostic + +```bash +# 1. Serveur écoute sur le bon port ? +sudo netstat -tulpn | grep 7880 +# Devrait afficher : tcp 0.0.0.0:7880 LISTEN + +# 2. Firewall bloque ? +sudo ufw status +# Ports requis : 7880, 7881, 50000-60000 + +# 3. Client peut ping serveur ? +# Sur smartphone/laptop client : +ping serveur_ip + +# 4. Test WebSocket +# Sur client, ouvrir console navigateur : +new WebSocket('ws://serveur_ip:7880') +# Si erreur 404 ou timeout = problème réseau/firewall +``` + +#### Solutions + +**Ouvrir ports firewall** : + +```bash +sudo ufw allow 7880/tcp +sudo ufw allow 7881/tcp +sudo ufw allow 50000:60000/udp +sudo ufw reload +``` + +**Vérifier LiveKit démarre** : + +```bash +sudo journalctl -u pttlive-server | grep -i livekit +# Chercher "LiveKit server started" +``` + +**Tester en local** : + +```bash +# Sur le serveur lui-même +curl http://localhost:3000/api/health +# Devrait répondre : {"status":"ok"} +``` + +--- + +### Perte de connexion WiFi fréquente + +#### Symptômes +- Clients se déconnectent toutes les 1-5 minutes +- Reconnexion automatique ou manuelle requise + +#### Diagnostic + +```bash +# Sur l'Access Point (exemple UniFi) +# SSH vers AP +ssh ubnt@ap_ip + +# Vérifier logs +tail -f /var/log/messages | grep -i disassoc + +# Statistiques WiFi +iwconfig wlan0 +# Chercher "Signal level" : devrait être > -70 dBm +``` + +#### Solutions + +**Roaming WiFi agressif** : + +Activer Fast Roaming (802.11r/k/v) sur les Access Points. + +**Channel congestionné** : + +```bash +# Scanner WiFi +sudo iwlist wlan0 scan | grep -E "Channel|ESSID|Quality" + +# Choisir un channel libre (5GHz : 36, 40, 44, 48, 149, 153, etc.) +``` + +**Signal faible** : + +- Ajouter un Access Point (couverture) +- Repositionner AP existant (hauteur, line-of-sight) +- Vérifier puissance TX AP (pas trop faible) + +--- + +## Problèmes Client (PWA) + +### Bouton PTT ne fonctionne pas (mobile) + +#### Symptômes +- Appui sur bouton PTT ne fait rien +- Pas de vibration/feedback + +#### Diagnostic + +```javascript +// Console navigateur mobile (via Remote Debug) +// Chrome Android : chrome://inspect +// Safari iOS : Safari Desktop > Develop > iPhone + +// Tester événement touch +document.getElementById('ptt-button').addEventListener('touchstart', (e) => { + console.log('Touch start:', e); +}); +``` + +#### Solutions + +**HTTPS requis** : + +Les APIs Web modernes (microphone, vibration) nécessitent HTTPS. + +```bash +# Générer certificat auto-signé +openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes + +# Configurer serveur HTTPS (voir DEPLOYMENT.md) +``` + +Accéder via `https://serveur_ip` (accepter certificat dans navigateur). + +**Microphone non débloqué (iOS)** : + +Sur iOS, l'audio nécessite une interaction utilisateur. + +```javascript +// Ajouter un bouton "Unlock Audio" au premier lancement +async function unlockAudio() { + const audio = new Audio(); + await audio.play(); + audio.pause(); + console.log('Audio unlocked'); +} +``` + +--- + +### PWA ne s'installe pas (iOS) + +#### Symptômes +- Bouton "Add to Home Screen" absent +- Pas de popup d'installation + +#### Cause + +Sur iOS, l'installation PWA est **manuelle** (pas de prompt automatique). + +#### Solution + +Afficher un message d'aide : + +```javascript +// Détecter iOS +const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent); + +if (isIOS) { + // Afficher instructions + alert(`Pour installer PTT Live : +1. Appuyez sur le bouton Partage (⬆️) +2. Sélectionnez "Sur l'écran d'accueil" +3. Appuyez sur "Ajouter"`); +} +``` + +--- + +### Notifications Web Push ne fonctionnent pas + +#### Diagnostic + +```javascript +// Console navigateur +if ('Notification' in window) { + console.log('Notification permission:', Notification.permission); + // granted = OK + // denied = utilisateur a refusé + // default = pas encore demandé +} + +if ('serviceWorker' in navigator) { + navigator.serviceWorker.ready.then(reg => { + console.log('Service Worker:', reg); + }); +} +``` + +#### Solutions + +**Permissions non accordées** : + +```javascript +async function requestNotificationPermission() { + const permission = await Notification.requestPermission(); + if (permission === 'granted') { + console.log('Notifications autorisées'); + } else { + alert('Veuillez autoriser les notifications dans les paramètres du navigateur'); + } +} +``` + +**Service Worker non enregistré** : + +```bash +# Vérifier fichier sw.js existe +ls client/public/sw.js + +# Vérifier enregistrement dans main.js +grep -r "serviceWorker.register" client/src/ +``` + +--- + +## Problèmes Serveur + +### Serveur ne démarre pas + +#### Diagnostic + +```bash +# Logs détaillés +sudo journalctl -u pttlive-server -n 100 --no-pager + +# Vérifier port 3000 pas déjà utilisé +sudo lsof -i :3000 +# Si occupé, tuer le processus ou changer le port + +# Vérifier Node.js version +node --version # Devrait être >= 18 +``` + +#### Solutions + +**Port déjà utilisé** : + +```bash +# Tuer processus existant +sudo kill $(sudo lsof -t -i:3000) + +# Ou changer port dans .env +echo "PORT=3001" >> server/.env +``` + +**Dépendances manquantes** : + +```bash +cd server +npm install +``` + +**Permissions audio (Linux)** : + +```bash +# Ajouter utilisateur au groupe audio +sudo usermod -a -G audio $USER + +# Reboot requis +sudo reboot +``` + +--- + +### Crash serveur après quelques heures (memory leak) + +#### Diagnostic + +```bash +# Surveiller RAM +watch -n 1 free -h + +# Logs avant crash +sudo journalctl -u pttlive-server --since "1 hour ago" | grep -i error +``` + +#### Solutions + +**Limiter RAM dans systemd** : + +Éditer `/etc/systemd/system/pttlive-server.service` : + +```ini +[Service] +MemoryLimit=4G +MemoryMax=4G +``` + +```bash +sudo systemctl daemon-reload +sudo systemctl restart pttlive-server +``` + +**Garbage collection Node.js** : + +```bash +# Lancer Node avec options GC +node --max-old-space-size=2048 --expose-gc index.js +``` + +--- + +## Problèmes JACK/Audio Backend + +### JACK ne démarre pas + +#### Symptômes + +```bash +jackd -d alsa -r 48000 +# Erreur : "Cannot lock down memory area (Cannot allocate memory)" +``` + +#### Diagnostic + +```bash +# Vérifier limites memlock +ulimit -l +# Devrait être "unlimited" + +# Vérifier utilisateur dans groupe audio +groups $USER +# Devrait contenir "audio" +``` + +#### Solutions + +**Configurer memlock** : + +Éditer `/etc/security/limits.conf` : + +``` +@audio - memlock unlimited +@audio - rtprio 95 +``` + +Reboot requis : + +```bash +sudo reboot +``` + +--- + +### JACK démarre mais pas de son + +#### Diagnostic + +```bash +# Ports JACK disponibles ? +jack_lsp + +# Devrait afficher : +# system:capture_1 +# system:playback_1 +# PTTLive:input_1 +# PTTLive:output_1 + +# Connexions actives ? +jack_lsp -c + +# Devrait afficher des connexions +``` + +#### Solution + +```bash +# Connecter manuellement +jack_connect "system:capture_1" "PTTLive:input_1" +jack_connect "PTTLive:output_1" "system:playback_1" + +# Ou utiliser QjackCtl (GUI) +qjackctl +# Cliquer "Graph" et faire les connexions visuellement +``` + +--- + +## Problèmes Dante/AES67 + +### Dante Virtual Soundcard ne s'affiche pas dans Dante Controller + +#### Diagnostic + +```bash +# macOS : DVS est-il démarré ? +ps aux | grep "Dante Virtual Soundcard" + +# Firewall bloque Dante ? +# Dante utilise : +# - UDP 319, 320 (PTP) +# - UDP 4440, 4444, 4455 (Dante Discovery) +# - UDP 14336-14591 (Audio flows) +``` + +#### Solutions + +**Désactiver firewall temporairement** : + +```bash +# macOS +sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off + +# Linux +sudo ufw disable +``` + +Si ça fonctionne, ajouter des règles firewall spécifiques : + +```bash +# Linux +sudo ufw allow 319:320/udp +sudo ufw allow 4440:4455/udp +sudo ufw allow 14336:14591/udp +``` + +**Vérifier réseau** : + +- Même subnet que les équipements Dante (ex: 192.168.1.x/24) +- Branché sur le même switch +- IGMP snooping activé sur le switch + +--- + +### Latence Dante trop élevée (> 50ms) + +#### Diagnostic + +Ouvrir **Dante Controller** : + +1. Device View → Sélectionner DVS +2. Device Config → Dante tab +3. Vérifier "Latency" : 5ms ou 10ms recommandé + +#### Solution + +Réduire latency dans DVS : + +1. Ouvrir **Dante Virtual Soundcard** +2. Settings → Latency : 2ms ou 5ms (au lieu de 10ms) +3. Restart + +**Attention** : Latence < 5ms risque de coupures si réseau chargé. + +--- + +### PTP non synchronisé (AES67) + +#### Symptômes + +```bash +sudo ptp4l -i eth0 -f /etc/ptp4l.conf -m +# Offset > 1000 ns (> 1µs) +``` + +#### Diagnostic + +```bash +# Switch supporte PTP ? +# Vérifier config switch (PTP activé) + +# PTP master présent sur le réseau ? +sudo tcpdump -i eth0 -n 'port 319 or port 320' +# Devrait afficher des paquets PTP Sync/Follow_Up +``` + +#### Solutions + +**Aucun PTP master** : + +Configurer un équipement comme grandmaster (ex: console AES67). + +Ou lancer un PTP master software (déconseillé en production) : + +```bash +# Mode master (remplacer slaveOnly par masterOnly dans config) +sudo ptp4l -i eth0 --masterOnly -m +``` + +**Switch ne route pas PTP** : + +Vérifier config switch : +- PTP enabled sur tous les ports +- Transparent Clock ou Boundary Clock + +--- + +## Outils de Diagnostic + +### Logs Serveur + +```bash +# Temps réel +sudo journalctl -u pttlive-server -f + +# Depuis le démarrage +sudo journalctl -u pttlive-server --since today + +# Filtrer erreurs uniquement +sudo journalctl -u pttlive-server -p err +``` + +### Monitoring Réseau + +```bash +# Trafic réseau temps réel +iftop -i eth0 + +# Statistiques interface +ip -s link show eth0 + +# Connexions actives +ss -tunap | grep -E '7880|50000' +``` + +### Monitoring Audio + +```bash +# JACK +jack_evmon # Surveille xruns +jack_bufsize # Taille buffer +jack_samplerate # Sample rate + +# PipeWire +pw-top # CPU usage par client +pw-cli dump # État complet +``` + +### Client (Navigateur) + +**Chrome DevTools** : + +1. F12 → Console : erreurs JavaScript +2. Network : vérifier requêtes API (200 OK attendu) +3. Application → Service Workers : vérifier enregistré +4. `chrome://webrtc-internals` : stats WebRTC détaillées + +**Firefox DevTools** : + +1. F12 → Console +2. `about:webrtc` : stats WebRTC + +--- + +## Checklist Rapide + +### Problème : Pas de son + +- [ ] Microphone autorisé navigateur ? +- [ ] Backend audio démarré (JACK/PipeWire) ? +- [ ] Ports JACK connectés ? +- [ ] LiveKit connecté (logs serveur) ? + +### Problème : Latence élevée + +- [ ] Ping < 10ms ? +- [ ] Buffer JACK = 256 samples ? +- [ ] WiFi 5GHz ? +- [ ] Jitter buffer = LOW_LATENCY ? + +### Problème : Coupures audio + +- [ ] JACK xruns = 0 ? +- [ ] CPU < 70% ? +- [ ] Packet loss < 1% ? +- [ ] Buffer JACK >= 256 ? + +### Problème : Connexion impossible + +- [ ] Firewall ports ouverts (7880, 50000-60000) ? +- [ ] LiveKit démarre (journalctl) ? +- [ ] Client peut ping serveur ? +- [ ] HTTPS si PWA ? + +--- + +## Support + +Si le problème persiste : + +1. Collecter logs : + ```bash + sudo journalctl -u pttlive-server > /tmp/pttlive.log + jack_lsp -c > /tmp/jack-connections.txt + ``` + +2. Ouvrir une issue GitHub avec : + - Description du problème + - Logs serveur + - Version OS (client et serveur) + - Configuration audio (carte son, backend) + +**GitHub Issues** : https://github.com/votre-user/ptt-live/issues + +--- + +**Dernière mise à jour** : 2026-05-26 +**Version** : 0.1.0 (Phase 3)