Struct Output

Source

pub struct Output { /* private fields */ }

Implementations§

Source §

impl Output

Source

pub fn new(url: impl Into<String>) -> Self

Source

pub fn new_by_write_callback<F>(write_callback: F) -> Self
where F: FnMut(&[u8]) -> i32 + 'static,

Creates a new Output instance with a custom write callback and format string.

This method initializes an Output object that uses a provided write_callback function to handle the encoded data being written to the output stream. You can optionally specify the desired output format via the format method.

§Parameters:

write_callback: fn(buf: &[u8]) -> i32: A function that processes the provided buffer of encoded data and writes it to the destination. The function should return the number of bytes successfully written (positive value) or a negative value in case of error.

§Return Value:

Returns a new Output instance configured with the specified write_callback function.

§Behavior of `write_callback`:

Positive Value: Indicates the number of bytes successfully written.
Negative Value: Indicates an error occurred. For example:
- ffmpeg_sys_next::AVERROR(ffmpeg_sys_next::EIO): Represents an input/output error.
- Other custom-defined error codes can also be returned to signal specific issues.

§Example:

let output = Output::new_by_write_callback(move |buf| {
    println!("Processing {} bytes of data for output", buf.len());
    buf.len() as i32 // Return the number of bytes processed
})
.set_format("mp4");

Source

pub fn set_seek_callback<F>(self, seek_callback: F) -> Self
where F: FnMut(i64, i32) -> i64 + 'static,

Sets a custom seek callback for the output stream.

This function assigns a user-defined function that handles seeking within the output stream. Seeking is required for certain formats (e.g., mp4, mkv) where metadata or index information needs to be updated at specific positions in the file.

Why is seek_callback necessary?

Some formats (e.g., MP4) require seek operations to update metadata (moov, mdat).
If no seek_callback is provided for formats that require seeking, FFmpeg will fail with:
```
[mp4 @ 0x...] muxer does not support non seekable output
```
For streaming formats (flv, ts, rtmp, hls), seeking is not required.

FFmpeg may invoke seek_callback from different threads.

If using a File as the output, wrap it in Arc<Mutex<File>> to ensure thread-safe access.

§Parameters:

seek_callback: FnMut(i64, i32) -> i64
- offset: i64: The target seek position in the stream.
- whence: i32: The seek mode determining how offset should be interpreted:
  - ffmpeg_sys_next::SEEK_SET (0): Seek to an absolute position.
  - ffmpeg_sys_next::SEEK_CUR (1): Seek relative to the current position.
  - ffmpeg_sys_next::SEEK_END (2): Seek relative to the end of the output.
  - ffmpeg_sys_next::AVSEEK_FLAG_BYTE (2): Seek using byte offset instead of timestamps.
  - ffmpeg_sys_next::AVSEEK_SIZE (65536): Query the total size of the stream.
  - ffmpeg_sys_next::AVSEEK_FORCE (131072): Force seeking, even if normally restricted.

§Return Value:

Positive Value: The new offset position after seeking.
Negative Value: An error occurred. Common errors include:
- ffmpeg_sys_next::AVERROR(ffmpeg_sys_next::ESPIPE): Seek is not supported.
- ffmpeg_sys_next::AVERROR(ffmpeg_sys_next::EIO): General I/O error.

§Example (Thread-safe seek callback using `Arc<Mutex<File>>`):

Since FFmpeg may call write_callback and seek_callback from different threads, use Arc<Mutex<File>> to ensure safe concurrent access.

use std::fs::File;
use std::io::{Seek, SeekFrom, Write};
use std::sync::{Arc, Mutex};

// ✅ Create a thread-safe file handle
let file = Arc::new(Mutex::new(File::create("output.mp4").expect("Failed to create file")));

// ✅ Define the write callback (data writing logic)
let write_callback = {
    let file = Arc::clone(&file);
    move |buf: &[u8]| -> i32 {
        let mut file = file.lock().unwrap();
        match file.write_all(buf) {
            Ok(_) => buf.len() as i32,
            Err(e) => {
                println!("Write error: {}", e);
                ffmpeg_sys_next::AVERROR(ffmpeg_sys_next::EIO) as i32
            }
        }
    }
};

