mpv Dropped Frames Stuttering: How to Fix It

When mpv drops frames, video may judder, pause briefly, fall behind audio, or look uneven during camera movement. The most likely causes are a display refresh mismatch, a decoder that cannot keep up, expensive scaling or shaders, subtitle rendering, an overloaded configuration, a problematic output path, or a slow network source. The fastest way to find the real cause is to measure the symptom, reproduce it with a clean command, and restore custom features one category at a time.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before editing mpv.conf, determine whether frames are genuinely being dropped. Uneven motion can also come from the source frame cadence, an incompatible display refresh rate, duplicate frames, or network buffering. Those problems can look similar but require different fixes.

1.1 Open the stats overlay

Play the affected video and press i to open mpv's statistics overlay. Depending on your input configuration and mpv build, pressing i again may show additional pages. Look for dropped-frame counters, delayed frames, display synchronization information, video frame rate, display refresh rate, decoder details, hardware decoding status, and rendering times.

Watch the counters while the visible stutter occurs. A counter that increases at the same moment as the stutter is strong evidence of a processing, decoding, or presentation problem. If the counters remain stable, the apparent judder may be encoded into the source or caused by frame-rate and refresh-rate cadence.

Success means the dropped and delayed counters stop increasing during normal playback. Once playback is smooth and the counters remain stable, stop changing settings. A counter may occasionally change during seeking, startup, track switching, or window resizing without indicating a persistent problem.

1.2 Test without your normal configuration

Run mpv from a terminal with configuration loading disabled. Replace the example path with a local file that reliably demonstrates the problem:

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

On Windows PowerShell, Command Prompt, Linux shells, and macOS Terminal, quote paths containing spaces. Dragging a file into the terminal can help insert its full path, although you should still inspect the resulting quoting.

If the clean command plays smoothly, mpv itself, the media file, and the basic system playback path are probably functional. The cause is likely in mpv.conf, an auto profile, input.conf, a script, a shader, or another user customization. If the clean command still drops frames, investigate decoding, graphics drivers, display timing, audio output, the file, or system load.

1.3 Compare a local file with the original stream

If the problem occurs with an online URL, compare it with a known-good local video. This separates rendering and decoding problems from network access, stream delivery, yt-dlp integration, and remote server behavior.

• If local playback is smooth but the stream stalls, examine bandwidth, stream buffering, the remote server, URL extraction, and the selected stream quality.
• If both local and streamed media drop frames, focus on decoding, GPU output, display synchronization, shaders, subtitles, and system load.
• If only one local file is affected, inspect that file's codec, bitrate, frame rate, timestamps, HDR characteristics, and integrity.

A stream pause caused by missing data is not necessarily a rendered dropped frame. Use terminal messages and the cache information in the stats overlay to distinguish network starvation from a slow video pipeline.

2. Check mpv Settings Directly Related to Dropped Frames

After the baseline test, inspect the options most likely to increase rendering time or disturb timing. Change one category at a time and replay the same demanding scene after each adjustment.

2.1 Review display refresh mismatch and synchronization

A common source of apparent stutter is a mismatch between the video's frame rate and the display's refresh rate. For example, 24 fps material cannot be distributed perfectly across a fixed 60 Hz refresh cycle without an uneven cadence. This may look like regular judder even when mpv reports no dropped frames.

First, check the video frame rate and detected display refresh rate in the stats overlay. If your operating system and display support it, test a refresh rate that is equal to or a clean multiple of the content frame rate. Typical useful relationships include 24 fps on 48 Hz, 72 Hz, 96 Hz, or 120 Hz, although exact fractional rates such as 23.976 fps can complicate the match.

mpv's display synchronization features can adapt playback to the display. Test them temporarily instead of committing them immediately:

mpv --no-config --video-sync=display-resample "video.mkv"

Display-resample mode can make small audio resampling adjustments while synchronizing video presentation to the display. Its effectiveness depends on reliable refresh detection, the output driver, the display server, and the stability of the display clock.

