Mediatracker/README.md

MediaTracker

Application Dockerisée de recensement de médiathèque. Scanne vos partages NAS en lecture seule, identifie automatiquement films et séries à partir des noms de fichiers, récupère les jaquettes via l'API publique IMDB, et expose une interface web pour rechercher votre catalogue — y compris en plusieurs langues.

---

Fonctionnalités

• Scan automatique : scan complet au premier démarrage, puis scan incrémental périodique (configurable)
• Détection films/séries : parse-torrent-name reconnaît la grande majorité des conventions de nommage torrent
• Jaquettes automatiques : récupérées via l'API de suggestion IMDB publique (sans clé API)
• Recherche multilingue : cherchez en français ou en anglais — les titres sont croisés avec IMDB en temps réel
• Multi-NAS : autant de sources que nécessaire, montées en lecture seule
• Affiches locales : si un poster.jpg / folder.jpg existe à côté du fichier, il est utilisé en priorité
• Interface web : thème sombre, cartes avec jaquette, modal de détail, panneau de scan avec historique

---

Stack technique

Composant	Technologie
Backend	Python 3.12 · FastAPI · SQLAlchemy
Base de données	MariaDB 11
Planificateur	APScheduler
Parser	parse-torrent-name (PTN)
Métadonnées	IMDB suggestion API (public)
Frontend	HTML/CSS/JS vanilla · Nginx
Conteneurs	Docker Compose v2

---

Prérequis

• Docker ≥ 24 et Docker Compose ≥ v2
• Python 3.x sur l'hôte (pour generate-compose.py, stdlib uniquement)
• Vos partages NAS montés sur le système hôte (voir ci-dessous)

---

Monter un partage NAS (SMB/CIFS)

Si votre NAS est accessible en SMB, installez cifs-utils puis montez le partage :

sudo apt install cifs-utils          # Debian/Ubuntu
sudo mkdir -p /mnt/nas1

# Montage manuel (test)
sudo mount -t cifs //192.168.1.100/Videotheque /mnt/nas1 \
  -o username=VOTRE_USER,password=VOTRE_PASS,uid=$(id -u),gid=$(id -g),iocharset=utf8

# Montage permanent via /etc/fstab
//192.168.1.100/Videotheque  /mnt/nas1  cifs  credentials=/etc/nas-creds,uid=1000,gid=1000,iocharset=utf8,_netdev  0  0

/etc/nas-creds (permissions 600) :

username=VOTRE_USER
password=VOTRE_PASS

MediaTracker ne monte rien lui-même et n'écrit jamais sur le NAS.

---

Installation

1. Cloner le dépôt

git clone https://github.com/votre-repo/mediatracker.git
cd mediatracker

2. Configurer l'environnement

cp .env.example .env

Éditez .env et adaptez a minima :

DB_ROOT_PASSWORD=un_mot_de_passe_fort
DB_PASSWORD=un_autre_mot_de_passe

NAS_1=NAS Principal|/mnt/nas1
# NAS_2=Séries|/mnt/nas2

3. Générer le fichier Docker Compose override

python3 generate-compose.py

Ce script lit .env, vérifie que les chemins existent, et génère docker-compose.override.yml avec les volumes en lecture seule. Relancez-le à chaque modification des entrées NAS_*.

4. Lancer l'application

docker compose -f docker-compose.yml -f docker-compose.override.yml up -d --build

L'interface est disponible sur http://localhost:8080 (ou le port défini par APP_PORT).

Au premier démarrage, un scan complet est lancé automatiquement.

---

Ajouter ou modifier un NAS

1. Éditez .env (ajoutez ou modifiez une entrée NAS_X)
2. Régénérez l'override : python3 generate-compose.py
3. Redémarrez le backend :

docker compose -f docker-compose.yml -f docker-compose.override.yml up -d backend

---

Conventions de nommage supportées

MediaTracker utilise parse-torrent-name pour analyser les noms de fichiers.

Films

The.Dark.Knight.2008.1080p.BluRay.x264.mkv
Inception (2010) 4K HDR.mkv
Parasite.2019.FRENCH.1080p.WEB-DL.mp4
Dune Part Two (2024).mkv

Séries

Breaking.Bad.S01E01.1080p.mkv
Game.of.Thrones.S08E06.The.Iron.Throne.720p.mkv
/Stranger Things/Season 2/Stranger.Things.S02E04.mkv
/The.Wire/Saison 3/S03E01.mkv

Les dossiers nommés Season X, Saison X ou SXX sont automatiquement détectés comme indicateurs de saison.

---

Recherche multilingue

La recherche fonctionne en français comme en anglais sans configuration supplémentaire.

Mécanisme : lors d'une recherche, la requête est envoyée à l'API de suggestion IMDB (publique, multilingue). Les identifiants IMDB retournés sont croisés avec la colonne imdb_id de la base locale. Ainsi, chercher « chevalier noir » retrouve un film indexé sous son titre anglais « The Dark Knight » si son imdb_id est présent en base.

Les imdb_id sont peuplés automatiquement lors du scan (phase de récupération des jaquettes).

---

API Reference

Méthode	Endpoint	Description
GET	/api/search?q=…&type=all|movie|series	Recherche (titre + IMDB cross-ref)
POST	/api/scan/full	Déclenche un scan complet
POST	/api/scan/incremental	Déclenche un scan incrémental
GET	/api/scan/status/{id}	Statut d'un scan
GET	/api/scan/history	20 derniers scans
GET	/api/stats	Compteurs globaux
GET	/api/nas	Liste des NAS et leur statut
GET	/api/health	Healthcheck
GET	/api/local-poster?path=…	Sert une jaquette locale depuis le NAS

---

Troubleshooting

NAS inaccessible au démarrage

Le backend démarre même si un NAS est inaccessible. Vérifiez les logs :

docker compose logs backend | grep -i nas

Assurez-vous que le point de montage hôte existe avant de lancer generate-compose.py.

Fichiers non reconnus

Les fichiers que PTN ne parvient pas à analyser sont enregistrés dans la table unmatched_files. Consultez-les directement en base :

SELECT file_path, reason FROM unmatched_files ORDER BY scanned_at DESC LIMIT 50;

Ou via les stats de l'interface (compteur « non reconnus »).

Jaquettes manquantes après le scan

Les jaquettes sont récupérées en parallèle après le scan de fichiers (10 workers). Si le réseau est lent ou IMDB indisponible, relancez un scan incrémental :

curl -X POST http://localhost:8080/api/scan/incremental

Réinitialiser complètement la base de données

docker compose down -v
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d --build

Toutes les données sont supprimées. Un scan complet repart automatiquement.

Voir les logs en temps réel

docker compose logs -f backend

---

Licence

MIT — voir LICENSE.