mpv Subtitles Have Black Boxes: How to Fix It

When mpv subtitles have black boxes, the cause is usually a subtitle background color, an unusually thick border, styling embedded in an ASS or SSA subtitle track, a config override, or a font-rendering problem. The video decoder, HDR pipeline, hardware decoding, and network source are less likely to be responsible because mpv normally renders subtitles after decoding the video. The safest troubleshooting method is to reproduce the symptom without your normal configuration, identify whether ASS styling is involved, and then change one subtitle option at a time.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin with a temporary clean launch. This does not delete or rename your configuration files. It simply tells mpv not to load them for the current run.

Open a terminal, PowerShell window, or Command Prompt and run:

mpv --no-config "path/to/video.mkv"

On Windows, you might use:

mpv.exe --no-config "C:\Videos\example.mkv"

On Linux or macOS, a typical command is:

mpv --no-config "/home/user/Videos/example.mkv"

Keep quotation marks around paths containing spaces. If mpv is not available through your shell's executable path, run the command from the folder containing mpv or provide the trusted executable's full path.

1.1 Interpret the clean test

• If the boxes disappear, an option, profile, script, or input binding in your normal configuration is responsible.
• If the boxes remain, the selected subtitle track may contain its own ASS styling, or the issue may involve font fallback or rendering.
• If subtitles disappear entirely, confirm that the file contains a subtitle track and that mpv selected it.
• If the file does not open, fix the path or shell quoting before diagnosing subtitle appearance.

Success means the same subtitle line appears without the unwanted opaque rectangle or excessive border. Once the clean test produces acceptable subtitles, stop changing unrelated video, audio, HDR, or hardware-decoding options. You have already narrowed the problem to configuration or subtitle styling.

1.2 Compare ASS and plain-text subtitle behavior

ASS and SSA subtitles can carry author-defined fonts, colors, borders, shadows, alignment, positioning, and opaque boxes. SRT and other plain-text formats generally rely more heavily on mpv's normal subtitle styling options. That difference is central to this problem.

Use the track list shown in the terminal, mpv's on-screen track controls, or the stats overlay to identify the active subtitle format. You can also test a known plain SRT file as an external subtitle:

mpv --no-config --sub-file="test.srt" "video.mkv"

If an SRT file looks normal while an embedded ASS track has black boxes, the embedded ASS styles are the leading suspect. If both formats show the same boxes, inspect mpv's general subtitle options and font environment.

2. Check Subtitle Options and Embedded Styles

The options most directly related to this symptom are sub-back-color, subtitle border settings, and sub-ass-override. Search your configuration before changing output drivers, hardware decoders, or shader chains.

2.1 Check sub-back-color and border settings

The sub-back-color option controls the subtitle background color for mpv-styled text. A fully or heavily opaque black value can create a dark rectangle behind every subtitle line. Look in your mpv.conf for entries such as:

sub-back-color=...

Temporarily comment out the line by placing # at its beginning, or test a transparent background from the command line:

mpv --no-config --sub-back-color="#00000000" "video.mkv"

mpv color values may include an alpha component, so use the syntax documented for your installed build. If a command is rejected, check mpv --list-options or the current mpv manual rather than guessing.

Also search for subtitle border and shadow options, including sub-border-size, sub-border-color, sub-shadow-offset, and sub-shadow-color. A very large border can resemble a black box, especially with bold text or tightly spaced lines. Test a modest border:

mpv --no-config --sub-border-size=2 "video.mkv"

Success looks like readable text with a thin outline rather than a solid rectangle. If this fixes the symptom, copy only the confirmed value into mpv.conf and stop. Do not reset unrelated settings.

2.2 Understand sub-ass-override behavior

The sub-ass-override option determines how mpv treats styling stored in ASS subtitles. Depending on the selected mode, mpv can respect the subtitle author's styles, apply selected user style changes, or strip much of the embedded styling.

Run this diagnostic test:

mpv --no-config --sub-ass-override=strip "video.mkv"

This test is especially useful when the black area appears only with one embedded ASS or SSA track. The strip mode removes most ASS formatting and renders the dialogue more like ordinary subtitles. It may also remove intentional placement, colors, signs, karaoke effects, and typesetting.

