2626 * branch + same args.
2727 * - `Encoding failed: <err>` throws on the encoder's
2828 * `success: false`.
29+ *
30+ * `encodeWhileCapturing` runs the same mp4 encode during multi-worker disk
31+ * capture, feeding frames in order as they land, and falls back to this
32+ * stage's encode if it fails.
2933 */
3034
3135import {
@@ -38,6 +42,7 @@ import {
3842 statSync ,
3943 writeFileSync ,
4044} from "node:fs" ;
45+ import { readFile } from "node:fs/promises" ;
4146import { dirname , join } from "node:path" ;
4247import {
4348 encodeFramesChunkedConcat ,
@@ -47,16 +52,18 @@ import {
4752 MIXED_AUDIO_FILENAME ,
4853 resolveConfig ,
4954 runFfmpeg ,
55+ spawnStreamingEncoder ,
5056 type EngineConfig ,
5157 type EncodeResult ,
58+ type LandedFrame ,
5259} from "@hyperframes/engine" ;
5360import {
5461 clearGifFramesBeforeNext ,
5562 gifClearsAfterLeavingFrameInPlace ,
5663 type Fps ,
5764} from "@hyperframes/core" ;
5865import type { ProducerLogger } from "../../../logger.js" ;
59- import { formatExportFrameName } from "../../../utils/paths.js" ;
66+ import { formatCaptureFrameName , formatExportFrameName } from "../../../utils/paths.js" ;
6067import type { ProgressCallback , RenderJob } from "../../renderOrchestrator.js" ;
6168import {
6269 buildGifPalettegenArgs ,
@@ -108,7 +115,8 @@ export interface EncodeStageInput {
108115 enableChunkedEncode : boolean ;
109116 chunkedEncodeSize : number ;
110117 /** Already-resolved engine config from the orchestrator; direct callers fall back below. */
111- engineConfig ?: Pick < EngineConfig , "ffmpegEncodeTimeout" | "vp9CpuUsed" > ;
118+ engineConfig ?: Pick < EngineConfig , "ffmpegEncodeTimeout" | "vp9CpuUsed" > &
119+ Partial < Pick < EngineConfig , "ffmpegStreamingTimeout" > > ;
112120 abortSignal : AbortSignal | undefined ;
113121 assertNotAborted : ( ) => void ;
114122 onProgress ?: ProgressCallback ;
@@ -254,23 +262,183 @@ function startEncodeProgress(
254262 return ( frames = total ) => reportEncodeProgress ( job , frames , total , onProgress , 75 ) ;
255263}
256264
265+ function resolveEngineConfig ( input : EncodeStageInput ) {
266+ return input . engineConfig ?? input . job . config . producerConfig ?? resolveConfig ( ) ;
267+ }
268+
269+ function videoEncoderOptions ( input : EncodeStageInput , engineCfg : Pick < EngineConfig , "vp9CpuUsed" > ) {
270+ const { job, preset } = input ;
271+ return {
272+ fps : job . config . fps ,
273+ width : input . width ,
274+ height : input . height ,
275+ codec : preset . codec ,
276+ preset : preset . preset ,
277+ quality : input . effectiveQuality ,
278+ bitrate : input . effectiveBitrate ,
279+ pixelFormat : preset . pixelFormat ,
280+ vp9CpuUsed : engineCfg . vp9CpuUsed ,
281+ useGpu : job . config . useGpu ,
282+ hdr : preset . hdr ,
283+ // Distributed chunk renders pass these so the encoder writes closed-GOP
284+ // keyframes that survive `-f concat -c copy` at assemble time. In-process
285+ // renders leave both undefined → preserves the existing open-GOP output.
286+ lockGopForChunkConcat : input . lockGopForChunkConcat === true ,
287+ gopSize : input . gopSize ,
288+ } ;
289+ }
290+
291+ /**
292+ * Software libx264 from JPEG only: the streaming encoder then runs the disk encoder's
293+ * arguments (same bytes). Needs a core the capture workers leave free.
294+ */
295+ export function canEncodeWhileCapturing (
296+ input : EncodeStageInput ,
297+ workerCount : number ,
298+ cpuCount : number ,
299+ ) : boolean {
300+ return (
301+ workerCount > 1 &&
302+ workerCount < cpuCount &&
303+ ! input . isPngSequence &&
304+ ! input . isGif &&
305+ ! input . enableChunkedEncode &&
306+ input . preset . codec === "h264" &&
307+ ! input . preset . hdr &&
308+ input . job . config . useGpu !== true &&
309+ input . captureImageFormat === "jpeg" &&
310+ input . lockGopForChunkConcat !== true
311+ ) ;
312+ }
313+
314+ export interface EncodeWhileCapturing {
315+ /** A worker finished writing this frame. */
316+ onFrameLanded : ( frame : LandedFrame ) => void ;
317+ /** Capture succeeded and every frame is in `framesDir`: encode the rest. */
318+ finish : ( ) => Promise < EncodeStageResult > ;
319+ /** Capture failed: stop the encoder and wait for it to exit. */
320+ abort : ( ) => Promise < void > ;
321+ /** Frames handed to the encoder so far. */
322+ readonly framesFed : number ;
323+ }
324+
325+ /** The merge renames a worker's frame into `framesDir` at any moment; rename is atomic, so it is at one of the two. */
326+ async function readLandedFrame ( workerPath : string | undefined , mergedPath : string ) {
327+ if ( workerPath !== undefined ) {
328+ try {
329+ return await readFile ( workerPath ) ;
330+ } catch ( error ) {
331+ if ( ( error as NodeJS . ErrnoException ) . code !== "ENOENT" ) throw error ;
332+ }
333+ }
334+ return readFile ( mergedPath ) ;
335+ }
336+
337+ /**
338+ * Feeds frames 0, 1, 2… to the encoder as each lands; capture never waits on it.
339+ * On failure `finish` re-runs `runEncodeStage` on the same frames.
340+ */
341+ export function encodeWhileCapturing (
342+ input : EncodeStageInput ,
343+ totalFrames : number ,
344+ ) : EncodeWhileCapturing {
345+ const engineCfg = resolveEngineConfig ( input ) ;
346+ const stop = new AbortController ( ) ;
347+ const signal = input . abortSignal
348+ ? AbortSignal . any ( [ input . abortSignal , stop . signal ] )
349+ : stop . signal ;
350+ const landed = new Map < number , string > ( ) ;
351+ let captureDone = false ;
352+ let framesFed = 0 ;
353+ let wake : ( ( ) => void ) | null = null ;
354+ const nudge = ( ) => {
355+ wake ?.( ) ;
356+ wake = null ;
357+ } ;
358+ signal . addEventListener ( "abort" , nudge , { once : true } ) ;
359+ let reportFed = null as ( ( frames ?: number ) => void ) | null ;
360+
361+ const encoder = spawnStreamingEncoder (
362+ input . videoOnlyPath ,
363+ { ...videoEncoderOptions ( input , engineCfg ) , imageFormat : "jpeg" } ,
364+ signal ,
365+ engineCfg ,
366+ ) ;
367+ const fed : Promise < unknown > = ( async ( ) => {
368+ const stream = await encoder ;
369+ for ( let next = 0 ; next < totalFrames ; next ++ ) {
370+ while ( ! landed . has ( next ) && ! captureDone && ! signal . aborted ) {
371+ await new Promise < void > ( ( resolve ) => ( wake = resolve ) ) ;
372+ }
373+ if ( signal . aborted ) return ;
374+ const mergedPath = join ( input . framesDir , formatCaptureFrameName ( next , "jpg" ) ) ;
375+ const frame = await readLandedFrame ( landed . get ( next ) , mergedPath ) ;
376+ landed . delete ( next ) ;
377+ if ( ! ( await stream . writeFrame ( frame ) ) ) {
378+ throw new Error ( stream . getExitError ( ) ?? "encoder exited before the last frame" ) ;
379+ }
380+ framesFed ++ ;
381+ reportFed ?.( framesFed ) ;
382+ }
383+ } ) ( ) . then (
384+ ( ) => undefined ,
385+ ( error : unknown ) => error ?? new Error ( "encode failed" ) ,
386+ ) ;
387+ const closeEncoder = async ( ) => ( await encoder . catch ( ( ) => null ) ) ?. close ( ) ;
388+
389+ return {
390+ onFrameLanded : ( frame ) => {
391+ landed . set ( frame . index , frame . path ) ;
392+ nudge ( ) ;
393+ } ,
394+ finish : async ( ) => {
395+ const start = Date . now ( ) ;
396+ captureDone = true ;
397+ input . log . info ( "[Render] Encoded frames while capturing" , {
398+ framesFed,
399+ totalFrames,
400+ } ) ;
401+ const encoded = startEncodeProgress ( input . job , "Encoding video" , input . onProgress ) ;
402+ reportFed = encoded ;
403+ nudge ( ) ;
404+ const failure = await fed ;
405+ const result = await closeEncoder ( ) ;
406+ input . assertNotAborted ( ) ;
407+ if ( failure === undefined && result ?. success ) {
408+ encoded ( ) ;
409+ return { encodeMs : Date . now ( ) - start } ;
410+ }
411+ input . log . warn (
412+ "[Render] Encoding while capturing failed; encoding the frames after capture" ,
413+ {
414+ error : String ( failure ?? result ?. error ) ,
415+ } ,
416+ ) ;
417+ return runEncodeStage ( input ) ;
418+ } ,
419+ abort : async ( ) => {
420+ stop . abort ( ) ;
421+ await fed ;
422+ await closeEncoder ( ) ;
423+ } ,
424+ get framesFed ( ) {
425+ return framesFed ;
426+ } ,
427+ } ;
428+ }
429+
257430export async function runEncodeStage ( input : EncodeStageInput ) : Promise < EncodeStageResult > {
258431 const {
259432 job,
260433 log,
261434 outputPath,
262435 framesDir,
263436 videoOnlyPath,
264- width,
265- height,
266437 needsAlpha,
267438 hasAudio,
268439 audioOutputPath,
269440 isPngSequence,
270441 isGif,
271- preset,
272- effectiveQuality,
273- effectiveBitrate,
274442 enableChunkedEncode,
275443 chunkedEncodeSize,
276444 abortSignal,
@@ -313,7 +481,7 @@ export async function runEncodeStage(input: EncodeStageInput): Promise<EncodeSta
313481 return { encodeMs : Date . now ( ) - stage5Start } ;
314482 }
315483
316- const engineCfg = input . engineConfig ?? job . config . producerConfig ?? resolveConfig ( ) ;
484+ const engineCfg = resolveEngineConfig ( input ) ;
317485
318486 if ( isGif ) {
319487 // ── Stage 5 (gif): two-pass palette encode ───────────────────────
@@ -357,24 +525,7 @@ export async function runEncodeStage(input: EncodeStageInput): Promise<EncodeSta
357525
358526 const frameExt = frameFileExtension ( input . captureImageFormat ) ;
359527 const framePattern = `frame_%06d.${ frameExt } ` ;
360- const encoderOpts = {
361- fps : job . config . fps ,
362- width,
363- height,
364- codec : preset . codec ,
365- preset : preset . preset ,
366- quality : effectiveQuality ,
367- bitrate : effectiveBitrate ,
368- pixelFormat : preset . pixelFormat ,
369- vp9CpuUsed : engineCfg . vp9CpuUsed ,
370- useGpu : job . config . useGpu ,
371- hdr : preset . hdr ,
372- // Distributed chunk renders pass these so the encoder writes closed-GOP
373- // keyframes that survive `-f concat -c copy` at assemble time. In-process
374- // renders leave both undefined → preserves the existing open-GOP output.
375- lockGopForChunkConcat : input . lockGopForChunkConcat === true ,
376- gopSize : input . gopSize ,
377- } ;
528+ const encoderOpts = videoEncoderOptions ( input , engineCfg ) ;
378529 const encodeResult = enableChunkedEncode
379530 ? await encodeFramesChunkedConcat (
380531 framesDir ,
0 commit comments