mpv Display Sync Not Working: How to Fix It

When mpv display sync is not working, the usual symptom is uneven motion even though the file itself plays, or an unexpected number of dropped, delayed, or repeated frames. The cause is usually one of four things: the selected video-sync mode is not active, mpv has detected the wrong display refresh rate, audio timing is forcing corrections, or the operating system compositor and variable refresh rate behavior are interfering. Config profiles, scripts, shaders, hardware decoding, subtitles, HDR processing, and network performance can complicate the diagnosis. The safest approach is to prove display sync with a local file and a clean command before changing permanent settings.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin with a short local video stored on a fast local drive. Choose material with obvious continuous motion, such as a slow camera pan. Avoid an online URL, playlist, network share, complex shader chain, or unusually high-bitrate file for the first test because each adds a separate failure category.

Run mpv from a terminal with its normal configuration disabled:

mpv --no-config --video-sync=display-resample --interpolation=no "path/to/video.mkv"

On Windows, use Command Prompt or PowerShell and quote paths containing spaces. On Linux and macOS, use the appropriate shell quoting. If the executable is not on your system path, invoke it using its full trusted installation path.

This test deliberately disables interpolation. Display synchronization and interpolation are related but distinct. The display-resample mode adjusts playback timing to align video presentation with the display while resampling audio as necessary. Interpolation creates intermediate presentation samples to reduce judder when frame cadence and refresh cadence do not divide evenly. Testing both simultaneously can hide which feature is failing.

1.1 What a successful test looks like

Open mpv's statistics overlay by pressing i, or use the binding configured by your build. Watch the refresh estimate, dropped frames, delayed frames, estimated frame rate, and A/V sync. A successful result generally has stable audio, stable A/V synchronization, and no continuously increasing unexplained dropped or delayed frame count after startup. Some files still exhibit normal cadence judder when interpolation is off, especially 24 fps material on a 60 Hz display.

If motion is stable and the counters stop increasing, stop changing low-level settings. Reintroduce your normal configuration in small groups. If the clean command fails, continue with refresh detection, output, audio, and operating system checks.

2. Check the Display-Sync Options and Configuration Layers

The most relevant option is video-sync. For most display-synchronized playback tests, start with --video-sync=display-resample. Other modes have different correction strategies. For example, display-oriented drop modes can correct timing by dropping video or audio rather than continuously resampling audio. Do not switch among modes randomly. Compare one mode at a time while watching statistics.

2.1 Verify the effective option rather than the intended option

An option in mpv.conf may be overridden by a later line, an auto profile, a command-line argument, a script, or an IPC client. Search your configuration for these terms:

• video-sync
• interpolation
• audio-pitch-correction
• display-fps-override
• video-sync-max-video-change
• video-sync-max-audio-change
• vo, gpu-api, and gpu-context
• hwdec

Use mpv --show-profile=profile-name to inspect a named profile. Also check conditional profiles that activate for fullscreen mode, protocol-based URLs, file extensions, HDR files, or particular display names. A profile applied near the end of configuration processing can silently replace an earlier display-sync choice.

2.2 Inspect input bindings and scripts

Search input.conf for commands that cycle or set video-sync, interpolation, speed, audio delay, video delay, or display FPS overrides. A reused key can change the option during playback without making the cause obvious.

Temporarily test without user scripts. Timing scripts, automatic profile selectors, refresh-rate switchers, shader managers, and IPC controllers can modify relevant properties after startup. Screenshot settings normally do not affect cadence, but a conflicting screenshot binding can prevent the key you expected to use for a timing command from doing so. Do not delete your configuration folder. Use --no-config, then selectively load a copied test configuration.

2.3 Add interpolation only after display sync is stable

After the non-interpolated test succeeds, run:

mpv --no-config --video-sync=display-resample --interpolation=yes "path/to/video.mkv"

If this introduces stutter, the GPU may not be completing rendering before presentation deadlines, particularly with expensive scaling, HDR tone mapping, or custom shaders. Test with default rendering and no shader chain. Success means the delayed-frame count remains stable and panning appears more even. If interpolation adds delayed frames, disable it and retain working display sync rather than masking a performance limitation.

3. Check Refresh Rate, VRR, the Compositor, and GPU Output

Display sync depends on mpv receiving a usable estimate of the actual display refresh rate. A nominal 60 Hz desktop may operate near 59.94 Hz, and a video may be approximately 23.976 fps rather than exactly 24 fps. Small differences are expected and are one reason audio resampling exists. A grossly incorrect or unstable refresh estimate prevents reliable cadence.

3.1 Confirm which display is presenting the video

