Subtitles

Sovereign carries both kinds of embedded subtitle track through to the player, and they take different routes to get there. Text tracks (SRT, ASS/SSA) become native HLS subtitle tracks that any HLS-capable player discovers, lists and renders like broadcast captions. Image-based tracks (PGS, VOBSUB, DVB) carry pixels rather than words, so an HLS player can’t render them and HLS can’t carry them at all; those are turned into one image per caption and drawn over the video by the client itself.

Both belong to a specific media file, so each version of a title has its own set of tracks.

---

How It Works

1. The first time a media file is played, Sovereign probes it and records every subtitle track it finds: the language, the track title, whether it’s Forced or SDH, and whether it’s text or images. The probe takes about a second even on a file carrying dozens of tracks, and it’s what fills the track menu.
2. Text tracks are converted to WebVTT by the same pass that produces the video you’re watching, so captions can’t fall behind the picture.
3. Image-based tracks are prepared separately, and only for the track a viewer actually picks.

Nothing is generated at import time, so a file nobody plays never has its subtitles prepared.

---

Text Tracks

Every text track is prepared up front, when the stream starts, not when you pick one. That’s what lets you switch languages an hour into a film: by then the pass that produces the cues may well have finished, and a track left out of it would have nothing to fall back on.

They become part of the HLS presentation itself:

• The stream advertises one native subtitle track per text track, labelled with its language and title (for example “English - SDH”).
• Content is served in time-aligned pieces that match the video, so captions stay in sync throughout playback, including after seeking to a new position mid-video.
• If your account has a preferred subtitle language and the file has a track in it, that track is marked as the default so the player can turn it on for you. With no preference of your own, the server-wide Sovereign__Playback__DefaultSubtitleLanguage applies instead. It’s unset out of the box, so unless you set it, subtitles start off.

Because the cues are produced alongside the video rather than by a separate pass over the file, there’s no waiting for extraction on a first play and no second reader competing with playback for your storage. They’re produced per session instead of cached, which costs nothing measurable, because the pass already reads every byte of the source to build the video.

---

Image-Based Tracks

A Blu-ray remux commonly carries its subtitles only as PGS, and many such files have no text track at all. Left alone, those titles would play with no subtitles available.

So Sovereign renders each caption of the chosen track to its own image and hands the set to the client, which draws them over the picture in time with playback. The video isn’t touched: burning the captions in would force a re-encode of a title that would otherwise have been copied untouched, which on an HDR remux means converting the whole film to get text onto it.

Image-based tracks are the only subtitle work you may have to wait for:

• It runs only when a viewer selects the track, because a single file can carry dozens of image-based tracks and preparing all of them would cost close to a gigabyte to serve the one that gets picked.
• It’s cached per track. The wait is paid once; every later playback of that track starts immediately.
• How long it takes depends on the source. Where the file carries an index Sovereign can seek by, which covers most Matroska rips, a feature-length track is ready in well under a minute. Where it doesn’t, the whole file has to be read through and the wait runs to tens of minutes.

The player tells you which state you’re in and starts drawing captions as soon as they’re ready, so you can leave the track selected and keep watching.

---

Using Subtitles

• Web player - open the settings menu in the player controls and choose Subtitles. Every available track is listed by name, image-based tracks included, and “Off” hides captions again.
• Roku - press Down during playback to open the options menu and choose Subtitles. Text tracks follow the device’s system caption settings, so size, colour and style honour your Roku accessibility preferences.
• Android - open the options panel (Down or Menu on a TV remote, the gear on a phone) and choose Subtitles. Image-based tracks are marked (image).

---

Supported Formats

Category	Formats
Delivered as native subtitle tracks	SRT, ASS/SSA
Drawn over the video by the client	PGS (Blu-ray), VOBSUB (DVD), DVB, XSUB

Other text formats, such as MP4’s own timed text, are recognised and listed when a file carries one, but Sovereign doesn’t deliver their captions. They’re rare in a real library.

---

Language and Metadata

Each track records the language detected from the file, along with any Forced or SDH (hearing impaired) flag. Sovereign composes the name you see from those plus the track’s own embedded title, which is what keeps “Spanish - Castilian” and “Spanish - Latin American” apart instead of showing them as “Spanish” and “Spanish (2)”. An image-based track also carries its format in the name, so a file offering both an SRT and a PGS English track doesn’t present two identical rows when one of them costs a wait.

The names are composed on the server, so every client shows the same wording.

---

Storage

Image-based tracks are cached under the media file’s asset directory, one directory per track:

{assets}/subtitles/{shard}/{mediaId}/{mediaFileId}/{trackIndex}_{language}/

{trackIndex} is the 0-based position of the track among the file’s subtitle tracks.

Text tracks aren’t stored here. They live in the stream’s working directory for as long as the stream does and are cleaned up with it, the same as the video segments beside them.

---

Caching

The probe runs once per file. Once a file has subtitle rows recorded, it isn’t probed again, so subtitle tracks added to a file on disk afterwards won’t appear until those rows are cleared. Sovereign also remembers, for as long as it’s running, which files turned out to have no subtitle tracks at all, so playing an audio-only or subtitle-free file repeatedly doesn’t re-probe it.

Prepared image cues are reused indefinitely. If the images for a track go missing on disk while the database still expects them, selecting the track prepares them again.