Subtitles

Dubby supports external subtitle files, embedded subtitle tracks, and automatic downloads from OpenSubtitles.

Subtitle sources

External files

Place subtitle files next to your video files with a language code suffix:

Movie Name (2024).mkv
Movie Name (2024).en.srt          # English subtitles
Movie Name (2024).en.forced.srt   # Forced subtitles (foreign dialog only)
Movie Name (2024).es.srt          # Spanish subtitles

External subtitles are auto-detected during library scans. Supported formats: .srt, .ass, .ssa, .vtt

Embedded tracks

Subtitles embedded inside the video container (MKV, MP4) are automatically extracted during the probe step. The server extracts each track as WebVTT for client-side rendering.

OpenSubtitles

When configured, Dubby searches OpenSubtitles for missing subtitle tracks during the ingest pipeline’s enhance stage. Downloaded subtitles are saved alongside your media files.

OpenSubtitles supports two types of API keys:

• Consumer API keys (free) — Short alphanumeric strings. Allow 5 subtitle downloads per IP per 24 hours without an account. To increase limits, add your OpenSubtitles username and password during setup — Dubby will authenticate on your behalf.
• VIP/Paid API keys — JWT tokens (start with eyJ...). Include higher download limits and use the dedicated VIP server (vip-api.opensubtitles.com). No username/password needed.

Dubby automatically detects which type of key you’ve entered and configures the appropriate server URL and authentication method.

Note

Subtitle downloads require write access to your media directories. The default Docker volume mounts are read-write, so this works out of the box.

Tip

If you have an OpenSubtitles VIP subscription, use your paid API key for the best experience — higher download limits and a dedicated server with lower latency.

Supported formats

Format	Type	How it’s rendered
SRT	Text	Converted to WebVTT, rendered client-side
WebVTT	Text	Rendered client-side natively
ASS / SSA (simple)	Text	Converted to WebVTT (styling simplified)
ASS / SSA (complex)	Text	Burned into video stream
PGS / SUP (Blu-ray)	Image-based	Burned into video stream
VOBSUB (DVD)	Image-based	Burned into video stream

Text vs image-based subtitles

Text-based subtitles (SRT, WebVTT, simple ASS) are extracted and delivered as a separate WebVTT file. The client renders them as an overlay — no transcoding required.

Image-based subtitles (PGS, VOBSUB) and complex ASS/SSA must be “burned” into the video frame by the server. This triggers a full video transcode, which significantly increases server CPU/GPU usage.

Tip

If you have PGS subtitles and want to avoid transcoding, consider finding SRT equivalents. Tools like SubtitleEdit can OCR PGS subtitles into SRT format.

Subtitle selection

When starting playback, subtitle track selection follows this priority:

1. Explicit selection — Track chosen by the user in the player UI
2. Session memory — Last-used track within the current show (persists across episodes)
3. User preference — Global subtitle language preference set in profile settings
4. None — Subtitles are off by default

Forced subtitles

Forced subtitles contain only foreign-language dialog (e.g., alien speech in a primarily English film). They’re identified by:

• Filename suffix: .forced.srt
• Container flag: the “forced” flag on an embedded track

Forced subtitle tracks are treated separately from regular subtitle tracks in the player UI.

Subtitle rendering

On web clients, subtitles are rendered using a custom overlay positioned on top of the video. This ensures consistent appearance across browsers and avoids CSS conflicts with the player UI.

On TV clients (Apple TV, Android TV), subtitles are rendered by the native video player (AVPlayer or ExoPlayer).