docs: add English translation of README
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
snoopy
229
README.md
229
README.md
@@ -223,3 +223,232 @@ docker compose logs -f backend
|
||||
## Licence
|
||||
|
||||
MIT — voir [LICENSE](LICENSE).
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
# MediaTracker — English
|
||||
|
||||
Dockerized media library scanner. Scans your NAS shares in read-only mode, automatically identifies movies and TV series from filenames, fetches posters via the public IMDB API, and exposes a web UI to browse your catalogue — including multilingual search.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
- **Automatic scanning**: full scan on first start, then periodic incremental scans (configurable interval)
|
||||
- **Movie/series detection**: parse-torrent-name handles the vast majority of torrent naming conventions
|
||||
- **Automatic posters**: fetched via the public IMDB suggestion API (no API key required)
|
||||
- **Multilingual search**: search in French or English — titles are cross-referenced with IMDB at query time
|
||||
- **Multi-NAS**: any number of sources, all mounted read-only
|
||||
- **Local artwork**: if a `poster.jpg` / `folder.jpg` exists next to the video file, it is used first
|
||||
- **Web interface**: dark theme, poster cards, detail modal, scan panel with history
|
||||
|
||||
---
|
||||
|
||||
## Tech stack
|
||||
|
||||
| Component | Technology |
|
||||
|-------------|-------------------------------------|
|
||||
| Backend | Python 3.12 · FastAPI · SQLAlchemy |
|
||||
| Database | MariaDB 11 |
|
||||
| Scheduler | APScheduler |
|
||||
| Parser | parse-torrent-name (PTN) |
|
||||
| Metadata | IMDB suggestion API (public) |
|
||||
| Frontend | Vanilla HTML/CSS/JS · Nginx |
|
||||
| Containers | Docker Compose v2 |
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Docker** ≥ 24 and **Docker Compose** ≥ v2
|
||||
- **Python 3.x** on the host (for `generate-compose.py`, stdlib only)
|
||||
- NAS shares mounted on the host system (see below)
|
||||
|
||||
---
|
||||
|
||||
## Mounting a NAS share (SMB/CIFS)
|
||||
|
||||
If your NAS is accessible via SMB, install `cifs-utils` and mount the share:
|
||||
|
||||
```bash
|
||||
sudo apt install cifs-utils # Debian/Ubuntu
|
||||
sudo mkdir -p /mnt/nas1
|
||||
|
||||
# Manual mount (testing)
|
||||
sudo mount -t cifs //192.168.1.100/Videos /mnt/nas1 \
|
||||
-o username=YOUR_USER,password=YOUR_PASS,uid=$(id -u),gid=$(id -g),iocharset=utf8
|
||||
|
||||
# Permanent mount via /etc/fstab
|
||||
//192.168.1.100/Videos /mnt/nas1 cifs credentials=/etc/nas-creds,uid=1000,gid=1000,iocharset=utf8,_netdev 0 0
|
||||
```
|
||||
|
||||
`/etc/nas-creds` (permissions `600`):
|
||||
```
|
||||
username=YOUR_USER
|
||||
password=YOUR_PASS
|
||||
```
|
||||
|
||||
> MediaTracker never mounts anything itself and never writes to the NAS.
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
### 1. Clone the repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/your-repo/mediatracker.git
|
||||
cd mediatracker
|
||||
```
|
||||
|
||||
### 2. Configure the environment
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edit `.env` and set at minimum:
|
||||
|
||||
```env
|
||||
DB_ROOT_PASSWORD=a_strong_password
|
||||
DB_PASSWORD=another_strong_password
|
||||
|
||||
NAS_1=Main NAS|/mnt/nas1
|
||||
# NAS_2=4K Movies|/mnt/nas2
|
||||
```
|
||||
|
||||
### 3. Generate the Docker Compose override
|
||||
|
||||
```bash
|
||||
python3 generate-compose.py
|
||||
```
|
||||
|
||||
This script reads `.env`, checks that paths exist, and generates `docker-compose.override.yml` with read-only volumes. Re-run it whenever you change `NAS_*` entries.
|
||||
|
||||
### 4. Start the application
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d --build
|
||||
```
|
||||
|
||||
The interface is available at **http://localhost:8080** (or the port set by `APP_PORT`).
|
||||
|
||||
On first start, a full scan is triggered automatically.
|
||||
|
||||
---
|
||||
|
||||
## Adding or changing a NAS
|
||||
|
||||
1. Edit `.env` (add or update a `NAS_X` entry)
|
||||
2. Regenerate the override: `python3 generate-compose.py`
|
||||
3. Restart the backend:
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d backend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Supported naming conventions
|
||||
|
||||
MediaTracker uses [parse-torrent-name](https://github.com/platelminto/parse-torrent-name) to parse filenames.
|
||||
|
||||
### Movies
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
### TV series
|
||||
|
||||
```
|
||||
Breaking.Bad.S01E01.1080p.mkv
|
||||
Game.of.Thrones.S08E06.The.Iron.Throne.720p.mkv
|
||||
/Stranger Things/Season 2/Stranger.Things.S02E04.mkv
|
||||
/The.Wire/Season 3/S03E01.mkv
|
||||
```
|
||||
|
||||
Directories named `Season X`, `Saison X`, or `SXX` are automatically detected as season indicators.
|
||||
|
||||
---
|
||||
|
||||
## Multilingual search
|
||||
|
||||
Search works in any language without additional configuration.
|
||||
|
||||
**How it works:** when a search query is submitted, it is sent to the IMDB suggestion API (public, multilingual). The returned IMDB IDs are cross-referenced against the `imdb_id` column in the local database. Searching "chevalier noir" (French for "dark knight") will therefore find a film indexed under its English title "The Dark Knight", provided its `imdb_id` is stored in the database.
|
||||
|
||||
`imdb_id` values are populated automatically during the scan (poster-fetching phase).
|
||||
|
||||
---
|
||||
|
||||
## API Reference
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|---------------------------------------|--------------------------------------|
|
||||
| GET | `/api/search?q=…&type=all\|movie\|series` | Search (title + IMDB cross-ref) |
|
||||
| POST | `/api/scan/full` | Trigger a full scan |
|
||||
| POST | `/api/scan/incremental` | Trigger an incremental scan |
|
||||
| GET | `/api/scan/status/{id}` | Scan status |
|
||||
| GET | `/api/scan/history` | Last 20 scans |
|
||||
| GET | `/api/stats` | Global counters |
|
||||
| GET | `/api/nas` | NAS sources and their status |
|
||||
| GET | `/api/health` | Health check |
|
||||
| GET | `/api/local-poster?path=…` | Serve a local poster from the NAS |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### NAS not accessible at startup
|
||||
|
||||
The backend starts even if a NAS is unreachable. Check the logs:
|
||||
|
||||
```bash
|
||||
docker compose logs backend | grep -i nas
|
||||
```
|
||||
|
||||
Make sure the host mount point exists **before** running `generate-compose.py`.
|
||||
|
||||
### Unrecognized files
|
||||
|
||||
Files that PTN cannot parse are stored in the `unmatched_files` table. Query them directly:
|
||||
|
||||
```sql
|
||||
SELECT file_path, reason FROM unmatched_files ORDER BY scanned_at DESC LIMIT 50;
|
||||
```
|
||||
|
||||
Or check the "unmatched" counter in the UI stats panel.
|
||||
|
||||
### Posters missing after scan
|
||||
|
||||
Posters are fetched in parallel after the file walk (10 workers). If the network is slow or IMDB is unavailable, trigger an incremental scan to retry:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/scan/incremental
|
||||
```
|
||||
|
||||
### Full database reset
|
||||
|
||||
```bash
|
||||
docker compose down -v
|
||||
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d --build
|
||||
```
|
||||
|
||||
> All data is deleted. A full scan will start automatically.
|
||||
|
||||
### Stream logs in real time
|
||||
|
||||
```bash
|
||||
docker compose logs -f backend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT — see [LICENSE](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user