// ✅ Define the seek callback (position adjustment logic)
let seek_callback = {
    let file = Arc::clone(&file);
    Box::new(move |offset: i64, whence: i32| -> i64 {
        let mut file = file.lock().unwrap();

        match whence {
            // ✅ Handle AVSEEK_SIZE: Return total file size
            ffmpeg_sys_next::AVSEEK_SIZE => {
                if let Ok(size) = file.metadata().map(|m| m.len() as i64) {
                    println!("FFmpeg requested stream size: {}", size);
                    return size;
                }
                return ffmpeg_sys_next::AVERROR(ffmpeg_sys_next::EIO) as i64;
            }

            // ✅ Handle AVSEEK_FLAG_BYTE: Seek using byte offset
            ffmpeg_sys_next::AVSEEK_FLAG_BYTE => {
                println!("FFmpeg requested byte-based seeking. Seeking to byte offset: {}", offset);
                if let Ok(new_pos) = file.seek(SeekFrom::Start(offset as u64)) {
                    return new_pos as i64;
                }
                return ffmpeg_sys_next::AVERROR(ffmpeg_sys_next::EIO) as i64;
            }

            // ✅ Standard seek modes
            ffmpeg_sys_next::SEEK_SET => file.seek(SeekFrom::Start(offset as u64)),
            ffmpeg_sys_next::SEEK_CUR => file.seek(SeekFrom::Current(offset)),
            ffmpeg_sys_next::SEEK_END => file.seek(SeekFrom::End(offset)),
            _ => Err(std::io::Error::new(std::io::ErrorKind::InvalidInput, "Unsupported seek mode")),
        }.map_or(ffmpeg_sys_next::AVERROR(ffmpeg_sys_next::EIO) as i64, |pos| pos as i64)
    })
};

// ✅ Create an output with both callbacks
let output = Output::new_by_write_callback(write_callback, "mp4")
    .set_seek_callback(seek_callback);

Source

pub fn set_format(self, format: impl Into<String>) -> Self

Sets the output format for the container.

This method allows you to specify the output format for the container. If no format is specified, FFmpeg will attempt to detect it automatically based on the file extension or output URL.

§Parameters:

format: &str: A string specifying the desired output format (e.g., mp4, flv, mkv).

§Return Value:

Returns the Output instance with the newly set format.

Source

pub fn set_video_codec(self, video_codec: impl Into<String>) -> Self

Sets the video codec to be used for encoding.

§Arguments

video_codec - A string slice representing the desired video codec (e.g., "h264", "hevc").

§Returns

Self - Returns the modified Output struct, allowing for method chaining.

§Examples

let output = Output::from("rtmp://localhost/live/stream")
    .set_video_codec("h264");

Source

pub fn set_audio_codec(self, audio_codec: impl Into<String>) -> Self

Sets the audio codec to be used for encoding.

§Arguments

audio_codec - A string slice representing the desired audio codec (e.g., "aac", "mp3").

§Returns

Self - Returns the modified Output struct, allowing for method chaining.

§Examples

let output = Output::from("rtmp://localhost/live/stream")
    .set_audio_codec("aac");

Source

pub fn set_subtitle_codec(self, subtitle_codec: impl Into<String>) -> Self

Sets the subtitle codec to be used for encoding.

§Arguments

subtitle_codec - A string slice representing the desired subtitle codec (e.g., "mov_text", "webvtt").

§Returns

Self - Returns the modified Output struct, allowing for method chaining.

§Examples

let output = Output::from("rtmp://localhost/live/stream")
    .set_subtitle_codec("mov_text");

Source

pub fn set_frame_pipelines( self, frame_pipelines: Vec<FramePipelineBuilder>, ) -> Self

Replaces the entire frame-processing pipeline with a new sequence of transformations for pre-encoding frames on this Output.

This method clears any previously set pipelines and replaces them with the provided list.

Note: This method accepts FramePipelineBuilder instead of FramePipeline. For details on why FramePipelineBuilder is used, see its documentation.

§Parameters

frame_pipelines - A list of FramePipelineBuilder instances defining the transformations to apply before encoding.

§Returns

