Subtitles
Odeion can serve subtitles from two sources: streams embedded in the media file, and external files downloaded from subtitle providers.
Embedded Subtitles
Section titled “Embedded Subtitles”During the media extract processing stage, Odeion examines each media file for embedded subtitle streams. Text-based subtitle formats are automatically extracted to individual SRT files so they can be served directly to players without transcoding.
Supported text formats that are extracted: SubRip (SRT), Advanced SubStation Alpha (ASS/SSA), WebVTT, MOV Text.
Bitmap-based subtitle formats (PGS from Blu-ray, VobSub from DVD, DVB) cannot be extracted as text. They are tracked in the database and handled during transcoding by burning them into the video stream when selected by the user. This requires an active transcoding session.
Subtitle extraction can be enabled or disabled in Admin > Settings > Processing. When disabled, embedded text subtitles are still detected and listed in the database, but the SRT files are not created.
Subtitle Files on Disk
Section titled “Subtitle Files on Disk”Library scans pick up subtitle files sitting next to your media. Recognized extensions: .srt, .vtt, .ass, .ssa, .sub, .idx.
Name the file after the video with a language suffix so the language is detected:
| Filename | Detected language |
|---|---|
Movie.Name.2020.en.srt | English |
Movie.Name.2020.eng.srt | English (3-letter codes work) |
Movie.Name.2020.srt | Defaults to English |
External Subtitles
Section titled “External Subtitles”Odeion integrates with OpenSubtitles for downloading external subtitle files. To enable this, configure your OpenSubtitles API key in Admin > Settings > Metadata (provider credentials live with the other metadata providers, not on the Subtitles page).
Once configured, subtitles can be searched and downloaded from the media detail page in the web interface or app. Search results are ranked by relevance, download count, and language match.
Downloaded subtitles are stored in the subtitles/ subdirectory of the data directory.
Subtitle Settings
Section titled “Subtitle Settings”The following options are available in Admin > Settings > Subtitles:
| Setting | Description |
|---|---|
subtitle_enabled | Master toggle for the subtitle system |
subtitle_auto_download | Automatically search and download subtitles for new content |
subtitle_languages | Preferred languages for automatic download |
subtitle_allow_manual_search | Let users search providers on demand |
subtitle_burn_in_default | Whether to burn bitmap subtitles into the video by default |
subtitle_auto_extract | Extract text-based embedded subtitles during processing |
Player Behavior
Section titled “Player Behavior”All client apps display available subtitles (both embedded and external) in the subtitle track picker during playback. Text subtitles are rendered client-side. Bitmap subtitles require server-side burn-in and will trigger a transcoding session if one is not already active.