mpv hwdec Black Screen: How to Fix It

When mpv plays audio but shows a black video after hardware decoding is enabled, the failure is usually between the selected hardware decoder, GPU driver, video output backend, and display system. A conflicting configuration, profile, script, shader, HDR option, or track selection can produce the same symptom. The safest approach is to prove that hardware decoding causes the black screen, identify the decoder and output backend mpv actually selected, and change one setting at a time. This guide covers Windows, Linux, and macOS without requiring codec packs, untrusted downloads, or destructive configuration resets.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin with a local video file that normally plays correctly. A local file removes yt-dlp, network access, expiring stream URLs, and remote server behavior from the first test. Choose a short, ordinary file if possible rather than beginning with HDR, Dolby Vision, AV1, 10-bit, or unusually high-resolution media.

1.1 Test without hardware decoding

Open a terminal, Command Prompt, or PowerShell window and run mpv without loading your normal configuration:

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

On Windows, use a correctly quoted path such as:

mpv.exe --no-config --hwdec=no "C:\Videos\test file.mkv"

If this command displays video, software decoding and the basic video output path work. Hardware decoding, or an option activated alongside it, is now the primary suspect. Stop investigating subtitles, audio devices, yt-dlp, and network access unless those components cause a separate problem.

If the clean software-decoding test is also black, the issue is broader than hardware decoding. Test another file, inspect track selection, and try a different video output backend before concluding that hwdec is responsible.

1.2 Reproduce the failure cleanly

Next, enable automatic hardware-decoder selection while continuing to ignore all configuration files:

mpv --no-config --hwdec=auto "path/to/video.mkv"

A meaningful reproduction has two clear results: the first command shows video, while the second produces black output. That strongly indicates a decoder, driver, backend, or zero-copy interoperability problem.

Do not change several permanent settings yet. A clean comparison gives you a known baseline and prevents unrelated configuration edits from hiding the real cause.

1.3 Check whether Ctrl+h caused the change

In mpv's default input bindings, Ctrl+h cycles hardware decoding. An accidental press can therefore change behavior during playback. Press Ctrl+h while watching the on-screen message, or restart mpv with an explicit --hwdec=no option.

Success means video returns immediately or after reopening the file with hardware decoding disabled. If that happens, stop changing unrelated playback settings. You have confirmed the category of failure and can decide whether software decoding is acceptable or whether you want to test a compatible hardware mode.

2. Check Options, Profiles, Scripts, and Playback State

A clean command can work even when an ordinary mpv launch fails. In that case, the problem is probably in mpv.conf, input.conf, an auto profile, a script, a shader, or another user-loaded component.

2.1 Inspect the effective hardware-decoding option

Search your configuration for hwdec. Common entries include hwdec=auto, a platform-specific decoder, or a copy-back variant. Also inspect included configuration files and profiles that activate only for particular codecs, resolutions, protocols, or file extensions.

Check input.conf for a custom binding that changes hwdec. A script can also modify properties after startup, so the initial command line does not always describe the final playback state.

Temporarily comment out only the relevant line rather than deleting an entire configuration directory. Restart mpv and replay the same file. Success means the video appears with the targeted option disabled. At that point, keep the working setting and avoid unrelated edits.

2.2 Understand copy-back and zero-copy modes

Hardware-decoding modes differ in how decoded frames reach mpv's renderer. In a zero-copy or direct rendering path, frames may remain in GPU-managed memory. This can be efficient, but it requires compatible sharing between the decoder API, graphics backend, driver, and display system.

Copy-back decoding transfers decoded frames back into normal system memory before rendering. It can add overhead, but it often avoids GPU-frame interoperability problems. The exact available names depend on the operating system, mpv build, FFmpeg support, hardware, and driver.

Test modes reported as available by your installation rather than copying a platform-specific value blindly. Representative tests include:

mpv --no-config --hwdec=auto-copy "path/to/video.mkv"
mpv --no-config --hwdec=d3d11va-copy "path/to/video.mkv"
mpv --no-config --hwdec=vaapi-copy "path/to/video.mkv"
mpv --no-config --hwdec=nvdec-copy "path/to/video.mkv"

Not every mode exists on every build. An error stating that a mode is unavailable is useful diagnostic information, not a reason to install a random codec pack. Success means copy-back displays the same file reliably while the direct mode remains black. If so, use the copy-back mode and stop testing more invasive changes unless its performance is inadequate.

2.3 Separate D3D11VA, VAAPI, and NVDEC

• D3D11VA is primarily associated with hardware video decoding through Direct3D 11 on Windows.
• VAAPI is commonly used on Linux with supported Intel, AMD, and other compatible driver stacks.
• NVDEC uses NVIDIA's decoding facilities where the mpv and FFmpeg build supports them.

These are not interchangeable labels. A decoder can initialize successfully while frame transfer to the chosen video output backend fails. That is why the terminal log and a copy-back comparison are more useful than assuming that a named API must work because the GPU supports the codec.

2.4 Disable shaders and HDR processing for one test

