mpv Black Screen Audio Works: How to Fix It

When mpv plays audio but shows a black video window, the player is usually opening the media successfully but failing somewhere in the video path. The cause might be a file with no usable video track, an incorrect track selection, a configuration option, a script or input binding, an incompatible video output backend, hardware decoding, an unsupported pixel format, HDR processing, a damaged file, or a problem specific to an online stream. The fastest approach is not to change everything at once. First reproduce the symptom with a clean command, then isolate the file, track, decoder, video output, configuration, and operating-system layers in that order.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin with one local media file that you are legally allowed to play and that you know contains visible video. A familiar H.264 MP4 or similar ordinary file is a better diagnostic sample than an HDR title, high-bitrate stream, unusual codec, playlist, or online URL.

Open a terminal or command prompt and run mpv without loading your normal configuration:

mpv --no-config "path/to/test-video.mp4"

On Windows, use the complete path if necessary:

mpv --no-config "C:\Users\YourName\Videos\test-video.mp4"

On Linux or macOS, quote paths containing spaces:

mpv --no-config "/home/yourname/Videos/test video.mp4"

This test bypasses mpv.conf, input.conf, user profiles, and most customization-related causes. It does not assume that hardware decoding is enabled. If the picture appears, mpv and the media are fundamentally usable, so stop changing system drivers or installing software. The problem is probably in your normal configuration, profile, script, shader, or launch command.

If the clean command still produces audio with a black window, try a second known-good local file. The result separates a file-specific limitation from a broader output or decoding problem:

• If only one file fails, inspect that file's tracks, codec, pixel format, and integrity.
• If all local files fail, focus on video output, decoding, GPU drivers, and display integration.
• If local files work but URLs fail, focus on the URL, network, yt-dlp, authentication, and selected stream formats.

1.1 Distinguish black video from an audio-only file

Some files have cover art, subtitles, or an audio track but no continuous video track. Others use misleading extensions or contain multiple editions with different track layouts. Inspect the track list in mpv's terminal output or press i for the information overlay and, where available, use the interactive track controls.

You can also run:

mpv --no-config --vid=auto "path/to/file"

Look for a video track identified as Video in the terminal. If no video track exists, a black or static window is not a video-rendering failure. Success here means confirming that the file actually contains a selectable video stream. Once that is established, stop changing output settings until you have checked track selection.

2. Check Options, Tracks, Profiles, Scripts, and Output Settings

If --no-config works, compare the clean result with your normal launch. Reintroduce customizations in small groups rather than editing or deleting the entire configuration directory. Back up individual files before changing them.

2.1 Correct an absent or incorrectly selected video track

An explicit --vid=no, video=no, or unsuitable track ID can disable video while allowing audio to continue. This option may be present in mpv.conf, a profile, a desktop shortcut, an application launcher, a wrapper script, or an IPC client command.

Test automatic video selection:

mpv --no-config --vid=auto "path/to/file"

During playback, the default _ key cycles video tracks in standard mpv bindings. Custom input.conf files can replace that behavior, so do not rely on the key if you have changed bindings. You can inspect the active tracks through the console output or stats interface instead.

Subtitle-only and audio-only confusion can also occur when a playlist entry points to a subtitle file, an image, an audio rendition, or a manifest containing no selected video rendition. Verify the current playlist item and track list. Success means mpv reports a video track as selected and displays moving frames. Stop changing track options when that happens.

2.2 Inspect mpv.conf, input.conf, and profiles

Search your configuration for settings that affect whether or how video is rendered. Relevant examples include:

• vid=no or a fixed vid value
• vo= selecting a backend incompatible with the current system
• hwdec= forcing a problematic hardware decoder
• vf= adding a video filter chain
• glsl-shaders= loading custom shaders
• profile= activating a profile unexpectedly
• video-rotate, cropping, scaling, or geometry settings producing a misleading result
• lavfi-complex or complex filter graphs that fail to output video