If the boxes disappear with --sub-ass-override=strip, the file's embedded ASS style or an ASS drawing is responsible. You then have three practical choices:

• Keep the authored style and accept the background if it is intentional.
• Use strip for that file or a narrowly defined mpv profile.
• Use another subtitle track or a corrected subtitle file from a legitimate source.

Do not make strip a global setting unless you are comfortable losing intentional ASS formatting in every file. Success means the dialogue becomes normally readable while the video remains unchanged.

2.3 Inspect profiles, input bindings, and scripts

An option may be activated indirectly. Search mpv.conf, included configuration files, profiles, and script options for terms beginning with sub- and sub-ass-. Also inspect input.conf for bindings that change subtitle styling during playback.

A profile can apply only to particular file types, protocols, displays, or playback conditions. This explains why local files might look normal while a network stream does not, or why only HDR content appears affected. Use:

mpv --show-profile=PROFILE_NAME

Replace PROFILE_NAME with the profile you want to inspect. This displays the profile's options without requiring you to infer them from playback behavior.

Temporarily disable one third-party subtitle-related script by moving only that script out of the active scripts directory, then repeat the same test. Avoid deleting the entire configuration folder. If the problem stops, restore the script and review its documented settings or update it through its trusted project source.

3. Check Fonts, Rendering, and Source-Specific Limitations

If the black boxes remain under --no-config, check whether the subtitle track requests fonts that are unavailable. Font fallback usually changes the typeface or character coverage, but malformed fonts, missing glyphs, and unusual ASS styles can also produce unexpected outlines or blocks.

3.1 Test font fallback

Try a common font that is installed on your operating system:

mpv --no-config --sub-font="Arial" "video.mkv"

On systems without Arial, use a known installed font such as DejaVu Sans, Liberation Sans, or another standard sans-serif font. This option is most meaningful when mpv controls styling. Embedded ASS styles may continue requesting their own fonts unless styling is overridden.

For a combined diagnostic test, use:

mpv --no-config --sub-ass-override=strip --sub-font="DejaVu Sans" "video.mkv"

If this removes the boxes and restores missing characters, install the legitimately obtained font required by the subtitle or keep an appropriate fallback. Never download random font bundles or codec packs from untrusted sites.

3.2 Separate subtitle rendering from video rendering

Hardware decoding, HDR tone mapping, GPU shaders, and video output settings usually affect the image rather than subtitle background styling. Still, a rendering defect can occasionally make transparency or compositing look wrong. Test without hardware decoding:

mpv --no-config --hwdec=no "video.mkv"

If the subtitle background is unchanged, restore your preferred hardware-decoding setting and focus on subtitle styles. If disabling hardware decoding fixes transparency artifacts across multiple unrelated subtitle files, update the GPU driver through the operating system or hardware vendor's official channel, then retest.

On Linux, compare the normal display session with another supported session only if you already have both Wayland and X11 available. Do not change display servers merely because one ASS track contains a box. On Windows and macOS, verify that mpv can access its configuration and font directories, but avoid changing broad folder permissions when ordinary files already play correctly.

3.3 Rule out URLs, yt-dlp, playlists, and network streams

For an online URL, yt-dlp may help mpv obtain separate video, audio, and subtitle resources. However, once a subtitle track is loaded, its visual style is generally handled by mpv and the subtitle renderer. A black background is therefore rarely repaired by changing audio backends, stream quality, or bandwidth settings.

Test the same subtitle track with a local file when legally and technically available. If only one remote subtitle track has the boxes, it may contain authored ASS styling. If mpv cannot load subtitles at all, then check terminal messages for yt-dlp availability, network access, expired URLs, authentication requirements, or unsupported media. These are loading problems, not styling problems.

Similarly, screenshot settings do not normally alter live subtitle rendering. A screenshot can include or exclude subtitles depending on the command used, but it does not create the on-screen background. Compare the live image with a screenshot only to determine whether the artifact is part of mpv's composed frame or an external display issue.

4. Use mpv Diagnostics to Find the Active Cause

Terminal output can reveal the selected subtitle track, subtitle format, missing fonts, rejected options, loaded scripts, and active profiles. Run mpv from a terminal instead of launching it only through a file manager.

4.1 Create a focused log

