Docs: M1 on macOS also encodes AVIF - Linux would be fine

[Zabrah]

Sorry, I'm not that experienced using Git and this is not an issue itself. Therefore I somehow wanted to report the incorrectness of the information in the Docs https://bun.com/docs/runtime/image which says, only M3+ can encode AVIF on macOS. My M1 iMac can encode to AVIF as well, so there may be a software encoder be implemented in macOS for M1 and M2.

Still it would be nice to also see AVIF encoding in Linux with this getting realized: #30204

[Hotragn]

Your report lines up with the source — the "M3+ only" claim is in the docs but nowhere in the code, so there's nothing on Bun's side that could be rejecting your M1.

The claim is docs/runtime/image.mdx:193:

² AVIF encode needs an OS AV1 encoder — Apple Silicon M3+ only. Intel Mac and M1/M2 reject with ERR_IMAGE_FORMAT_UNSUPPORTED; AVIF decode works everywhere ImageIO does (macOS 13+).

What actually happens: bun_coregraphics_encode (src/jsc/bindings/image_coregraphics_shim.cpp:361) maps the AVIF format to the UTI "public.avif" and hands it straight to ImageIO via CGImageDestinationCreateWithData. If ImageIO won't take it, the call returns CG_UNAVAILABLE / CG_ENCODE_FAILED, which surfaces as ERR_IMAGE_FORMAT_UNSUPPORTED. There is no CPU-model check in the path — grepping src/runtime/image/ and the CoreGraphics shim for a chip, sysctl, or hardware-capability probe turns up nothing. Bun's own error text agrees and is careful not to name a chip (src/runtime/image/Image.rs:653):

Image: format not supported on this machine (HEIC/AVIF/TIFF require the OS codec; AVIF encode needs an AV1 encoder)

So whether AVIF encode works is decided entirely by ImageIO at runtime, and the "M3+ / M1 and M2 reject" sentence is a stronger, more specific claim than either the code or — per your result — the OS makes. AV1 hardware encode genuinely isn't on M1/M2, but that doesn't preclude ImageIO using a software encoder, which is the most likely explanation for what you're seeing.

I'm on Windows and can't reproduce on macOS myself, so rather than substitute one unverified hardware claim for another, I think the honest fix is to make the docs describe the mechanism instead of the silicon: AVIF encode is delegated to the OS codec, is available where macOS provides an AVIF encoder, and raises ERR_IMAGE_FORMAT_UNSUPPORTED where it doesn't. That's exactly what the code does, and it stays correct as OS support changes underneath it.

Two things that would firm this up, if you don't mind:

1. Your macOS version — since ImageIO's AVIF encoder arrived with a specific release, that's the variable actually worth documenting.
2. The output of bun -e 'await Bun.file("in.jpg").image().avif({quality:60}).write("out.avif"); console.log(Bun.file("out.avif").size)' — a non-zero size confirms a real encode rather than a silent fallback.

Happy to send the docs PR with that correction and credit this thread. And agreed on Linux AVIF — that's #30204's territory, not a docs issue.

(No need to apologise for not opening an issue — a docs claim that contradicts a real machine is worth reporting wherever it's easiest.)

[Hotragn]

A correction to what I wrote above. I said the "M3+ only" line was a stronger claim than the OS makes. That was wrong. There is no chip check in Bun's code. But the claim does have a basis, and it's written down in the encode test (test/js/bun/image/image.test.ts, the HEIC/AVIF encode block):

AV1 encode goes through VideoToolbox/AVE which only exists on M3+ (M1/M2 and Intel return kVTCouldNotFindVideoEncoderErr).

So the gate lives in macOS, not in Bun. The docs describe what Jarred saw when he wrote the feature. I also guessed that ImageIO might fall back to a software encoder. I have no evidence for that, so please ignore it.

That makes your M1 result the interesting part. It conflicts with a tested expectation, so it's either a newer macOS adding an encoder path or something else producing the file. The two things I asked for would settle it: your macOS version, and whether .avif() gives you an actual AVIF. This one-liner checks that the output really is AVIF, not just some file with that extension:

const out = await Bun.file("in.jpg").image().avif({ quality: 60 }).bytes();
console.log((await new Bun.Image(out).metadata()).format); // "avif" if the encode really happened

Until someone confirms that on an M1/M2, I don't think the docs should change. I'm not going to open that PR on my reasoning alone.