Ffmpeg on PHP Boy Scout

The afternoon the agent earned its keep

Thu, 09 Jul 2026 00:00:00 +0000

There’s a kind of bug that’s worse than a crash. A crash at least tells you where. This one just… stopped. I asked ffmpeg-wasi to remux a clip into a Matroska file, no re-encoding, just repackage the same streams into an .mkv, and it never came back. No error, no output. The test harness eventually gave up and shot it.

The same job to an .mp4? A dozen milliseconds. Change the file extension and a blink becomes a heat-death-of-the-universe operation.

Normally this is the moment a war story starts costing me evenings. FFmpeg compiled to wasm32-wasi, running under wazero, reading and writing through an in-memory filesystem… that’s a lot of layers, any of which could be the one that loops, and the traditional way to find out is to build test rigs for each layer by hand and lose a week to the plumbing. I know what that costs because I’ve paid it before.

This time I didn’t pay it. The hang surfaced while an agent was implementing stream-copy for me, so rather than pull the work back onto my own bench, I told it to chase the bug too. What follows is the deduction it ran. My contribution was two decisions at two forks, and I’ll point at them as we pass.

It got it wrong first

I want to start with the wrong turn, because it’s the most instructive part.

The agent’s first theory was confident and detailed: it traced the guest’s filesystem calls, saw the Matroska muxer seeking back and forth rewriting its header, and declared the finalisation seek-backs the culprit, an I/O pattern my filesystem bridge couldn’t satisfy. Plausible. Specific. Wrong.

And here’s the bit that sold me: it then designed the experiment that killed its own theory. Matroska has a streamable mode that writes without any seek-backs at all, so it flipped that on… and the job still hung. Theory dead, evidence in hand, no sulking. I’ve watched humans (fine, me) defend a pet theory for two days past its expiry date. The agent binned its own in minutes and moved on to the thing you should always do when guessing stops working: bisect.

Ruling out the world, one build at a time

This was my first fork. The agent asked whether to keep poking at it in place or to bring in native tooling, and I chose native. So it built a real FFmpeg, same n8.1.2 source, same minimal configure flags, and started eliminating suspects:

It tested	Result	Which ruled out
Native FFmpeg, 64-bit, real files → mkv	works	the muxer / our configure flags
wasm backed by a real OS directory	hangs	the in-memory filesystem
Native FFmpeg, 32-bit (`-m32`) → mkv	works	a 32-bit integer overflow
wasm under wazero’s interpreter	hangs	a code-generation bug

Sit with that table for a second. Two of those rows are whole native builds of FFmpeg, one of them 32-bit with the toolchain to match, spun up as casually as you’d write a unit test. That’s the part that would have eaten my week. Each row walks an interesting suspect free, until the only thing left holding the bag is the plainest fact in the whole setup: this is running under WASI. Not the muxer. Not the maths. Not my filesystem. Not the runtime. The environment.

The environment was missing a number

WASI is a smaller world than POSIX. No threads, no network, and, it turns out, no /dev/urandom. Most code never notices. Right up until it does.

With the bisection result in hand, the agent went and read the Matroska muxer’s source. Every Matroska track carries a unique random identifier, so at startup the muxer seeds a pseudo-random number generator via libavutil’s av_get_random_seed(). In a build configured as tightly as ours, that function has exactly one source of real entropy compiled in: reading /dev/urandom. The Windows crypto API, arc4random, OpenSSL, libgcrypt… all configured out. Just the one device.

Which WASI doesn’t have. So the read fails, and the function falls back to its last resort, get_generic_seed(): a genuinely clever routine that manufactures entropy out of thin air by reading clock() in a tight loop and harvesting the jitter in how it advances. It’s a lovely trick. It has one requirement. The clock has to advance.

Under WASI, clock() doesn’t advance. The seeding call never returns. The muxer hangs before it has written a single byte, and the .mp4 muxer never asks for randomness at all, which is the entire reason it was fine all along.

The agent didn’t leave that as a theory either. It wired av_get_random_seed() into a trivial diagnostic op, one that does nothing else… and that hung too. Root cause, demonstrated in isolation.

A device, not a patch

