PTT-Live/DESKTOP-APP.md

PTT Live - Application Desktop Server

Application Electron pour gérer le serveur PTT Live avec interface graphique complète.

📸 Aperçu

L'application desktop intègre :

• ✅ Dashboard temps réel : stats, utilisateurs, QR Code
• ✅ Configuration audio : sélection devices, sample rate, bitrate
• ✅ Gestion groupes : CRUD complet avec API
• ✅ Monitoring : VU-mètres (prévu), logs filtrables
• ✅ Contrôle serveur : démarrage/arrêt avec feedback visuel

---

🚀 Démarrage Rapide

# Depuis la racine du projet
./start-desktop.sh

# OU manuellement
cd electron
npm start

L'application démarre automatiquement le serveur PTT Live au lancement.

---

📦 Installation

Les dépendances sont déjà installées. Si nécessaire :

cd electron
npm install

---

🎯 Utilisation

1. Dashboard

Stats temps réel :

• Uptime serveur
• Nombre d'utilisateurs connectés
• Groupes actifs
• Total connexions

QR Code :

• Généré automatiquement avec l'IP réseau
• Scanner depuis smartphone pour connexion rapide
• Bouton copier URL

Utilisateurs :

• Liste en temps réel
• Groupe de chaque utilisateur
• Heure de connexion

2. Configuration Audio

Périphériques :

• Sélection input/output depuis dropdown auto-détecté
• Support macOS (CoreAudio), Linux (JACK/PipeWire)
• Appliquer instantanément (bridge audio rechargé)

Paramètres :

• Sample Rate : 44.1 / 48 / 96 kHz
• Bitrate par défaut : 32-320 kbps
• Jitter Buffer : 20-100 ms

3. Gestion Groupes

• Créer : bouton "➕ Nouveau groupe"
• Modifier : depuis la liste (nom, bitrate)
• Supprimer : confirmation requise
• Sauvegardé automatiquement dans config.yaml

4. Monitoring

VU-Mètres (à venir) :

• Niveaux audio par canal (input/output)
• Temps réel via WebSocket
• Détection clipping

5. Logs

• Logs serveur en temps réel
• Filtrage par niveau (error/warn/info/debug)
• Bouton "Effacer"
• Format timestamp + niveau + message

---

🏗️ Architecture Technique

┌─────────────────────────────────────────────────┐
│           ELECTRON APP (Desktop)                │
│                                                 │
│  ┌───────────────────────────────────────────┐ │
│  │        MAIN PROCESS (Node.js)             │ │
│  │                                           │ │
│  │  • spawn server/index.js                 │ │
│  │  • IPC handlers (start/stop/status)      │ │
│  │  • Tray icon (macOS/Linux)               │ │
│  │  • Logs forwarding → Renderer            │ │
│  └───────────────────────────────────────────┘ │
│                    ↕ IPC                       │
│  ┌───────────────────────────────────────────┐ │
│  │      RENDERER PROCESS (Frontend)          │ │
│  │                                           │ │
│  │  • HTML/CSS/JS (pas de framework)        │ │
│  │  • Fetch API REST :3000/admin/*          │ │
│  │  • WebSocket audio levels (prévu)        │ │
│  │  • QR Code (qrcode.js)                   │ │
│  └───────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
                    ↕ HTTP
┌─────────────────────────────────────────────────┐
│         SERVEUR PTT LIVE (spawned)              │
│                                                 │
│  • LiveKit Server (binaire Go)                 │
│  • Audio Bridge Manager                        │
│  • API REST Express :3000                      │
│  • WebSocket Audio Levels                      │
└─────────────────────────────────────────────────┘

---

🔌 API Consommées

L'interface desktop utilise toutes les routes admin existantes :

Endpoint	Méthode	Usage
/admin/stats	GET	Dashboard metrics
/admin/users	GET	Liste utilisateurs
/admin/groups	GET	Liste groupes
/admin/groups	POST	Créer groupe
/admin/groups/:id	PUT	Modifier groupe
/admin/groups/:id	DELETE	Supprimer groupe
/admin/config	GET	Config complète
/admin/config/audio	PUT	Mettre à jour audio
/admin/audio/devices	GET	Énumérer devices
/admin/audio/device	POST	Sélectionner device
/admin/devices/list	GET	Auto-détection (macOS/Linux)
/admin/logs	GET	Logs serveur
/health	GET	Health check

WebSocket (prévu) :

• ws://localhost:3000/audio-levels → VU-mètres temps réel

---

📦 Build pour Distribution

macOS

cd electron
npm run build:mac

Génère :

• dist/mac/PTT Live Server.app
• dist/PTT Live Server-0.3.0.dmg

Linux

cd electron
npm run build:linux

Génère :

• dist/PTT Live Server-0.3.0.deb
• dist/PTT Live Server-0.3.0.AppImage

Tester le build

# macOS
open dist/mac/PTT\ Live\ Server.app

# Linux
./dist/PTT\ Live\ Server-0.3.0.AppImage

---

🎨 Personnalisation

Icônes

Placer les icônes dans electron/assets/ :

electron/assets/
├── icon.icns       # macOS (512x512 minimum)
├── icon.png        # Linux (512x512)
└── tray-icon.png   # Tray 22x22 ou 44x44 (retina)

Générer icônes depuis PNG :

# macOS .icns
iconutil -c icns assets/icon.iconset

# Linux .png
convert icon.png -resize 512x512 assets/icon.png

Thème

Modifier electron/ui/styles.css :

:root {
  --bg-primary: #1a1a1a;
  --accent-primary: #4a9eff;
  /* ... */
}

