mpv PGS Subtitles Not Rendering: How to Fix It

When mpv plays a Blu-ray-derived video but its PGS subtitles are missing, incomplete, badly scaled, washed out, or absent from screenshots, the problem usually falls into one of a few categories: the subtitle track is not selected, subtitles have been disabled or hidden, a configuration or script is overriding normal behavior, the file or stream does not expose a usable PGS track, or the active video output and hardware-decoding path is behaving unexpectedly. PGS subtitles are image-based rather than text-based, so troubleshooting them differs from fixing an SRT font or character-encoding problem. The steps below isolate each layer without requiring codec packs, wholesale configuration deletion, or random third-party binaries.

1. Confirm the Symptom With a Minimal Clean mpv Command

Start by determining whether mpv can render the PGS track without your normal configuration. This is the fastest way to separate a media or installation problem from a customization problem.

1.1 Run mpv without loading your configuration

Open a terminal in the directory containing the test video and run an appropriate command for your platform:

• Windows: mpv.exe --no-config --sid=auto "C:\path\to\video.mkv"
• Linux or macOS: mpv --no-config --sid=auto "/path/to/video.mkv"

The --no-config option prevents mpv from loading the usual configuration files and user scripts. The --sid=auto option asks mpv to select a subtitle track according to its normal selection rules. Keep the file path quoted, especially when it contains spaces, brackets, ampersands, or shell-sensitive characters.

While the file is playing, press j or the subtitle-track cycling key defined by your active mpv bindings. Watch the on-screen display for each available subtitle track. Also press v to make sure subtitle visibility has not been toggled off.

Success means that the expected bitmap subtitles appear at the correct moments and remain visible during playback. If this clean command works, stop investigating codecs, operating-system permissions, and GPU drivers. The media and basic mpv subtitle renderer are working, so the cause is almost certainly in your configuration, profile, input bindings, or scripts.

1.2 Verify that the track is actually PGS

PGS, commonly identified as hdmv_pgs_subtitle, consists of bitmap images and timing information. It is not styled like ASS and does not use a selectable text font like SRT. Options intended only for text-subtitle fonts, outlines, or ASS styling therefore cannot repair a missing PGS track.

Run mpv --no-config --term-status-msg='${track-list}' "file.mkv", inspect the normal terminal output at startup, or use mpv's interactive track list if your interface provides one. A probing tool such as ffprobe can also identify the subtitle codec, provided it comes from a trusted FFmpeg installation.

If no PGS stream appears, mpv cannot display a track that the selected file, playlist entry, disc backup, or network response does not contain. Confirm that you opened the intended file and that its subtitle track was preserved when the media was created. Success at this stage is a listed subtitle stream with a valid track ID and an image-subtitle codec.

2. Check Subtitle Selection and mpv Settings Directly Related to PGS

Once the track is confirmed, examine the controls that can select, hide, delay, reposition, or override it. Change one setting at a time and replay a scene where a subtitle is known to occur.

2.1 Select the subtitle track explicitly

Automatic selection can choose no track or choose a different language based on track flags and language preferences. First list the tracks, note the numeric subtitle ID, and launch mpv with that ID:

mpv --no-config --sid=3 "file.mkv"

Replace 3 with the ID reported by mpv, not necessarily the stream index reported by another application. If the PGS images now appear, the renderer is fine and the issue is selection policy. Review options such as sid, slang, and subs-with-matching-audio in your configuration. A forced-only PGS track may contain images only for signs or foreign-language dialogue, so silence for long stretches can be normal.

2.2 Check visibility, timing, position, and scale

Look for these subtitle-related conditions:

• sub-visibility=no hides the selected track without deselecting it.
• A large positive or negative sub-delay can move images outside the scene being tested.
• Extreme subtitle position or margin settings can move images toward or beyond the visible area.
• Unusual subtitle scaling can make bitmap images unexpectedly small or oversized.
• Language and forced-track preferences can select a sparse track instead of the full dialogue track.

Test a known subtitle timestamp using --sub-visibility=yes --sub-delay=0. If you have customized image-subtitle scaling, temporarily remove those adjustments or reset them on the command line. Success means the same PGS event appears at its expected timestamp and within the visible video area.

2.3 Inspect configuration files, profiles, and input bindings