On multi-monitor systems, move mpv fully onto the target display before entering fullscreen. Displays with different refresh rates can confuse compositor scheduling, especially when a window spans both screens. Confirm the operating system has actually applied the selected refresh rate instead of merely showing the desired mode in a control panel.

As a diagnostic step, disconnect or disable other displays, or set them to matching refresh rates. If cadence becomes stable, the problem is likely in mixed-refresh composition rather than the media file. Stop changing mpv's sync parameters and address display or compositor configuration instead.

3.2 Test variable refresh rate separately

VRR can improve presentation, but its interaction with windowed composition, fullscreen behavior, frame-rate ranges, and multi-monitor setups differs by operating system and driver. Test once with VRR enabled and once with it disabled for mpv. Do not assume that enabling both VRR and interpolation will automatically produce smoother motion.

A successful VRR test has steady pacing without repeated brightness fluctuations, oscillating refresh behavior, or rising delayed frames. If fixed refresh works and VRR does not, use fixed refresh for mpv until the driver or compositor behavior is corrected.

3.3 Compare output and hardware decoding paths

Start with mpv's normal GPU output rather than forcing a legacy or platform-specific output driver. Then compare hardware decoding with software decoding:

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

If software decoding works but hardware decoding does not, the issue may involve the hardware decoder, zero-copy path, driver, pixel format, HDR surface, or GPU context. You can then test a supported copy-back hardware decoding mode listed by your installed mpv build. Copy-back can avoid some direct-surface interoperability problems at the cost of additional copying.

If both modes accumulate delayed frames, reduce GPU work. Remove shaders, use ordinary scaling, and test SDR content before HDR. HDR tone mapping and high-resolution scaling can miss presentation deadlines even when decoding itself is fast enough.

4. Check Audio Resampling, Tracks, Subtitles, and Media Limits

In display-resample mode, mpv normally makes small audio-speed adjustments to keep audio and display-timed video aligned. This can be mistaken for an audio defect, particularly when the required correction is excessive because refresh detection is wrong.

4.1 Interpret audio side effects correctly

If audio warbles, changes pitch, breaks up, or repeatedly loses sync, do not immediately increase correction limits. Confirm the detected refresh rate and verify playback speed is 1.0. Test a different audio output backend if the current backend reports underruns or unstable latency. Bluetooth devices and network audio systems can introduce changing latency, although stable latency alone does not necessarily defeat display sync.

Test another audio track and a simple stereo output. Passthrough and bitstreaming constrain the ability to resample audio, so temporarily disable passthrough when diagnosing display-resample. Success means audio remains clean while A/V sync stays near a stable value and video counters do not rise continuously.

4.2 Rule out track and subtitle processing issues

Use mpv's track list to verify the selected video, audio, and subtitle tracks. Test once with subtitles disabled. Ordinary text subtitles rarely cause persistent cadence failure, but complex styled subtitles, dense animation, or expensive font rendering can increase render time. Image subtitles may also add work at high resolutions.

If disabling subtitles stops delayed frames, retain display sync and troubleshoot subtitle rendering separately. If changing the audio track fixes the issue, inspect the problematic track's codec, channel layout, passthrough status, and backend messages rather than altering video cadence.

4.3 Separate file limitations from player settings

Variable-frame-rate media, damaged timestamps, discontinuities, and incorrectly authored files can produce uneven cadence that no display-sync mode can fully repair. Compare multiple known-good local files with different frame rates. If only one file fails in a clean test, inspect that file rather than making global mpv changes.

High-bitrate media can also expose storage or network bottlenecks. A decoder waiting for data may look like a display-sync problem, but the log will show buffering, demuxer, cache, or read issues. Copy a short sample to a local SSD when permitted and compare it with the original source.

5. Use Logs and Statistics to Identify the Failing Layer

Terminal output is often more useful than visual guessing. Run a reproducible test and save the log:

mpv --no-config --msg-level=all=v --log-file=mpv-display-sync.log --video-sync=display-resample "path/to/video.mkv"

Verbose logs can contain local paths, URLs, device names, and other private information. Review and redact them before sharing publicly.

5.1 Read dropped and delayed frames

• Dropped frames: Video frames were not presented as intended. A rapidly increasing count can indicate correction behavior, decoding delays, or missed timing.
• Delayed frames: Rendering or presentation did not finish on time. Expensive shaders, interpolation, HDR processing, GPU contention, or compositor behavior are common suspects.
• Stable counters: A small number during startup or seeking is less concerning than a count that rises throughout uninterrupted playback.
• A/V sync movement: Persistent swings can point to audio backend instability, timestamp problems, or an incorrect refresh estimate.

