onProgress callback

onProgress is one of the shared Phase 8 video execution controls. FFmpeg-backed operations use FFmpeg's machine-readable -progress pipe:2 output rather than scraping human-formatted status lines.

#Type

1onProgress?: (progress: {2  percent: number;3  time: number;   // encoded position, seconds4  speed: number;  // e.g. 2.3 means ~2.3× realtime5}) => void;

#Where it applies

Pass onProgress at the top level of VideoCreationOptions:

1await painter.createVideo({2  source: './input.mp4',3  trim: {4    startTime: 10,5    endTime: 40,6    outputPath: './clip.mp4',7    mode: 'accurate',8  },9  onProgress: ({ percent, time, speed }) => {10    process.stdout.write(`\r${percent.toFixed(1)}%  ${time.toFixed(2)}s  ${speed.toFixed(2)}x`);11  },12});

The same callback is forwarded by FFmpeg-backed conversion, trim, compositing, audio, overlay, frame-output, transition, and other render operations that execute through the shared video runtime.

Metadata-only work such as getInfo/ffprobe does not manufacture FFmpeg encode progress. Very short FFmpeg jobs may also finish before many progress records are emitted.

#Pipeline progress

videoPipeline().render() accepts the same control:

1const result = await painter2  .videoPipeline('./input.mp4')3  .trim(0, 15)4  .text({5    text: 'Apexify',6    x: 32,7    y: 32,8    startTime: 0,9    endTime: 4,10    font: { size: 36, family: 'Arial' },11    fill: { color: '#ffffff' },12  })13  .render({14    outputPath: './out.mp4',15    onProgress: ({ percent }) => console.log(percent),16  });17 18console.log(result.passes, result.executionPlan);

A pipeline can contain several FFmpeg passes. The callback reports the active pass's FFmpeg progress; use result.executionPlan and result.passes after rendering to inspect the deterministic pass plan that actually ran.

#Related controls

1await painter.createVideo({2  source: './input.mp4',3  convert: { outputPath: './out.mp4' },4  signal: controller.signal,5  timeoutMs: 120_000,6  overwrite: false,7  onProgress: handleProgress,8});

• signal aborts active work where applicable.
• timeoutMs bounds the FFmpeg process.
• overwrite: false rejects an existing output rather than replacing it.
• onProgress observes the active FFmpeg process without changing output semantics.

#Behaviour and limits

percent is derived from FFmpeg's reported encoded time against the operation's expected duration when that duration is known. It is operational progress, not a promise of frame/sample-level completion accuracy. Filters, muxer flushes, multi-pass pipeline stages, and very short clips can make updates uneven.

The callback should stay lightweight. If your application needs persistence, queue or throttle writes instead of performing expensive synchronous work on every progress record.