sublogue/AGENT.md

Your subtitles deserve metadata. Sublogue adds it.

Sublogue is a lightweight private 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.

Additionally, Sublogue can clean junk out of your subtitles automatically or on demand.

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
• Automatically strips OCR junk, music-only lines, timecodes, and other subtitle noise for a cleaner, more readable SRT.
• 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

Getting started

All top-level documentation and runtime logs are kept in the repository root:

• AGENT.md for setup and operating notes
• docker-compose.yml for a direct local deployment
• docker-compose.proxy.yml for deployments behind Nginx Proxy Manager
• sublogue.log for runtime logging after the server starts

Quick start with Docker:

docker build -t sublogue:local .
docker run -d \
  --name sublogue \
  -p 5050:5000 \
  -v /path/to/config:/config \
  -v /path/to/media:/media \
  sublogue:local

Installation methods

⚓ Docker Compose

Create `data/` and `media/` folders next to the compose file, then run:

version: "3.9"
services:
  sublogue:
    build:
      context: .
    image: sublogue:local
    container_name: sublogue
    restart: unless-stopped
    environment:
      - TZ=Pacific/Auckland
    volumes:
      - ./data:/config
      - ./media:/media
    ports:
      - "5000:5000"

Start the stack:

docker compose up -d --build

Open http://localhost:5000.

🦎 Komodo

Create a new stack and paste a Komodo template like this:

version: "3.9"
services:
  sublogue:
    build:
      context: .
    image: sublogue:local
    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

Timing And Insertion Logic

Sublogue never shifts existing subtitle timing. It only inserts metadata blocks into safe gaps.

Decision	What Sublogue checks	Outcome
Find insertion gap (start)	Time before the first dialogue subtitle (minus a 500ms safety buffer)	Uses that gap for intro blocks
Find insertion gap (end)	Time after the last dialogue subtitle (plus a 500ms safety buffer)	Uses that gap for outro blocks
Insufficient gap	No space to fit the intro/outro blocks	Skips insertion and reports “Insufficient Gap”
Reading speed	Word count vs a 160 WPM target (min 1.2s, max 6.0s per block)	Splits plot into readable blocks
Existing Sublogue blocks	Looks for {SUBLOGUE} markers or legacy signatures	Removes old blocks before inserting new ones

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 may 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

• 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