6f551ba439
Dockerized media library scanner for NAS drives. Identifies movies and series from filenames, fetches posters via the public IMDB suggestion API (no key required), and exposes a dark-themed web UI with multilingual search support. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
226 lines
7.1 KiB
Markdown
226 lines
7.1 KiB
Markdown
# 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 :
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
git clone https://github.com/votre-repo/mediatracker.git
|
|
cd mediatracker
|
|
```
|
|
|
|
### 2. Configurer l'environnement
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Éditez `.env` et adaptez a minima :
|
|
|
|
```env
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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 :
|
|
|
|
```bash
|
|
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d backend
|
|
```
|
|
|
|
---
|
|
|
|
## Conventions de nommage supportées
|
|
|
|
MediaTracker utilise [parse-torrent-name](https://github.com/platelminto/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 :
|
|
|
|
```bash
|
|
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 :
|
|
|
|
```sql
|
|
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 :
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8080/api/scan/incremental
|
|
```
|
|
|
|
### Réinitialiser complètement la base de données
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
docker compose logs -f backend
|
|
```
|
|
|
|
---
|
|
|
|
## Licence
|
|
|
|
MIT — voir [LICENSE](LICENSE).
|