Writing video with FFmpeg: the GPU encoder and small pictures
Audience: people who write video (
.mp4,.mov,.mkv) in the Eugo image with theffmpegprogram, 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 run | Encoder you get on a GPU machine | Encoder 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_video | h264_nvenc | mpeg4, after one warning line |
matplotlib's FFMpegWriter (it runs the ffmpeg program) | h264_nvenc | mpeg4 (FFmpeg's warning reaches only matplotlib's DEBUG log) |
PyAV container.add_stream("h264") | h264_nvenc | mpeg4 (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 size | What happened |
|---|---|
| 64x64, written with no encoder named | ffmpeg exited 234: InitializeEncoder failed: invalid param (8): Frame Dimension less than the minimum supported value |
| 96x64 | refused every time |
| 128x128 | refused, 5 of 5 tries |
| 160x160 | opened 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_nvencnamed 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.