mpv Fullscreen Freezes: How to Fix It

When mpv freezes while entering, leaving, or remaining in fullscreen, the player itself may not be the only component involved. Fullscreen transitions can change the presentation path, compositor behavior, refresh synchronization, output size, shader workload, HDR state, and audio or video timing. Customized configurations add other possibilities, including fullscreen profiles, scripts, input bindings, subtitles, hardware decoding, and external tools. The safest way to find an mpv fullscreen freezes fix is to reproduce the problem with a clean command, isolate one category at a time, and stop as soon as the smallest reliable correction is identified.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin by determining whether fullscreen alone triggers the freeze. Do not edit or remove your main configuration yet. Open a terminal, Command Prompt, or PowerShell window and run mpv with configuration loading temporarily disabled.

Use a trusted local video that normally plays correctly:

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

On Windows, replace the example with a properly quoted Windows path. On Linux or macOS, preserve quotes when a path contains spaces or shell-sensitive characters. Start playback in a window, wait several seconds, press f to enter fullscreen, wait again, and press f to leave fullscreen.

This command removes two major variables. --no-config bypasses user configuration files, scripts, and most customization, while --hwdec=no uses software decoding instead of a hardware decoder. It does not permanently change your installation.

1.1 Interpret the clean test

• If fullscreen works, the likely cause is a configuration option, profile, script, shader, input binding, or hardware-decoding path.
• If the video still freezes, investigate the GPU driver, video output context, compositor, display server, audio backend, media file, or operating system.
• If only one file fails, suspect its codec, timestamps, subtitle tracks, resolution, bit depth, or corruption.
• If only online media fails, separate fullscreen rendering from network, yt-dlp, authentication, and stream instability.

Success means you can enter fullscreen, remain there for at least a minute, and return to windowed mode without the picture, interface, or process becoming unresponsive. Once the minimal test works, stop changing system-wide settings. Reintroduce your normal options methodically instead.

1.2 Distinguish a frozen picture from a frozen process

A motionless image does not always mean mpv has stopped responding. Press the pause key, toggle the on-screen controller, or open the statistics overlay with Shift+i. Listen for continuing audio and observe whether statistics update. Continuing audio with a stuck frame points toward video presentation, GPU synchronization, or decoding. A responsive overlay over frozen video suggests a decoding or track problem. If the window and audio both stop, inspect scripts, IPC clients, output drivers, and terminal logs.

2. Check Options and Customizations Related to Fullscreen

If the clean test succeeds, compare it with your normal launch command. The goal is not to erase the entire config folder. Temporarily disable one relevant layer, test, and restore it if the symptom remains.

2.1 Inspect fullscreen options, bindings, and profiles

Review mpv.conf, input.conf, command-line aliases, desktop shortcuts, and launcher arguments. Look for fullscreen-related options, profile conditions, geometry settings, monitor selection, refresh-rate behavior, video output choices, and commands bound to f or mouse events.

A custom binding can execute several commands when fullscreen changes. A conditional profile may also activate only at a particular resolution, codec, or display. Test the exact binding by using the on-screen controller or running mpv with no configuration. If one method freezes and another does not, inspect input.conf for chained commands or script bindings.

Use --show-profile=PROFILE_NAME to print the contents of a named profile. Also inspect any auto profiles or conditional profiles that may become active for large video, HDR content, or specific protocols. Success means fullscreen works after disabling one identified profile or binding. At that point, correct that item instead of simplifying unrelated settings.

2.2 Disable scripts without deleting them

Scripts can react to fullscreen events, resize windows, communicate through IPC, fetch metadata, modify tracks, or run external programs. Start with --no-config to prove customization is involved. Then load your ordinary options without scripts, or temporarily move only suspected scripts to a separate backup location if your setup does not provide a convenient launcher switch.

Pay special attention to scripts that manage display refresh rates, window placement, automatic cropping, shaders, subtitles, screenshots, playlists, or external IPC clients. An IPC client can appear to freeze mpv if it repeatedly sends commands or waits on an event. Success is repeatable fullscreen switching with the suspect script absent. Check the script's documentation and update it from its legitimate source before restoring it.

2.3 Test subtitles and track selection

Complex styled subtitles can increase CPU and GPU work, particularly when the fullscreen viewport is much larger than the window. Temporarily disable subtitle display with v, or start with:

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

