mpv Screenshots Black: How to Fix It

If mpv plays a video normally but saves a black screenshot, the player is usually displaying the frame through a path that its screenshot function cannot capture correctly. Common causes include hardware decoding or overlay behavior, an incompatible video output driver, a custom screenshot binding, an unwritable screenshot directory, an HDR conversion problem, or a script or profile that changes screenshot behavior. Online streams can add another complication if the frame is unavailable when the command runs. The steps below isolate these possibilities without deleting your configuration or changing many unrelated settings.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin by determining whether the black image comes from mpv itself, your configuration, or an operating system window-capture tool. Use a short local video that you know plays correctly. A common H.264 or H.265 file is suitable, but testing a second ordinary file can help rule out damaged or unusual media.

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

mpv --no-config --hwdec=no --vo=gpu test-video.mp4

Replace test-video.mp4 with the actual path. Quote a path containing spaces:

mpv --no-config --hwdec=no --vo=gpu "C:\Videos\test video.mp4"

On Linux or macOS, the equivalent may look like this:

mpv --no-config --hwdec=no --vo=gpu "/home/user/Videos/test video.mp4"

Pause on a clearly visible frame and press s. mpv should display a screenshot confirmation and save an image containing the current video frame. If this works, stop changing drivers or system packages. The successful clean test indicates that the media decoder and basic screenshot path work, so the cause is probably in your normal configuration, profile, input binding, shader, or script.

If the clean test still produces a black image, try a different video output driver:

mpv --no-config --hwdec=no --vo=gpu-next test-video.mp4

If your build does not support gpu-next, mpv will report that in the terminal. Do not assume that every build exposes every video output. You can inspect the available outputs with:

mpv --vo=help

Success means that an mpv-generated screenshot contains the expected frame. Once that happens, keep the working command as your reference and investigate only the differences between it and your normal launch.

2. Understand the Three Screenshot Modes

mpv has multiple screenshot commands, and they do not capture exactly the same content. Testing all three helps distinguish video-frame problems from subtitle, OSD, scaling, or window-composition problems.

• s takes a screenshot of the video, normally including visible subtitles.
• S takes a screenshot of the video without subtitles.
• Ctrl+s takes a screenshot of the window as displayed, including scaling, subtitles, and on-screen display elements.

The exact result can also be affected by custom input bindings. With an unmodified default configuration, test the commands on the same paused frame. If s and S are black but Ctrl+s works, the problem is likely in the direct video-frame capture path. Hardware decoding, overlays, the selected video output, filters, or HDR processing deserve attention.

If s works but Ctrl+s is black, the issue is more likely related to window capture, rendering, compositing, or support for the window screenshot command in the active video output. If only the subtitle-free S result works, inspect subtitle rendering, subtitle filters, scripts, and unusually complex subtitle formats.

Stop testing modes once you have identified one that reliably creates the image you need. There is no reason to replace a working screenshot mode merely because another mode behaves differently.

2.1 Verify Custom Input Bindings

A line in input.conf can replace mpv's default action for s, S, or Ctrl+s. Search your active input configuration for these keys and for commands containing screenshot, script-message, or run.

Useful explicit bindings include:

s screenshot video

S screenshot video

Ctrl+s screenshot window

The available screenshot command arguments depend on mpv's command interface, so compare custom lines with the manual for your installed build. A script may also intercept a key and perform its own image export. Temporarily comment out only the suspect binding or launch with --no-input-default-bindings while supplying a known test binding through a small temporary input file.

Success is a visible screenshot confirmation followed by a nonblack file. Once the explicit binding works, leave unrelated key mappings untouched.

3. Check Screenshot Options, Profiles, and Scripts

mpv can read options from a global configuration, a user configuration, file-specific settings, profiles, and command-line arguments. Wrapper applications may add still more arguments. A black screenshot that disappears under --no-config should be approached as a configuration comparison, not as a codec installation problem.