Check input.conf for bindings that set vid no, change tracks, toggle filters, load profiles, alter opacity, or issue script messages. A key can appear harmless while invoking a script that changes playback properties.

Use mpv's profile inspection option when a profile may be involved:

mpv --show-profile=profile-name

Replace profile-name with the profile you want to inspect. Also review conditional profiles, which may activate based on filename, protocol, resolution, or other properties. Comment out one suspect option at a time, restart mpv, and retest. Success means the image returns immediately after one specific option or profile is removed. Preserve that finding instead of making unrelated changes.

2.3 Disable scripts and shaders temporarily

A Lua or JavaScript extension can change tracks, filters, output properties, playlist behavior, or IPC state. Temporarily bypass normal configuration with --no-config. If you need finer isolation, temporarily move only the suspected script out of the scripts directory or launch without loading it, depending on how it is configured.

Remove custom shaders for one test:

mpv --no-config --glsl-shaders-clr "path/to/file"

A clean test is preferable because a shader may be loaded by a profile rather than the main option list. If removing a shader restores video, verify that the shader supports your current mpv video output, GPU API, and input format before enabling it again.

2.4 Test hardware decoding without assuming it is enabled

Hardware decoding is only one possible cause. First determine whether your normal command or configuration enables hwdec. Then force software decoding for a controlled test:

mpv --no-config --hwdec=no "path/to/file"

If software decoding displays video, the file is decodable but the active hardware-decoding path, GPU driver, device selection, or zero-copy interoperation may be failing. You can next try mpv's generally recommended automatic hardware-decoding mode:

mpv --no-config --hwdec=auto "path/to/file"

If hwdec=no works and hwdec=auto gives a black screen, keep hardware decoding disabled temporarily. That is a valid fix, although CPU use may rise with high-resolution or high-bitrate video. Do not keep changing unrelated subtitle or audio settings after this test identifies the boundary.

2.5 Test the video output backend

The video output driver presents decoded frames through the operating system and GPU stack. A decoder can produce frames while an incompatible or malfunctioning output backend still displays black.

Test mpv's modern GPU renderer:

mpv --no-config --vo=gpu-next "path/to/file"

If that fails, test the established GPU output:

mpv --no-config --vo=gpu "path/to/file"

For diagnostic purposes, inspect the video outputs available in your build:

mpv --vo=help

Choose only a backend listed by your installed mpv build. Platform support varies, so copying a backend name from another operating system may produce an error or fallback rather than a useful test. A fallback software-oriented output may help identify a GPU presentation problem, but availability differs by build.

Success means one listed output backend consistently renders the same file that appeared black with another backend. Set the working vo only after confirming it with several files, including one ordinary SDR file.

2.6 Isolate unsupported pixel formats and HDR processing

High-bit-depth, chroma-subsampled, RGB, Dolby Vision, or other unusual formats can expose limitations in a decoder, filter, hardware device, shader, or display path. HDR content can also appear extremely dark, but a completely black frame suggests checking whether frames are being decoded and presented.

Test the problem file using software decoding and a clean renderer:

mpv --no-config --hwdec=no --vo=gpu-next "path/to/hdr-or-unusual-file"

Then compare it with a basic SDR file. If SDR works but the unusual file does not, review the terminal output for pixel-format conversion, decoder, shader-compilation, or GPU texture errors. Remove custom tone-mapping options, filters, and shaders for the test. Success is visible video with reasonable brightness and colors. Once achieved, add HDR or shader options individually.

2.7 Check screenshots without confusing them with live output

A screenshot can help determine whether decoded video exists before or during presentation, but screenshot behavior depends on the selected screenshot mode and processing stage. If screenshots are black while playback is visible, inspect screenshot format, directory permissions, shader behavior, and whether the image viewer is handling HDR data correctly. If playback is black but a screenshot contains a valid frame, the decoder is probably working and the presentation path deserves closer attention.

Confirm that mpv can write to the screenshot directory and that a binding has not changed the screenshot command or mode. Do not treat one black screenshot as proof that the source contains black frames.

