Struct VideoWriterBuilder 

pub struct VideoWriterBuilder { /* private fields */ }

Builder for a VideoWriter. Required parameters (width, height) are positional; everything else has a default.

Implementations

impl VideoWriterBuilder

pub fn pixel_format(self, fmt: impl Into<String>) -> Self

Any non-hardware AVPixelFormat name (av_get_pix_fmt). Default: "rgba". Frames are tightly packed, planes concatenated in descriptor order (e.g. yuv420p = Y then U then V).

pub fn fps(self, num: i32, den: i32) -> Self

Frame rate as num/den. Default (30, 1); NTSC rates like fps(30000, 1001) are supported. Every written frame advances exactly den/num seconds.

pub fn queue_capacity(self, frames: usize) -> Self

Queue depth in frames. Default: max(1, min(4, 64 MiB / frame_size)), so large frames do not silently reserve a lot of memory. The queue is count-bounded: with write each slot holds an exact frame_size copy (capacity × frame_size bytes total); with write_owned each slot holds the caller’s Vec as provided, including any spare capacity it carries.

pub fn filter_desc(self, desc: impl Into<String>) -> Self

Optional FFmpeg filter chain between the pushed frames and the encoder, e.g. "hue=s=0" or "pad=ceil(iw/2)*2:ceil(ih/2)*2" (an odd-size remedy). Must be a single connected graph (WriterError::DisconnectedFilterGraph otherwise) consuming exactly one video input and producing exactly one video output (WriterError::FilterShape otherwise), with the output downstream of the input (WriterError::UnreachableFilterOutput otherwise).

Generator filters embedded in the graph (color, testsrc, …) are allowed as long as the pushed frames still reach the output — e.g. compositing over a generated background with "color=...[bg];[in][bg]overlay=shortest=1". The same rules as the FFmpeg CLI apply: a graph built to outlive the pushed stream (an overlay without shortest=1, a concat onto an unbounded generator) keeps running after finish closes the input, until the generator ends or the job is aborted (dropping the VideoWriter aborts it) — that is the semantics asked for, not a writer malfunction.

The validation is structural (see WriterError::UnreachableFilterOutput): the pushed frames must be wired into the flow that feeds the output, but a filter that may discard them at runtime is accepted — a streamselect whose current map selects another input still passes, since that map is commandable mid-stream (sendcmd), and a multi-stream concat steering the pushed stream into a sink leg runs exactly as declared, like both would in the CLI.

The opened Output’s set_video_filter supplies the same chain from the output side and is honored when this builder-level description is absent; setting BOTH fails with WriterError::ConflictingFilterDescriptions.

pub fn open(self, output: impl Into<Output>) -> Result<VideoWriter>

Builds the pipeline and starts it, returning without waiting for the first frame.

Output option matrix

The writer builds a job with no inputs and exactly one video stream encoded from the pushed frames, so every Output option is classified: it is either honored by that single-stream pipeline or rejected here with a typed error. Nothing is silently ignored, and new options are classified the same way when they appear — rejected until the writer can genuinely honor them.

Honored (the video stream and its container):

• target: a URL/path, a write callback (new_by_write_callback), or a packet sink (subject to the packet sink’s own validation); a write callback also honors set_seek_callback and set_io_buffer_size — with a URL/path target both are inert, exactly as their own Output docs state for every job in this crate, not just the writer
• container: set_format, set_format_opt(s), add_metadata / add_metadata_map / remove_metadata / clear_all_metadata, add_stream_metadata, add_attachment(_with_mimetype), set_max_muxing_queue_size, set_muxing_queue_data_threshold
• video encoding: set_video_codec (except "copy", rejected: pushed frames must be encoded), set_video_codec_opt(s) / set_video_bitrate, set_video_qscale, set_pix_fmt, set_video_bsf, set_force_key_frames, set_bits_per_raw_sample, set_framerate / set_framerate_max / set_vsync_method (encoder-side resampling of the pushed CFR stream, exactly as in any other job), set_max_video_frames, set_start_time_us / set_recording_time_us / set_stop_time_us, set_sws_opts, video-typed frame pipelines (wgpu…), and set_video_filter (used when no builder-level filter_desc is set; both at once is WriterError::ConflictingFilterDescriptions)
• vacuously satisfied no-ops: disable_audio / disable_subtitle / disable_data (those streams never exist), disable_auto_copy_metadata (there are no inputs to copy from), set_shortest / set_shortest_buf_duration_us (a single stream has nothing to be cut against, FFmpeg parity), and an add_stream_metadata specifier that matches no stream

Rejected with WriterError::UnsupportedOutputOption — options whose effect would require an audio stream, a subtitle stream, or an input file, none of which a writer job can have:

• audio: set_audio_codec, set_audio_codec_opt(s) / set_audio_bitrate, set_audio_qscale, set_audio_sample_rate, set_audio_channels, set_audio_sample_fmt, set_audio_bsf, set_max_audio_frames, set_swr_opts
• subtitle: set_subtitle_codec, set_subtitle_codec_opt(s), set_subtitle_bsf, set_max_subtitle_frames
• input-referencing: map_metadata_from_input, add_chapter_metadata and add_program_metadata (chapters and programs only ever come from inputs)

Rejected with other typed errors (as before): stream maps (WriterError::StreamMapsUnsupported), disable_video (WriterError::NoVideoDestination), set_video_codec("copy"), and an audio/subtitle-typed frame pipeline (no stream of that type exists).

A format that cannot actually carry the video stream is not second-guessed at build time: it surfaces as a pipeline error from finish, like any other muxer failure.