3.1 Inspect Screenshot Format and Directory Settings

Search mpv.conf and launch scripts for options beginning with screenshot-. Important examples include the screenshot directory, filename template, image format, compression, and tagging behavior. Use a simple writable directory and a standard format during testing:

--screenshot-directory="C:\Users\YourName\Pictures\mpv-test" --screenshot-format=png

On Linux or macOS:

--screenshot-directory="$HOME/Pictures/mpv-test" --screenshot-format=png

Create the directory first. Avoid testing with a network share, protected system folder, removable drive, cloud placeholder directory, or a path containing shell-sensitive characters. PNG is useful for diagnosis because it avoids questions about JPEG quality or encoder parameters.

A directory problem normally causes a write error or no output rather than a valid black image. However, it can be confused with the same symptom when an image viewer opens an older black file with the expected name. Check the file's modification time and make sure mpv reports the new destination.

3.2 Disable Suspect Profiles Selectively

Profiles can enable hardware decoding, shaders, filters, HDR options, or a different video output only for particular files or protocols. Run:

mpv --show-profile=profile-name

Replace profile-name with the profile you use. Inspect the expanded options for vo, gpu-api, gpu-context, hwdec, vf, lavfi-complex, glsl-shaders, and screenshot settings.

Test by omitting one profile or one suspect option at a time. Do not erase the entire config directory. Success means the screenshot becomes correct immediately after one option or profile is removed, while playback remains normal. At that point, stop and adjust that specific setting.

3.3 Test Without Scripts and Shaders

User scripts can redefine keys, seek just before capture, call an external screenshot utility, or process exported images. Shaders and filter graphs can also change which rendering stage contains the visible image. Use --no-config as the fastest clean comparison. If needed, make a temporary configuration containing only your screenshot directory and one video output.

When a script is suspected, disable only that script by moving it temporarily outside the scripts directory or by using a clean temporary config directory. Restore it after the test. If screenshots work without the script, check the script's documentation and reported errors rather than reinstalling mpv.

4. Test Video Output, Hardware Decoding, and HDR

The most useful targeted test for mpv screenshots that are black is disabling hardware decoding. Some GPU decoding and presentation paths use surfaces or overlays that are not copied in the way a particular screenshot mode expects.

4.1 Disable Hardware Decoding

Run the same file with:

mpv --hwdec=no test-video.mp4

If that works, compare it with your normal hwdec setting. You may keep software decoding for captures, select a different supported hardware-decoding method, or create a screenshot-oriented profile. Check available methods with:

mpv --hwdec=help

High-bitrate 4K or 8K files may use considerably more CPU when hardware decoding is disabled. The diagnostic goal is not necessarily to make hwdec=no permanent. It is to prove whether GPU-backed frames are involved.

Success means the same paused frame is visible in the saved image with hardware decoding off. Stop changing subtitle, audio, and network settings if this test fixes a local file, because those areas are unlikely to be the cause.

4.2 Compare Supported Video Outputs

Use mpv --vo=help and test a modern GPU output supported by your build. Common choices include gpu and, where available, gpu-next. Avoid copying obsolete driver recommendations from unrelated systems.

Hardware overlays can display video in a plane that desktop or window capture tools do not see. This often causes an operating system screenshot of the mpv window to show a black rectangle even though mpv's own s command works. In that case, use mpv's internal screenshot function instead of Print Screen, Snipping Tool, a desktop screenshot shortcut, or a window-capture application.

If an external window screenshot is required, changing the video output or disabling hardware acceleration may force composited rendering, but behavior varies by operating system, GPU driver, and display server. Success means both the player and chosen capture method show the same frame. Once one reliable capture route works, avoid unnecessary driver changes.

4.3 Isolate HDR and Tone Mapping

HDR video can appear black or nearly black when the captured frame is interpreted with incompatible color metadata or viewed in software that mishandles the image. Test an ordinary SDR file first. Then capture the HDR file as PNG and open it in more than one color-managed image viewer.