3. Check the Operating System, File, URL, and External Tools

3.1 Verify GPU drivers and the display server

If every video remains black even with --no-config, test whether the behavior began after a GPU driver, operating-system, display-server, dock, remote-desktop, or monitor change. On Linux, compare sessions only if both Wayland and X11 are already available and supported by your system. On laptops with multiple GPUs, ensure mpv is not being launched on a device that cannot present to the active display.

Update GPU drivers through the operating system, hardware vendor, or trusted distribution repositories. Avoid random driver bundles and codec packs. A successful system-level fix makes a clean mpv command display multiple ordinary local videos without special filters.

3.2 Check shell quoting and file paths

A malformed path can cause mpv to open a different playlist entry, interpret part of a filename as an option, or load an unexpected external subtitle or audio file. Put paths and URLs in quotes. Use -- before a filename beginning with a hyphen:

mpv --no-config -- "-sample-video.mkv"

For external audio or subtitle options, verify that each path targets the intended file. An external audio track does not add missing video, and a subtitle file opened as the main item does not become a movie.

3.3 Separate audio-backend messages from the video problem

Because audio is already playing, the audio backend is usually not the cause of a black picture. However, device resets, clock problems, or wrapper applications can complicate synchronization. Test video without audio only as a diagnostic step:

mpv --no-config --audio=no "path/to/file"

If the picture appears only when audio is disabled, collect a log and investigate synchronization, device, or application integration messages. Do not assume that changing volume or reinstalling audio codecs will repair video output.

3.4 Diagnose online URLs, network streams, and yt-dlp

If local files work, mpv's core output path is functioning. For an online URL, confirm that the URL is still valid, reachable, and permitted for playback. Some websites require a current yt-dlp installation, while direct network streams may fail because of expired tokens, authentication, redirects, TLS issues, or server-side format changes.

Run the URL from a terminal with a clean configuration:

mpv --no-config "https://example.com/video-or-stream"

If the terminal reports yt-dlp errors, verify which executable mpv finds and obtain updates only from the project's official release channels or your trusted package manager. Do not use yt-dlp to bypass access controls or DRM.

A format selection can also result in an audio-only rendition. Remove custom ytdl-format settings for the test, or use automatic selection. Inspect the reported tracks after the stream opens. Success means the URL produces both selected video and audio tracks. Stop modifying GPU settings if the same mpv installation plays local video correctly and the URL supplies no video stream.

3.5 Identify damaged or unsupported media

A truncated file, malformed container, missing reference frames, unsupported codec profile, or corrupt video stream may still contain playable audio. Compare the file with another trusted player or media-inspection tool obtained from a reputable source. Check mpv's output for decoder initialization failures and repeated corrupt-packet messages.

If only one file fails across players, obtain a valid copy from its legitimate source or re-encode media you own using a trusted tool. Installing an indiscriminate codec pack is not an appropriate mpv fix because mpv normally uses its bundled or linked FFmpeg decoding capabilities.

4. Use mpv Diagnostics to Find the Failing Layer

Terminal output often states whether mpv selected video, initialized a decoder, enabled hardware acceleration, created a GPU context, or rejected a pixel format. Launch mpv from a terminal instead of by double-clicking the file so the messages remain visible.

4.1 Increase message detail and save a log

Create a diagnostic log with more detail:

mpv --no-config --msg-level=all=v --log-file=mpv-black-screen.log "path/to/file"

The log can contain local paths, URLs, query tokens, usernames, or other private information. Review and redact it before sharing. Search for terms such as Video, VO, hwdec, error, failed, pixel format, and shader.

A useful log should answer four questions:

1. Was a video track detected and selected?
2. Did the video decoder initialize and produce frames?
3. Was a video output and GPU context created?
4. Did presentation fail after decoding?

Do not treat every warning as the cause. Compare the failing log with a successful clean playback log and focus on differences near video initialization.