If this mode introduces audio pitch concerns, synchronization warnings, or worse playback, return to the default test. Do not combine several unfamiliar video-sync, interpolation, and timing options at once. Success means pans have consistent cadence, audio stays synchronized, and dropped or delayed counters do not rise.

2.2 Reduce scaler, shader, HDR, and interpolation load

High-quality scalers, debanding, interpolation, user shaders, and HDR processing can exceed the GPU's rendering budget. This is particularly likely with 4K video, high refresh rates, integrated graphics, battery-saving modes, or complex shader chains.

Search mpv.conf and profiles for options involving scale, cscale, dscale, glsl-shaders, deband, interpolation, vo=gpu-next, tone mapping, target color settings, and HDR peak detection. Then compare the customized setup against:

mpv --no-config --vo=gpu-next "video.mkv"

If your installed build or graphics stack does not work correctly with that output, test the default selected by --no-config rather than forcing it permanently. You can also disable an inherited shader chain for a diagnostic run:

mpv --no-config --glsl-shaders-clr "video.mkv"

Start with mpv defaults, then restore one shader or quality option at a time. Success means rendering remains comfortably within each frame's time budget. The statistics overlay should show stable presentation without growing delayed-frame counts.

2.3 Test hardware decoding both ways

Hardware decoding can reduce CPU usage significantly, especially for high-resolution HEVC, AV1, VP9, and H.264 content. It is not automatically faster or more compatible in every setup, however. Driver limitations, unsupported codec profiles, bit depth, pixel formats, filters, or hardware-to-software frame transfers can make it ineffective.

Compare these controlled tests:

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

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

Watch CPU usage, GPU video-decoder activity, terminal warnings, and the dropped-frame counter. If hwdec=auto fixes high CPU saturation and playback becomes stable, hardware decoding is useful for that file. If it causes corruption, decoder fallback, crashes, or additional frame drops, software decoding may be the safer choice until the driver or compatibility issue is resolved.

Do not assume that low total CPU usage proves software decoding is fast enough. One decoding thread may be saturated while other cores remain idle. Conversely, do not force a specific hardware API copied from another operating system. Let auto establish a portable baseline before testing platform-specific methods.

2.4 Isolate subtitle and track-related load

Complex ASS subtitles can trigger expensive font lookup, shaping, animation, blur, scaling, and compositing. Test the same scene with subtitles disabled:

mpv --no-config --sid=no "video.mkv"

If playback becomes smooth, re-enable the intended subtitle track and inspect subtitle-specific configuration, attached fonts, external subtitle files, and any subtitle scripts. Confirm that the selected subtitle file is local and readable. A malformed or unusually elaborate subtitle track may affect only particular scenes.

Also confirm that mpv selected the intended video and audio tracks. The stats overlay and track list identify codecs, languages, and selected streams. High-resolution alternate video tracks or unusual lossless audio tracks can change processing demands. Test another audio track or disable audio briefly:

mpv --no-config --aid=no "video.mkv"

If disabling audio removes repeated timing disruptions, investigate the audio backend, device selection, exclusive-mode options, sample-rate conversion, and wireless audio stability. Silent testing is diagnostic, not a final fix.

2.5 Inspect profiles, scripts, input bindings, and screenshot behavior

Automatic profiles may activate only for certain resolutions, protocols, codecs, displays, or file names. This can explain why one file stutters while another does not. Use --show-profile to inspect a named profile:

mpv --show-profile=profile_name

Review mpv.conf for profile sections and conditional auto profiles. Temporarily comment out the suspected profile rather than deleting the configuration directory.

Scripts can poll playback state, communicate through IPC, manage playlists, download metadata, change filters, or react to file events. Move only the suspected script out of the active scripts directory for a test, or use --no-config to bypass normal configuration and script loading. Restore scripts individually.

