Frame judder with video playback

Overview

VRR displays are great for games, where frame production is inherently irregular, but fixed-cadence video can still judder if the display pipeline doesn’t pace frames correctly.
For example, on a 40-60 Hz VRR panel I noticed unmistakable judder when playing 30 fps content in mpv on Wayland. 50 fps content looked fine.

On a 40-60 Hz VRR panel, refresh rate can vary only between 16.67 ms and 25 ms.
But 30 fps video delivers a new frame every 33.33 ms, which falls below the panel’s minimum VRR rate.
Because of this, frames cannot be displayed at a uniform cadence and instead alternate between longer and shorter display times, about 41.67 (25+16.67) ms and 25 ms.
The average frame rate remains correct, but the uneven frame pacing appears as visible judder.

The client or media player passes the content frame rate using a new content-frame-rate-v1 protocol to the compositor.
The compositor should do the low framerate compensation (LFC) to choose the smallest stable refresh multiple that fits within the VRR range.
For 30 fps content on a 40 to 60 Hz panel, that target becomes 60 Hz, so each video frame is shown for exactly two scanouts.
This restores a stable presentation cadence and removes judder.
The compositors can implement this by deriving a virtual display mode from the current KMS mode and retiming vtotal, vsync_start, vsync_end, and vrefresh to the computed target refresh rate so that the panel scans out at exactly target_hz.

To fix this, I carried out a PoC, you can check the full implementation details here: Fixing judder issue with video playback