Jellyfin external subtitle guide

How to Convert PGS to SRT for Jellyfin and Add External Subtitles

Jellyfin may need to remux, convert or burn a PGS subtitle depending on the playback client and media path. Because PGS contains subtitle pictures, burn-in requires the server to process the video. Converting an extracted SUP/PGS track into a reviewed external SRT gives Jellyfin a text subtitle option that may be easier for the client to render.

PGS to SRT Workflow for Jellyfin

Important: SRT does not guarantee Direct Play. Jellyfin also checks the container, video, audio and subtitle compatibility, and playback can be affected by bitrate, quality settings, bandwidth and client capabilities.

  1. Extract the PGS track as SUP if it remains embedded in MKV.
  2. Convert the SUP subtitle images to SRT with OCR.
  3. Review the recognized text and timing.
  4. Match the SRT base filename to the movie or episode.
  5. Add language and optional Jellyfin flags with dot-separated suffixes.
  6. Place the SRT beside the media file and scan the library.

Convert a .sup file to SRT

Why PGS Subtitles Can Cause Remuxing or Video Transcoding

PGS is a picture subtitle format used in Blu-ray workflows. Jellyfin client compatibility depends on container, video, audio and subtitle support together. If a subtitle format or its container path is unsupported, Jellyfin may remux, convert the subtitle path or burn the subtitle into video.

Burning subtitles means rendering the subtitle layer onto video frames. Jellyfin's codec documentation describes subtitle burn-in as a particularly intensive transcoding path. The exact outcome varies by client, version, browser, hardware and media. For the format background, read what PGS subtitles are.

FactorPGS/SUPSRT
Stored dataSubtitle images and timing.Subtitle text and timing.
EditabilityRequires OCR first.Easily edited.
Blu-ray appearanceExact graphics are retained.Player controls appearance.
Position and colorStored in images.Limited and client-dependent.
Playback pathCan require remuxing or burn-in.Often easier to render, but client-dependent.
Direct PlayDepends on full media/client compatibility.May remove one incompatibility but does not guarantee it.

Direct Play, Remux, Direct Stream and Transcode in Jellyfin

Direct Play

The file is delivered without transcoding or modification and adds almost no server processing load.

Remux

The container changes while audio and video streams remain untouched.

Direct Stream

Audio is transcoded while the original video remains untouched, according to Jellyfin's current transcoding documentation.

Transcode

The video stream is transcoded. Subtitle burn-in requires video processing and falls into this demanding category.

Jellyfin documentation and dashboard labels can evolve. Use the current official definitions in the installed server version and do not substitute another media server's terminology.

Even after selecting SRT, playback may still not Direct Play because of unsupported video, audio, container, bitrate, quality limit, bandwidth, HDR tone mapping, client settings or a subtitle/container combination that still needs remuxing.

Selecting SRT only tests one part of the playback chain. Check the server dashboard while playing the file to identify the actual mode.

Step 1. Extract the PGS Track from MKV

If the desired PGS track is embedded inside an MKV, identify its language and whether it is full or forced, then extract it as a standalone SUP file. Do not assume the first subtitle stream is PGS or the correct language.

Step 2. Convert the SUP Subtitle Images into SRT Text

  1. Open the homepage converter.
  2. Choose the extracted SUP file.
  3. Select the language visible in the subtitle images.
  4. Run OCR.
  5. Review names, accents, punctuation, similar-looking characters and line breaks.
  6. Download the SRT.
  7. Keep the SUP until the SRT is fully tested.

OCR accuracy varies. Original PGS timings can be carried into the text cues, but verify the output. SRT does not keep exact PGS colors, fonts or positions; the target Jellyfin client determines text-subtitle rendering.

Convert SUP to SRT for Jellyfin Convert and correct PGS with Subtitle Edit

How Jellyfin Parses External Subtitle Filenames

Jellyfin external subtitle and audio tracks can use dot-separated suffix fields. Each field can be a language identifier, a special flag or arbitrary text used as the stream title when it is not parsed as a language or flag and no embedded title already exists.

MediaBaseName.[title-or-flag].[language-or-flag].srt
  • The external SRT must share the media file's base name.
  • Separate suffix fields with periods.
  • Keep one subtitle stream per SRT file.
  • Jellyfin documents that flags are ignored for external containers containing more than one stream.