Temporarily remove custom shaders, LUTs, ICC settings, user filters, and manually forced color-space options. Also compare s with Ctrl+s. A window screenshot may represent the tone-mapped display result, while a video screenshot can follow a different stage of the rendering pipeline.

Success means the screenshot has visible detail and reasonable brightness in a reliable viewer. If only one viewer shows black, the file may be valid and the viewer may be mishandling its color information.

5. Check Tracks, Subtitles, Streams, and External Tools

A black capture is sometimes the correct result for the frame mpv has selected. Confirm that a video track is active and that the player is not showing a subtitle-only, audio-only, attached-picture, or temporarily unavailable stream.

5.1 Verify the Active Video Track

Use mpv's track list in the console or interface. You can also run:

mpv --term-status-msg="Video: ${video-format} Track: ${vid}" test-video.mp4

For a simpler practical check, press the key bound to the track list or inspect terminal startup output. Make sure a real video track is selected and not disabled with --vid=no. Custom profiles for music, playlists, cover art, or subtitle workflows may intentionally disable video.

Subtitle settings generally do not turn the underlying video screenshot black. If S works but s fails, however, temporarily disable subtitles with --sid=no and remove subtitle-specific filters or scripts. Audio track selection and audio backends do not normally control screenshot pixels. Investigate audio only if a script waits for playback state or a broken media timeline prevents the expected frame from being decoded.

5.2 Test Online URLs Separately

For online media, first test whether screenshots work with a local file. If local captures work, do not modify GPU drivers yet. The difference may involve yt-dlp, URL resolution, authentication, network interruption, seeking, or a stream that has not delivered a decodable video frame.

Start the URL from a terminal and wait until motion is visibly playing before pausing and pressing s. Review whether mpv selected an audio-only format. If mpv uses yt-dlp, ensure the configured executable path points to a trusted, functioning installation. Do not download replacement binaries from random sites.

Live streams and network sources may return black frames during reconnects, discontinuities, ad transitions, or unavailable segments. Test several seconds later and compare with a local copy that you are legally permitted to save. Protected video may restrict access to decoded frames. Do not attempt to bypass DRM or access controls.

Success means a screenshot works after the stream has delivered a visible decoded frame. If local files work consistently but one URL does not, treat it as a source-specific limitation rather than a general mpv failure.

6. Check Permissions, Paths, Drivers, and Display Systems

Confirm that the screenshot destination exists and is writable by the account running mpv. On Windows, protected folders, security software, Controlled Folder Access, or launching mpv under a different account can block writes. On Linux and macOS, directory ownership, sandboxing, application permissions, or read-only mounts may be relevant.

Use a plain local directory under your home folder. If a terminal command contains spaces, parentheses, ampersands, dollar signs, or backslashes, quote it according to your shell. Incorrect shell quoting can send part of a screenshot template or URL to mpv as a different argument.

If mpv's own screenshot is black across multiple ordinary files even with --no-config --hwdec=no, update the GPU driver through the operating system, computer manufacturer, or GPU vendor's official channel. On Linux, compare sessions only if practical: X11 and Wayland can impose different restrictions on external window capture. Those restrictions do not necessarily affect mpv's internal video screenshot command.

An audio backend is rarely responsible for a black screenshot. Changing PulseAudio, PipeWire, ALSA, CoreAudio, or Windows audio output is not a useful first step unless terminal output shows that playback never advances because of an audio initialization failure. Keep the investigation tied to the observed frame and log messages.

7. Use Logs and Runtime Information to Find the Exact Cause

Run mpv from a terminal so errors remain visible. A useful diagnostic command is:

mpv --no-config --hwdec=no --msg-level=all=v --log-file=mpv-screenshot.log test-video.mp4

Reproduce the black screenshot, close mpv, and search the log for terms such as screenshot, vo, gpu, hwdec, error, failed, and permission. Verbose logs can contain local file paths and URLs, so remove private data before sharing them publicly.

