@@ -29,7 +29,7 @@ import {
2929 getGpuEncoderName ,
3030 mapPresetForGpuEncoder ,
3131} from "../utils/gpuEncoder.js" ;
32- import { formatFfmpegError } from "../utils/runFfmpeg.js" ;
32+ import { formatFfmpegError , isExternalFfmpegInterruption } from "../utils/runFfmpeg.js" ;
3333import { getFfmpegBinary } from "../utils/ffmpegBinaries.js" ;
3434import { getHdrEncoderColorParams } from "../utils/hdr.js" ;
3535import { withEvenDimensionPad } from "../utils/evenDimensions.js" ;
@@ -159,6 +159,8 @@ export interface StreamingEncoderResult {
159159 durationMs : number ;
160160 fileSize : number ;
161161 error ?: string ;
162+ /** Stable machine-readable cause for failures safe to retry on a fresh host. */
163+ failureReason ?: "external_interruption" ;
162164}
163165
164166export interface StreamingEncoder {
@@ -179,6 +181,8 @@ export interface StreamingEncoder {
179181 * unsupported codec, disk full) instead of a bare "encoder exited" message.
180182 */
181183 getExitError : ( ) => string | undefined ;
184+ /** Machine-readable cause available after FFmpeg exits unexpectedly mid-write. */
185+ getExitFailureReason ?: ( ) => "external_interruption" | undefined ;
182186}
183187
184188/**
@@ -465,6 +469,7 @@ export async function spawnStreamingEncoder(
465469 let exitStatus : "running" | "success" | "error" = "running" ;
466470 let stderr = "" ;
467471 let exitCode : number | null = null ;
472+ let exitSignal : NodeJS . Signals | null = null ;
468473 let terminationReason : ManagedProcessTerminationReason = "exit" ;
469474
470475 ffmpeg . stdin ?. on ( "error" , ( ) => { } ) ;
@@ -486,6 +491,7 @@ export async function spawnStreamingEncoder(
486491 } ) ;
487492 const exitPromise = managed . wait ( ) . then ( ( outcome ) => {
488493 exitCode = outcome . exitCode ;
494+ exitSignal = outcome . signal ;
489495 stderr = outcome . stderr ;
490496 terminationReason = outcome . reason ;
491497 exitStatus = outcome . reason === "exit" && outcome . exitCode === 0 ? "success" : "error" ;
@@ -530,7 +536,15 @@ export async function spawnStreamingEncoder(
530536 const encoder : StreamingEncoder = {
531537 writeFrame : async ( buffer : Buffer ) : Promise < boolean > => {
532538 const stdin = ffmpeg . stdin ;
533- if ( exitStatus !== "running" || ! stdin || stdin . destroyed ) {
539+ if ( exitStatus !== "running" ) {
540+ return false ;
541+ }
542+ if ( ! stdin || stdin . destroyed ) {
543+ // The OS can close the pipe (EPIPE) before Node delivers the child
544+ // process `close` event. Wait for the shared exit settlement so the
545+ // caller can synchronously inspect getExitFailureReason() instead of
546+ // losing a host-interruption signal in this narrow race.
547+ await exitPromise ;
534548 return false ;
535549 }
536550 // Copy the buffer before writing — Node streams hold a reference to the
@@ -604,6 +618,14 @@ export async function spawnStreamingEncoder(
604618 durationMs,
605619 fileSize : 0 ,
606620 error : `${ formatFfmpegError ( exitCode , stderr ) } ${ inactivitySuffix } ` ,
621+ failureReason : isExternalFfmpegInterruption ( {
622+ exitCode,
623+ signal : exitSignal ,
624+ stderr,
625+ terminationReason,
626+ } )
627+ ? "external_interruption"
628+ : undefined ,
607629 } ;
608630 }
609631
@@ -618,6 +640,18 @@ export async function spawnStreamingEncoder(
618640 if ( exitStatus !== "error" ) return undefined ;
619641 return formatFfmpegError ( exitCode , stderr ) ;
620642 } ,
643+
644+ getExitFailureReason : ( ) => {
645+ if ( exitStatus !== "error" ) return undefined ;
646+ return isExternalFfmpegInterruption ( {
647+ exitCode,
648+ signal : exitSignal ,
649+ stderr,
650+ terminationReason,
651+ } )
652+ ? "external_interruption"
653+ : undefined ;
654+ } ,
621655 } ;
622656
623657 return encoder ;
0 commit comments