Self - Returns the modified Output, enabling method chaining.

§Example

let output = Output::from("some_url")
    .set_frame_pipelines(vec![
        FramePipelineBuilder::new(AVMediaType::AVMEDIA_TYPE_VIDEO).filter("opengl", Box::new(my_filter)),
        // Additional pipelines...
    ]);

Source

pub fn add_frame_pipeline(self, frame_pipeline: FramePipelineBuilder) -> Self

Adds a single FramePipelineBuilder to the existing pipeline list.

If no pipelines are currently defined, this method creates a new pipeline list. Otherwise, it appends the provided pipeline to the existing transformations.

Note: This method accepts FramePipelineBuilder instead of FramePipeline. For details on why FramePipelineBuilder is used, see its documentation.

§Parameters

frame_pipeline - A FramePipelineBuilder defining a transformation.

§Returns

Self - Returns the modified Output, enabling method chaining.

§Example

let output = Output::from("some_url")
    .add_frame_pipeline(FramePipelineBuilder::new(AVMediaType::AVMEDIA_TYPE_VIDEO).filter("opengl", Box::new(my_filter)))
    .add_frame_pipeline(FramePipelineBuilder::new(AVMediaType::AVMEDIA_TYPE_AUDIO).filter("my_custom_filter1", Box::new(...)).filter("my_custom_filter2", Box::new(...)));

Source

pub fn add_stream_map(self, linklabel: impl Into<String>) -> Self

Adds a stream mapping for a specific stream or stream type, re-encoding it according to this output’s codec settings.

§Linklabel (FFmpeg-like Specifier)

This string typically follows "<input_index>:<media_type>" syntax:

"0:v" – the video stream(s) from input #0.
"1:a?" – audio from input #1, ignore if none present (due to ?).
Other possibilities include "0:s", "0:d", etc. for subtitles/data, optionally with ?.

By calling add_stream_map, you force re-encoding of the chosen stream(s). If the user wants a bit-for-bit copy, see add_stream_map_with_copy.

§Parameters

linklabel: An FFmpeg-style specifier referencing the desired input index and media type, like "0:v", "1:a?", etc.

§Returns

Self - for chained method calls.

§Example

// Re-encode the video stream from input #0 (fail if no video).
let output = Output::from("output.mp4")
    .add_stream_map("0:v");

Source

pub fn add_stream_map_with_copy(self, linklabel: impl Into<String>) -> Self

Adds a stream mapping for a specific stream or stream type, copying it bit-for-bit from the source without re-encoding.

§Linklabel (FFmpeg-like Specifier)

Follows the same "<input_index>:<media_type>" pattern as add_stream_map:

"0:a" – audio stream(s) from input #0.
"0:a?" – same, but ignore errors if no audio exists.
And so on for video (v), subtitles (s), attachments (t), etc.

§Copy vs. Re-encode

Here, copy = true by default, meaning the chosen stream(s) are passed through without decoding/encoding. This generally only works if the source’s codec is compatible with the container/format you’re outputting to. If you require re-encoding (e.g., to ensure compatibility or apply filters), use add_stream_map.

§Parameters

linklabel: An FFmpeg-style specifier referencing the desired input index and media type, like "0:v?".

§Returns

Self - for chained method calls.

§Example

// Copy the audio stream(s) from input #0 if present, no re-encode:
let output = Output::from("output.mkv")
    .add_stream_map_with_copy("0:a?");

Source

pub fn set_start_time_us(self, start_time_us: i64) -> Self

Sets the start time (in microseconds) for output encoding.

If this is set, FFmpeg will attempt to start encoding from the specified timestamp in the input stream. This can be used to skip initial content.

§Parameters

start_time_us - The start time in microseconds.

§Returns

Self - The modified Output, allowing method chaining.

§Example

let output = Output::from("output.mp4")
    .set_start_time_us(2_000_000); // Start at 2 seconds

Source

pub fn set_recording_time_us(self, recording_time_us: i64) -> Self

Sets the recording time (in microseconds) for output encoding.

This indicates how many microseconds of data should be processed (i.e., maximum duration to encode). Once this time is reached, FFmpeg will stop encoding.

§Parameters

