Initial release — MediaTracker v1.0
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>
This commit is contained in:
snoopy
225
README.md
Normal file
225
README.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user