Review input.conf for repeated bindings, script messages, filter toggles, shader toggles, and screenshot commands. Screenshot capture can cause a brief pause when writing a large image to a slow disk, network folder, synchronized directory, or inaccessible location. If stuttering happens only when taking screenshots, test a writable local screenshot directory and a less expensive image format or configuration.

3. Check the Operating System and External Playback Path

3.1 Update or roll back the GPU driver carefully

GPU drivers control decoding, presentation, synchronization, HDR output, and shader compilation. If the issue began immediately after a driver or operating system update, test a stable vendor-provided driver or a known working distribution package. If the driver is old, update it through the GPU manufacturer, operating system, or Linux distribution.

Avoid random driver bundles, codec packs, and unofficial binary download sites. mpv normally relies on FFmpeg decoding and does not need a generic codec pack. Success means the same clean command renders without driver errors, visual corruption, or accumulating frame drops.

3.2 Compare display servers and compositor conditions

On Linux, Wayland and X11 can behave differently depending on the compositor, driver, scaling configuration, and mpv output path. Fractional scaling, multiple monitors with different refresh rates, variable refresh rate, and compositor effects may influence frame presentation. Test on one display, at a fixed refresh rate, with the mpv window entirely on that display.

On Windows and macOS, check whether the operating system reports the expected refresh rate and whether an external display, dock, adapter, HDR mode, or screen recorder changes presentation timing. Temporarily disable overlays and recording tools that inject into the graphics path.

3.3 Check power, temperature, and competing workloads

Laptops may throttle the CPU or GPU on battery power. Thermal throttling can also appear only after several minutes of high-bitrate playback. Test while connected to power with an appropriate performance mode, and close workloads that heavily use the decoder, GPU, disk, or network.

Success is not merely lower utilization. The key result is stable clocks and enough decoding and rendering capacity to present every frame on time.

3.4 Validate paths, permissions, yt-dlp, and network access

For online URLs, run mpv from a terminal and check whether it can locate yt-dlp when extraction is required. Use a trusted installation source and keep the external tool available in the system path or configure its known location correctly. Shell quoting matters when URLs contain ampersands, question marks, or other characters interpreted by the shell.

Check firewall, proxy, DNS, VPN, and certificate-related messages if the stream cannot load consistently. A working extractor does not guarantee that a remote server can deliver the selected bitrate fast enough. Test a lower stream quality or a different authorized source to distinguish extraction from bandwidth limitations.

For local media, test a short path on a fast local disk. Network shares, removable drives, cloud-synchronized folders, and damaged storage can deliver data unevenly. Confirm that mpv has permission to read the file and any external subtitle, shader, font, or playlist entries.

4. Use Logs and Runtime Information to Locate the Bottleneck

4.1 Capture useful terminal output

Launch mpv from a terminal so warnings remain visible. For more detail, raise selected message levels rather than enabling maximum output without a purpose:

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

Verbose logs can be large, so reproduce the issue briefly. Look near the timestamp of the stutter for decoder errors, late frames, audio underruns, cache starvation, failed hardware decoding, display synchronization warnings, or shader compilation problems.

4.2 Write a reproducible log file

Save output when you need to compare tests or request support:

mpv --no-config --log-file=mpv-clean-test.log "video.mkv"

Then repeat with the normal configuration and a different log filename. Comparing the clean and configured runs can reveal an added option, profile, script, filter, or output change. Review logs before sharing them because URLs, local paths, usernames, headers, or other private data may appear.

4.3 Interpret the evidence

• Growing dropped or delayed counts with high rendering time suggest GPU load, shaders, scaling, HDR processing, or presentation trouble.
• Decoder errors or a saturated CPU suggest codec complexity, damaged media, or unavailable hardware decoding.
• Cache depletion during URL playback suggests network or server throughput rather than a local rendering failure.
• Audio underruns or repeated device resets suggest an audio backend, device, or sample-rate issue.
• No counter changes with regular cadence judder suggest a frame-rate and refresh-rate mismatch or source-encoded motion.