Record what happens during at least a minute of uninterrupted playback. Do not draw conclusions from seeking, opening the statistics overlay, changing tracks, or entering fullscreen because those actions can cause isolated timing events.

5.2 Inspect configuration and runtime state

Use --show-profile for profiles and compare terminal output between configured and --no-config runs. If an IPC client is attached, disconnect it during testing. An external controller can alter speed, pause state, tracks, or properties after mpv has parsed its command line.

For URL playback, confirm whether the problem occurs after the media is resolved and buffered. The yt-dlp path affects URL extraction and format selection, not display synchronization directly. An outdated, missing, or incorrectly invoked external tool can select an unsuitable stream or fail before playback, but it cannot repair cadence. Use an authorized URL, verify network access, and compare the resolved stream with a local file.

6. Run a Clean Temporary Test Before Permanent Changes

Change one variable at a time using this sequence:

1. Play a known-good local SDR file with --no-config.
2. Enable --video-sync=display-resample with interpolation disabled.
3. Verify the display refresh estimate and observe stats for one minute.
4. Compare --hwdec=no with your normal hardware decoding choice.
5. Enable interpolation only after the base mode works.
6. Add subtitles, the preferred audio track, HDR processing, and shaders individually.
7. Restore scripts, profiles, input bindings, IPC tools, and URL playback last.

After each step, success means smooth expected cadence for that refresh-rate combination, stable A/V sync, clean audio, and counters that do not continuously increase. Stop as soon as the symptom returns. The most recently restored feature is then the leading suspect.

Do not make several permanent edits at once. Keep a backup of the individual configuration file you edit, and comment out specific lines rather than removing the entire configuration directory.

7. Quick Fix Checklist

• Test a local file with --no-config --video-sync=display-resample --interpolation=no.
• Confirm mpv reports a plausible, stable display refresh rate.
• Keep the player entirely on one display during testing.
• Compare fixed refresh with VRR enabled and disabled.
• Check stats for continuously rising dropped or delayed frames.
• Disable interpolation before evaluating basic display sync.
• Remove shaders and HDR processing for the baseline test.
• Compare software decoding with hardware decoding.
• Disable audio passthrough and test a simple audio track.
• Disable subtitles briefly to rule out expensive rendering.
• Inspect profiles, scripts, input bindings, and IPC clients for overrides.
• Use a local file before testing yt-dlp, URLs, playlists, or network streams.
• Save a verbose log and look for refresh, audio, decoder, GPU, or buffering errors.

8. Frequently Asked Questions

8.1 Why does 24 fps video still judder with display-resample?

Display synchronization corrects clock drift and presentation timing, but it does not guarantee that every source frame receives an identical number of refresh intervals. Approximately 24 fps content displayed at 60 Hz has an uneven cadence unless interpolation, VRR within a suitable range, or a compatible refresh mode is used. First verify stable sync without interpolation, then enable interpolation if your GPU can sustain it.

8.2 Should I use display-resample, display-vdrop, or display-adrop?

Start with display-resample because it is designed to align playback with the display while making small audio timing adjustments. Drop-oriented modes use different correction strategies and may be useful in specific output constraints. Select them deliberately after examining audio capabilities and frame statistics, not as interchangeable smoothness presets.

8.3 Why does interpolation make playback worse?

Interpolation adds GPU rendering work. If the shader chain, scaling, HDR conversion, or GPU load is already close to its limit, interpolation can create delayed frames. Confirm that display sync works with interpolation disabled, remove custom shaders, and then retest. If delayed frames continue rising, leave interpolation off.

8.4 Can yt-dlp cause display sync to fail?

Not directly. yt-dlp helps mpv resolve supported online media and select formats. However, the selected stream may have unusual timestamps, variable frame rate, insufficient buffering, or a bitrate your connection cannot sustain. Compare the same playback setup with a local file. If local playback is stable, investigate stream selection, network throughput, and buffering rather than display sync first.

8.5 Does hardware decoding improve smoothness?

It can reduce CPU load, but a hardware decoding path can also introduce driver or surface-sharing problems. Compare it with --hwdec=no. If software decoding is smooth and fast enough, the display-sync configuration is probably valid and the hardware path needs separate troubleshooting.

8.6 When should I stop changing settings?

Stop when a clean test produces stable A/V sync, clean audio, a plausible refresh estimate, and no continuously increasing dropped or delayed frames. Occasional events during startup, seeking, track changes, or fullscreen transitions are not evidence that the mode is broken. Once the baseline works, restore custom features one at a time and keep the last known-good configuration.