Fix video stutter on a Linux signage player

What the stutter points to

Match the symptom to the cause before you change anything:

• Every video stutters, on every OS you put on that box. The file asks for more decode than the hardware path delivers. Fix it on the content side: bitrate first, resolution second.
• Stutters on Linux only; the Windows twin plays the same file. The decode path. The Windows install arrives with the vendor decode stack active; on Linux the player falls back to software decoding until you add the VA-API driver. Same box, different driver. This is the case this page fixes.
• Clean at 1280 x 720, slow from 1920 x 1080 upward. Software decode hitting its pixel ceiling. The deficit grows with frame size, which is why the small file plays and the big one drops frames. See video that stutters on a 4K monitor but not on 1080p for the same failure one size up.
• The same videos turned choppy after a player update. The release, not the OS. Install the previous release back and report the change to whoever maintains the player.
• The desktop tears and window drags stall too. The X display driver layer, one level below video decode. The follow-up below covers it.

Check that you are decode-bound

• Play the exact file that stutters on the Windows twin. Same i5 CPU, same 8 GB of RAM, same SSD, and it plays there: that box handles this file with room to spare, and the deficit is in the Linux software stack.
• Open a CPU monitor during Linux playback. Software decode pins one core at or near 100 percent, worst in the busiest scenes of the file. With the driver active, the decode load moves into the graphics silicon; the CPU cores sit well below their ceiling.

Both checks reading that way means install the driver. Idle cores with clean 720p playback point somewhere else, and the driver will change little there.

Install the driver

• VA-API is the open specification and library that hands video encode and decode to the graphics hardware on Linux. Install the driver package that matches your graphics. On an Ubuntu box with an i5 CPU and its built-in graphics, run apt install i965-va-driver.
• Reboot, so every player process opens the new driver from a fresh start.
• Replay the heaviest file with the monitor open. The core that sat at 100 percent should fall well below it, and the stutter should go or shrink.
• Re-check after every player update. A release can change the decoder it uses.

The Windows twin needed no such step here. When a Windows box does need one, adding codec support to a Windows signage player covers it.

Set the expectation: on this hardware class the driver install makes playback clearly smoother and can still leave a gap against the Windows box. Close the rest on the content side.

If frames still drop after the driver

• The X display driver. If video improved but the desktop still tears or drags, check which display driver the X server loaded; its log names the driver. If a legacy vendor package is in use, move the X server to the kernel's modesetting driver with a file under /etc/X11/xorg.conf.d/ and restart X.
• A discrete graphics card. On a box using an add-in card with the open-source driver, VA-API support is still not fully mature, and VDPAU is the reliable acceleration path on that stack. Check the player's documentation for which interface it uses.
• The player release. Same videos, clean on the previous version, choppy now: roll back and report it.

Keep the content inside the budget

• Re-encode to H.264 MP4 and test the video bitrate on the box itself before you deploy. The bitrate sets the steady decode load, and the box tells you its ceiling.
• Hold the loop at 1920 x 1080 and 30 frames per second unless the screen forces more. The example below shows what 4K and 60 fps add to the arithmetic.
• Match the codec to what the driver accelerates. H.264 is the safe profile on every acceleration path here; on the Android player we ship, H.264 MP4 is the one we recommend, since H.265 and VP9 depend on the unit.
• If a 4K panel is what loads the box, check the viewing distance before you keep it. Our planning figure is 30 ft of viewing distance per inch of letter height, and what size digital signage screen you need works the screen sizes out from it.

Recommendation: On an Ubuntu signage box with an i5-class CPU and its built-in graphics, run apt install i965-va-driver, reboot, and replay the heaviest file. Deploy only when it plays a full loop with no core pinned at 100 percent. If frames still drop after the driver, fix the X display driver or roll back the player, then cut bitrate, resolution or frame rate in that order, before changing any hardware.

Example: the 1080p loop on the i5 box

Inputs: the box is an i5 CPU with its built-in graphics, 8 GB of RAM and an SSD, running Ubuntu 20.04 LTS. Its twin runs Windows 10 and plays the loop smoothly. The file is a 1920 x 1080 MP4 at 30 frames per second, the common export for a signage loop.

Rule in words: every frame must be decoded and drawn inside one frame interval, and the interval is 1000 ms divided by the frame rate.

The arithmetic:

• 1000 ms / 30 frames per second = 33.3 ms per frame.
• At 60 frames per second, 1000 / 60 = 16.7 ms per frame.
• Pixels per frame: 1920 x 1080 = 2,073,600. At 30 frames per second that is 2,073,600 x 30 = 62,208,000 pixels per second.
• A 3840 x 2160 frame is 8,294,400 pixels, four times the 1080p frame.

Result: in software, one CPU core must decode, scale and color-convert 62 million pixels a second inside a 33.3 ms budget per frame, while the same CPU runs the player and the desktop. That core pins at 100 percent and the busy scenes drop frames. With the VA-API driver, the decode block runs in the graphics silicon and the same box plays the file, as its Windows twin already does.

Decision: on this CPU class, anything above a 1920 x 1080, 30 frames per second H.264 load in software drops frames; the driver install is the fix, and it comes first. If the content must run at 60 frames per second, the budget halves to 16.7 ms per frame; at 3840 x 2160 the pixel load quadruples. Past either point an accelerated decode path is mandatory.

Questions