This guide uses a consistent site convention: BaseName.language.flag.srt. Official examples may place parsed fields in different dot-separated order because Jellyfin parses fields individually.

Name External SRT Files for Jellyfin Movies

/Movies/Film (1986)/
  Film.mkv
  Film.en.srt

Match Film, the actual media base filename. Add a language field before .srt, put the subtitle beside the movie and confirm the operating system has not added .txt after .srt.

Multiple languages

Film.mkv
Film.en.srt
Film.es.srt
Film.ja.srt

Descriptive title

Film.mkv
Film.Director Commentary.en.srt

Only use arbitrary title fields that do not collide with a language or special flag, and verify how the current Jellyfin version displays them.

Name External SRT Files for Jellyfin TV Episodes

/Shows/Series Name A (2021)/Season 01/
  Series Name A (2021) S01E01 Title.mkv
  Series Name A (2021) S01E01 Title.en.srt

Put the SRT in the same season folder as the episode, match the complete episode base filename, preserve the SxxEyy identifier and title when present, and add dot-separated language and optional flags before .srt.

Multiple languages

Series Name A (2021) S01E01 Title.mkv
Series Name A (2021) S01E01 Title.en.srt
Series Name A (2021) S01E01 Title.fr.srt

Do not use one SRT for multiple episode files. For broader season and show organization, use the official Jellyfin TV show naming guide.

Use Default, Forced and Hearing-Impaired Flags Correctly

Default

Film.default.srt
Film.en.default.srt

Default marks the track as the default variant. Selection behavior can still depend on user/client preferences and track availability. Do not mark every subtitle as default.

Forced or foreign

Film.en.forced.srt
Film.en.foreign.srt

Forced subtitles normally cover selected foreign-language or alien dialogue, signs or similar limited content. Jellyfin documents foreign as an alias flag. Do not label a full dialogue track as forced simply to make it auto-select.

SDH, CC and HI

Film.en.sdh.srt
Film.en.cc.srt
Film.en.hi.srt

SDH and CC may include speaker identifiers, music and sound effects. Jellyfin documents hi as a hearing-impaired flag, but hi is also the Hindi language abbreviation. hi by itself resolves as Hindi; include another language field such as Film.en.hi.srt when using it as a hearing-impaired flag.

Multiple flags

Film.default.en.forced.srt

Dot-separated fields can contain more than one special flag. Use only truthful combinations.

Multi-stream warning: Jellyfin documents that filename flags are ignored on external containers with more than one stream. Use a normal single-stream SRT sidecar for the workflow in this guide.

Add the SRT to Jellyfin and Refresh the Library

  1. Put the SRT beside its matching movie or episode.
  2. Confirm its base filename matches the media.
  3. Confirm suffixes are dot-separated.
  4. Confirm the Jellyfin server process can read the file and directory.
  5. Run the appropriate library scan or item metadata refresh in the current Jellyfin interface.
  6. Reopen the media item.
  7. Inspect the subtitle selector.
  8. Test the actual target client.

Interface labels change across Jellyfin releases and client surfaces, so use qualified scan or refresh wording. Avoid universal button paths. On Docker or NAS setups, confirm that the subtitle file exists inside the container or mounted library path, not only on the host.

Fix permissions by granting the Jellyfin server read access to the specific media library path. Do not use chmod 777 or run Jellyfin as root as a shortcut.

Select the SRT and Check Jellyfin Playback Status

  1. Start playback with the original PGS track and inspect the server dashboard.
  2. Switch to the external SRT track.
  3. Inspect the dashboard again.
  4. If playback still converts, test with subtitles off.

If playback still converts with subtitles off, subtitles are not the only cause. Check video codec, audio format, container, bitrate, quality limit, HDR tone mapping, network and client support.

Hardware acceleration can help supported transcoding workloads, but subtitle burn-in still adds processing and can involve compatibility or pipeline limitations.

What Changes When PGS Becomes SRT

PGS stores rendered subtitle graphics. SRT stores text and timestamps. SRT does not preserve exact PGS colors, fonts, anti-aliased outlines, graphical signs, screen positions or multi-region image layout. Review the converted file before relying on it for accessibility, translation or public release.

Troubleshooting Jellyfin External SRT Subtitles

Jellyfin does not show the SRT track

Check the base filename, folder, dot-separated suffixes, hidden .txt extension, read permissions, library scan and container mount visibility.

The subtitle language or flags look wrong

