🎧 Guide Utilisateur — Webradio Manager v2.14.0

Version : 2.14.0 | Langue : Français | Plateformes : Windows, Linux, Raspberry Pi

Table des matières

1. Premiers pas
2. Interface Studio DJ
3. Connexion et sécurité
4. Le Deck (lecteur)
5. Volume et VU-mètres
6. Playlist
7. Playlists nommées
8. Enchaînement automatique
9. Bibliothèque
10. Import multi-plateforme
11. Planification (Scheduler)
12. Spots Automatisés
13. Recherche Multi-plateformes
14. Streaming Icecast
15. Paramètres audio
16. Intégrations
17. Paramètres
18. Monitoring
19. Synchronisation réseau (WebDAV / FTP / Samba)
20. Raccourcis Clavier
21. Dépannage
22. Recherche en ligne et webradios
23. Favoris, Récents et Top
24. Menu contextuel (clic droit)
25. Radios personnalisées
26. Programmer une radio
27. Normalisation du volume
28. Sauvegardes et restauration
29. File d'attente de téléchargement
30. Déploiement Docker

1. Premiers pas

Prérequis

• Python 3.11+
• FFmpeg (pour le streaming)
• Icecast (installé automatiquement ou manuellement)

Démarrage

# Linux / Raspberry Pi
cd webradio-manager
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env    # éditer avec vos secrets
python3 start.py

# Windows
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
python start.py

Variantes :

python start.py --port 8080 --debug     # mode debug + port custom
gunicorn --bind 0.0.0.0:5000 wsgi:app  # production Gunicorn
docker compose up --build -d             # Docker

Ouvrez votre navigateur à : http://localhost:5000

Premier démarrage

Au premier lancement, l'application : 1. Crée la base de données SQLite (webradio.db) 2. Initialise le deck 3. Crée un compte admin par défaut : - Utilisateur : admin - Mot de passe : aléatoire, affiché une seule fois dans les logs (ligne « identifiants initiaux »), ou la valeur de ADMIN_PASSWORD si elle est définie - ⚠️ Changez ce mot de passe après la première connexion

Configuration initiale

1. Paramètres > Bibliothèque : configurez le dossier de musique
2. Paramètres > Streaming : installez/démarrez Icecast
3. Paramètres > Connexions : configurez Spotify/Deezer (optionnel)
4. Lancez le scan de la bibliothèque

2. Interface Studio DJ

Le Studio DJ est l'interface principale : un deck (lecteur), ses VU-mètres, le panneau Favoris / Récents / Top et, dessous, trois colonnes — Playlist, Bibliothèque et Recherche en ligne.

Navigation

• Sidebar gauche : navigation entre les vues (Dashboard, Studio, Bibliothèque, Playlist, Planification, Spots, Paramètres)
• Barre d'outils : streaming, notifications
• Footer : état du stream, nombre de pistes

Vues principales

3. Connexion et sécurité

Connexion

1. À l'ouverture, un formulaire de connexion s'affiche
2. Entrez votre identifiant et mot de passe
3. Un CAPTCHA peut apparaître si la protection est activée

Rôles utilisateur

Sessions multi-utilisateurs

Chaque compte utilisateur dispose de sa propre session de travail : - Deck : l'état du deck est propre à chaque utilisateur connecté - Playlists : chaque utilisateur a ses playlists (les playlists créées avant le système de sessions restent visibles) - Planification (scheduler) et spots : propres à chaque utilisateur - Préférences (thème, langue, configuration) : sauvegardées par utilisateur - Bibliothèque musicale : partagée entre tous les utilisateurs

Concrètement : un DJ et un admin peuvent travailler en parallèle, chacun avec ses decks, sa playlist et ses paramètres, sans interférer avec l'autre.

Changement de mot de passe

1. Allez dans Paramètres > Compte (si disponible)
2. Ou demandez une réinitialisation via l'admin

Protection anti-brute-force

• Maximum 5 tentatives de connexion par minute
• Blocage temporaire de 5 minutes après échecs
• Journal d'audit des connexions (admin)

4. Le Deck (lecteur)

Le studio n'a qu'un seul deck (Deck A) : le second deck n'existe plus.

Contrôles de base

Égaliseur

