Your subtitles deserve metadata. Sublogue adds it.
Sublogue is a lightweight open-source tool for enriching SRT files. Pull metadata from OMDb, TMDB, or TVMaze and automatically append plot summaries, runtimes, directors, and cast details to the start or end of your subtitles.
Why? Because if the cast list and IMDb/RT rating show up in the first minute, my wife asks fewer questions and we actually get to watch the movie.
## Features
- Insert plot summaries into existing .srt files without shifting timings
- Fetch metadata (plot, runtime, director, cast, IMDb/RT ratings) using OMDb, TMDb, TVMaze and Wikipedia - add these integrations under Settings before scanning
- Preserve original dialogue and timing with safe insertion logic while cleaning watermarks (YTS, OpenSubtitles, etc.)
- Automation rules can run cleanup-only mode on schedules, or combined cleanup + metadata enrichment
- Folder Rules to have seperate logic for different folders (for example TV shows could have runtime but not actors, etc)
- Clean, fast web UI for scanning and batch processing built with Svelte (frontend) + Python/Flask (server)
- Three themes included: OLED, Ocean, and Dracula White
## Screenshots
## Getting started
To get started installing Sublogue, expand on your posion below. Personally, I recommend **Komodo**. It's great.
**Quick Start with Docker:**
```sh
docker run -d \
--name sublogue \
-p 5050:5000 \
-v /path/to/config:/config \
-v /path/to/media:/media \
ghcr.io/ponzischeme89/sublogue:latest
```
**Installation Methods (Expand sections to see details)**
⚓ Docker Compose
Create `data/` and `media/` folders next to the compose file, then run:
```yaml
version: "3.9"
services:
sublogue:
image: ghcr.io/ponzischeme89/sublogue:latest
container_name: sublogue
restart: unless-stopped
environment:
- TZ=Pacific/Auckland
volumes:
- ./data:/config
- ./media:/media
ports:
- "5000:5000"
```
Start the stack:
```bash
docker compose up -d
```
Open `http://localhost:5000`.
🧡 Unraid
Use the included template at `unraid-sublogue.xml`.
- `/mnt/user/appdata/sublogue` -> `/config`
- `/mnt/user/appdata/sublogue/media` -> `/media`
Start the container and open `http://:5000`.
🦎 Komodo
Create a new stack and paste a Komodo template like this:
```yaml
version: "3.9"
services:
sublogue:
image: ghcr.io/ponzischeme89/sublogue:latest
container_name: sublogue
ports:
- "5000:5000"
environment:
- TZ=Etc/UTC
- PUID=1000
- PGID=1000
volumes:
- /volume1/Docker/sublogue/data:/config
- /volume1/Media:/media
restart: unless-stopped
networks:
- npm_network
networks:
npm_network:
external: true
```
## Integrations
| Provider | Signup / API key | Rate limits (see provider for current limits) | Notes |
| --- | --- | --- | --- |
| OMDb | https://www.omdbapi.com/apikey.aspx | Free tier has a daily cap 1000 | Requires API key |
| TMDb | https://www.themoviedb.org/settings/api | Per-second rate limit | Requires API key |
| TVmaze | https://www.tvmaze.com/api | Polite usage limits | No API key required |
| Wikipedia | https://www.mediawiki.org/wiki/API:Main_page | No hard limits, be polite | No API key required; strict title matching |
## Limitations
- API rate limits: OMDb is tight, TMDb is better, TVMaze is polite-but-limited. Heavy scans may hit caps.
- Metadata gaps: If providers don’t have it, Sublogue won’t either. Ratings/plots can be missing or stale.
- Localisation: Only TMDb supports proper language/region data. OMDb/TVMaze are mostly English-only.
- Long plots: Big summaries go in as-is. Your TV may split them across multiple screens.
- Formats: Only .srt is supported. No WebVTT, ASS/SSA, or embedded subs yet.
- Duplicate inserts: Reprocessing the same file will stack multiple plot blocks.
- Offline use: Requires internet for metadata lookups — no offline mode.
- File access: Read-only or locked files cannot be processed.
## Roadmap
- [x] TVMaze integration
- [ ] More UI themes (OLED variants, Ocean+, and high-contrast)
- [ ] Poster + backdrop previews in results
- [ ] Smart duplicate-detection (don’t re-insert plot blocks)
- [ ] Automatic rate-limit backoff + retry logic
- [ ] Optional “short plot mode” for long summaries
- [ ] Expanded localisation using TMDb (title, plot, cast where available)
- [ ] Multi-format subtitle support (WebVTT, ASS/SSA)
- [ ] Offline caching of recent metadata lookups
- [ ] Per-scan analytics: success/fail counts, rate-limit warnings
- [ ] CLI mode for batch operations
## Support
- Help spread the word about Sublogue by telling your friends about this repo
- Give the repo a star (This really helps)
- Check out my other project, which is an open source renamer tool (with a very poor naming choice, but i'll likely change this in future)
