Struct VideoEncoderBuilder 

pub struct VideoEncoderBuilder { /* private fields */ }

Builder for constructing a VideoEncoder.

Created by calling VideoEncoder::create(). Call build() to open the output file and prepare for encoding.

Examples

use ff_encode::{VideoEncoder, VideoCodec, Preset};

let mut encoder = VideoEncoder::create(test_out("output.mp4"))
    .video(1920, 1080, 30.0)
    .video_codec(VideoCodec::H264)
    .preset(Preset::Medium)
    .build()?;

Implementations

impl VideoEncoderBuilder

pub fn audio(self, sample_rate: u32, channels: u32) -> Self

Configure audio stream settings.

pub fn audio_codec(self, codec: AudioCodec) -> Self

Set audio codec.

pub fn audio_bitrate(self, bitrate: u64) -> Self

Set audio bitrate in bits per second.

impl VideoEncoderBuilder

pub fn pixel_format(self, fmt: PixelFormat) -> Self

Override the pixel format for video encoding.

When omitted the encoder uses yuv420p by default, except that H.265 Main10 automatically selects yuv420p10le.

pub fn hdr10_metadata(self, meta: Hdr10Metadata) -> Self

Embed HDR10 static metadata in the output.

Sets color_primaries = BT.2020, color_trc = SMPTE ST 2084 (PQ), and colorspace = BT.2020 NCL on the codec context, then attaches AV_PKT_DATA_CONTENT_LIGHT_LEVEL and AV_PKT_DATA_MASTERING_DISPLAY_METADATA packet side data to every keyframe.

Pair with codec_options using H265Options { profile: H265Profile::Main10, .. } and pixel_format(PixelFormat::Yuv420p10le) for a complete HDR10 pipeline.

pub fn color_space(self, cs: ColorSpace) -> Self

Override the color space (matrix coefficients) written to the codec context.

When omitted the encoder uses the FFmpeg default. HDR10 metadata, if set via hdr10_metadata(), automatically selects BT.2020 NCL — this setter takes priority over that automatic choice.

pub fn color_transfer(self, trc: ColorTransfer) -> Self

Override the color transfer characteristic (gamma curve) written to the codec context.

When omitted the encoder uses the FFmpeg default. HDR10 metadata automatically selects PQ (SMPTE ST 2084) — this setter takes priority. Use ColorTransfer::Hlg for HLG broadcast HDR.

pub fn color_primaries(self, cp: ColorPrimaries) -> Self

Override the color primaries written to the codec context.

When omitted the encoder uses the FFmpeg default. HDR10 metadata automatically selects BT.2020 — this setter takes priority.

impl VideoEncoderBuilder

pub fn container(self, container: OutputContainer) -> Self

Set container format explicitly (usually auto-detected from file extension).

pub fn output_sink(self, sink: impl IoSink + 'static) -> Self

Mux into sink instead of writing a file.

The path given to VideoEncoder::create is then only what the muxer is guessed from – nothing is created on disk – so it still needs a usable extension, or an explicit container.

sink is anything that writes and seeks and can move to the encoder’s thread. Seeking is not optional: MP4 rewrites its header once the sizes are known, and a sink that cannot seek would produce an unplayable file.

Incompatible with two_pass, which opens the output again for the second pass; that combination is rejected by build.

Examples

use std::io::Cursor;
use ff_encode::VideoEncoder;

let mut encoder = VideoEncoder::create("out.mp4")
    .video_size(640, 360)
    .output_sink(Cursor::new(Vec::new()))
    .build()?;

pub fn on_progress<F>(self, callback: F) -> Self

where F: FnMut(&EncodeProgress) + Send + 'static,

Set a closure as the progress callback.

pub fn progress_callback<C: EncodeProgressCallback + 'static>( self, callback: C, ) -> Self

Set a crate::EncodeProgressCallback trait object (supports cancellation).

pub fn two_pass(self) -> Self

Enable two-pass encoding for more accurate bitrate distribution.

Two-pass encoding is video-only and is incompatible with audio streams.

pub fn faststart(self) -> Self

Relocate the moov atom to the front of MP4/MOV output (movflags=+faststart).

This makes the file playable via progressive download / streaming before it is fully fetched, the standard requirement for web-delivered files. It has no effect on non-MP4/MOV containers or on fragmented MP4 (which already streams via its own movflags). Because FFmpeg relocates the atom by rewriting the file at finalize, faststart adds a second pass over the output, so it is not free for very large files.

pub fn metadata(self, key: &str, value: &str) -> Self

Embed a metadata tag in the output container.

Calls av_dict_set on AVFormatContext->metadata before the header is written. Multiple calls accumulate entries; duplicate keys use the last value.

pub fn chapter(self, chapter: ChapterInfo) -> Self

Add a chapter to the output container.

Allocates an AVChapter entry on AVFormatContext before the header is written. Multiple calls accumulate chapters in the order added.

pub fn subtitle_passthrough( self, source_path: &str, stream_index: usize, ) -> Self

Copy a subtitle stream from an existing file into the output container.

Opens source_path, locates the stream at stream_index, and registers it as a passthrough stream in the output. Packets are copied verbatim using av_interleaved_write_frame without re-encoding.

stream_index is the zero-based index of the subtitle stream inside source_path. For files with a single subtitle track this is typically 0 (or whichever index ffprobe reports).

If the source cannot be opened or the stream index is invalid, a warning is logged and encoding continues without subtitles.

pub fn codec_opt(self, key: impl Into<String>, value: impl Into<String>) -> Self

Set a codec-private option by name, for the long tail that has no typed builder (x264-params, aq-mode, psy-rd, …).

Applies to the video codec only. A video output’s audio track opens its own codec context, which this does not reach; use AudioEncoder for audio-only output that needs the same escape hatch.

Repeatable, and applied in call order via av_opt_set on the codec’s priv_data before avcodec_open2, after codec_options() — so a key named here overrides the same key set through the typed API.

Escape-hatch semantics

Prefer codec_options(): it is validated at compile time and portable across encoders. Nothing here is checked until FFmpeg sees it, and keys are codec-specific.

Unlike the typed options, which log and continue when an encoder does not support them, an option rejected here fails build() with crate::EncodeError::InvalidConfig — the key was named explicitly, so dropping it silently would defeat the purpose. The consequence is worth planning for: a configuration carrying libx264 keys will fail once the caller switches to a hardware encoder.

let encoder = VideoEncoder::create("out.mp4")
    .video(1920, 1080, 30.0)
    .codec_opt("x264-params", "keyint=48:min-keyint=48")
    .build()?;

pub fn codec_options(self, opts: VideoCodecOptions) -> Self

Set per-codec encoding options.

Applied via av_opt_set before avcodec_open2 during build(). This is additive — omitting it leaves codec defaults unchanged. Any option that the chosen encoder does not support is logged as a warning and skipped; it never causes build() to return an error.

The crate::VideoCodecOptions variant should match the codec selected via video_codec(). A mismatch is silently ignored.

pub fn add_attachment( self, data: Vec<u8>, mime_type: &str, filename: &str, ) -> Self

Embed a binary attachment in the output container.

Attachments are supported in MKV/WebM containers and are used for fonts (required by ASS/SSA subtitle rendering), cover art, or other binary files that consumers of the file may need.

• data — raw bytes of the attachment
• mime_type — MIME type string (e.g. "application/x-truetype-font", "image/jpeg")
• filename — the name reported inside the container (e.g. "Arial.ttf")

Multiple calls accumulate entries; each attachment becomes its own stream with AVMEDIA_TYPE_ATTACHMENT codec parameters.

impl VideoEncoderBuilder

pub fn video(self, width: u32, height: u32, fps: f64) -> Self

Configure video stream settings.

pub fn video_codec(self, codec: VideoCodec) -> Self

Set video codec.

pub fn bitrate_mode(self, mode: BitrateMode) -> Self

Set the bitrate control mode for video encoding.

pub fn preset(self, preset: Preset) -> Self

Set encoding preset (speed vs quality tradeoff).

pub fn hardware_encoder(self, hw: HardwareEncoder) -> Self

Set hardware encoder.

pub fn allow_codec_substitution(self) -> Self

Accept an encoder from a different codec family when the requested codec has no encoder available.

By default, asking for H.264 and getting anything that is not H.264 is an error. Some codecs have an LGPL-compatible stand-in (VP9 for H.264, AV1 for H.265) that can encode the frames, but the output is that other codec, so it is only used when this is set. When it is used, a warning names the encoder that was chosen, and actual_video_codec reports it.

impl VideoEncoderBuilder

pub fn build(self) -> Result<VideoEncoder, EncodeError>

Validate builder state and open the output file.

Errors

Returns EncodeError if configuration is invalid, the output path cannot be created, or no suitable encoder is found.

Trait Implementations

impl Debug for VideoEncoderBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.