format: AVIF is the twenty third format, and its encoder is somebody else's

[donislawdev]

AVIF joins the list, and it is the first format here whose pixels are coded by
somebody else's encoder rather than by code in this repository.

tfg generate --format avif --size 300kb
tfg generate --format avif --size 2mb --set width=1920 --set height=1080

What it does

One frame, 8 bit, 4:2:0, in an ISO base media container. width, height and
quality can be set, and the picture goes up to 40 megapixels - the same
ceiling PNG, JPG and GIF use - so Full HD and 4K are both in reach. Left alone,
the picture is the largest of a fixed set that fits the size asked for, up to
640x480, which is what JPG does.

Every size from its minimum of 311 B upwards is reachable, with no gaps. The
padding travels in a free box, the box the container sets aside for space that
means nothing, and it takes any length at all.

Why a borrowed encoder

AV1 is too large to write by hand for one format. The coefficient tables alone
in the nearest implementation are fourteen times the size of this project's
entire WebP encoder, and the whole of it is half again the size of this whole
program. The encoder is github.com/gen2brain/gav1d, pinned, written in Go,
with an empty go.mod of its own - so it brings nothing else along, needs no C
compiler, and links no socket.

Raising it moves bytes, which puts it in the same class as the Go compiler this
project already pins.

Three things measurement changed

The library this started with reached the network. gen2brain/avif runs its
codec as WebAssembly through wazero, and wazero imports net for WASI
sockets - so the command line binary linked a socket for the first time. That
binary not linking net is a promise this project keeps and checks, so the road
was abandoned after being built and measured. gav1d costs 2.30 MB against
6.02 MB, encodes five times faster, allocates twenty six times less, and
reaches nothing.

The encoder's AVX2 path reads past the end of a buffer. A 640x256 picture
kills the process - in two runs out of three, so it turns on what the heap looks
like rather than on the input alone. One size out of 240 crashed with the
assembly and none without it, and the bytes are identical either way. The tag
that removes it lives in .github/build-tags, and every command that compiles
this project reads that file rather than carrying a copy. Probe:
tools/probes/avifasm.

Planning coded the picture to learn its size, so previewing a thousand files
cost 51 seconds where BMP costs a fifth of one, and twenty thousand never
finished inside the test timeout. Each step of the size ladder now carries a
measured ceiling, planning is arithmetic again, and the encode happens while
writing. A thousand files now preview in 0.208 s.

Evidence

• Byte stability on three systems and two architectures: Windows, Linux
  (WSL) and macOS on arm64 produce the same five files, byte for byte. Pinned in
  generator-golden.json as well.
• Readers, with a negative control: Pillow reads every padded file and
  refuses a truncated one and a corrupted payload. ffprobe accepts all three
  broken files, so it witnesses nothing - the evidence rests on Pillow and on a
  structural checker that walks the box tree, which catches five deliberate
  breaks out of five.
• Opened by a person: ImageGlass shows it at 320x240, 300 KB, with the label
  readable.
• Seven new guards, each proven by a mutation. Six stale mutation entries
  repaired along the way, three of them older than this branch.

Binaries: command line 8 010 752 -> 10 417 664 B, window 52 041 709 B.

Full record, including the roads turned down and what they cost:
docs/STACK.md section 4.2.1.

🤖 Generated with Claude Code