Use evidence to choose the next test. Do not apply a large collection of performance options from an unrelated configuration, because that removes your ability to identify the actual cause.

5. Run a Clean Temporary Test Before Changing Many Options

A controlled test matrix is safer than deleting your configuration. Choose one local file and one scene that consistently exposes the problem. Restart mpv for each test so runtime toggles do not carry over.

1. Run mpv --no-config "video.mkv" and record the dropped-frame result.
2. Test --hwdec=auto, then --hwdec=no.
3. Test subtitles disabled with --sid=no.
4. Test the suspected display-sync mode separately.
5. Return to your normal configuration and disable only shaders or interpolation.
6. Restore scripts, profiles, and quality settings one group at a time.

After every step, replay the same section for long enough to reproduce the original symptom. Success means the visible motion is stable, audio remains synchronized, and counters stop growing. When one change reliably fixes the problem across repeated runs, stop and document it. Additional tuning can reintroduce the issue.

If no test fixes one specific file, inspect it with a reputable media-information tool or FFmpeg utilities. Very high bitrates, damaged packets, unusual timestamps, unsupported profiles, and variable frame-rate behavior can be properties of the media rather than an mpv configuration failure.

6. Quick Fix Checklist

• Open the stats overlay and confirm whether dropped or delayed counters actually increase.
• Test the same local file with --no-config.
• Compare a local file with the problematic URL or network stream.
• Check video frame rate against the operating system's display refresh rate.
• Test --video-sync=display-resample separately.
• Disable shaders, interpolation, debanding, and expensive scaling temporarily.
• Compare --hwdec=auto with --hwdec=no.
• Disable subtitles and test alternate audio or video tracks.
• Inspect auto profiles, scripts, input bindings, and screenshot destinations.
• Check GPU drivers, power limits, thermals, compositor behavior, and monitor configuration.
• For URLs, verify yt-dlp discovery, network throughput, cache status, and shell quoting.
• Capture a short clean log and compare it with normal configured playback.

7. Frequently Asked Questions

7.1 Why does mpv stutter when its dropped-frame counter is zero?

The video may have uneven source timestamps, duplicated frames, low-frame-rate motion, or cadence judder caused by displaying 24 fps content at 60 Hz. Check the detected video rate and display refresh rate. A compatible display mode or carefully tested display synchronization can improve cadence, but it cannot restore motion information absent from the source.

7.2 Should hardware decoding always be enabled?

No. Hardware decoding often reduces CPU demand, but compatibility varies by codec, profile, bit depth, driver, filtering path, and GPU. Compare --hwdec=auto and --hwdec=no on the same scene. Keep the option that produces stable playback without corruption or fallback warnings.

7.3 Can subtitles cause mpv dropped frames and stuttering?

Yes. Complex animated ASS subtitles, font processing, blur, and compositing can increase rendering load. Test with --sid=no. If that fixes the issue, inspect the selected subtitle track, attached fonts, subtitle options, and scripts instead of weakening unrelated decoder settings.

7.4 Why do online videos stutter while local files play smoothly?

The likely causes are insufficient bandwidth, remote server variation, cache depletion, URL extraction, an unnecessarily high selected format, or network filtering. Watch cache information and terminal output. Confirm yt-dlp is available when required, quote the URL correctly, and test a lower authorized stream quality.

7.5 Why does 4K HDR playback drop frames?

4K HDR can combine demanding decoding, high bit depth, tone mapping, scaling, peak detection, shaders, and display conversion. Test hardware decoding, remove custom shaders, and return tone-mapping options to defaults. Also verify the GPU driver and HDR display path. Restore enhancements only after the clean path is stable.

7.6 When should I stop troubleshooting?

Stop when the same test scene plays repeatedly without visible disruption, audio remains synchronized, and dropped or delayed counters remain stable during ordinary playback. Do not chase counters caused only by seeking, startup, resizing, or track switching unless they correspond to a persistent viewing problem.