recording_time_us - The maximum duration (in microseconds) to process.

§Returns

Self - The modified Output, allowing method chaining.

§Example

let output = Output::from("output.mp4")
    .set_recording_time_us(5_000_000); // Record for 5 seconds

Source

pub fn set_stop_time_us(self, stop_time_us: i64) -> Self

Sets a stop time (in microseconds) for output encoding.

If set, FFmpeg will stop encoding once the input’s timestamp surpasses this value. Effectively, encoding ends at this timestamp regardless of remaining data.

§Parameters

stop_time_us - The timestamp (in microseconds) at which to stop.

§Returns

Self - The modified Output, allowing method chaining.

§Example

let output = Output::from("output.mp4")
    .set_stop_time_us(10_000_000); // Stop at 10 seconds

Source

pub fn set_framerate(self, framerate: AVRational) -> Self

Sets a target frame rate (AVRational) for output encoding.

This can force the output to use a specific frame rate (e.g., 30/1 for 30 FPS). If unset, FFmpeg typically preserves the source frame rate or uses defaults based on the selected codec/container.

§Parameters

framerate - An AVRational representing the desired frame rate numerator/denominator (e.g., AVRational { num: 30, den: 1 } for 30fps).

§Returns

Self - The modified Output, allowing method chaining.

§Example

use ffmpeg_sys_next::AVRational;
let output = Output::from("output.mp4")
    .set_framerate(AVRational { num: 30, den: 1 });

Source

pub fn set_vsync_method(self, method: VSyncMethod) -> Self

Sets the video sync method to be used during encoding.

FFmpeg uses a variety of vsync policies to handle frame presentation times, dropping/duplicating frames as needed. Adjusting this can be useful when you need strict CFR (constant frame rate), or to pass frames through without modification (VsyncPassthrough).

§Parameters

method - A variant of VSyncMethod, such as VsyncCfr or VsyncVfr.

§Returns

Self - The modified Output, allowing method chaining.

§Example

let output = Output::from("output.mp4")
    .set_vsync_method(VSyncMethod::VsyncCfr);

Source

pub fn set_bits_per_raw_sample(self, bits: i32) -> Self

Sets the bits per raw sample for video encoding.

This value can influence quality or color depth when dealing with certain pixel formats. Commonly used for high-bit-depth workflows or specialized encoding scenarios.

§Parameters

bits - The bits per raw sample (e.g., 8, 10, 12).

§Returns

Self - The modified Output, allowing method chaining.

§Example

let output = Output::from("output.mkv")
    .set_bits_per_raw_sample(10); // e.g., 10-bit

Source

pub fn set_audio_sample_rate(self, audio_sample_rate: i32) -> Self

Sets the audio sample rate (in Hz) for output encoding.

This method allows you to specify the desired audio sample rate for the output. Common values include 44100 (CD quality), 48000 (standard for digital video), and 22050 or 16000 (for lower bitrate applications).

§Parameters

audio_sample_rate - The sample rate in Hertz (e.g., 44100, 48000).

§Returns

Self - The modified Output, allowing method chaining.

§Example

let output = Output::from("output.mp4")
    .set_audio_sample_rate(48000); // Set to 48kHz

Source

pub fn set_audio_channels(self, audio_channels: i32) -> Self

Sets the number of audio channels for output encoding.

Common values include 1 (mono), 2 (stereo), 5.1 (6 channels), and 7.1 (8 channels). This setting affects the spatial audio characteristics of the output.

§Parameters

audio_channels - The number of audio channels (e.g., 1 for mono, 2 for stereo).

§Returns

Self - The modified Output, allowing method chaining.

§Example

let output = Output::from("output.mp4")
    .set_audio_channels(2); // Set to stereo

Source

pub fn set_audio_sample_fmt(self, sample_fmt: AVSampleFormat) -> Self

Sets the audio sample format for output encoding.

This method allows you to specify the audio sample format, which affects how audio samples are represented. Common formats include:

AV_SAMPLE_FMT_S16 (signed 16-bit)
AV_SAMPLE_FMT_S32 (signed 32-bit)
AV_SAMPLE_FMT_FLT (32-bit float)
AV_SAMPLE_FMT_FLTP (32-bit float, planar)