The fix isn’t a patch to FFmpeg. It’s a device. My filesystem bridge already fabricates a couple of the POSIX fixtures a guest expects (/tmp routed to scratch space, /dev/null as a discard sink), so /dev/urandom is the same trick with real randomness behind it, backed by Go’s crypto/rand:

// Read fills buf with random bytes; a short read never happens (crypto/rand
// fills the whole slice or errors), matching /dev/urandom's contract.
func (*randFile) Read(buf []byte) (int, experimentalsys.Errno) {
	if _, err := rand.Read(buf); err != nil {
		return 0, experimentalsys.EIO
	}

	return len(buf), 0
}

Now the muxer’s very first entropy read succeeds, the seed returns immediately, and the clever-but-doomed clock loop is never reached. The .mkv remux that had been hanging forever finishes in ten milliseconds. And the fix isn’t Matroska-specific: any format that wants a random seed now gets one for free.

What the afternoon actually cost

Here’s the arithmetic that made me want to write this up.

From the first observed hang to a verified fix was a little over an hour. That hour included the wrong theory and the experiment that disproved it, two complete native builds of FFmpeg (one of them 32-bit), runs across two wazero execution modes, a read through libavutil’s entropy code, the diagnostic op that proved the root cause in isolation, and the fix itself. The agent even went looking for prior art and couldn’t find anyone who’d written this failure up… a genuinely undocumented corner of WASI, run to ground between lunch and tea.

By hand? Most of a week, and the bulk of it spent on build plumbing rather than thinking: getting a matching native FFmpeg to configure, wrangling a 32-bit toolchain, wiring the trace points. None of that work is hard. It’s just time, and it’s exactly the kind of time a solo developer doesn’t have lying around, which is how deep bugs like this end up parked on a “someday” list with the .mkv button greyed out.

My whole part was two forks (dig in place, or go native? and later: document it before touching anything else) and reading the result. The judgement stayed mine. The legwork didn’t.

I’ve compared these agents to Golden Retrievers before, and I stand by it: eager, tireless, loyal to their training, occasionally proud of a shredded cushion. A dog that plays fetch all day is good company. But this one went down the burrow after something I couldn’t see, and came back with the exact rabbit.

Good boy.

Introducing afmpeg and ffmpeg-wasi: FFmpeg with no install, no CGO, no disk

Sun, 28 Jun 2026 00:00:00 +0000

keryx renders short promo reels, and the way it does that, today, is the way nearly everything does: it shells out to the ffmpeg binary. Which is fine, until you ask it to render a project that doesn’t exist on disk. keryx can work on an in-memory project, a repo cloned straight into RAM with no local checkout, and the moment it tries to hand that to ffmpeg, the whole thing falls over. The binary wants real files in a real directory. There aren’t any.

I went looking for a way out and didn’t find one I could live with. The bindings that use purego/dlopen are immature and still need the host’s libav libraries installed. The CGO bindings to libav are mature and can absolutely work in memory, but they’re CGO, and CGO takes away the thing I most want from a Go program: a clean static cross-compile to a single binary that runs anywhere. The famous ffmpeg.wasm is an emscripten build aimed at the browser, which is the opposite target from a server-side Go tool. And the one existing WASI-capable build pins FFmpeg 5.1, which is end-of-life, and I’m not shipping an out-of-support media decoder whose entire job is parsing untrusted files. Every road had a tollbooth I wasn’t willing to pay.

So I built two new things instead, and because they’re so closely tied I’m introducing them together.

ffmpeg-wasi: current FFmpeg, sandboxed, CGO-free

ffmpeg-wasi (repo) is the foundation, and it’s the harder of the two to build. It takes FFmpeg’s media libraries, the libav* family, and builds them to wasm32-wasi, then drives them with a small purpose-built engine, producing a single .wasm artifact that runs anywhere a WASI runtime does. No native FFmpeg install, no C toolchain at deploy time, no shelling out to a binary. It’s built to run under wazero, the zero-dependency pure-Go WebAssembly runtime, so a Go program can transcode, filter and mux media embedded, sandboxed, and CGO-free, still cross-compiling to one static binary.

The interesting bit, the reason this didn’t already exist, is a wall that FFmpeg 7.0 put up. The 7.x series rewrote the command-line tool to be mandatorily multithreaded, and a pure-Go WASI runtime can’t run that, because the threading model it needs (wasi-threads, spawning real threads) isn’t something wazero does. Every project trying to get current FFmpeg into WASI hits that wall, which is exactly why the existing build froze at the last single-threaded CLI, 5.1, and went EOL there. ffmpeg-wasi goes under the wall instead of over it: it doesn’t compile the CLI at all. It links the libav* libraries directly, which build single-threaded without complaint, and drives them with its own engine. That’s the move nobody else has made, and it’s the whole reason this can track current, maintained FFmpeg rather than a frozen one.

afmpeg: the pure-Go binding that lives in memory

afmpeg (repo) was the catalyst for all this, and it’s the part a Go developer actually touches. It’s a small, idiomatic Go API (New, Run, Probe, Close) sitting on top of the ffmpeg-wasi artifact, with one important twist: its I/O is bridged to an afero.Fs. afero isn’t in the standard library, but it’s the filesystem abstraction a great deal of Go already reaches for when it wants to swap a real disk for something else, and that “something else” is exactly the point here. The inputs and outputs of a media job can live entirely in memory, or in any afero backend you like, and ffmpeg is none the wiser. keryx gets to render its in-memory project without ever touching the disk, which was the whole reason I started.

This isn’t a roadmap post. Both projects are released and run today: afmpeg is at v0.4.0, ffmpeg-wasi at n8.1.2-1 (current FFmpeg, not the EOL 5.1), and between them they do real in-memory transcodes, verified end to end, WAV to AAC and H.264 rescaled and re-encoded with x264. Stripped of keryx’s reel-specific filtergraph, the shape a caller actually deals with is about this small:

// Compile the ffmpeg-wasi module once, then reuse the runtime.
rt, err := afmpeg.New(ctx, afmpeg.WithModuleFile("ffmpeg-wasi-lgpl.wasm"))
if err != nil {
 return err
}
defer rt.Close(ctx)

// The whole job lives in memory: no temp dir, nothing on disk.
fs := afero.NewMemMapFs()
afero.WriteFile(fs, "in.wav", input, 0o644)

// Drive it with the ffmpeg arguments you already know...
res, err := rt.Run(ctx, fs, "-i", "in.wav", "-c:a", "aac", "out.m4a")
if err != nil || res.ExitCode != 0 {
 return fmt.Errorf("render failed: %w (%s)", err, res.Stderr)
}

// ...then read the finished file straight back out of memory.
out, _ := afero.ReadFile(fs, "out.m4a")

The .wasm itself is a published release artifact you pin by SHA-256 (or let afmpeg fetch and verify for you with WithModuleURL), so the licence boundary stays explicit and nothing surprising ends up in your binary.

It doesn’t do everything yet, and I’d rather say so than let you find out the hard way. Single input to single output and Probe work now; the full multi-pad filter_complex and multi-output muxing are the next thing on the bench. But the part that nobody had cracked, getting current FFmpeg to run sandboxed, pure-Go, over a virtual filesystem with nothing on disk, is done, and you can pull it today.

Why it’s two repos

There’s a reason these are separate projects rather than one, and it’s about licences, not tidiness. The moment you compile FFmpeg you’re handling LGPL and GPL code, and I wanted that boundary to be obvious rather than smeared across one repo where nobody’s quite sure what’s covered by what. So the build tooling and the (L)GPL .wasm artifacts live in ffmpeg-wasi, with no grey areas, and afmpeg stays a clean permissive layer on top of the published artifact. I’m also shipping both LGPL and GPL builds of the artifact, so anyone who just wants the output and doesn’t fancy doing their own FFmpeg build can pick the licence that suits them and get on with it.

Both repos are public, so you can rebuild or relink either one yourself, and the doc sites are now linked in the nav up top.

There’s a stack of stories behind these two already, the threading wall and the spike that found the way under it, the afero-to-WASI filesystem bridge, the day I built a reel-shaped API and then reverted it before merge for being too narrow, the licence decision in full. I’ll be writing those up as the work lands. For now this is the headline: I needed an FFmpeg I could embed in a Go program with no install, no CGO, and no disk, couldn’t buy one off the shelf, so I built it in the open, and as of today it’s there to pull.