Use separate dot fields and avoid suffixes that no longer share the media base name. Remember that hi alone is Hindi, and flags are ignored on external multi-stream containers.

The forced subtitle does not auto-select

Confirm the file contains genuinely forced content, uses forced or foreign as a dot-separated field and is visible to Jellyfin. Selection can still depend on client and user preferences.

SRT timing is wrong

Confirm the SRT and video come from the same release, edition and cut. Determine whether the offset is constant or progressive, then correct the SRT in Subtitle Edit or another editor.

SRT contains OCR errors

Recheck recognition language, compare with the original PGS images and fix names, accents, punctuation and similar-looking characters. Keep the SUP as a reference.

SRT displays boxes or replacement characters

Save as UTF-8 and confirm the client font supports the script. Distinguish broken file encoding from missing font glyphs.

SRT still causes Remux or Direct Stream

This is possible. The container, subtitle delivery or audio path may still need conversion while video remains untouched. Inspect the dashboard and current codec matrix.

SRT still causes video Transcode

Test with subtitles off, then check video codec, resolution, bitrate, quality limit, HDR or tone-mapping need, client support and settings. Check logs if the dashboard is insufficient.

Playback fails because transcoding is disabled for the user

Jellyfin user settings can restrict playback requiring transcoding or conversion without re-encoding. An administrator should review the user's playback permissions and client compatibility.

Official Jellyfin References Used

Related SUP and PGS Guides

Convert SUP/PGS to SRT Online

Run OCR on the extracted SUP subtitle before adding the SRT to Jellyfin.

Extract PGS with FFmpeg

Copy an embedded MKV PGS stream to a standalone SUP file.

Extract PGS with MKVToolNix

Find the track ID and extract PGS with mkvextract.

Use external SRT subtitles with Plex

Compare the Plex-specific naming and playback workflow.

Browse all SUP and PGS guides.

Frequently Asked Questions

Does PGS always make Jellyfin transcode video?

No. Playback depends on the client, container and subtitle compatibility. PGS may work through a supported path, require remuxing or need to be burned into video. Burn-in requires video transcoding.

Does converting PGS to SRT guarantee Direct Play?

No. SRT can remove picture-subtitle burn-in as one incompatibility, but the video, audio, container, bitrate, quality settings, network and client must also be compatible.

How should I name an English SRT for a Jellyfin movie?

Match the video base filename and add a dot-separated language field, such as Film.en.srt beside Film.mkv.

How should I name an SRT for a Jellyfin TV episode?

Match the complete episode base filename, such as Series Name S01E01.en.srt beside Series Name S01E01.mkv in the same season folder.

How do I mark a Jellyfin subtitle as forced?

Add forced as a dot-separated field, for example Film.en.forced.srt. Jellyfin also documents foreign as a forced flag alias.

How do I mark an SRT as default in Jellyfin?

Add default as a separate field, such as Film.en.default.srt. Actual selection can still depend on user and client preferences.

How do I mark SDH or hearing-impaired subtitles?

Jellyfin documents sdh, cc and hi. Use a filename such as Film.en.sdh.srt. Because hi alone means Hindi, include another language field when using it as the hearing-impaired flag.

Why is Jellyfin not detecting the SRT?

Common causes include a mismatched base filename, wrong folder, hidden .txt extension, unreadable permissions, missing container mount, malformed suffixes or a library that has not been scanned after the file was added.

Can Jellyfin save an embedded PGS subtitle as editable SRT?

Do not rely on streaming subtitle conversion as a saved OCR workflow. Extract the PGS track as SUP, run OCR separately and add the reviewed SRT as an external track.

Why does SRT still cause Remux or Direct Stream?

The client may need a different container or audio format even when the SRT is usable. Check the dashboard to see the current playback type and consult the codec-support matrix.

Is subtitle burn-in CPU intensive?

Official Jellyfin documentation describes burning subtitles as a particularly intensive transcoding workflow because the subtitle layer must be applied while video is processed. Hardware acceleration can help supported operations but does not remove every cost or limitation.

Should I delete the original PGS after conversion?

Keep it until the SRT has been checked for OCR accuracy, timing and missing visual information. Keeping both can also serve clients with different capabilities.

Ready to create an external SRT for Jellyfin?

Convert the extracted SUP/PGS subtitle with OCR, review the text, then place the SRT beside its matching Jellyfin movie or episode.

Convert SUP to SRT