A global mpv.conf may look correct while an auto profile changes settings only for HDR files, particular extensions, large resolutions, network protocols, or specific directories. Use --show-profile=profile-name to print a named profile's contents. Also search your configuration files for sid, sub-visibility, sub-delay, slang, sub-scale, vf, vo, and hwdec.

Review input.conf for bindings that change subtitle visibility, subtitle ID, subtitle delay, or subtitle position. A key may have been rebound by you, a frontend, or a copied configuration. Temporarily rename only the individual file under investigation, or override its relevant option on the command line. Do not delete the entire configuration directory.

Scripts can also observe file-load events and set tracks or properties through mpv's scripting and IPC interfaces. Move one suspect user script out of the scripts directory for a temporary test, then restore it if nothing changes. When --no-config works but ordinary startup fails, continue narrowing configuration components until the smallest responsible setting or script is identified.

2.4 Do not confuse subtitle and audio or video track IDs

mpv maintains separate selections for video, audio, and subtitles. Options such as vid, aid, and sid are not interchangeable. A copied profile that sets sid=no disables subtitle selection, while changing aid only selects audio. Confirm the on-screen message says the chosen ID belongs to a subtitle track.

3. Test Video Output, Hardware Decoding, HDR, and Scaling

PGS images are normally composited into the presented video by mpv's rendering pipeline. Users sometimes assume that hardware-decoded video means subtitles are drawn by the hardware decoder itself. They are not simply another decoded video plane controlled by the Blu-ray subtitle stream. The selected video output, GPU rendering path, filters, and scaling choices can affect the final composition.

3.1 Test with software decoding

Run a short, known-good local sample with hardware decoding disabled:

mpv --no-config --hwdec=no --sid=TRACK_ID "sample.mkv"

This test is especially useful when the problem occurs only with a specific hardware API, zero-copy path, driver, or high-bit-depth format. If PGS works with --hwdec=no but disappears with your usual hardware decoding, keep software decoding temporarily and test safer hardware-decoding modes documented for your platform. Avoid stacking filters and custom shaders during this comparison.

Success means subtitles render over software-decoded video at the expected time. At that point, stop changing subtitle options. The next investigation belongs to the hardware-decoding, video-output, or GPU-driver layer.

3.2 Remove custom shaders and complex video filters temporarily

High-quality scaling shaders, interpolation filters, debanding chains, crop filters, and custom GPU hooks complicate the render path. Start with --no-config, which removes most user-added complexity, or explicitly test without custom glsl-shaders and video filters. Reintroduce components one at a time.

If a particular shader or filter causes the failure, verify that it is designed for your current mpv rendering API and video format. Do not assume that a shader package is compatible merely because video remains visible. Success is a repeatable change where subtitles work without one component and fail when that same component is restored.

3.3 Separate HDR visibility from actual rendering failure

HDR and tone-mapping settings can make PGS subtitles appear unusually bright, dim, gray, or washed out even though they are being rendered. Bitmap subtitles often contain colors authored for a particular presentation context. Display transfer characteristics, peak-brightness assumptions, tone mapping, and contrast can change their apparent intensity.

Test the same timestamp with a clean configuration and, when possible, on a normal SDR sample. If the subtitle shape is present but its brightness is wrong only in HDR output, track the issue as an HDR or color-pipeline problem rather than a missing-track problem. Reset custom target-display, tone-mapping, shader, and output color options before adjusting subtitle placement.

Scaling can produce a different false alarm. A PGS stream authored for one video canvas may look too small after unusual panscan, crop, display-resample, or window-scaling choices. Restore normal aspect and zoom settings. Stop when the subtitle is consistently visible and proportionate; further changes risk fixing one file while breaking others.

3.4 Compare video output behavior

If subtitles remain absent only under one video-output configuration, test mpv's recommended GPU output for your build and operating system rather than guessing obsolete driver names. Use the terminal to see which output initializes successfully. A failed or fallback output can explain why behavior differs from another machine.

Update the graphics driver through the operating system, GPU vendor, or computer manufacturer when the clean software-decoding test works but a supported GPU path fails. On Linux, note whether the session uses Wayland or X11 and whether the failure follows one session type. On macOS and Windows, compare fullscreen and windowed playback only after proving the selected PGS track is active.

4. Check the File, Stream, URL, and Operating-System Environment

