Skip to main content

Writing video with FFmpeg: the GPU encoder and small pictures

Audience: people who write video (.mp4, .mov, .mkv) in the Eugo image with the ffmpeg program, PyAV, mediapy or matplotlib, on a machine with an NVIDIA GPU.

The one thing to take away: when you do not name an encoder, Eugo's FFmpeg encodes H.264 on the GPU (h264_nvenc). The GPU's encoder has a minimum picture size: on the DGX Spark (GB10) a 128x128 picture is refused and 160x160 works. A smaller video then fails on a GPU machine instead of falling back. Name a CPU encoder for small videos: -c:v mpeg4 (MPEG-4 Part 2), or scale the picture up first.

How this guide was written: the behaviour and the sizes below were measured on the DGX Spark (GB10) in test builds of Eugo's FFmpeg between 2026-10-03 and 2026-10-15 (section 4 has the dates); they were not re-run for this page. Other NVIDIA GPUs may have a different minimum.


1. What a plain write uses​

FFmpeg normally writes .mp4 with H.264 only when the x264 library is built in. x264 is GPL-licensed and Eugo's FFmpeg leaves it out, so Eugo's FFmpeg uses NVIDIA's hardware H.264 encoder instead, wherever it can open it:

What you runEncoder you get on a GPU machineEncoder you get with no usable GPU
ffmpeg -i in.mov out.mp4 (no encoder named; also .mov, .mkv)h264_nvenc (H.264, on the GPU)mpeg4 (MPEG-4 Part 2, on the CPU), after one warning line
ffmpeg ... -c:v h264 out.mp4, mediapy's write_videoh264_nvencmpeg4, after one warning line
matplotlib's FFMpegWriter (it runs the ffmpeg program)h264_nvencmpeg4 (FFmpeg's warning reaches only matplotlib's DEBUG log)
PyAV container.add_stream("h264")h264_nvencmpeg4 (PyAV hides FFmpeg's warning unless you turn its logging on)

FFmpeg chooses the encoder by opening it once on a 256x256 test picture, before it knows the size of your video. That is why a picture size the GPU encoder refuses is not caught at that point.

2. Small pictures fail on a GPU machine​

NVENC, the GPU's video encoder, refuses pictures below its minimum size. Measured on the DGX Spark (GB10):

Picture sizeWhat happened
64x64, written with no encoder namedffmpeg exited 234: InitializeEncoder failed: invalid param (8): Frame Dimension less than the minimum supported value
96x64refused every time
128x128refused, 5 of 5 tries
160x160opened and wrote the video, 10 of 10 tries

Sizes between 128 and 160 were not measured. On a machine with no usable GPU the same 64x64 write succeeds, as MPEG-4 Part 2, because the CPU encoder has no such minimum.

3. What to do​

Name a CPU encoder for small videos. MPEG-4 Part 2 (mpeg4) is always in the image and runs on the CPU:

ffmpeg -i small.mov -c:v mpeg4 out.mp4

The same choice in the Python libraries:

  • PyAV: container.add_stream("mpeg4")
  • mediapy: media.write_video(path, images, codec="mpeg4")
  • matplotlib: animation.FFMpegWriter(codec="mpeg4")

Or scale the picture up to a size the GPU encoder takes (160x160 worked on the GB10), and keep H.264:

ffmpeg -i small.mov -vf scale=160:160 out.mp4

This changes the video's dimensions, so use it only when that is acceptable.

What does not work in Eugo's image:

  • -c:v libx264: x264 is not built into Eugo's FFmpeg (it is GPL-licensed), so FFmpeg stops with an unknown-encoder error.
  • -c:v libopenh264: the image ships a do-nothing stand-in for Cisco's OpenH264 library, which refuses to create an encoder until you install Cisco's own binary.
  • -c:v h264_nvenc named exactly: the same GPU encoder, with the same minimum size, and with no fallback.

4. Where the numbers come from​

All of them were measured on a DGX Spark (GB10):

  • The 64x64 write and its exit code 234: 2026-10-15.
  • 128x128 refused (5 tries) and 160x160 working (10 tries): 2026-10-14 and 2026-10-15.
  • Which encoder each way of writing gets, with and without a GPU: 2026-10-03.

Small pictures fail loudly on purpose: Eugo chose an error you can see over a silent fallback to a different encoder, and this page is where that choice is documented.