The format choice can impact quality, processing requirements, and compatibility.

§Parameters

sample_fmt - An AVSampleFormat enum value specifying the desired sample format.

§Returns

Self - The modified Output, allowing method chaining.

§Example

use ffmpeg_sys_next::AVSampleFormat::AV_SAMPLE_FMT_S16;

let output = Output::from("output.mp4")
    .set_audio_sample_fmt(AV_SAMPLE_FMT_S16); // Set to signed 16-bit

Source

pub fn set_video_qscale(self, video_qscale: i32) -> Self

Sets the video quality scale (VBR) for encoding.

This method configures a fixed quality scale for variable bitrate (VBR) video encoding. Lower values result in higher quality but larger file sizes, while higher values produce lower quality with smaller file sizes.

§Note on Modern Usage

While still supported, using fixed quality scale (-q:v) is generally not recommended for modern video encoding workflows with codecs like H.264 and H.265. Instead, consider:

For H.264/H.265: Use CRF (Constant Rate Factor) via -crf parameter
For two-pass encoding: Use target bitrate settings

This parameter is primarily useful for older codecs or specific scenarios where direct quality scale control is needed.

§Quality Scale Ranges by Codec

H.264/H.265: 0-51 (if needed: 17-28)
- 17-18: Visually lossless
- 23: High quality
- 28: Good quality with reasonable file size
MPEG-4/MPEG-2: 2-31 (recommended: 2-6)
- Lower values = higher quality
VP9: 0-63 (if needed: 15-35)

§Parameters

video_qscale - The quality scale value for video encoding.

§Returns

Self - The modified Output, allowing method chaining.

§Example

// For MJPEG encoding of image sequences
let output = Output::from("output.jpg")
    .set_video_qscale(2);  // High quality JPEG images

// For legacy image format conversion
let output = Output::from("output.png")
    .set_video_qscale(3);  // Controls compression level

Source

pub fn set_audio_qscale(self, audio_qscale: i32) -> Self

Sets the audio quality scale for encoding.

This method configures codec-specific audio quality settings. The range, behavior, and optimal values depend entirely on the audio codec being used.

§Quality Scale Ranges by Codec

MP3 (libmp3lame): 0-9 (recommended: 2-5)
- 0: Highest quality
- 2: Near-transparent quality (~190-200 kbps)
- 5: Good quality (~130 kbps)
- 9: Lowest quality
AAC: 0.1-255 (recommended: 1-5)
- 1: Highest quality (~250 kbps)
- 3: Good quality (~160 kbps)
- 5: Medium quality (~100 kbps)
Vorbis: -1 to 10 (recommended: 3-8)
- 10: Highest quality
- 5: Good quality
- 3: Medium quality

§Parameters

audio_qscale - The quality scale value for audio encoding.

§Returns

Self - The modified Output, allowing method chaining.

§Example

// For MP3 encoding at high quality
let output = Output::from("output.mp3")
    .set_audio_codec("libmp3lame")
    .set_audio_qscale(2);

// For AAC encoding at good quality
let output = Output::from("output.m4a")
    .set_audio_codec("aac")
    .set_audio_qscale(3);

// For Vorbis encoding at high quality
let output = Output::from("output.ogg")
    .set_audio_codec("libvorbis")
    .set_audio_qscale(7);

Source

pub fn set_max_video_frames(self, max_frames: impl Into<Option<i64>>) -> Self

Sets the maximum number of video frames to encode (-frames:v).

Equivalent FFmpeg Command:

ffmpeg -i input.mp4 -frames:v 100 output.mp4

Example Usage:

let output = Output::from("some_url")
    .set_max_video_frames(500);

Source

pub fn set_max_audio_frames(self, max_frames: impl Into<Option<i64>>) -> Self

Sets the maximum number of audio frames to encode (-frames:a).

Equivalent FFmpeg Command:

ffmpeg -i input.mp4 -frames:a 500 output.mp4

Example Usage:

let output = Output::from("some_url")
    .set_max_audio_frames(500);

Source

pub fn set_max_subtitle_frames(self, max_frames: impl Into<Option<i64>>) -> Self

