tmdb integration

Dockers/self-hosted-iptv/README.md

@@ -23,9 +23,20 @@ docker build -t self-hosted-iptv .
 docker run -d --name iptv -p 8080:8080 \
   -v /path/to/movies:/movies:ro \
   -v /path/to/series:/series:ro \
-  -v /path/to/data:/data:ro \
+  -v /path/to/data:/data \
   self-hosted-iptv
 ```
+When using TMDB metadata, mount `/data` read-write (as above) so the app can store and reuse metadata in `/data/tmdb_cache/`. Use `-v /path/to/data:/data:ro` only if you do not use TMDB.
+
+**Optional – EPG metadata (Dutch) from TMDB:**  
+To show series titles, episode names, and descriptions in the TV guide in **Dutch**, set a [TMDB API key](https://www.themoviedb.org/settings/api) (free after sign-up):
+
+- `TMDB_API_KEY` – your TMDB API key (v3).
+
+Series are matched by folder name (e.g. `series/W817` → search "W817"); episode info is matched from filenames like `S01E01`. All metadata is requested in Dutch (`language=nl`).
+
+- **Persistent cache:** Fetched metadata is stored under `/data/tmdb_cache/` (series search, series details, episode, episode credits). When generating the EPG, the app checks this cache first and only calls TMDB for missing entries. Mount `/data` read-write (omit `:ro`) so the cache can be written.
+- **Rate limit:** TMDB allows 40 requests per 10 seconds. The app enforces this limit when calling the API; if the cache is warm, few or no requests are made during EPG generation.
 
 3. In your IPTV client or **Plex DVR**, add:
    - **Playlist URL:** `http://<host>:8080/playlist.m3u`