Custom GLSL shaders, GPU scaling chains, tone-mapping settings, ICC profiles, and HDR output options affect rendering after decoding. Temporarily test the failing file with --no-config and no custom shaders. For HDR media, also compare against an ordinary SDR file encoded with a widely supported codec.

If SDR works with the same hwdec mode but HDR remains black, investigate the renderer, tone mapping, display capabilities, bit depth, and operating system HDR state. Do not treat that narrower result as proof that all hardware decoding is broken.

2.5 Verify video tracks and subtitle behavior

Display the track list and confirm that a video track is selected. A file can contain cover art, attached pictures, multiple video tracks, or unusual defaults. Use mpv's track controls or explicitly select the intended video track after identifying its ID.

Subtitles rarely cause a hardware-decoder black screen by themselves, but complex subtitle rendering or scripts that manipulate visibility can complicate testing. Temporarily disable subtitles with --sid=no. If video returns only when subtitles are disabled, you have isolated a rendering interaction rather than a decoder-selection failure.

3. Check the GPU Driver, Output Backend, and Operating System

Hardware decoding depends on more than the codec. The GPU driver must expose a supported decoding API, and mpv's selected video output and GPU context must be able to consume the resulting frames.

3.1 Look for a driver and backend mismatch

Update the GPU driver through the GPU vendor or operating system's trusted update mechanism. On laptops with integrated and discrete GPUs, confirm that mpv is not decoding on one adapter while presenting through an incompatible path on another. Testing mpv on the laptop's internal display can help distinguish a multi-GPU or external-display issue.

On Windows, compare the normal automatic backend with an explicitly supported GPU API only when the log suggests a backend problem. On Linux, note whether the session uses Wayland or X11 and which GPU owns the display. On macOS, keep the operating system current and test the default VideoToolbox-related automatic selection before forcing uncommon modes.

Success means the decoder initializes, frames are rendered, seeking works, and the terminal no longer reports failed frame mapping or device interoperation. Once playback is stable, stop switching backends.

3.2 Test the video output without making it permanent

mpv normally makes reasonable automatic choices, so use output-driver changes as temporary diagnostics. First list the video outputs recognized by your build:

mpv --vo=help

Then test an available output explicitly. Modern builds commonly expose GPU-oriented outputs, but names and support can vary. If one output works and another is black, keep the working test result and inspect why your configuration forced the failing output.

Avoid permanently selecting a legacy or fallback output merely because it opens a window. Confirm normal scaling, subtitles, color, HDR handling where applicable, and seeking before declaring the problem solved.

3.3 Check permissions, paths, and security controls

Permissions are less likely when audio plays from a local file, but they matter for external shaders, subtitle files, scripts, sockets, and network resources. Verify that mpv can read every referenced file. Quote paths containing spaces or shell-sensitive characters. On macOS, test whether terminal or file-access privacy controls affect files in protected folders.

Do not run mpv as administrator or root merely to fix video output. Elevated execution can create new configuration and security problems without correcting decoder interoperability.

3.4 Treat audio as a secondary diagnostic

If audio continues while the image is black, the audio backend is probably not the cause. If playback stalls completely, however, test with --audio=no to determine whether device initialization is blocking playback. Success in that test identifies a separate audio-output problem, not an hwdec rendering fix.

4. Use mpv Logs to Identify the Selected Decoder

The terminal output usually reveals whether mpv selected software decoding, D3D11VA, VAAPI, NVDEC, VideoToolbox, or another supported path. It can also show fallback behavior, unsupported pixel formats, device creation errors, and failed frame transfers.

4.1 Increase useful log detail

Run a clean test with targeted verbosity and save the complete output:

mpv --no-config --hwdec=auto --msg-level=vd=debug,vo=debug --log-file=mpv-hwdec.log "path/to/video.mkv"

Open the log as text and search for terms such as hwdec, Using hardware decoding, decoder, vo, gpu, failed, and fallback. Exact wording differs across builds, so focus on the sequence: device creation, decoder selection, frame format, video output initialization, and any failure immediately afterward.

Success looks like a hardware decoder being selected and decoded frames reaching the renderer without repeated errors. If the log shows automatic fallback to software decoding and video works, hardware decoding did not actually succeed even though playback continued.

4.2 Inspect profiles and runtime state

Use --show-profile to inspect a named profile when you suspect it changes hwdec or rendering settings:

mpv --show-profile=profile-name

During playback, mpv's stats overlay can show decoder and rendering information. The default i binding displays statistics, while additional pages or persistent display behavior may depend on the active stats script and bindings. Compare what the overlay reports during a working software-decoding run and a failing hardware-decoding run.

4.3 Check scripts and IPC changes

Lua or JavaScript scripts and external IPC clients can change mpv properties after startup. Temporarily run --no-config, which provides a clean baseline without normal user configuration and scripts. If that works, restore components in small groups: core configuration first, then profiles, scripts, shaders, and external controllers.

Do not assume a script is harmless because it is unrelated by name. Playback managers, quality selectors, HDR helpers, and auto-profile tools can all modify video properties.

5. Isolate Local Files, Online URLs, and Media Limitations

5.1 Test online playback separately