---

🐛 Debug

DevTools

Ouvrir automatiquement en mode dev :

cd electron
npm run dev

Ou manuellement dans main.js :

mainWindow.webContents.openDevTools();

Logs Console

Main Process :

console.log('[Main]', ...); // Terminal qui a lancé npm start

Renderer Process :

console.log('[Renderer]', ...); // DevTools → Console

Serveur PTT Live :

// Transmis au Renderer via IPC
window.electronAPI.server.onLog((log) => {
  console.log('[Serveur]', log);
});

Erreurs courantes

Port 3000 déjà utilisé :

# Tuer le process
lsof -i :3000
kill -9 <PID>

# OU changer de port
PORT=3001 npm start

Serveur ne démarre pas :

• Vérifier que server/index.js existe
• Vérifier permissions LiveKit binaire
• Voir logs dans DevTools console

QR Code ne s'affiche pas :

• Vérifier que le serveur tourne
• Voir console : "✅ QR Code généré"
• Script CDN chargé ?

---

🚧 TODO / Améliorations

Priorité haute

• WebSocket VU-mètres : implémenter connexion /audio-levels
• Vraies icônes : icns/png pour macOS/Linux
• Tray icon : avec menu contextuel fonctionnel

Priorité moyenne

• Graphiques monitoring : Chart.js pour latence/bande passante
• Export logs : bouton télécharger CSV/JSON
• Matrice routing : interface graphique drag & drop
• Notifications desktop : via Electron Notification API

Priorité basse

• Auth admin : mot de passe pour accès dashboard
• Thème toggle : dark/light mode
• Auto-update : electron-updater pour mises à jour
• I18n : français/anglais

Technique

• Tests : Spectron ou Playwright pour Electron
• CI/CD : GitHub Actions pour builds automatiques
• Signature code : macOS notarization + Linux AppImage signature

---

📝 Notes de Développement

Structure Fichiers

electron/
├── main.js              # Main Process
│                        # - Spawn serveur
│                        # - IPC handlers
│                        # - Window management
│
├── preload.js           # IPC Bridge sécurisé
│                        # - contextBridge
│                        # - Expose electronAPI
│
├── package.json         # Config Electron + electron-builder
│
└── ui/                  # Renderer Process (Frontend)
    ├── index.html       # Structure UI
    ├── styles.css       # Styles (dark theme)
    ├── app.js           # Logic frontend
    └── qrcode.min.js    # QR Code library

Communication IPC

Renderer → Main :

// Depuis ui/app.js
const result = await window.electronAPI.server.start();

Main → Renderer :

// Depuis main.js
mainWindow.webContents.send('server:status', { running: true });

// Écouté dans ui/app.js
window.electronAPI.server.onStatus((data) => {
  console.log('Status:', data);
});

Sécurité

• ✅ contextIsolation: true : isole Node.js du renderer
• ✅ nodeIntegration: false : pas d'accès Node direct
• ✅ preload.js : whitelist API exposées via contextBridge
• ⚠️ CSP manquant : ajouter Content-Security-Policy en prod

---

🤝 Contribution

L'app desktop est modulaire et extensible :

1. Ajouter une vue : créer <div id="view-xxx"> dans index.html
2. Ajouter un handler IPC : ipcMain.handle() dans main.js
3. Exposer au renderer : contextBridge.exposeInMainWorld() dans preload.js
4. Appeler l'API : fetch dans ui/app.js

---

📚 Ressources

• Electron Docs : https://www.electronjs.org/docs
• electron-builder : https://www.electron.build
• LiveKit Server API : https://docs.livekit.io
• QR Code.js : https://github.com/soldair/node-qrcode

---

📄 Licence

Même licence que PTT Live (MIT)

---

Version : 0.3.0 Dernière mise à jour : 2026-06-19