HEIC File Detection: The One-Line Fix a Commenter Gave Me
HEIC File Detection: The One-Line Fix a Commenter Gave Me A user wrote in that SnapShrink rejected their photo. The file was named vacation.jpg, the error said the format wasn't supported, and the same photo opened fin
HEIC File Detection: The One-Line Fix a Commenter Gave Me
A user wrote in that SnapShrink rejected their photo. The file was named vacation.jpg, the error said the format wasn't supported, and the same photo opened fine in their phone's gallery. I asked for the file, read the first bytes, and they weren't JPEG at all. The photo was a HEIC wearing a .jpg name, and my detector had trusted the name. That bug is what heic file detection is for, and a Dev.to commenter named omyvnss handed me the fix in a single sentence.
Why heic file detection can't trust the extension
Extensions are labels anyone can change, and they change constantly: phones save HEIC and users rename it, messaging apps rewrap files on send, downloads arrive with the wrong suffix. A detector that reads the extension misreads every one of those files, so the fix is to read the file's own header and let the bytes say what the file is.
JPEG files start with FF D8 FF. PNG files start with 89 50 4E 47. Those magic numbers are why sniffing works for most formats: the first bytes name the format, and the name on the file is irrelevant. HEIC is trickier, because it has no magic number in the same sense. It has a box structure, and the box is what you read.
The renaming happens more often than you'd think. A user renames a file to get past an upload form that only lists .jpg, and the form still rejects it, because the bytes are HEIC and the form checks those. AirDrop preserves HEIC while the receiving app tacks on a .jpg suffix. A phone set to save HEIC hands you a file that some other app already renamed. Every one of those files looks fine in a gallery and breaks in a converter that trusts the extension.
Heic file detection in twelve bytes
Every HEIF file starts with a box structure, and the first box is ftyp: four bytes for the box size, the letters ftyp, then a major brand such as heic or mif1. Reading the first twelve bytes of a file tells you whether it is HEIC before you decode a single pixel, and the check costs almost nothing.
The layout is fixed: bytes 0 to 3 hold the box size, bytes 4 to 7 hold the letters ftyp, and bytes 8 to 11 hold the major brand. iPhones write heic. Other writers use heix, hevc, heim, or heis, and mif1 is the generic HEIF brand. AVIF uses the same box with the brand avif, so the same sniff catches AVIF too. One check, two formats.
async function sniffFormat(file) {
const head = new Uint8Array(await file.slice(0, 12).arrayBuffer());
const box = String.fromCharCode(...head.slice(4, 8));
const brand = String.fromCharCode(...head.slice(8, 12));
const heicBrands = ['heic', 'heix', 'hevc', 'heim', 'heis', 'mif1', 'msf1'];
if (box === 'ftyp' && heicBrands.includes(brand)) return 'heic';
if (box === 'ftyp' && (brand === 'avif' || brand === 'avis')) return 'avif';
if (head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff) return 'jpeg';
if (head[0] === 0x89 && head[1] === 0x50) return 'png';
return 'unknown';
}
That is the whole detector: twelve bytes, a string compare, and a short brand list. It runs in a millisecond, and it runs before anything else touches the file.
The fix: let the bytes pick the decoder
The change was small: before routing a file to a decoder, run the twelve-byte sniff and let the bytes pick the decoder. A file named .jpg that sniffs as HEIC goes to the HEIC decoder, and a file named .heic that sniffs as JPEG goes to the JPEG decoder. The extension becomes a hint, not a decision about decoding.
The suggestion arrived as a comment on my Dev.to post about HEIC work. omyvnss wrote that I should check the ftyp box header before trusting the extension, and they were right: the misnamed files started converting instead of erroring, and the fix shipped in SnapShrink's HEIC detection. If you have a misnamed iPhone photo of your own, the HEIC to PNG converter takes it, whatever the extension says. For a smaller sharing file, the HEIC to JPG converter runs the same check.
Two edge cases are worth handling. A file shorter than twelve bytes has no header to read, so guard the slice and return unknown instead of crashing. A file that sniffs as nothing known should fall back to the extension, and if that fails too, the error message should name the bytes it found, so the user can see what the file actually is instead of guessing.
FAQ
Can a file have no extension at all?
Yes, and the sniff still works. The bytes don't care about the name, which is the point. A file with no extension and a ftyp/heic header is a HEIC file, and the decoder takes it from there.
Why not try every decoder until one works?
You can, but the errors are slow and confusing, and some decoders fail halfway through a file instead of up front. Twelve bytes up front is cheaper than a failed decode, and the error message names the format the file actually is.
Does sniffing replace validation?
No. Sniffing picks the decoder. The decoder still has to parse the whole file, and a corrupt HEIC fails there. Sniffing answers what the file is, not whether it is valid.
That vacation.jpg from the start of this article was a HEIC all along, and after the fix it converted without a complaint. The lesson cost me one rejected upload and one comment thread: file names are a suggestion, and twelve bytes settle the argument. If you parse uploads of any kind, read the header first. And if a reader spots your bug before you do, say their name when you write it up. Thanks, omyvnss.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.