# Writing video with FFmpeg: the GPU encoder and small pictures

Which H.264 encoder Eugo's FFmpeg picks on a machine with an NVIDIA GPU, the GPU encoder's minimum picture size, and what to do for small videos in ffmpeg, PyAV, mediapy and matplotlib.

Source: https://docs.eugo.io/docs/guides/video-with-ffmpeg-on-the-gpu/

---

> **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 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_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.