A local Matroska file with an embedded PGS track provides the best baseline. Online URLs and network streams add extraction, authentication, transport, and seekability variables that can resemble an mpv player issue.

4.1 Establish a local-file baseline

Copy a legally obtained test file to a simple local path that you can read. Avoid network shares, cloud placeholders, removable media, and paths with unusual shell characters for the first test. Confirm that the current user has read permission for the media and execute permission for its parent directories where applicable.

If an external subtitle file is being loaded, verify its exact path and extension. PGS is commonly embedded in containers or stored in formats such as SUP, but support depends on whether the file is valid and presented in a form mpv can demux. Quote both media and subtitle paths. Success means the same local file and explicit track ID work repeatedly from a clean command.

4.2 Treat online URLs and yt-dlp as a separate input layer

For supported web URLs, mpv may rely on yt-dlp to resolve media formats. The subtitle choices available from a website are not necessarily PGS, even when a local Blu-ray-derived file uses PGS. Many online services provide text subtitles, segmented captions, or no subtitle stream in the selected format.

Check the terminal output to confirm that yt-dlp is found, the URL resolves, and the resulting format includes the expected subtitle track. Use a trusted installation method and an explicit, correctly quoted executable path if needed. Do not download replacement binaries from random mirrors.

If local embedded PGS works but the URL does not expose PGS, stop changing mpv's PGS rendering settings. The limitation is upstream in the selected stream, extractor result, server manifest, authentication state, or playlist entry.

4.3 Consider network and media limitations

Network shares and high-bitrate streams can stall or arrive with discontinuities. A subtitle packet that has not arrived cannot be displayed. Test from local storage, then compare terminal messages around the missing event. If seeking backward makes the subtitle appear, investigate buffering, timestamp, demuxer, or stream continuity rather than font settings.

Damaged timestamps, malformed subtitle packets, or an incomplete remux can affect only one title. Compare at least two known-good PGS samples. If every other sample works, preserve your working mpv setup and repair or recreate the problematic media from a lawful source rather than adding global workarounds.

4.4 Understand which system components are relevant

Audio backend problems rarely cause PGS rendering failures directly. However, severe synchronization or timestamp problems can make subtitles appear at unexpected moments. Likewise, operating-system permissions matter for reading external subtitle files, configurations, shaders, scripts, logs, and yt-dlp, but not for styling an already decoded PGS image.

Use relevance as a filter: investigate the audio backend only if logs show clock or synchronization trouble, network access only for remote inputs, and filesystem permissions only when mpv cannot open a required file. This prevents a focused subtitle investigation from turning into unrelated system maintenance.

5. Use mpv Diagnostics to Find the Exact Failure Layer

mpv's terminal output is more useful than repeatedly toggling options. Capture evidence from one known subtitle timestamp and compare a failing normal run with a successful clean run.

5.1 Create a detailed log

Run a command similar to:

mpv --log-file=mpv-pgs.log --msg-level=all=v "file.mkv"

Verbose logging can be extensive. Reproduce the problem briefly, close mpv, and search the log for subtitle track selection, demuxer messages, decoder errors, video-output initialization, hardware decoding, scripts, and profile application. Remove or redact private file paths, URLs, tokens, and usernames before sharing a log.

A useful log identifies one of three outcomes: no subtitle stream was exposed, a stream was exposed but not selected, or the selected stream reached a pipeline that produced an error or unexpected output. Once one outcome is established, stop making changes to unrelated layers.

5.2 Inspect profiles and active tracks

Use --show-profile=NAME to inspect a profile before applying it. During playback, use mpv's track controls or console interface to examine the selected subtitle ID. The stats overlay can help confirm the active video output, decoder, resolution, frame timing, and other playback details, although the exact pages and bindings can vary with configuration.

Compare the following between clean and normal runs:

• Selected subtitle ID and language
• Subtitle visibility and delay
• Hardware decoder and video output
• Loaded scripts and applied profiles
• Filters, shaders, scaling, HDR, and tone-mapping options
• Demuxer warnings or packet errors

The first meaningful difference is a better lead than a long list of speculative fixes.

5.3 Test screenshot behavior separately

A visible subtitle during playback does not guarantee that every screenshot command captures it. mpv supports screenshot modes that can include or exclude subtitles and on-screen display elements. The result also depends on whether the command captures the composed video output or a different stage.