Un menu de presets (Flat, Rock, Pop, Vocal, Bass Boost, Électro) et trois curseurs verticaux High / Mid / Low. Toucher un curseur passe le preset sur « Personnalisé ».

Charger / jouer une piste

Titre en cours d'une webradio

Quand une webradio joue, le deck affiche « ♪ Artiste — Titre » (métadonnées ICY Icecast/Shoutcast, rafraîchies toutes les 10 s). Certaines stations n'en publient pas : seul leur nom s'affiche.

Indicateur d'état du flux

Sous le titre : « Résolution du flux… » (YouTube peut prendre plusieurs secondes), « Mise en mémoire tampon… » ou « Erreur de lecture du flux ».

Point Cue et boucle

• CUE : positionnez-vous sur la timeline puis cliquez CUE ; la touche V saute au point enregistré
• LOOP : active une zone de boucle ; désactivée, la lecture continue après la fin de boucle

5. Volume et VU-mètres

Le Master Volume règle la sortie globale (0 à 100 %). Deux VU-mètres affichent le niveau du deck (A) et de la sortie (M). Il n'y a plus de crossfader ni de pitch.

6. Playlist

Gestion

• Ajouter : clic droit sur une piste > « Ajouter à la playlist »
• Supprimer : bouton 🗑 ou suppression multiple avec checkboxes
• Réordonner : glisser-déposer ou boutons ⬆ ⬇

Vue complète

La vue Playlist dédiée permet de consulter et gérer toute la file d'attente.

Prochaine piste

Le bouton « Next » affiche la prochaine piste de la file d'attente.

7. Playlists nommées

Les playlists nommées permettent d'organiser vos titres en collections persistantes.

Créer une playlist

1. Cliquez sur Nouvelle playlist dans la vue Playlist
2. Donnez un nom et une description
3. Ajoutez des pistes depuis la bibliothèque

Gestion

• Renommer : clic droit > « Renommer »
• Supprimer : clic droit > « Supprimer »
• Exporter : export au format M3U

Importer depuis des plateformes

Vous pouvez créer une playlist locale à partir de playlists importées (Spotify, Deezer, YouTube) via l'onglet Import.

8. Enchaînement automatique

Quand une piste se termine, le deck charge et joue automatiquement la suivante de la playlist, dans l'ordre courant (celui que vous voyez, y compris après un glisser-déposer ou un « jouer ensuite »). Sur une playlist d'un seul titre, le deck s'arrête. Le contrôle manuel reste possible à tout moment.

9. Bibliothèque

Scan

• Cliquez sur Scanner pour analyser le dossier configuré
• Les fichiers MP3, FLAC, OGG, WAV, M4A sont supportés
• Le scan est incrémentaire : les pistes existantes sont mises à jour

Recherche et tri

• Barre de recherche avec filtrage en temps réel
• Tri par colonne (titre, artiste, album, durée, genre)
• Filtres par genre et source

Vérification d'intégrité

Cliquez sur Vérifier pour lister les pistes dont le fichier est manquant. - Modale avec checkboxes pour sélectionner les pistes à supprimer - Suppression en masse avec le bouton 🗑 Supprimer sélection

Édition des métadonnées

Cliquez sur 🖊 Modifier (dans la bibliothèque ou la modale infos piste) pour modifier : - Titre, artiste, album, genre, BPM, année, note

Définir la pochette d'une piste

Dans le modal Modifier la piste, section Pochette : - 📤 Upload — sélectionnez un fichier image local (JPG, PNG, WebP, GIF) pour l'envoyer directement - 🌐 Charger — saisissez l'URL d'une image et cliquez pour la télécharger

La pochette est enregistrée dans le dossier .covers (persistant) et remplace l'ancienne.

Enrichissement MusicBrainz

Cliquez sur 🔍 Enrichir MB dans la modale infos piste pour récupérer automatiquement : - Pochette d'album (Cover Art Archive) - Année de sortie - Métadonnées supplémentaires (tags, durée, etc.)

Enrichissement multi-sources

6 sources configurables : - MusicBrainz — Identification et métadonnées - AcoustID — Identification par empreinte audio - Discogs — Base de données musicale - Last.fm — Tags et popularity - Genius — Paroles et annotations - Wikidata — Données structurées

