mpv Green Screen Video: How to Fix It

An mpv green screen video problem usually appears as solid green frames, a green or purple tint, blocky corruption, flashing colors, or video that becomes damaged while audio continues normally. These symptoms most often point to a mismatch between the decoded pixel format and the video output path, failed hardware decoding, a GPU driver bug, an HDR or color-management conflict, or a custom shader or filter. Less commonly, the source file or network stream is damaged.

The fastest way to troubleshoot this mpv player issue is to separate mpv's default behavior from your personal configuration. Start with a clean software-decoding test, confirm what success looks like, and then restore one feature at a time. Stop as soon as playback is consistently correct. Changing additional settings after the symptom disappears can hide the real cause or introduce a second problem.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before editing mpv.conf, updating drivers, or replacing files, test the same video without your normal configuration. This bypasses custom profiles, scripts, shaders, filters, hardware-decoding settings, and most user-defined output choices.

1.1 Run mpv without configuration or hardware decoding

Open a terminal in the directory containing the affected file and run:

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

On Windows, use the complete path to mpv.exe if its directory is not in PATH:

"C:\Path\To\mpv.exe" --no-config --hwdec=no "C:\Videos\video-file.mkv"

On Linux or macOS, quote paths containing spaces:

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

This test asks mpv to ignore the normal configuration and decode the video in software. If the colors become correct, the media itself is probably usable. The likely cause is hardware decoding, a shader, a filter, an output option, a profile, or another customized setting.

If the green or corrupted output remains, try a second known-good file with a common codec and standard dynamic range. A short H.264 video is useful for comparison. If only one file fails, investigate that file's codec, bit depth, pixel format, or integrity. If every file fails, concentrate on the video output, mpv build, FFmpeg support, GPU driver, and operating-system graphics stack.

1.2 Compare local playback with the original source type

If the problem occurs with an online URL or network stream, do not assume that the network source and mpv's renderer are one issue. First test a local known-good file with the same clean command. Then, where you have legitimate access and the service supports playback through mpv, test the URL:

mpv --no-config --hwdec=no "https://example.com/video"

Correct local playback combined with broken URL playback suggests a stream, external-tool, format-selection, or network problem. Broken playback for both local and online media points more strongly toward decoding or rendering.

1.3 Know what counts as a successful test

A successful result means the picture has stable, natural colors throughout representative scenes. Test more than the opening logo. Seek forward, enter and leave fullscreen, and inspect bright and dark scenes. For HDR media, also check highlights and skin tones.

Once the clean test works, stop making broad system changes. Your next task is to identify the single customized feature that reintroduces the fault.

2. Check mpv Options and Customizations Directly Related to Green Video

mpv is highly configurable, so an option that worked with one GPU, driver, display server, or mpv build may behave differently after an upgrade. Inspect settings that affect decoding, pixel formats, color conversion, filtering, and rendering before changing unrelated subtitle or audio preferences.

2.1 Test software decoding before adjusting hardware decoding

Hardware decoding transfers some or all decoding work to the GPU or a platform video API. Green frames can appear when the decoder produces a surface that the selected renderer or driver mishandles. Confirm the difference with two controlled runs:

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

If software decoding works and automatic hardware decoding fails, you have isolated the problem to the hardware path. A practical immediate fix is to place this in mpv.conf:

hwdec=no

This can increase CPU usage, especially with 4K, high-frame-rate, high-bit-depth, or AV1 media. Watch for dropped frames and excessive CPU load. If software decoding remains smooth and colors are correct, it is a valid long-term workaround while you investigate the GPU driver or a different hardware-decoding method.

If you want hardware acceleration, test only methods documented and available for your operating system and build. Do not copy a platform-specific value blindly. Run mpv --hwdec=help to see recognized values, then test one at a time with --no-config. Success means correct colors, stable seeking, and no new frame drops or decoder errors.

2.2 Disable shaders, video filters, and post-processing

Custom GLSL shaders, interpolation settings, debanding combinations, VapourSynth filters, and user-defined video filters can corrupt color output or expose a driver problem. The clean --no-config test disables configuration-loaded customizations. If that fixes playback, inspect mpv.conf and any enabled profiles for entries involving:

• glsl-shaders or shader hooks
• vf video-filter chains
• VapourSynth or external filtering scripts
• Custom scaling, interpolation, debanding, or dithering
• Tone mapping, target color space, or HDR peak options
• Forced pixel formats or format-conversion filters

Comment out one related line or block at a time by placing # at the beginning of the line. Restart mpv after each change. If removing one shader or filter restores correct output, leave it disabled and stop changing other settings. You can later test an updated version of that component in isolation.

2.3 Examine output driver and graphics API choices

A forced video output driver, graphics API, or GPU context can cause green output when it does not cooperate with the installed driver or current display server. Look for options such as vo, gpu-api, and gpu-context in mpv.conf, profiles, launch scripts, and desktop shortcuts.

First let mpv select its normal output automatically:

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

If that works but your configured command does not, remove the forced output choice temporarily. Advanced users can compare output paths supported by their build, but each comparison should change only one option. Use mpv --vo=help and mpv --gpu-api=help rather than assuming that a particular backend exists.

Success means that colors remain correct during normal playback, seeking, fullscreen transitions, and window resizing. Once a working automatic or explicit output path is found, do not continue cycling through backends without a reason.

2.4 Check HDR and decoder output-format handling

HDR, 10-bit, 12-bit, chroma-subsampled, and hardware-surface formats place additional demands on the decoding and rendering chain. A green or purple cast can indicate that planes, bit depth, range, or color metadata are being interpreted incorrectly. Test an SDR file and the affected HDR file separately.

If SDR works but HDR fails, temporarily remove custom HDR, target-peak, tone-mapping, transfer, primaries, or display-profile settings. Do not force a color space merely because the image looks wrong. Incorrect overrides can mask bad metadata while making properly tagged files inaccurate.

Software decoding is especially useful here. If an HDR file works with --hwdec=no but not with hardware decoding, the decoder output format or zero-copy rendering path is the leading suspect. Keep software decoding as the temporary fix or test a supported hardware-decoding mode that copies decoded frames back to system memory, if one is listed by your build.

2.5 Inspect profiles, input bindings, scripts, and track settings

A profile may activate only for certain extensions, codecs, resolutions, or protocols. That can make the problem seem random. Search mpv.conf for profile sections in square brackets and review profile conditions. You can inspect a named profile with:

mpv --show-profile=profile-name

Input bindings can also change video properties during playback. Review input.conf for commands that cycle hardware decoding, video outputs, shaders, filters, color controls, or tracks. Temporarily test without configuration instead of deleting input.conf.

Scripts can alter filters, shaders, profiles, playlist behavior, and URL handling. Move only a suspected third-party script out of the scripts directory for a temporary test, or use a separate clean configuration directory. Avoid deleting the entire configuration folder because it contains useful evidence and may include unrelated settings you want to preserve.

Subtitle and audio selection rarely produce truly green video, but complex subtitle renderers, visualization scripts, or filter scripts can interact with rendering. Test with subtitles and audio disabled:

mpv --no-config --hwdec=no --sid=no --aid=no "video-file.mkv"

If this works while the normal clean test does not, re-enable one track at a time. Use mpv's track list to select a specific video, audio, or subtitle track. Stop when the responsible track or attached component is identified.

3. Check the Operating System, Driver, Source, and External Tools

If a clean mpv run still produces corrupted colors, the problem may sit below mpv or inside the source. Focus on components that participate directly in decoding and displaying the affected video.

3.1 Update or roll back the GPU driver carefully

GPU driver defects can affect hardware decoding, texture import, Vulkan, OpenGL, Direct3D, Wayland, X11, and HDR output. Obtain drivers through Windows Update, the GPU manufacturer's official support channel, your Linux distribution, or Apple's operating-system updates. Avoid third-party driver download sites.

If the issue began immediately after a driver update, a supported rollback may be more informative than another upgrade. Before changing the driver, preserve the clean software-decoding result. If --hwdec=no works, you can continue using mpv safely while planning the driver change.