Use the screenshot command intended to include subtitles, or bind an explicit command using mpv's documented screenshot flags. Test at a paused frame where the PGS image is clearly visible. If playback is correct but the saved image lacks subtitles, do not modify track selection, hardware decoding, or the subtitle file. The problem is the screenshot mode or binding.

Success means the captured file contains the visible PGS image. Once that happens, stop changing playback settings and update only the screenshot binding you actually use.

6. Run a Clean Temporary Test Before Making Permanent Changes

A controlled test protects a carefully customized mpv installation. Use a known-good local sample, a timestamp with a visible PGS event, and a terminal command that bypasses configuration.

1. Run mpv --no-config --hwdec=no --sid=TRACK_ID "sample.mkv".
2. Confirm subtitle visibility and reset delay to zero.
3. If successful, enable your normal hardware-decoding option and retest.
4. Restore the usual video output, then shaders and filters one group at a time.
5. Load the normal configuration without scripts, then restore scripts individually.
6. Test the original high-bitrate, HDR, network, or URL source last.

Record each result instead of changing several variables together. The moment one restored component makes the PGS track fail, repeat the comparison once to confirm causation. Then fix, remove, or scope that component rather than weakening the entire configuration.

If the clean software-decoded test fails on multiple known-good PGS files and no PGS decoder activity appears in the log, verify that mpv came from a reputable package source and that its required runtime components are intact. Use the official project guidance or your operating system's package manager. Avoid codec packs because mpv normally relies on its own supported multimedia stack rather than arbitrary system codec bundles.

7. Quick Fix Checklist

• Confirm the file contains a PGS or hdmv_pgs_subtitle track.
• Start with --no-config and a local known-good sample.
• Select the exact subtitle ID with --sid=ID.
• Set subtitle visibility on and subtitle delay to zero.
• Check whether the selected track is forced-only or otherwise sparse.
• Test with --hwdec=no to isolate the GPU decoding path.
• Temporarily remove custom shaders, filters, HDR overrides, and unusual scaling.
• Inspect mpv.conf, profiles, input.conf, scripts, and IPC clients.
• Use a local file before troubleshooting yt-dlp, playlists, or network streams.
• Capture a verbose log and compare clean versus normal startup.
• Use a screenshot command that explicitly includes subtitles.
• Stop changing settings as soon as the responsible layer is confirmed.

8. Frequently Asked Questions

8.1 Does mpv support Blu-ray PGS subtitles?

Yes, mpv can display image-based PGS subtitles when the media exposes a valid supported subtitle stream. The track still must be detected, selected, timed correctly, and composited through a functioning output path. PGS support does not mean every damaged SUP file, encrypted disc workflow, or incomplete network manifest will work automatically.

8.2 Why does the PGS track appear in the list but show no dialogue?

You may have selected a forced-only track containing only signs or foreign-language dialogue. Cycle through all subtitle tracks and compare their language, title, default flag, and forced flag. Also seek to a timestamp known to contain an event. If another PGS track displays full dialogue, no renderer repair is necessary.

8.3 Can hardware decoding prevent PGS subtitles from appearing?

Hardware decoding should not inherently disable PGS, but a particular decoder, zero-copy mode, GPU driver, video output, or filter combination can expose a rendering problem. Test the same sample with --hwdec=no. If software decoding fixes it, focus on the hardware and output path rather than subtitle language or font options.

8.4 Why do PGS subtitles look wrong only with HDR video?

HDR output and tone mapping can change the perceived brightness and contrast of composited subtitle images. First verify that the subtitle is present, then reset custom tone-mapping, target-display, shader, and scaling settings. A visible but overly bright or dim bitmap is a color-pipeline symptom, not necessarily a subtitle-decoding failure.

8.5 Why are subtitles visible during playback but missing from screenshots?

The screenshot command may be capturing video without subtitle or on-screen-display composition. Test an explicit screenshot mode that includes subtitles at a paused subtitle frame. If that works, correct the relevant input.conf binding and leave the functioning playback pipeline unchanged.

8.6 Should I reinstall mpv or delete my configuration?

Not initially. A clean --no-config test is safer and more informative. If it works, isolate the responsible option, profile, script, or binding. Consider reinstalling from a trusted source only when multiple known-good samples fail in a clean run and logs indicate missing or broken runtime functionality. Preserve your configuration for comparison rather than deleting it.