If local files work but an online URL is black, hardware decoding may not be the only variable. The remote format may use a different codec, bit depth, profile, or resolution. mpv may also rely on yt-dlp for URL extraction.

Run the URL from a terminal and inspect the selected video format and decoder. Verify that the configured yt-dlp path points to a trusted, working installation. An extraction error, unavailable format, authentication requirement, or expired URL should be fixed at the source rather than treated as a GPU problem.

For network streams, test a permitted direct stream URL and watch for timeouts, discontinuities, or missing video tracks. If the same downloaded or local sample plays but the live stream does not, examine network and stream-format behavior before changing the GPU driver again.

5.2 Compare codecs and bit depths

A GPU may decode H.264 successfully but fail or lack support for HEVC, AV1, 10-bit video, 4:2:2 chroma, or a particular profile. Hardware support also depends on the driver and decoding API. Test multiple known-good files and note their codecs rather than concluding that mpv is universally broken.

If only one format fails, use software decoding for that media or configure a selective profile after confirming the exact limitation. Success means supported formats use hardware decoding while unsupported ones fall back cleanly instead of producing a black screen.

5.3 Distinguish screenshots from displayed video

A screenshot problem does not necessarily mean playback frames are missing. Hardware-decoded frames, subtitles, and on-screen controls can be captured differently depending on the screenshot option and rendering path. If video is visible but saved screenshots are black, test a screenshot with software decoding and review your screenshot format, directory, and inclusion settings.

Conversely, if the window is black but a screenshot contains the correct frame, the decoder is producing an image and the issue is likely presentation, compositor, overlay, or display-backend related.

6. Run a Clean Temporary Test Before Permanent Changes

Use one file, one command, and one variable at a time. A practical test sequence is:

1. Run --no-config --hwdec=no.
2. Run --no-config --hwdec=auto.
3. Try an available copy-back mode.
4. Capture a debug log for the failing mode.
5. Test an ordinary SDR file and then the original file.
6. Restore the main configuration without scripts or shaders.
7. Restore profiles, scripts, and shaders individually.

Record whether video appears, which decoder is selected, and whether seeking remains stable. Do not evaluate only the first frame. A usable fix should survive seeking, pausing, fullscreen transitions, subtitle display, and replaying the file.

Stop changing settings as soon as you obtain reliable playback and understand which change produced it. More tweaks can replace a proven fix with a new, harder-to-diagnose interaction.

7. Quick Fix Checklist

• Press Ctrl+h and watch whether disabling hardware decoding restores video.
• Confirm the file works with mpv --no-config --hwdec=no.
• Compare that result with --no-config --hwdec=auto.
• Try a supported copy-back mode if direct hardware decoding is black.
• Read terminal output to confirm which decoder mpv actually selected.
• Check mpv.conf, profiles, and input.conf for hwdec changes.
• Temporarily remove scripts, shaders, HDR overrides, and custom video outputs from the test.
• Update the GPU driver through a trusted official channel.
• Check for a D3D11VA, VAAPI, NVDEC, GPU-context, or multi-GPU mismatch.
• Compare an SDR file with the failing HDR or high-bit-depth file.
• Verify the intended video track is selected and briefly disable subtitles.
• Test local playback before troubleshooting yt-dlp, URLs, or network streams.
• Save a targeted debug log before making permanent backend changes.

8. Frequently Asked Questions

8.1 Why does mpv show audio but no video with hwdec enabled?

The decoder may be producing frames that the selected renderer cannot import or display. Common causes include a zero-copy interoperability failure, an incompatible GPU driver and output backend, a multi-GPU mismatch, or unsupported media characteristics. If --hwdec=no restores video, focus on that decoding and rendering path.

8.2 Is software decoding a valid permanent fix?

Yes, if CPU usage, battery consumption, temperature, and playback smoothness remain acceptable. Software decoding is also a useful fallback for formats that the GPU cannot decode reliably. You do not need to force hardware decoding merely because it is available.

8.3 Should I use auto, a specific decoder, or copy-back?

Start with auto. If it selects a direct mode that produces black output, test an available copy-back mode. Force a specific decoder only after the log confirms that it matches your operating system, GPU, driver, and mpv build. Keep the simplest mode that plays reliably.

8.4 Why does Ctrl+h fix the black screen?

The default Ctrl+h binding cycles hardware decoding. Disabling hwdec moves decoding to the CPU and bypasses the failing hardware-frame path. This is both a quick workaround and a strong diagnostic signal.

8.5 Why does only HDR or 10-bit video fail?

HDR and high-bit-depth media place additional requirements on codec support, pixel formats, tone mapping, graphics APIs, drivers, and the display chain. Test the file with software decoding and default rendering. If ordinary SDR works, investigate the media-specific path rather than replacing every mpv setting.

8.6 When should I report the problem?

Report it when a current trusted build and current driver reproduce the issue with --no-config, a legal shareable sample or precise media description, and a complete debug log. Include the operating system, GPU, display server where relevant, selected decoder, video output, and exact commands. A clean reproduction is far more useful than a large configuration file with many unrelated options.