@@ -27,6 +27,7 @@ const PREPARED_HEIF_SUBDIR = "_heif_images";
2727const CACHE_SCHEMA = "hfheif-v1" ;
2828const DEFAULT_TIMEOUT_MS = 120_000 ;
2929export const HEIF_IMAGE_CONVERSION_FAILED = "HEIF_IMAGE_CONVERSION_FAILED" as const ;
30+ const HEIF_TOOL_UNAVAILABLE = "HEIF_TOOL_UNAVAILABLE" as const ;
3031
3132/** The `ftyp` brands of a HEIF still coded with the hevc codec. */
3233const HEIF_BRANDS = new Set ( [ "heic" , "heix" , "hevc" , "hevx" , "heim" , "heis" , "mif1" , "msf1" ] ) ;
@@ -47,6 +48,24 @@ export class HeifImageConversionError extends Error {
4748 }
4849}
4950
51+ /** The host's ffmpeg or ffprobe cannot do the job; a different photo would not help. */
52+ export class HeifToolUnavailableError extends Error {
53+ readonly code = HEIF_TOOL_UNAVAILABLE ;
54+ readonly owner = "system" as const ;
55+ readonly retryable = false as const ;
56+
57+ constructor ( label : string , reason : string ) {
58+ super (
59+ `Could not convert HEIC/HEIF image ${ label } : ${ reason } . ` +
60+ `Converting HEIC needs ffmpeg and ffprobe 7.0 or newer with the hevc decoder.` ,
61+ ) ;
62+ this . name = "HeifToolUnavailableError" ;
63+ }
64+ }
65+
66+ const TOOL_FAILURE_RE =
67+ / (?: f f m p e g | f f p r o b e ) n o t f o u n d | E N O E N T | O p t i o n n o t f o u n d | U n r e c o g n i z e d o p t i o n | U n k n o w n d e c o d e r | D e c o d e r \S + n o t f o u n d / i;
68+
5069export interface HeifTranscodeRequest {
5170 inputPath : string ;
5271 outputPath : string ;
@@ -62,6 +81,8 @@ export interface PrepareHeifImageInputsOptions {
6281 sourceAssets ?: Map < string , string > ;
6382 timeoutMs ?: number ;
6483 transcode ?: ( input : HeifTranscodeRequest ) => Promise < void > ;
84+ /** Leaves an image whose conversion failed as authored and reports it, instead of throwing. */
85+ onFailure ?: ( error : HeifImageConversionError | HeifToolUnavailableError ) => void ;
6586}
6687
6788export interface PreparedHeifImage {
@@ -102,7 +123,7 @@ function readHead(path: string): Buffer | null {
102123 }
103124}
104125
105- interface ProbedStream {
126+ export interface ProbedStream {
106127 width ?: number ;
107128 height ?: number ;
108129 coded_width ?: number ;
@@ -116,9 +137,9 @@ interface ProbedStream {
116137 } [ ] ;
117138}
118139
119- interface ProbeJson {
140+ export interface ProbeJson {
120141 streams ?: ProbedStream [ ] ;
121- stream_groups ?: { components ?: ProbedStream [ ] } [ ] ;
142+ stream_groups ?: { components ?: ProbedStream [ ] ; disposition ?: { default ?: number } } [ ] ;
122143}
123144
124145async function probeJson ( path : string , withGroups : boolean ) : Promise < ProbeJson > {
@@ -138,11 +159,17 @@ const ROTATION_FILTER = {
138159 270 : "transpose=1" ,
139160} as const ;
140161
162+ /** The primary item's grid: the group ffmpeg marks default, so an auxiliary grid listed first is skipped. */
163+ export function primaryGrid ( probed : ProbeJson ) : ProbedStream | undefined {
164+ const groups = probed . stream_groups ?? [ ] ;
165+ return ( groups . find ( ( g ) => g . disposition ?. default === 1 ) ?? groups [ 0 ] ) ?. components ?. [ 0 ] ;
166+ }
167+
141168// ffmpeg through 8.0 decodes a tiled HEIC as separate tiles and ignores its rotation, so stack, crop and rotate.
142169// The JPEG must equal the declared size (swapped for a quarter turn); a lone tile never passes.
143170export async function convertHeifToJpeg ( request : HeifTranscodeRequest ) : Promise < void > {
144171 const probed = await probeJson ( request . inputPath , true ) ;
145- const grid = probed . stream_groups ?. [ 0 ] ?. components ?. [ 0 ] ;
172+ const grid = primaryGrid ( probed ) ;
146173 const rotation = readHeifPrimaryRotation ( readFileSync ( request . inputPath ) ) ;
147174 const filters : string [ ] = [ ] ;
148175 let inputs : string [ ] = [ ] ;
@@ -253,10 +280,10 @@ async function ensurePreparedJpeg(
253280 if ( ! isUsableFile ( tmpPath ) ) throw new Error ( "conversion produced an empty file" ) ;
254281 renameWithRetry ( tmpPath , cachePath ) ;
255282 } catch ( error ) {
256- throw new HeifImageConversionError (
257- source . label ,
258- error instanceof Error ? error . message : String ( error ) ,
259- ) ;
283+ const reason = error instanceof Error ? error . message : String ( error ) ;
284+ throw TOOL_FAILURE_RE . test ( reason )
285+ ? new HeifToolUnavailableError ( source . label , reason )
286+ : new HeifImageConversionError ( source . label , reason ) ;
260287 } finally {
261288 rmSync ( tmpPath , { force : true } ) ;
262289 rmSync ( inlinePath , { force : true } ) ;
@@ -296,15 +323,21 @@ export async function prepareHeifImageInputs(
296323 if ( found . length === 0 ) return { html, preparedAssets, preparedImages } ;
297324
298325 const unique = new Map ( found . map ( ( item ) => [ item . filename , item . source ] ) ) ;
326+ const failed = new Set < string > ( ) ;
299327 await Promise . all (
300328 [ ...unique ] . map ( ( [ filename , source ] ) =>
301329 withMediaProbeSlot ( ( ) =>
302330 ensurePreparedJpeg ( source , join ( cacheDir , filename ) , join ( outputDir , filename ) , options ) ,
303- ) ,
331+ ) . catch ( ( error : HeifImageConversionError | HeifToolUnavailableError ) => {
332+ if ( ! options . onFailure ) throw error ;
333+ failed . add ( filename ) ;
334+ options . onFailure ( error ) ;
335+ } ) ,
304336 ) ,
305337 ) ;
306338
307339 for ( const { img, src, filename } of found ) {
340+ if ( failed . has ( filename ) ) continue ;
308341 const outputSrc = `${ outputSrcPrefix } /${ filename } ` ;
309342 img . setAttribute ( "src" , outputSrc ) ;
310343 preparedAssets . set ( outputSrc , join ( outputDir , filename ) ) ;
0 commit comments