If embedded subtitles are fine but an external subtitle file freezes, verify the subtitle path, file readability, encoding, and fonts. Animated ASS subtitles, many simultaneous events, large blur effects, and missing fonts that trigger fallback can be unusually expensive. Test a different subtitle track through mpv's track selection controls.

Also test explicit audio and video tracks when a file contains several alternatives. Use the track list shown in the terminal or the statistics overlay. A malformed secondary track or unusual attachment may make one file behave differently. Success means the same media survives fullscreen with subtitles disabled or with a different track selected, identifying a content-specific cause.

2.4 Remove shaders and reduce fullscreen GPU load

A shader that is acceptable in a small window may become too expensive at fullscreen resolution. Upscaling, debanding, interpolation, tone mapping, and user GLSL shaders can process millions more output pixels after the viewport expands. This can look like a freeze even when mpv is rendering extremely slowly.

Test with a clean command first. If necessary, disable custom shaders and expensive scaling options in a temporary profile. Watch frame timing and dropped frames in the statistics overlay. If fullscreen becomes responsive, restore effects individually, use a lighter shader, or reserve demanding shaders for lower-resolution output.

Success looks like stable playback and responsive controls at the fullscreen display's native resolution. Stop changing decoder settings if shader removal alone solves the issue.

2.5 Compare hardware decoding modes

Hardware decoding involves the decoder, GPU driver, graphics API, video output, and sometimes zero-copy interoperation. A failure at one boundary may appear only during a fullscreen swap-chain or presentation change. Compare software decoding with your current hardware mode:

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

Then test mpv's generally applicable automatic selection:

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

If software decoding works but hardware decoding freezes, keep software decoding as a temporary workaround for manageable files. Then update the GPU driver from the GPU or operating-system vendor and test a different supported hardware-decoding mode only after consulting the manual for your platform. Success means the same file and fullscreen sequence work repeatedly with one stable mode.

2.6 Separate HDR from ordinary playback

HDR can introduce tone mapping, high-bit-depth surfaces, display metadata, color-space conversion, and operating-system HDR behavior. Compare an SDR file with the problematic HDR file using the same clean command. Also note whether operating-system HDR is enabled and whether the problem occurs only on one display.

If SDR works but HDR freezes, avoid changing unrelated subtitle or network settings. Test the current GPU driver, another mpv GPU context, and a simpler output configuration. If possible, compare playback with system HDR consistently on and consistently off rather than toggling it during playback. Success means HDR playback remains responsive through repeated fullscreen transitions with correct colors and stable frame delivery.

3. Check the Operating System, GPU, and Display Path

3.1 Update or roll back the GPU driver carefully

Fullscreen transitions stress presentation and synchronization paths that ordinary windowed playback may not use in the same way. Install graphics drivers only through Windows Update, your hardware vendor, your Linux distribution, or Apple's operating-system updates. Avoid random driver bundles and codec packs.

If the issue began immediately after a driver update, a vendor-supported rollback may be more informative than repeatedly changing mpv options. Record the current driver version before making changes. Success means the clean test works across several files and after a restart. Once it does, restore mpv customizations gradually.

3.2 Test another GPU context

mpv can use different platform-specific GPU contexts depending on its build and operating system. The available choices differ, so first inspect your build's help output:

mpv --gpu-context=help

Run the clean test with one supported alternative using --gpu-context=VALUE. On Windows, this can help distinguish graphics API and presentation-path behavior. On Linux, it can help separate Wayland from X11-related operation when both are available. Do not copy an unsupported value from another platform.

If another context fixes fullscreen, keep that context as a targeted workaround and leave unrelated playback settings unchanged. Success requires reliable entry and exit, not merely one successful attempt.

3.3 Understand Wayland and X11 differences

On Linux, Wayland and X11 use different windowing, compositor, scaling, and presentation mechanisms. Confirm the actual session and mpv context instead of assuming that an X11 compatibility layer or native Wayland path is active. Fractional scaling, mixed-refresh monitors, and multi-GPU systems can expose context-specific problems.

If your installed mpv build supports both paths, compare them with a clean configuration. This is a diagnostic test, not a claim that either display system is universally better. If only one path freezes, investigate the compositor, graphics stack, and distribution updates associated with that session. Stop adjusting codecs if the exact same decoded media works through the alternative context.

