# 19_Navidrome

## navidrome-navidrome-1

*🎧 Your Personal Streaming Service*

<table id="bkmrk-imagedeluan%2Fnavidrom"><tbody><tr><th>Image</th><td>`deluan/navidrome:latest`</td></tr><tr><th>Version</th><td>0.61.2</td></tr><tr><th>Etat</th><td><span style="color: #008000;">Up</span></td></tr><tr><th>Compose project</th><td>navidrome</td></tr><tr><th>Reseau</th><td>navidrome\_default</td></tr><tr><th>URL</th><td>[https://navidrome.juxjux.ovh](https://navidrome.juxjux.ovh)</td></tr><tr><th>Source</th><td>[https://github.com/navidrome/navidrome](https://github.com/navidrome/navidrome)</td></tr></tbody></table>

### Ports

<table id="bkmrk-hotecontainerip45334"><thead><tr><th>Hote</th><th>Container</th><th>IP</th></tr></thead><tbody><tr><td>4533</td><td>4533/tcp</td><td>0.0.0.0</td></tr></tbody></table>

### Volumes

<table id="bkmrk-source-%28hote%29destina"><thead><tr><th>Source (hote)</th><th>Destination</th><th>Type</th><th>Mode</th></tr></thead><tbody><tr><td>`/home/debian/music`</td><td>`/music`</td><td>bind</td><td>rw, :shared</td></tr><tr><td>`/home/debian/docker/navidrome/data`</td><td>`/data`</td><td>bind</td><td>rw</td></tr></tbody></table>

---

## Integration Claude Code — MCP

<table id="bkmrk-statut-mcpmcp-actifo"><tbody><tr><th>Statut MCP</th><td><span style="color: #008000;">MCP actif</span></td></tr><tr><th>Outils (prefix)</th><td>`mcp__navidrome__`</td></tr><tr><th>Configuration</th><td>Script Python : C:\\Users\\eliob\\.claude\\mcp\_navidrome.py | Auth : Subsonic API avec hachage MD5 (user + token + sel)</td></tr></tbody></table>

### Outils disponibles

- `ping`
- `get_artists`
- `get_artist`
- `get_albums`
- `get_album`
- `get_song`
- `get_genres`
- `get_random_songs`
- `get_playlists`
- `get_playlist`
- `create_playlist`
- `get_starred`
- `star`
- `unstar`
- `search`
- `get_now_playing`

### Ce que nous pouvons faire ensemble

- Parcourir artistes, albums et pistes de la médiathèque musicale
- Rechercher un titre, artiste ou album
- Voir ce qui est en cours de lecture (now playing)
- Gérer les playlists (création, lecture)
- Étoiler/désigner des favoris
- Générer une sélection aléatoire par genre

---

## Scans automatiques

Trois mécanismes automatiques assurent la fraîcheur de la bibliothèque :

<table id="bkmrk-cronscripttyper%C3%B4le-%2A"><thead><tr><th>Cron</th><th>Script</th><th>Type</th><th>Rôle</th></tr></thead><tbody><tr><td>`*/5 * * * *`</td><td>`/home/debian/monitor-rclone.sh`</td><td>Watchdog</td><td>Détecte FUSE mort → restart service + restart container (recovery auto)</td></tr><tr><td>`30 4 * * *`</td><td>`/home/debian/navidrome_scan.sh`</td><td>Quick scan</td><td>vfs/refresh + scan quotidien (MAJ des titres existants)</td></tr><tr><td>`0 3 * * 1`</td><td>`/home/debian/navidrome_fullscan.sh`</td><td>Full scan</td><td>vfs/refresh + restart container → full scan hebdomadaire (détecte nouveaux albums/artistes)</td></tr></tbody></table>

Log commun : `/var/log/navidrome_scan.log`

### Quick scan vs Full scan

Le **quick scan** (`startScan` via API Subsonic) ne traverse que les dossiers déjà connus de Navidrome — il ne détecte pas les nouveaux artistes ou albums ajoutés sur kDrive. Seul un **full scan** indexe les nouveaux dossiers.

Le full scan est déclenché automatiquement au démarrage du container. C'est pourquoi `navidrome_fullscan.sh` fait un restart container plutôt qu'un simple appel API.

### Auth RC sur kdrive-music.service

Depuis rclone 1.74.3, `vfs/refresh` exige une authentification RC. Le service `kdrive-music.service` a été mis à jour le 2026-06-24 avec `--rc-user=rcadmin --rc-pass=RcMusic2026!`.

Commande de refresh manuel :

```
rclone rc --rc-addr 127.0.0.1:5576 --rc-user=rcadmin --rc-pass=RcMusic2026! vfs/refresh recursive=true
```

---

## REX — 2026-06-24 : FUSE mort récurrent

### Contexte

Le FUSE `/music` est mort en cours de journée. Symptôme Navidrome : `stat /music: transport endpoint is not connected` lors du scan.

### Cause

Le service `kdrive-music.service` peut rester `active (running)` avec un FUSE mort — le process rclone est vivant mais la connexion noyau FUSE est cassée. Systemd ne détecte pas ce cas et ne redémarre pas le service.

### Solution mise en place

Refactorisation de `monitor-rclone.sh` pour utiliser `systemctl restart` (au lieu d'un `rclone mount` direct) et redémarrer les containers Docker après remontage. Le watchdog tourne toutes les 5 minutes — la panne est détectée et corrigée automatiquement sans intervention.

### Procédure manuelle si besoin

```
sudo systemctl restart kdrive-music.service
ls /home/debian/music | head -5
sudo docker restart navidrome-navidrome-1
```

Puis force-fermer Symfonium et relancer — le token de session Navidrome est invalidé après le restart du container.

---

## REX — 2026-06-24 : nouveaux albums non détectés

### Contexte

Les Négresses Vertes (et d'autres albums récemment ajoutés sur kDrive) n'apparaissaient pas dans Navidrome malgré le cron quotidien.

### Cause

Double problème :

1. **Cache VFS 72h** : `--dir-cache-time 72h` sur `kdrive-music.service` — les nouveaux dossiers kDrive ne sont pas visibles dans le mount avant expiration ou `vfs/refresh`.
2. **Quick scan insuffisant** : le scan quotidien (`startScan` API) est un quick scan qui ne traverse que les dossiers déjà connus. Il ne détecte pas de nouveaux artistes.

### Solution immédiate

```
rclone rc --rc-addr 127.0.0.1:5576 --rc-user=rcadmin --rc-pass=RcMusic2026! vfs/refresh recursive=true
sudo docker restart navidrome-navidrome-1
```

Le restart container déclenche un full scan au démarrage (~20 min pour 16 000 titres). Vérifier avec `getScanStatus` (`"scanning":false` = terminé).

### Solution pérenne

Full scan hebdomadaire chaque lundi à 3h UTC (`navidrome_fullscan.sh`) — garantit que tout nouvel album ajouté dans la semaine est indexé au plus tard le lundi matin.

---

## REX — 2026-06-13 : FUSE corrompu / Symfonium inaccessible

### Contexte

Après l'incident sécurité rclone du 2026-06-09 (CVE-2026-41179), le service `kdrive-music.service` a été relancé. Il est resté actif 4 jours sans crash apparent, mais le mount FUSE `/home/debian/music` était silencieusement corrompu.

### Symptômes

- Symfonium (Subsonic) : erreur "trop d'erreurs, arrêt de lecture" sur tous les appareils portables
- Logs Navidrome : `transport endpoint is not connected` sur tous les fichiers audio
- `systemctl status kdrive-music.service` : **active (running)** depuis 3 jours — aucune indication du problème

### Cause

Le process rclone était vivant mais la connexion noyau FUSE était morte. Pas de crash = pas de restart automatique par systemd.

### Procédure de résolution

1. Redémarrer le service rclone : `sudo systemctl restart kdrive-music.service`
2. Vérifier que le mount répond : `ls /home/debian/music | head -5`
3. Redémarrer le container Navidrome — nécessaire même avec `:shared`, car le container garde l'ancienne référence FUSE corrompue
4. Sur les appareils : force-fermer Symfonium et relancer

### Notes

- La propagation `:shared` ne suffit pas à propager un nouveau mount FUSE à un container déjà démarré — le container doit être redémarré.
- **Attention spool /tmp** : un restart du service rclone peut créer un fichier `/tmp/rclone-spool*` de plusieurs Go si des fichiers cachés sont marqués "dirty". Préférer `vfs/refresh` (avec auth RC) au restart quand le FUSE n'est pas corrompu.