Lecture depuis la bibliothèque

Cliquez sur ▶ à côté d'une piste pour l'écouter directement : - Sélectionnez la sortie audio dans le menu déroulant - Arrêtez la lecture avec le bouton ⏹

Recherche YouTube (pistes sans fichier)

Si une piste n'a pas de fichier audio (import Deezer/Spotify), cliquez sur ▶️ Chercher sur YouTube pour basculer vers la recherche YouTube avec le titre pré-rempli.

10. Import multi-plateforme

L'onglet Import permet d'importer des playlists depuis plusieurs sources.

Spotify

1. Allez dans Paramètres > Connexions pour configurer l'OAuth Spotify
2. Cliquez sur Se connecter à Spotify
3. Autorisez l'application
4. Les playlists apparaissent dans l'onglet Import

Deezer

1. Ouvrez Deezer.com dans votre navigateur
2. Ouvrez les outils développeur (F12) > Stockage > Cookies
3. Copiez la valeur du cookie arl (192 caractères hexadécimaux)
4. Collez-la dans Paramètres > Connexions > Jeton ARL
5. Cliquez Valider le jeton ARL

YouTube

1. Cliquez sur l'onglet YouTube dans l'import
2. Recherchez une vidéo par mot-clé
3. Importez la piste (yt-dlp télécharge et encode en MP3)

Apple Music

1. Connectez votre compte Apple Music via l'authentification OAuth
2. Les playlists apparaissent dans l'onglet Import

SoundCloud

1. Connectez votre compte SoundCloud via l'authentification OAuth
2. Les playlists apparaissent dans l'onglet Import

Onglet « Toutes »

L'onglet Toutes regroupe les playlists de tous les services connectés (Spotify, Deezer, YouTube, Apple Music, SoundCloud) avec des badges indiquant la source. Vous pouvez créer une playlist locale à partir de la sélection.

11. Planification (Scheduler)

Créer un événement

1. Allez dans la vue Planification
2. Cliquez sur Ajouter un événement
3. Configurez : - Nom : description de l'événement - Date/heure : moment de déclenchement - Type : piste, radio (flux en direct) ou spot (annonce) - Récurrence : fréquence de répétition - Priorité : ordre d'exécution si conflit

Types de récurrence

Gestion

• Activer/Désactiver : interrupteur à côté de chaque événement
• Modifier : clic sur l'événement dans le calendrier
• Supprimer : bouton 🗑

12. Spots Automatisés

Types

Générer un spot

1. Allez dans la vue Spots
2. Sélectionnez le type de spot
3. Remplissez les champs (texte, ville, etc.)
4. Cliquez sur Générer
5. Le spot audio est créé et prêt à être planifié

Spot météo

• Utilise l'API Open-Meteo (gratuit, pas de clé API requise)
• Données : température, conditions, vent
• Langue : français

Spot « Next Up »

Annonce automatique du titre suivant avec TTS.

Gestion des spots

• Liste : tous les spots générés avec filtre par type
• Détails : informations complètes d'un spot
• Suppression : individuelle ou en masse
• Planification : associez un spot à un événement schedulé

13. Recherche Multi-plateformes

Recherchez simultanément dans :

Utilisation

1. Cliquez sur l'icône 🔍 dans la barre d'outils
2. Entrez votre recherche
3. Les résultats s'affichent par source
4. Cliquez sur un résultat pour l'ajouter à la playlist ou à la bibliothèque

Via API

curl "http://localhost:5000/api/v1/search?q=jazz&source=all&limit=10"

14. Streaming Icecast

Installation automatique

1. Allez dans Paramètres > Streaming
2. Vignette Icecast avec statut : ✓ En marche / ⚠ Arrêté / ✗ Non installé
3. Cliquez sur Installation automatique pour installer Icecast
4. Utilisez Démarrer / Arrêter pour contrôler le serveur

Méthodes d'installation automatique :

Linux manuel : sudo apt update && sudo apt install -y icecast2

La configuration (icecast.xml) est générée automatiquement avec le port, le mot de passe source et les points de montage des Paramètres.

Protocoles supportés

URL d'écoute

Les auditeurs se connectent à :

http://<votre-serveur>:8000/stream.mp3

Démarrer la diffusion

1. Cliquez sur Démarrer streaming dans le dashboard
2. Chargez une piste sur un deck et cliquez Play
3. L'audio est diffusé vers Icecast

Enregistrement

Vous pouvez enregistrer le flux en cours : 1. Cliquez sur Démarrer l'enregistrement dans les paramètres Icecast 2. Le fichier est sauvegardé dans le dossier configuré 3. Cliquez sur Arrêter l'enregistrement pour finaliser

HLS (HTTP Live Streaming)

Le streaming HLS est disponible pour les auditeurs qui ne supportent pas le MP3 direct :

http://<votre-serveur>:5000/api/v1/hls/radio.m3u8

15. Paramètres audio

Onglet Audio (Paramètres)

• Sortie decks (A/B) : périphérique principal pour la lecture des decks
• Sortie pré-écoute : périphérique pour tester des pistes
• Entrée micro : microphone pour enregistrement (si applicable)

Fonctionnement

1. La première fois, une demande d'accès au microphone peut apparaître (nécessaire pour détecter les périphériques)
2. Cliquez sur un sélecteur pour voir la liste des périphériques disponibles
3. Les choix sont sauvegardés dans le navigateur (localStorage)

Bibliothèque

Le lecteur intégré dans la bibliothèque a son propre sélecteur de sortie audio, indépendant des decks.

Visualiseur audio

Le visualiseur FFT affiche le spectre audio en temps réel avec : - Mode fréquence (barres) - Mode forme d'onde (canva) - VU-mètres pour chaque deck

16. Intégrations

Spotify

1. Créez une application sur https://developer.spotify.com
2. Entrez Client ID et Client Secret dans Paramètres > Connexions
3. Cliquez Se connecter à Spotify (OAuth)
4. Fonctionnalités : recherche, playlists, player, recommandations

Deezer

1. Connectez-vous à Deezer.com
2. Extrayez le cookie arl depuis les outils développeur
3. Collez-le dans Paramètres > Connexions
4. Cliquez Valider le jeton ARL
5. Fonctionnalités : recherche, playlists, import

YouTube

Aucune configuration nécessaire — l'API recherche directement via yt-dlp. Fonctionnalités : recherche, import de vidéos et playlists.

Apple Music

1. Configurez les identifiants Apple Music dans Paramètres > Connexions
2. Autorisez via OAuth
3. Fonctionnalités : recherche, playlists, import

SoundCloud

1. Configurez les identifiants SoundCloud dans Paramètres > Connexions
2. Autorisez via OAuth
3. Fonctionnalités : recherche, playlists, import

Last.fm (Scrobbler)

Configurez les clés API dans le fichier .env :

LASTFM_API_KEY=votre-cle
LASTFM_API_SECRET=votre-secret
LASTFM_SESSION_KEY=votre-session
LASTFM_USERNAME=votre-username
LASTFM_SCROBBLE_ENABLED=true

Fonctionnalités : scrobble automatique, historique, enrichissement métadonnées.

MusicBrainz

L'enrichissement automatique est activé par défaut (désactivable dans Paramètres > MusicBrainz). Utilise un header User-Agent avec email de contact (obligatoire pour MusicBrainz).

Open-Meteo (Météo)

API gratuite pour les spots météo. Aucune clé API requise.

17. Paramètres

Onglets disponibles

Configuration avancée

Les paramètres sont stockés en base de données (table settings) et accessibles via l'API POST /api/v1/settings.

Les paramètres sensibles (clés API, tokens) sont chiffrés en base via services/crypto_service.py.

18. Monitoring

Tableau de bord

L'onglet Monitoring (accessible aux admins) affiche : - Uptime du serveur - Utilisation CPU/RAM - État de la base de données - Clients WebSocket connectés - Statut des flux streaming

Métriques Prometheus

Endpoint : GET /api/v1/metrics (format Prometheus)

Health check

curl http://localhost:5000/api/v1/health
# {"status": "ok", "service": "webradio-manager"}

curl http://localhost:5000/api/v1/health/detailed
# {"uptime": "...", "memory": {...}, "db": {...}, "websocket": {...}}

19. Synchronisation réseau (WebDAV / FTP / Samba)

La bibliothèque locale peut être poussée vers un serveur distant depuis la vue Bibliothèque (menu ☁️ Sync).

Vérification de la configuration

Dans Paramètres > Bibliothèque, des boutons de test par protocole permettent de vérifier la connexion avant de synchroniser : - ☁️ Tester WebDAV — vérifie l'URL, l'authentification et l'accès au dossier distant - 📡 Tester FTP/SFTP — vérifie le login et l'accès au dossier distant - 🖥️ Tester Samba — vérifie le partage et le dossier distant

Le résultat s'affiche en vert (✓) ou rouge (✗) juste à côté des boutons, avec un message explicite.

WebDAV (NAS Synology, Nextcloud, ownCloud)

1. Allez dans Paramètres > Bibliothèque
2. Entrez l'URL WebDAV (ex: http://192.168.0.10:5005)
3. Entrez le Dossier distant (sous-dossier du NAS, ex: /music) — vide = racine de l'URL
4. Entrez les identifiants (utilisateur + mot de passe)
5. Cliquez ☁️ Tester WebDAV pour valider, puis dans la Bibliothèque ☁️ Sync > WebDAV

Astuce Synology : l'utilisateur doit avoir l'application WebDAV Server activée dans DSM.

FTP / SFTP (NAS, VPS)

1. Paramètres > Bibliothèque : serveur, port (21 FTP / 22 SFTP), protocole, identifiants, dossier distant
2. Cliquez 📡 Tester FTP/SFTP pour valider, puis dans la Bibliothèque : ☁️ Sync > FTP / SFTP

Samba / SMB (partage Windows, NAS Synology)

1. Paramètres > Bibliothèque : serveur, partage (ex: music sans slash), identifiants, dossier distant
2. Cliquez 🖥️ Tester Samba pour valider, puis dans la Bibliothèque : ☁️ Sync > Samba (SMB)

Les fichiers audio sont uploadés dans le dossier distant (sous-dossiers recréés), les fichiers déjà présents sont ignorés.

20. Raccourcis Clavier

21. Dépannage

Le stream ne démarre pas

1. Vérifiez FFmpeg : ffmpeg -version
2. Vérifiez Icecast dans Paramètres > Streaming
3. Vérifiez le port Icecast (défaut : 8000)
4. Consultez les logs serveur

Les spots TTS ne fonctionnent pas

1. Vérifiez la connexion Internet (gTTS nécessite Google)
2. Vérifiez les paramètres TTS dans Paramètres
3. Vérifiez le moteur sélectionné (gTTS ou espeak)

La bibliothèque est vide

1. Configurez le dossier dans Paramètres > Bibliothèque
2. Cliquez sur Scanner
3. Vérifiez que les fichiers sont au format supporté (MP3, FLAC, OGG, WAV, M4A)

Périphériques audio non détectés