After updating or rolling back, reboot when the platform requires it and repeat the exact clean hardware-decoding test. Success means hardware decoding now produces correct colors on multiple files. If it does not, return to software decoding rather than changing many mpv options simultaneously.

3.2 Compare display servers and display conditions where relevant

On Linux, behavior can differ between Wayland and X11 because the presentation and hardware-surface paths differ. If your desktop offers both sessions, a controlled comparison can reveal whether the problem is display-server-specific. This is a diagnostic test, not a requirement to abandon your preferred session.

On any platform, determine whether corruption appears only on an HDR display, an external monitor, or a particular refresh-rate configuration. Test the same file on the built-in display or in SDR mode when practical. A display-specific result points toward the graphics, HDR, or color-management path rather than the encoded video.

3.3 Verify the mpv build and FFmpeg capabilities

mpv relies on FFmpeg libraries for media decoding and demuxing. An old build may lack fixes or support needed for a newer codec, profile, pixel format, or container feature. Check the active executable with:

mpv --version

Make sure the command launches the build you intended to use. On systems with multiple installations, the terminal, desktop shortcut, and file association may point to different executables.

Update mpv through the official package source recommended for your platform or a trusted operating-system package manager. Do not install random codec packs. mpv builds normally use their included or linked FFmpeg support, and an unrelated system codec pack is unlikely to repair mpv's internal decoding path.

After updating, repeat the clean software test before restoring custom options. If the updated build works, add back your configuration gradually. Do not assume every old shader or script remains compatible.

3.4 Separate URL and yt-dlp failures from rendering failures

For supported online sites, mpv may use yt-dlp to resolve media URLs. If a local file plays correctly but an online URL produces bad or unexpected output, inspect whether yt-dlp is found and whether the selected format is compatible. Run the URL from a terminal and read the messages about format selection, external tools, and network requests.

Confirm that the trusted yt-dlp executable is on PATH or that your configured path points to the intended file. Update it through its official installation method when a supported site's format changes. Do not use this workflow to bypass DRM or access media without authorization.

For direct network streams, try another legitimate stream and, where possible, test a local copy obtained through an authorized method. If corruption changes with reconnects or appears as missing blocks rather than a stable green tint, packet loss or a damaged stream is more likely than a color-conversion error.

3.5 Distinguish playback corruption from green screenshots

If playback looks correct but screenshots are green, the decoder may be fine. The failure is probably in frame readback, screenshot format conversion, or a hardware-surface path. Compare a screenshot after launching with --hwdec=no. Also remove custom screenshot-format and screenshot-filter options for the test.

Success means the saved image matches the visible frame. If software decoding fixes only screenshots, keep it for captures or investigate the graphics backend. There is no reason to change subtitle, audio, network, or file-path settings when normal playback is already correct.

4. Use mpv Diagnostics to Identify the Failing Stage

Terminal output is more useful than guessing. It can reveal the selected decoder, hardware-decoding method, pixel format, video output, active filters, tracks, dropped frames, and errors from scripts or external tools.

4.1 Create a focused verbose log

Run the affected file with a clean configuration and write a log:

mpv --no-config --msg-level=all=v --log-file=mpv-clean.log "video-file.mkv"

Then create a second log using your normal configuration:

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

Compare the lines that identify the video codec, pixel format, hardware decoder, filters, video output, GPU API, and errors. Do not publish logs without checking them first. Logs can contain local paths, URLs, usernames, network addresses, and other private information.

If the normal log shows a shader, filter, profile, or hardware path absent from the clean log, test that difference directly. Once removing it produces stable colors, stop. The comparison has done its job.

4.2 Use the stats overlay and track list

mpv's built-in stats display can show codec details, frame timing, dropped frames, output information, and other playback data. Open it using the binding available in your configuration, or consult the current mpv manual if your custom input.conf has replaced the default binding.

Check whether the affected file is 10-bit, HDR, unusually high resolution, or decoded through hardware acceleration. Also inspect the track list. Containers can include multiple video tracks, cover art, attached pictures, audio tracks, and subtitles. Select the intended video track instead of assuming the automatically chosen track is correct.