Sets the maximum number of subtitle frames to encode (-frames:s).

Equivalent FFmpeg Command:

ffmpeg -i input.mp4 -frames:s 200 output.mp4

Example Usage:

let output = Output::from("some_url")
    .set_max_subtitle_frames(200);

Source

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

Sets a video codec-specific option.

These options control video encoding parameters such as compression, quality, and speed.

Supported Parameters:

Parameter	Description
`crf=0-51`	Quality level for x264/x265, lower means higher quality (`0` is lossless)
`preset=ultrafast, superfast, fast, medium, slow, veryslow`	Encoding speed, affects compression efficiency
`tune=film, animation, grain, stillimage, fastdecode, zerolatency`	Optimizations for specific types of content
`b=4M`	Bitrate (e.g., `4M` for 4 Mbps)
`g=50`	GOP (Group of Pictures) size, affects keyframe frequency

Example Usage:

let output = Output::from("some_url")
    .set_video_codec_opt("crf", "18")
    .set_video_codec_opt("preset", "fast");

Source

pub fn set_video_codec_opts( self, opts: Vec<(impl Into<String>, impl Into<String>)>, ) -> Self

Sets multiple video codec options at once.

Example Usage:

let output = Output::from("some_url")
    .set_video_codec_opts(vec![
        ("crf", "18"),
        ("preset", "fast")
    ]);

Source

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

Sets a audio codec-specific option.

These options control audio encoding parameters such as bitrate, sample rate, and format.

Supported Parameters:

Parameter	Description
`b=192k`	Bitrate (e.g., `128k` for 128 Kbps, `320k` for 320 Kbps)
`compression_level=0-12`	Compression efficiency for formats like FLAC

Example Usage:

let output = Output::from("some_url")
    .set_audio_codec_opt("b", "320k")
    .set_audio_codec_opt("compression_level", "6");

Source

pub fn set_audio_codec_opts( self, opts: Vec<(impl Into<String>, impl Into<String>)>, ) -> Self

Sets multiple audio codec options at once.

Example Usage:

let output = Output::from("some_url")
    .set_audio_codec_opts(vec![
        ("b", "320k"),
        ("compression_level", "6")
    ]);

Source

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

Sets a subtitle codec-specific option.

These options control subtitle encoding parameters such as format and character encoding.

Supported Parameters:

Parameter	Description
`mov_text`	Subtitle format for MP4 files
`srt`	Subtitle format for `.srt` files
`ass`	Advanced SubStation Alpha (ASS) subtitle format
`forced_subs=1`	Forces the subtitles to always be displayed

Example Usage:

let output = Output::from("some_url")
    .set_subtitle_codec_opt("mov_text", "");

Source

pub fn set_subtitle_codec_opts( self, opts: Vec<(impl Into<String>, impl Into<String>)>, ) -> Self

Sets multiple subtitle codec options at once.

Example Usage:

let output = Output::from("some_url")
    .set_subtitle_codec_opts(vec![
        ("mov_text", ""),
        ("forced_subs", "1")
    ]);

Source

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

Sets a format-specific option for the output container.

FFmpeg supports various format-specific options that can be passed to the muxer. These options allow fine-tuning of the output container’s behavior.

Example Usage:

let output = Output::from("some_url")
    .set_format_opt("movflags", "faststart")
    .set_format_opt("flvflags", "no_duration_filesize");

§Common Format Options:

Format	Option	Description
`mp4`	`movflags=faststart`	Moves moov atom to the beginning of the file for faster playback start
`flv`	`flvflags=no_duration_filesize`	Removes duration/size metadata for live streaming

Parameters:

key: The format option name (e.g., "movflags", "flvflags").
value: The value to set (e.g., "faststart", "no_duration_filesize").

Returns the modified Output struct for chaining.

Source

pub fn set_format_opts( self, opts: Vec<(impl Into<String>, impl Into<String>)>, ) -> Self

Sets multiple format-specific options at once.

This method allows setting multiple format options in a single call.

Example Usage:

let output = Output::from("some_url")
    .set_format_opts(vec![
        ("movflags", "faststart"),
        ("flvflags", "no_duration_filesize")
    ]);

Parameters: