Optionalinput: string | string[]Override the ffmpeg binary path (default: FFMPEG_PATH env or 'ffmpeg')
Get (and cache) the version info for the current binary.
Get (and cache) the capability registry for the current binary.
Check if a codec is available in the current binary. Does not throw — returns a GuardResult.
Check if a feature is available by version gate + capability.
Select the best available video codec from a priority list. Returns null if none are available.
Select the best available hardware accelerator from a priority list.
Overwrite output files without asking (default: true)
Enable progress reporting on stderr
Add an input. Chainable input options follow.
Seek within the last-added input (fast seek, before -i)
Limit duration of the last-added input
Force format of the last-added input
Add (or switch to) an output path. Call before codec/filter options.
Set video codec, e.g. 'libx264', 'libx265', 'copy'
Set video bitrate, e.g. '2M', '4000k'
Set output frame rate (-r after -i)
Set input frame rate (-r before -i, for raw inputs)
Set output video size, e.g. '1280x720' or '1280:720'
Set video filter chain (-vf). Accepts a filter string or a FilterChain / serialized filter function result.
Set pixel format
Set CRF value (codec-dependent)
Disable video stream
Set encoder preset (-preset), e.g. 'slow', 'faster', 'p4'
Set H.264/H.265 profile (-profile:v)
Set H.264/H.265 level (-level:v), e.g. '4.1'
Set container/muxer flags (-movflags), e.g. '+faststart'.
Repeatable: movflags('+faststart').movflags('+frag_keyframe').
Max GOP size in frames (-g). For HLS this is what determines the keyframe interval, so it must be a multiple of the segment duration × fps.
Constrain frame-rate conversion. Default ffmpeg behaviour is 'auto', which silently duplicates or drops frames depending on the input.
The flag name is version-dependent: -vsync before ffmpeg 5.1 and
-fps_mode from 5.1 on. Emitting -fps_mode unconditionally makes every
encode fail with "Unrecognized option 'fps_mode'" on 4.x and 5.0, so the
right one is chosen in buildArgs() from the probed binary version.
Rate-control bounds (VBV): min/max bitrate plus buffer size.
Supplying all three keeps the encoder inside a sliding-window bitrate
budget, which is what streaming targets require. Omit min to only cap
the maximum; bufferSize defaults to max because ffmpeg's VBV needs a
buffer to look at, and an unset one produces an unpredictable peak.
Tag output colour properties (-color_primaries / -color_trc / -colorspace / -color_range). Passing an unknown key throws, so a typo cannot silently produce an untagged file.
Set audio codec, e.g. 'aac', 'libopus', 'copy'
Set audio bitrate, e.g. '128k', '192k'
Set audio sample rate, e.g. 44100, 48000
Set number of audio channels
Set audio filter chain (-af). Accepts a filter string or a FilterChain / serialized filter function result.
Disable audio stream
Set subtitle codec
Disable subtitle stream
Force output format
Add stream mapping, e.g. '0:v:0', '0:a:1'
Limit output duration
Seek in output (re-encode seek, accurate)
Pass arbitrary extra args for the current output
Pass arbitrary extra args at the global level
Enable hardware acceleration (-hwaccel). Does NOT validate availability — use checkHwaccel() first.
Optionalopts: { device?: string }Set -filter_complex string directly. Only the last call takes effect.
Every input path this builder will read, in order.
Every output path this builder will write, in order.
Spawn the process with full event-emitter control. Useful for streaming progress or piping stdout.
Run ffmpeg and return a Promise that resolves on success.
Rejects with a typed error: FFmpegSpawnError on a non-zero exit,
FFmpegTimeoutError when timeout elapses, FFmpegAbortError
when signal fires.
Probe the binary version and return a human-readable string. Also caches the version for subsequent requireVersion() checks.
Return a human-readable command line string. Useful for debugging or logging.
Fluent FFmpeg builder. All methods return
thisfor chaining. Call.run()to execute or.spawn()for event-based control.Example