Crate ff_encode

Expand description

§ff-encode

Video and audio encoding - the Rust way.

This crate provides video and audio encoding functionality for timeline export. It supports automatic codec selection with LGPL compliance, hardware acceleration, and provides a clean Builder pattern API.

§Features

Video Encoding: H.264, H.265, VP9, AV1, ProRes, DNxHD
Audio Encoding: AAC, Opus, MP3, FLAC, PCM, Vorbis
Hardware Acceleration: NVENC, QSV, AMF, VideoToolbox, VA-API
LGPL Compliance: Automatic codec fallback when GPL features disabled
Progress Callbacks: Real-time encoding progress updates
Builder Pattern: Ergonomic encoder configuration

§Usage

§Basic Encoding

use ff_encode::{VideoEncoder, VideoCodec, AudioCodec, BitrateMode, Preset};
use ff_format::VideoFrame;

// Create encoder with Builder pattern
let mut encoder = VideoEncoder::create("output.mp4")?
    .video(1920, 1080, 30.0)          // resolution, FPS
    .video_codec(VideoCodec::H264)     // codec
    .bitrate_mode(BitrateMode::Cbr(8_000_000))  // 8 Mbps
    .preset(Preset::Medium)            // speed/quality balance
    .audio(48000, 2)                   // sample rate, channels
    .audio_codec(AudioCodec::Aac)
    .audio_bitrate(192_000)            // 192 kbps
    .build()?;

// Check actual codec used
println!("Video codec: {}", encoder.actual_video_codec());
println!("Audio codec: {}", encoder.actual_audio_codec());

// Push frames
for frame in frames {
    encoder.push_video(&frame)?;
}

// Push audio
encoder.push_audio(&audio_samples)?;

// Finish encoding
encoder.finish()?;

§Progress Callbacks

use ff_encode::{VideoEncoder, EncodeProgress};

// Simple closure-based callback
let mut encoder = VideoEncoder::create("output.mp4")?
    .video(1920, 1080, 30.0)
    .on_progress(|progress| {
        println!("Encoded {} frames ({:.1}%) at {:.1} fps",
            progress.frames_encoded,
            progress.percent(),
            progress.current_fps
        );
    })
    .build()?;

§Progress Callbacks with Cancellation

use ff_encode::{VideoEncoder, EncodeProgressCallback, EncodeProgress};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};

struct CancellableProgress {
    cancelled: Arc<AtomicBool>,
}

impl EncodeProgressCallback for CancellableProgress {
    fn on_progress(&mut self, progress: &EncodeProgress) {
        println!("Progress: {:.1}%", progress.percent());
    }

    fn should_cancel(&self) -> bool {
        self.cancelled.load(Ordering::Relaxed)
    }
}

let cancelled = Arc::new(AtomicBool::new(false));
let mut encoder = VideoEncoder::create("output.mp4")?
    .video(1920, 1080, 30.0)
    .progress_callback(CancellableProgress {
        cancelled: cancelled.clone()
    })
    .build()?;

// Later, to cancel encoding:
cancelled.store(true, Ordering::Relaxed);

§Hardware Encoding

use ff_encode::{VideoEncoder, HardwareEncoder};

// Check available hardware encoders
for hw in HardwareEncoder::available() {
    println!("Available: {:?}", hw);
}

// Create encoder with auto hardware detection
let mut encoder = VideoEncoder::create("output.mp4")?
    .video(1920, 1080, 60.0)
    .hardware_encoder(HardwareEncoder::Auto)  // auto-detect
    .build()?;

// Check what encoder was actually used
println!("Using: {}", encoder.actual_video_codec());
println!("Hardware encoder: {:?}", encoder.hardware_encoder());
println!("Is hardware encoding: {}", encoder.is_hardware_encoding());

§LGPL Compliance & Commercial Use

By default, this crate is LGPL-compliant and safe for commercial use without licensing fees.

§Default Behavior (LGPL-Compatible)

When H.264/H.265 encoding is requested, the encoder automatically selects codecs in this priority:

Hardware encoders (LGPL-compatible, no licensing fees):
- NVIDIA NVENC (h264_nvenc, hevc_nvenc)
- Intel Quick Sync Video (h264_qsv, hevc_qsv)
- AMD AMF/VCE (h264_amf, hevc_amf)
- Apple VideoToolbox (h264_videotoolbox, hevc_videotoolbox)
- VA-API (h264_vaapi, hevc_vaapi) - Linux
Fallback to royalty-free codecs:
- For H.264 request → VP9 (libvpx-vp9)
- For H.265 request → AV1 (libaom-av1)

§GPL Feature (Commercial Licensing Required)

Enable GPL codecs (libx264, libx265) only if:

You have appropriate licenses from MPEG LA, or
Your software is GPL-licensed (open source), or
For non-commercial/educational use only

# WARNING: Requires GPL compliance and licensing fees for commercial use
ff-encode = { version = "0.1", features = ["gpl"] }

§Checking Compliance at Runtime

You can verify which encoder was selected:

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

println!("Using: {}", encoder.actual_video_codec());
println!("LGPL compliant: {}", encoder.is_lgpl_compliant());

Structs§

AacOptions: AAC per-codec options.
AudioEncoder: Encodes audio frames to a file using FFmpeg.
AudioEncoderBuilder: Builder for constructing an AudioEncoder.
Av1Options: AV1 per-codec options (libaom-av1).
DnxhdOptions: Avid DNxHD / DNxHR per-codec options.
EncodeProgress: Encoding progress information.
FlacOptions: FLAC per-codec options.
H264Options: H.264 (AVC) per-codec options.
H265Options: H.265 (HEVC) per-codec options.
ImageEncoder: Encodes a single VideoFrame to a still image file.
ImageEncoderBuilder: Builder for ImageEncoder.
Mp3Options: MP3 (libmp3lame) per-codec options.
OpusOptions: Opus (libopus) per-codec options.
ProResOptions: Apple ProRes per-codec options.
SvtAv1Options: SVT-AV1 (libsvtav1) per-codec options.
VideoEncoder: Encodes video (and optionally audio) frames to a file using FFmpeg.
VideoEncoderBuilder: Builder for constructing a VideoEncoder.
Vp9Options: VP9 (libvpx-vp9) per-codec options.

Enums§

AacProfile: AAC encoding profile.
AudioCodec: Audio codec identifier.
AudioCodecOptions: Per-codec encoding options for audio.
Av1Usage: AV1 encoding usage mode.
BitrateMode: Bitrate control mode for video encoding.
Container: Container format for output file.
DnxhdVariant: DNxHD / DNxHR encoding variant.
EncodeError: Encoding error type.
H264Preset: libx264 encoding speed/quality preset.
H264Profile: H.264 encoding profile.
H264Tune: libx264 perceptual tuning parameter.
H265Profile: H.265 encoding profile.
H265Tier: H.265 encoding tier.
HardwareEncoder: Hardware encoder type.
Mp3Quality: MP3 quality mode: VBR quality scale or CBR fixed bitrate.
OpusApplication: Opus encoder application mode.
Preset: Encoding preset (speed vs quality tradeoff).
ProResProfile: Apple ProRes encoding profile.
VideoCodec: Video codec identifier.
VideoCodecOptions: Per-codec encoding options.

Constants§

CRF_MAX: Maximum CRF value accepted by H.264/H.265 encoders.

Traits§

EncodeProgressCallback: EncodeProgress callback trait for monitoring encoding progress.
VideoCodecEncodeExt: Encode-specific methods for VideoCodec.

Crate ff_encode

Crate ff_encode Copy item path

§ff-encode

§Features

§Usage

§Basic Encoding

§Progress Callbacks

§Progress Callbacks with Cancellation

§Hardware Encoding

§LGPL Compliance & Commercial Use

§Default Behavior (LGPL-Compatible)

§GPL Feature (Commercial Licensing Required)

§Checking Compliance at Runtime

Structs§

Enums§

Constants§

Traits§

Crate ff_encode