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("output.mp4")
    .video(1920, 1080, 30.0)
    .video_codec(VideoCodec::H264)
    .preset(Preset::Medium)
    .build()?;

Implementations

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 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.

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

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

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 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 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_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 VideoCodecOptions variant should match the codec selected via video_codec(). A mismatch is silently ignored.

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.

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.

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.