Use --show-profile to inspect a named profile. During playback, mpv's stats overlay can show the selected video output, decoder, dropped frames, filters, and timing information, depending on the active stats script and build. The track list confirms whether video, audio, and subtitle streams are selected.

Look for a specific difference rather than treating every warning as fatal. For example, a failed screenshot write points to a path or permission issue, while hardware surface or video output errors justify testing --hwdec=no or another supported VO. Once the log identifies a concrete cause and the screenshot works after that single correction, stop changing options.

8. Run a Clean Temporary Test Before Permanent Changes

Use this sequence to avoid introducing several variables at once:

1. Choose a short, ordinary local video with a visible video track.
2. Create a writable screenshot directory under your user account.
3. Run mpv with --no-config --hwdec=no --vo=gpu.
4. Pause on a bright frame and test s, S, and Ctrl+s.
5. Confirm the new files by checking their timestamps and opening them in a second viewer.
6. If successful, add your normal hardware decoding option and retest.
7. Add your preferred video output, shaders, filters, profile, and scripts one category at a time.
8. Stop immediately when the black screenshot returns. The last restored category contains the likely cause.

This controlled approach is faster than replacing codecs, reinstalling unrelated software, or deleting your complete mpv configuration. Keep a copy of the working command so you can verify future changes.

9. Quick Fix Checklist

• Test a local SDR file with mpv --no-config --hwdec=no --vo=gpu.
• Compare s, S, and Ctrl+s on the same paused frame.
• Use mpv's screenshot command instead of an operating system window capture.
• Set a simple, existing, writable screenshot directory.
• Check input.conf for replaced screenshot bindings.
• Inspect profiles for hardware decoding, video output, filters, and shaders.
• Disable scripts and custom shaders temporarily, one category at a time.
• Verify that a real video track is selected.
• Test local media before diagnosing yt-dlp, URLs, or network streams.
• Open HDR screenshots in another capable image viewer.
• Use --msg-level=all=v and --log-file to capture errors.
• Stop when one controlled change produces a correct screenshot.

10. Frequently Asked Questions

10.1 Why Is the mpv Window Visible but My Desktop Screenshot Is Black?

The video may be displayed through a hardware overlay or GPU presentation path that a desktop capture tool cannot read. Try mpv's internal s command. If that succeeds, mpv is working and the limitation belongs to the external window-capture path.

10.2 Why Does Ctrl+s Work When s Produces Black?

Ctrl+s captures the displayed window result, while s targets the video screenshot path. A difference suggests a problem involving decoded surfaces, hardware acceleration, filtering, or the active video output. Test --hwdec=no and a supported GPU VO.

10.3 Can Subtitles Cause a Black Screenshot?

Ordinary subtitles should not make the entire video frame black. Compare s with S and test --sid=no. If only captures with subtitles fail, inspect subtitle scripts, filters, and complex subtitle rendering rather than changing the audio configuration.

10.4 Why Are Screenshots Black Only for HDR Videos?

The capture may contain HDR or color information that an image viewer interprets incorrectly, or custom tone-mapping settings may affect the captured stage. Test an SDR file, remove custom shaders and color options temporarily, use PNG, and open the result in another color-aware viewer.

10.5 Why Does the Problem Affect Only Online Videos?

The URL may resolve to audio only, the stream may not have delivered a complete video frame, or yt-dlp may be unavailable or misconfigured. Confirm that local screenshots work, wait for visible playback, inspect the selected tracks, and review terminal output for URL or network errors.

10.6 Should I Reinstall mpv or Delete My Configuration?

Not initially. A successful --no-config test proves that the installed player can capture frames and points to a specific setting, binding, profile, script, or shader. Compare options methodically. Reinstallation is appropriate only after clean tests fail across ordinary local files and logs indicate damaged or missing application components.