Use a temporary log file with increased subtitle-related verbosity:

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

If that output is excessively large, use a narrower message level supported by your build. Search the log for terms such as sub, ass, font, profile, script, error, and warn. Remove or redact private URLs, usernames, tokens, and local paths before sharing a log publicly.

Look for evidence rather than treating every warning as the cause. A missing requested font is relevant. An unrelated audio-device warning is not likely to explain an opaque subtitle background when audio still plays.

4.2 Use the stats overlay and track list

mpv's stats overlay can help identify active tracks and rendering details. The default binding is commonly i, although custom input bindings may replace it. Use mpv's track-switching controls or on-screen console to compare subtitle tracks in the same file.

If one track has boxes and another does not, the difference is probably in the subtitle content or format. If every track has identical boxes only under your normal configuration, a global subtitle option or script is more likely.

4.3 Check whether an option exists

When a command fails, do not assume the setting was applied. Run:

mpv --list-options

Search the output for the exact option name. This is safer than relying on old configuration snippets because option availability and accepted values can change over time. An unknown or malformed option may be ignored after an error, leaving the original symptom untouched.

5. Run a Clean Temporary Test Before Making Permanent Changes

Use one reproducible video, one subtitle track, and a short timestamp where the box is obvious. Then test in this order:

1. Run mpv --no-config "video.mkv".
2. Run the same command with --sub-ass-override=strip.
3. If needed, add a known installed font.
4. Test a transparent sub-back-color and a modest border size.
5. Only if the artifact affects multiple subtitle files, test --hwdec=no.
6. Re-enable your normal configuration and inspect profiles, bindings, and scripts one at a time.

Change only one variable between tests. Keep notes showing the command and result. This prevents a working fix from being hidden among unrelated changes.

Once a command removes the unwanted box without damaging subtitle readability, stop. Add only that option to the appropriate place. For a problem limited to ASS tracks or one type of content, prefer a profile or per-file setting over a global override.

6. Quick Fix Checklist

• Test the file with --no-config.
• Identify whether the selected subtitle is ASS, SSA, SRT, or another format.
• Test --sub-ass-override=strip to expose embedded ASS styling.
• Search configuration files for sub-back-color and oversized border or shadow values.
• Check profiles, included files, input.conf, and subtitle-related scripts.
• Try a known installed font when missing fonts or glyphs appear in the log.
• Compare another subtitle track or an external SRT file.
• Use --log-file and --msg-level to capture relevant warnings.
• Test --hwdec=no only when multiple files show compositing artifacts.
• Keep the first confirmed fix and avoid changing unrelated audio, HDR, stream, or screenshot settings.

7. Frequently Asked Questions

7.1 Why do only ASS subtitles have black boxes?

ASS subtitles can define opaque boxes, borders, shadows, drawings, and positioning inside the subtitle file. Plain SRT subtitles usually rely on mpv's general styling. If --sub-ass-override=strip removes the box, embedded ASS styling is the likely cause.

7.2 Does sub-back-color affect every subtitle format?

Not necessarily in the same way. General subtitle styling options primarily affect text styled by mpv, while ASS tracks can preserve their authored styles depending on sub-ass-override. Test both a plain subtitle and the original ASS track before making a global change.

7.3 Is a thick black outline the same as a black background?

No. A background fills a rectangular area behind the text. A border follows the shapes of the letters, although an extreme border size can merge into a box-like mass. Reduce sub-border-size to distinguish the two.

7.4 Will changing hardware decoding fix subtitle boxes?

Usually not. Hardware decoding affects video decoding, while subtitle backgrounds are commonly determined by subtitle styles. Test --hwdec=no only if transparency or compositing is wrong across multiple unrelated subtitle files.

7.5 Why does the clean command work but normal playback does not?

Your regular configuration is applying an option, profile, script, included file, or input binding that changes subtitle styling. Compare the clean command with your configuration and restore components individually until the responsible setting is identified.

7.6 Should I permanently use sub-ass-override=strip?

Use it permanently only if you prefer plain subtitles and accept losing ASS typesetting, signs, colors, positioning, and effects. If the issue affects one file or profile, apply the override narrowly. Stop troubleshooting once subtitles display correctly under the scope you actually need.