3.4 Check compositor and Windows G-Sync behavior

Variable refresh rate can interact with windowed and fullscreen presentation. On Windows systems using G-Sync or another variable-refresh feature, test whether the driver is configured for fullscreen only or for both windowed and fullscreen applications. Temporarily disabling variable refresh for mpv, preferably with an application-specific driver profile, can identify the interaction without changing every application.

Also test with overlays and capture utilities closed. Game overlays, performance monitors, screen recorders, and desktop enhancement tools may hook presentation. On Linux, compositor behavior and direct scanout may change when a window becomes fullscreen. Temporarily testing a compositor setting can be useful, but avoid permanently disabling desktop protections or effects before the clean test proves a connection.

Success means mpv crosses the fullscreen boundary without a stalled frame or black screen after changing one presentation-related setting. Keep the narrowest application-specific fix.

3.5 Do not assume fullscreen is exclusive

mpv fullscreen commonly means a borderless window managed as fullscreen by the operating system or compositor. It should not automatically be treated as exclusive fullscreen in the way some games use that term. Consequently, advice about forcing exclusive mode may not apply and can distract from the actual video-output problem.

Instead, observe what changes: the display mode, refresh rate, HDR state, monitor, compositor path, or variable-refresh behavior. If a custom script switches refresh rates or displays, disable that script during testing.

3.6 Rule out audio backend stalls

A fullscreen freeze can coincide with an audio device change, especially when HDMI or DisplayPort audio is tied to a display. Test muted playback and, if needed, temporary playback without audio:

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

If video remains responsive without audio, inspect the selected audio device, Bluetooth transitions, HDMI output, exclusive audio settings, and backend messages. Success means fullscreen works with a stable audio device. Do not keep video-focused changes that had no effect.

4. Separate Local Files From URLs, Streams, and External Tools

4.1 Validate yt-dlp and shell quoting

For online URLs, first play a local file with the same fullscreen procedure. If local playback works, the rendering path may be healthy. Online playback can stall because the network stream stops delivering data, an extractor fails, or a URL is altered by shell parsing.

Quote URLs containing ampersands, question marks, or other shell-sensitive characters. Confirm that mpv can find yt-dlp through the expected executable path. Obtain yt-dlp only from its official project or a trusted package manager. Test the URL outside fullscreen and inspect terminal output before blaming the fullscreen transition.

Success means the stream continues buffering and playing while fullscreen changes. If only one service or URL fails, treat it as an extractor, authentication, or source issue rather than a general mpv player issue.

4.2 Test network and high-bitrate media

A network stream may exhaust its buffer near the moment you press fullscreen by coincidence. Watch cache information in the statistics overlay and compare the stream with a downloaded, lawfully obtained local sample of similar codec and resolution. Wired networking or a stable local network test can separate throughput problems from rendering.

High-bitrate local media also requires adequate storage throughput. Test from a local internal drive when diagnosing playback from a slow network share, removable disk, or sleeping storage device. Success means cache health and decoding remain stable independently of fullscreen.

4.3 Check screenshots and writable paths

A custom input binding may combine fullscreen with a screenshot command, or a script may capture frames during a mode change. Verify that the screenshot directory exists and is writable. Check for path characters that require quoting and for network folders that may be unavailable.

Test the fullscreen key and screenshot key separately. If the freeze occurs only after a screenshot command, correct the output path or image settings instead of modifying the GPU context.

5. Use mpv Diagnostics to Locate the Failure

5.1 Capture terminal output and a log file

Launch mpv from a terminal so messages remain visible. For a persistent record, use:

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

Increase detail selectively with --msg-level. For example, raising relevant video-output, decoder, or window-system components can be more readable than enabling maximum verbosity everywhere. Consult the manual for recognized message prefixes in your build.

Reproduce the freeze once, note the time, and close mpv normally if possible. Search the final messages for device loss, failed presentation, decoder errors, audio-device changes, script exceptions, or stream timeouts. Logs may include file paths, URLs, and system details, so redact private information before sharing them.

5.2 Use the statistics overlay and track list

Press Shift+i to inspect performance statistics. Look for dropped frames, delayed frames, decoder information, hardware-decoding status, output resolution, and cache behavior. Exact fields can vary by mpv version and configuration.