1. Utilisez HTTPS ou localhost (pas d'IP en HTTP)
2. Cliquez sur le sélecteur pour déclencher la permission
3. Vérifiez les permissions du navigateur

Fenêtres CMD visibles (Windows)

• Redémarrez le serveur après une mise à jour
• Le mode production masque automatiquement les fenêtres

Routes 404

• Redémarrez le serveur Flask (python start.py)
• Vérifiez que tous les blueprints sont chargés

L'application ne démarre pas

Windows :

pip install -r requirements.txt
:: Vérifier que le port 5000 n'est pas utilisé
netstat -ano | findstr :5000
python start.py --debug

Linux :

ss -tlnp | grep 5000
pip install -r requirements.txt --force-reinstall
python3 start.py --debug

Raspberry Pi — Pas de son

sudo apt install -y pulseaudio
pactl info
pactl list sinks

Erreurs d'authentification

• Vérifiez que le token JWT n'est pas expiré
• Utilisez le endpoint /auth/refresh pour rafraîchir
• Vérifiez les rôles : admin/dj/viewer

WebSocket ne se connecte pas

1. Vérifiez que SocketIO est actif côté serveur
2. Vérifiez les paramètres CORS
3. Testez : curl http://localhost:5000/api/v1/ws/health

Enrichissement MusicBrainz échoue

1. MusicBrainz requiert un header User-Agent avec email
2. Vérifiez la connexion Internet
3. Le rate limit est de 1 requête/seconde

Deezer GATEWAY_ERROR

L'API GW de Deezer est instable. Le fallback passe par du scraping HTML. Réessayez quelques instants plus tard.

Dernière mise à jour : 2026-08-10 Version : 2.8.0 Mainteneur : Rom (Rom08000)

22. Recherche en ligne et webradios

Le panneau Recherche en ligne (tableau de bord, à droite de la Bibliothèque) ajoute des titres à la playlist sans les télécharger : la lecture est résolue à la volée.

Les logos des stations s'affichent quand ils existent. Glisser-déposer ou double-clic ajoute à la playlist. Spotify, Deezer et Apple Music ne figurent plus ici : leurs API publiques ne donnent qu'un extrait de 30 s.

Une piste « en ligne » peut être rendue locale par clic droit > Télécharger (YouTube uniquement ; un flux radio ne se télécharge pas). Une vidéo déjà importée n'est jamais retéléchargée (détection de doublon).

23. Favoris, Récents et Top

Le panneau en haut à droite du tableau de bord a trois onglets :

• ★ Favoris : clic droit sur une piste (Playlist, Bibliothèque, Recherche en ligne) > Ajouter aux favoris / Retirer des favoris
• 🕘 Récents : dernières pistes lues, dont les radios (reprise en un double-clic)
• 🔥 Top : les plus jouées sur 7 jours

Un champ de recherche filtre la liste ; ＋ Tout ajoute tous les titres affichés à la playlist. Glisser-déposer ou double-clic ajoute une piste à la playlist.

24. Menu contextuel (clic droit)

Sur une piste de la Playlist, de la Bibliothèque ou de la Recherche en ligne :

25. Radios personnalisées

Paramètres > Radios :

• Ajouter une radio : nom, URL du flux, logo (optionnel)
• Importer un CSV : colonnes name, url, logo (séparateur , ou ;) ; les URL déjà présentes sont ignorées
• Exporter en CSV, modifier (✎) ou supprimer (✕)

Elles apparaissent en tête des résultats Webradio / Radio FR et sous ⭐ Mes radios.

26. Programmer une radio

Planification > Ajouter un événement > Type « Diffuser une radio (flux en direct) » :

1. Choisissez une radio (radios perso ou radios en favoris)
2. Réglez la date/heure de début et l'heure de fin
3. Choisissez une récurrence (ex. Du lundi au vendredi)

À l'heure dite, le deck lance la radio ; à l'heure de fin il s'arrête et reprend la piste précédente. L'onglet du navigateur doit être ouvert (c'est lui qui joue le son).

27. Normalisation du volume

Les pistes locales sont mesurées (EBU R128, cible −16 LUFS) et un gain de −12 à +6 dB est appliqué pour que toutes sonnent au même niveau. La mesure se fait à la première lecture ; Paramètres > Général propose l'interrupteur Normaliser le volume et Analyser toute la bibliothèque. Les flux radio et pistes en ligne ne sont pas modifiés.

28. Sauvegardes et restauration

Paramètres > Administration (SQLite) :

• Une sauvegarde automatique est faite chaque jour (7 conservées) ; Sauvegarder maintenant en crée une à la demande
• ⬇ télécharge une sauvegarde
• ↺ Restaurer remplace la base par la sauvegarde choisie, après une sauvegarde de sécurité (webradio_prerestore_*) ; vous devrez peut-être vous reconnecter

Avec PostgreSQL, utilisez pg_dump.

29. File d'attente de téléchargement

La vue File d'attente liste les imports YouTube : compteur fait/total par tâche et flèche ▶ pour déplier le statut de chaque piste (✓ terminée, ✕ erreur, ⏭ déjà présente, • en attente). Les tâches s'exécutent l'une après l'autre.

30. Déploiement Docker

docker compose up -d --build
docker compose logs webradio | grep "identifiants initiaux"   # mot de passe admin

Interface : http://localhost:5000 — flux Icecast : http://localhost:8000. Un volume unique (/app/data) contient tout l'état ; la musique se monte sur /music (variable MUSIC_DIR). Détails dans le README.md.