A useful diagnostic result is a consistent boundary. For example, every 8-bit H.264 file works while 10-bit HEVC fails only under hardware decoding. That boundary is much more actionable than the general statement that mpv is not working.

5. Run a Clean Temporary Test Before Changing Many Options

When --no-config succeeds, build a temporary test configuration instead of repeatedly editing your main setup. Create a new empty directory and point mpv to it with the configuration-directory option supported by your build, or continue using explicit command-line options with --no-config.

5.1 Restore features in a controlled order

1. Confirm clean software-decoded playback.
2. Enable your preferred video output without enabling hardware decoding.
3. Enable hardware decoding and retest several files.
4. Add HDR or color-management options.
5. Add filters and shaders one at a time.
6. Restore profiles and input bindings.
7. Restore third-party scripts individually.
8. Test subtitles, online URLs, playlists, and IPC integrations last.

Play the same representative section after each step. If green frames return immediately after one change, remove that change and repeat the previous working command. A repeatable result identifies the cause more reliably than a large config rewrite.

5.2 Preserve a known-good command

Save the simplest working command in your notes. For many users, it will resemble:

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

This provides a recovery path while you repair the main configuration. It also helps distinguish future media-specific failures from configuration regressions.

6. Quick Fix Checklist

• Run the affected file with --no-config --hwdec=no.
• Test a second known-good SDR file.
• If software decoding works, leave hardware decoding disabled temporarily.
• Remove forced vo, gpu-api, and gpu-context choices.
• Disable custom shaders, video filters, and HDR overrides.
• Check profiles, scripts, and input bindings for automatic video changes.
• Compare playback with subtitles and audio tracks disabled.
• Use mpv --version to verify the executable and build in use.
• Update mpv and GPU drivers only through trusted official channels.
• Use verbose logs to compare clean and configured playback.
• For URLs, verify network access and the trusted yt-dlp path.
• If only screenshots are green, test software decoding and default screenshot settings.
• Stop changing settings as soon as correct playback is repeatable.

7. Frequently Asked Questions

7.1 Why does mpv show green video while audio still works?

Audio and video use separate decoding and output paths. The audio stream can continue normally while the video decoder, hardware surface, pixel-format conversion, shader, or GPU presentation stage fails. Start with --no-config --hwdec=no. If that fixes the picture, the file's audio is unrelated and the hardware or customized video path deserves attention.

7.2 Is disabling hardware decoding a real fix?

Yes, provided the CPU can decode the media smoothly. Software decoding avoids problematic GPU video-decoding and surface-sharing paths. Watch CPU usage, dropped frames, temperature, and battery consumption. If playback remains smooth and colors are correct, you can stop there or investigate a driver update later.

7.3 Why are only HDR or 10-bit videos green?

Those files may use decoder output formats, bit depths, color metadata, and tone-mapping paths that ordinary 8-bit SDR video does not exercise. Remove custom HDR and color overrides, test software decoding, and compare the same display in SDR mode. A failure limited to hardware-decoded HDR strongly suggests an output-format, driver, or graphics-backend issue.

7.4 Can subtitles cause a green screen in mpv?

Ordinary text subtitles are unlikely to turn the decoded picture green. However, subtitle-related scripts, complex rendering modifications, or filters can affect the rendering chain. Test with --sid=no and no configuration. If the problem disappears, restore the subtitle track and related scripts separately to identify the exact component.

7.5 Why does a local file work but an online URL does not?

The URL may involve yt-dlp, a changing website format, a live stream, packet loss, authentication, or a different codec than your local file. Run mpv in a terminal, verify the trusted yt-dlp executable, and inspect the selected stream. If the downloaded or direct media data is already corrupted, changing mpv's color options will not repair it.

7.6 What should I do if even the clean software test is green?

Test another known-good file, verify the active mpv build, and capture a verbose log. If all files fail, check the video output, graphics driver, display server, and operating-system updates. If only one file fails, inspect its codec and pixel format and test it with another reputable player or analysis tool. The file may be damaged or use a feature unsupported by the active build.