Use mpv's track controls or terminal output to identify the selected video, audio, and subtitle tracks. Compare the failing selection with a working one. Success is a clear correlation, such as freezes occurring only with one subtitle track, one hardware decoder, or a sharp rise in rendering time after fullscreen scaling.

5.3 Compare configured and clean runs

Create two logs: one from your normal command and one from --no-config. Keep the media, display, and fullscreen sequence identical. Differences in loaded scripts, profiles, GPU context, hardware decoding, shaders, tracks, and audio devices provide a focused shortlist.

A log is useful when it narrows the next test. Avoid changing ten options based on one warning that does not coincide with the freeze.

6. Run a Clean Temporary Test Before Permanent Changes

Use a small test matrix rather than random experimentation. Keep notes and change one category at a time.

1. Test a known-good local SDR file with --no-config --hwdec=no.
2. Repeat with --hwdec=auto.
3. Test one supported alternative GPU context.
4. Restore normal configuration but leave scripts and shaders disabled.
5. Restore scripts individually.
6. Test subtitles, HDR, online URLs, playlists, and network sources separately.

Repeat entry and exit from fullscreen several times after each change. Let playback continue long enough to detect sustained rendering problems. If one change fixes the issue consistently, stop. Save that working command, then make only the corresponding permanent edit.

For example, if a clean software-decoding test succeeds while the equivalent hardware-decoding test freezes, there is no reason to rewrite subtitle settings. If disabling a heavy shader solves the problem, do not also change the audio backend and display server.

7. Quick Fix Checklist

• Run mpv --no-config --hwdec=no "file" and test fullscreen repeatedly.
• Confirm whether the picture, audio, overlay, or entire process actually freezes.
• Disable custom fullscreen bindings, conditional profiles, scripts, and IPC clients individually.
• Test without subtitles, then select alternate audio and video tracks.
• Remove custom shaders and check whether fullscreen resolution overwhelms the GPU.
• Compare software decoding with --hwdec=auto.
• Use mpv --gpu-context=help before testing another supported context.
• Update trusted GPU drivers or investigate a recent driver regression.
• Compare Wayland and X11 paths where both are supported.
• Test an application-specific G-Sync or variable-refresh setting on Windows.
• Check HDMI, DisplayPort, Bluetooth, and other audio-device transitions.
• Compare local SDR media with HDR, URLs, streams, and high-bitrate files.
• Verify yt-dlp availability, URL quoting, screenshot paths, and network access.
• Capture a log and retain the smallest change that reliably fixes the freeze.

8. Frequently Asked Questions

8.1 Why does mpv freeze only when entering fullscreen?

Entering fullscreen can change output dimensions, compositor behavior, synchronization, variable refresh, monitor selection, HDR state, or the graphics presentation path. It can also make shaders significantly more expensive. A clean software-decoding test helps separate configuration and decoder problems from system presentation issues.

8.2 Why does audio continue while the video is frozen?

This usually indicates that demuxing or audio playback continues while video decoding, GPU rendering, or frame presentation has stalled. Check the statistics overlay, compare hardware and software decoding, disable shaders, and test another supported GPU context.

8.3 Can subtitles cause mpv fullscreen freezes?

Yes, particularly complex styled subtitles rendered over a much larger fullscreen viewport. Disable subtitles temporarily and test another track. If that fixes the issue, investigate subtitle complexity, font availability, and renderer load rather than replacing codecs.

8.4 Should I delete my mpv configuration folder?

No. Start with --no-config, which safely bypasses configuration for one run. If that fixes the problem, disable options, profiles, scripts, and shaders in small groups. This preserves a working setup and identifies the actual cause.

8.5 Is Windows G-Sync always the cause?

No. It is one possible interaction when behavior differs between windowed and fullscreen presentation. Test an application-specific variable-refresh setting and compare results. If nothing changes, restore the setting and investigate the GPU context, driver, shaders, HDR, and hardware decoding.

8.6 What should I include when asking for help?

Provide your operating system, mpv build information, GPU and driver, display server, the exact command, whether --no-config --hwdec=no works, the media type, and a redacted log. State whether the freeze occurs entering, leaving, or staying in fullscreen and whether audio or overlays remain responsive.