4.2 Use the stats overlay and track list

Press i during playback to view basic information. The default I binding usually toggles a persistent information display, although custom bindings may differ. Stats can reveal the selected codec, dimensions, frame rate, dropped frames, output information, and hardware-decoding state.

If dimensions and frame timing are present but the window remains black, output or presentation becomes more likely. If no video information appears, inspect track selection and source format first. Use the track list to verify that the selected item is not audio-only.

4.3 Compare normal and clean launches

Run the same file twice and save separate logs:

mpv --log-file=normal.log "path/to/file"

mpv --no-config --log-file=clean.log "path/to/file"

If clean playback works, compare the reported options, profiles, scripts, shaders, hardware decoder, and video output. This is more reliable than guessing which config line matters.

5. Run a Clean Temporary Test Before Making Permanent Changes

Use a small test matrix and record each result. Change one variable per run:

1. Play a known-good SDR local file with --no-config.
2. Play the failing file with --no-config.
3. Play it with --no-config --hwdec=no.
4. Test --vo=gpu-next, then --vo=gpu if available.
5. Confirm --vid=auto and inspect the track list.
6. For URLs, verify that local playback still works and remove custom format selection.
7. Reintroduce profiles, scripts, filters, and shaders one at a time.

Stop as soon as one controlled change reliably restores the image. Repeat that exact test with two or three files before saving it in mpv.conf. Permanent changes made too early can hide the original cause or create a second mpv player issue.

6. Quick Fix Checklist

• Run mpv --no-config "file" with a known-good local SDR video.
• Confirm that mpv detects and selects a real video track.
• Remove vid=no or an invalid fixed video-track ID.
• Test --hwdec=no even if you are unsure whether hwdec is active.
• Test --vo=gpu-next and --vo=gpu when listed by --vo=help.
• Disable custom shaders, filters, scripts, and conditional profiles temporarily.
• Compare ordinary SDR playback with the failing HDR or unusual-format file.
• Quote file paths and verify external subtitle and audio paths.
• For URLs, remove custom yt-dlp format selection and confirm a video rendition exists.
• Save a verbose log and identify whether failure occurs at track, decode, or output initialization.

7. Frequently Asked Questions

7.1 Why does mpv play sound but show no video?

mpv may have selected no video track, opened an audio-only source, failed to decode the video's format, or decoded frames that the selected output backend could not present. Configuration options, scripts, shaders, hardware decoding, HDR processing, GPU drivers, and online format selection can each cause this symptom. A --no-config test with a known-good local file provides the quickest separation.

7.2 Should I disable hardware decoding first?

Test it, but do not assume it is the cause. Run --no-config --hwdec=no. If video appears, compare that result with --hwdec=auto. If both remain black, focus on track selection, software decoder errors, video output, pixel formats, and the source itself.

7.3 What if gpu-next shows a black screen?

Check mpv --vo=help, then test another output supported by your build, such as --vo=gpu. Also combine the test with --hwdec=no so hardware decoding and presentation are not changed simultaneously. If only one backend works, use it temporarily and investigate GPU driver or display-server compatibility.

7.4 Can subtitles cause a black screen?

Ordinary subtitles do not normally replace valid video with black. However, a subtitle file may have been opened as the main playlist item, a script or complex subtitle-related filter may alter rendering, or a playlist may pair subtitles with an audio-only source. Confirm the current item and selected video track, then test without configuration.

7.5 Why do local files work but online videos remain black?

This usually moves suspicion away from the basic GPU output path. The URL may provide an audio-only rendition, require an updated yt-dlp, contain expired authorization data, or use a format your current path cannot decode. Inspect the terminal output and track list, remove custom ytdl-format settings, and test a direct legal stream if available.

7.6 When should I stop troubleshooting?

Stop changing settings when the same controlled command displays video reliably across several representative files. If one file alone remains black, investigate that file rather than rewriting the global configuration. If one option restores every file, save only that verified change and keep your diagnostic log for reference.