PTT-Live/docs/TROUBLESHOOTING.md

Guide de Troubleshooting - PTT Live

Guide de diagnostic et résolution des problèmes courants.

---

Table des matières

1. Problèmes Audio
2. Problèmes Réseau
3. Problèmes Client (PWA)
4. Problèmes Serveur
5. Problèmes JACK/Audio Backend
6. Problèmes Dante/AES67
7. 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

# 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é

# 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

# 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

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

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

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

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

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

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

# 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

# server/config/config.yaml
audio:
  channels: 2  # Stéréo

Redémarrer serveur :

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

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

sudo ufw allow 7880/tcp
sudo ufw allow 7881/tcp
sudo ufw allow 50000:60000/udp
sudo ufw reload

Vérifier LiveKit démarre :

sudo journalctl -u pttlive-server | grep -i livekit
# Chercher "LiveKit server started"

Tester en local :

# 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

# 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é :

# 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

// 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.

# 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.

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

// 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

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

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

# 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

# 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é :

# Tuer processus existant
sudo kill $(sudo lsof -t -i:3000)

# Ou changer port dans .env
echo "PORT=3001" >> server/.env

Dépendances manquantes :

cd server
npm install

Permissions audio (Linux) :

# Ajouter utilisateur au groupe audio
sudo usermod -a -G audio $USER

# Reboot requis
sudo reboot

---

Crash serveur après quelques heures (memory leak)

Diagnostic

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

[Service]
MemoryLimit=4G
MemoryMax=4G

sudo systemctl daemon-reload
sudo systemctl restart pttlive-server

Garbage collection Node.js :

# 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

jackd -d alsa -r 48000
# Erreur : "Cannot lock down memory area (Cannot allocate memory)"

Diagnostic

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

sudo reboot

---

JACK démarre mais pas de son

Diagnostic

# 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

# 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

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

# macOS
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off

# Linux
sudo ufw disable

Si ça fonctionne, ajouter des règles firewall spécifiques :

# 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

sudo ptp4l -i eth0 -f /etc/ptp4l.conf -m
# Offset > 1000 ns (> 1µs)

Diagnostic

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

# 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

# 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

# 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

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

   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)