From f4b9596a88508522c653cad0cb3616e40fcbbc71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Padez?= Date: Sat, 29 Aug 2026 07:36:32 +0100 Subject: [PATCH] HEIC gets a thumbnail, through the decoder that can actually read it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit sharp ships its own libvips and libheif built WITHOUT the HEVC decoder, so a HEIC parses its header, reports 4032x3024, and then fails on the pixels with "bad seek". that reads like a corrupt file and is not one — every photograph an iPhone takes is HEVC-coded HEIF, so it is most of what arrives from a phone. ImageMagick links the SYSTEM libheif, which has the codec. so a `.heic` goes through `convert` to a lossless PNG and sharp takes it from there. PNG rather than JPEG for the intermediate so the single real encode is the final one and the thumbnail is not a copy of a copy. removed in a `finally` either way — a failed decode must not leave a stray file a later run mistakes for a finished thumbnail. this is deliberately the same approach av-club has used for weeks (sidecar/sharp/decodable.ts), on these exact files. copied rather than shared, because the platform must not import from a plugin — the dependency only runs the other way, and fifteen lines of spawn is cheaper than inverting it. `convert` exits 0 having written nothing when the codec is missing, so the OUTPUT FILE is the test rather than the exit code. that is not defensive: it is precisely the failure this exists to handle. IT NEEDS `libheif-plugin-libde265`, which is not in a default Ubuntu install — libheif packages its codecs separately and ships the AV1 one, not the HEVC one. declared in av-club's manifest today, and installed on this host to prove the path. without it, `convert` fails the same way sharp does and the browser falls back to the file icon, which is the correct degradation rather than a break. the in-memory failure cache did exactly what its comment said it would: the HEIC stayed 422 after the codec was installed, until a restart. "a restart is the natural moment to give a file another chance after somebody has installed a codec" — written weeks ago, met today. verified: a real iPhone HEIC, 2 MB in, 12 KB out, 5.3s cold and 22ms cached, and the image is right. png, svg and mp4 unchanged. Co-Authored-By: Claude Opus 5 Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043 --- src/servers/api/file-browser/thumbnails.ts | 60 +++++++++++++++++++++- 1 file changed, 58 insertions(+), 2 deletions(-) diff --git a/src/servers/api/file-browser/thumbnails.ts b/src/servers/api/file-browser/thumbnails.ts index 82de48be..c6483a68 100644 --- a/src/servers/api/file-browser/thumbnails.ts +++ b/src/servers/api/file-browser/thumbnails.ts @@ -1,5 +1,5 @@ import { createHash } from 'node:crypto'; -import { mkdir, stat } from 'node:fs/promises'; +import { mkdir, rm, stat } from 'node:fs/promises'; import { extname, join } from 'node:path'; import sharp from 'sharp'; @@ -179,6 +179,44 @@ const spawnFfmpeg = async (args: string[], output: string): Promise => * Errors are swallowed to `false` rather than thrown — a file sharp cannot read is a fact about the * file, and the caller already turns that into a fallback icon and a remembered failure. */ +/** Extensions sharp's bundled libheif cannot decode — see `decodeViaImageMagick`. */ +const NEEDS_IMAGEMAGICK = new Set(['heic', 'heif']); + +/** + * Get a HEIC into something sharp can actually read. + * + * ── Why this is necessary at all ── + * + * sharp ships its own libvips and libheif, built WITHOUT the HEVC decoder — so it parses a HEIC's + * header, reports 4032x3024 quite happily, and then fails on the pixels with "bad seek". That reads + * exactly like a corrupt file and is not one. Every photograph an iPhone takes is HEVC-coded HEIF, so + * this is not an edge case; it is most of what arrives from a phone. + * + * ImageMagick links the SYSTEM libheif, which does have the codec — provided + * `libheif-plugin-libde265` is installed. That package is the entire difference: without it, + * ImageMagick fails the same way with "Unsupported codec". Observed on two hosts running identical + * libheif 1.17.6, one working and one not. + * + * ── This is deliberately the same approach av-club already uses ── + * + * `plugins/av-club/sidecar/sharp/decodable.ts` solved this first and has been converting these exact + * files for weeks. Copied rather than shared because the platform must not import from a plugin — the + * dependency only runs the other way — and fifteen lines of spawn is a smaller cost than inverting that. + * + * PNG for the intermediate, not JPEG: it is lossless, so the single real encode is the final one and the + * thumbnail is not a copy of a copy. + */ +const decodeViaImageMagick = async (input: string, output: string): Promise => { + const proc = Bun.spawn(['convert', `${input}[0]`, output], { stdout: 'ignore', stderr: 'ignore' }); + const timer = setTimeout(() => proc.kill(), 30_000); + await proc.exited; + clearTimeout(timer); + // The file is the test, never the exit code — ImageMagick exits 0 having written nothing when the + // codec is missing, which is precisely the case this exists to handle. + const written = await stat(output).catch(() => null); + return written !== null && written.size > 0; +}; + const resizeImage = async (input: string, output: string, size: number): Promise => { try { await sharp(input, { failOn: 'none', limitInputPixels: false, animated: false }) @@ -237,7 +275,25 @@ export async function buildThumbnail( let ok: boolean; if (kind === 'image') { - ok = await resizeImage(absPath, cachePath, size); + /* + HEIC goes through ImageMagick first. Everything else — jpeg, png, webp, avif, svg — sharp reads + directly, so this costs nothing for the common case. + + The intermediate lands in the same cache directory and is removed either way: a failure here + must not leave a stray PNG that a later run mistakes for a finished thumbnail. + */ + const ext = extname(absPath).slice(1).toLowerCase(); + if (NEEDS_IMAGEMAGICK.has(ext)) { + const intermediate = `${cachePath}.decoded.png`; + try { + ok = + (await decodeViaImageMagick(absPath, intermediate)) && (await resizeImage(intermediate, cachePath, size)); + } finally { + await rm(intermediate, { force: true }); + } + } else { + ok = await resizeImage(absPath, cachePath, size); + } } else { // `-ss` BEFORE `-i` is the fast seek — it jumps rather than decoding a second of video first. ok = await spawnFfmpeg(['-ss', SEEK_SECONDS, '-i', absPath, ...common], cachePath);