ffmpeg-next Rust Documentation

The ffmpeg-next crate uses a versioning scheme that tracks FFmpeg versions rather than strictly following SemVer.

• Major and Minor versions: These track the major and minor versions of FFmpeg. For example, ffmpeg-next v4.2.x is designed to support the FFmpeg 4.2.x series.
• Patch versions: These are reserved for changes to the ffmpeg-next crate itself and do not track FFmpeg patch versions.

Warning: Because minor versions track FFmpeg versions, they may introduce backward-incompatible changes (behaving like SemVer major versions). Patch versions may introduce new APIs (behaving like SemVer minor versions). You should pin your dependency to a specific version to ensure stability.

The ffmpeg_next::codec module provides several key abstractions for working with media codecs:

• Context: The primary interface for codec operations.
• Parameters: Represents codec parameters (e.g., bit rate, profile).
• Capabilities: Describes the capabilities of a codec.
• Flags: Represents codec-specific flags.
• Id: Represents a codec identifier.
• Compliance: Describes codec compliance levels.
• Profile: Represents codec profiles.
• Debug: Provides debugging information.

Other submodules include packet, subtitle, video, audio, decoder, and encoder.

The Output struct is the primary interface for muxing and writing media files. It wraps an AVFormatContext and provides methods to add streams, write headers/trailers, and manage metadata. It implements Deref and DerefMut to the underlying Context, allowing access to common format properties.

Key capabilities:

• Stream Management: Add audio/video streams using encoders or existing codec contexts.
• Lifecycle: Write the file header (write_header) and finalize the file (write_trailer).
• Metadata: Set global metadata for the output file.
• Chapters: Add and manage chapters within the output.
• Debugging: Dump the format information to a stream (e.g., stderr) using dump functions.

The Opened struct represents an active decoder instance. To decode media, you follow a pattern of sending packets to the decoder and receiving frames from it.

1. Send Packets: Use send_packet to pass a packet to the decoder.
2. Signal EOF: Use send_eof to send a NULL packet, which signals the end of the stream and puts the decoder into draining mode.
3. Receive Frames: Use receive_frame to pull decoded Frame objects from the decoder's internal buffer.
4. Flush: Use flush to clear the decoder's internal buffers.

Starting with version 4.3.4, ffmpeg-next introduced automatic FFmpeg version detection. This makes the explicit version feature flags obsolete.

• Obsolete flags: ffmpeg4, ffmpeg41, ffmpeg42, and ffmpeg43.
• Action required: If you are manually specifying any of these flags in your Cargo.toml, you should remove them.
• Backward compatibility: If you use ffmpeg43 via the default feature, it is currently a no-op and safe to leave, but it will be removed from default features in version 4.4 and completely removed in version 5.0.

You can query several properties from an Opened decoder instance:

• bit_rate(): Returns the bitrate as a usize.
• delay(): Returns the codec delay as a usize.
• profile(): Returns the codec Profile.
• frame_rate(): Returns the frame rate as an Option<Rational>. Returns None if the framerate is not set (represented by a numerator of 0).

Use into_inner() to consume the StreamIo and reclaim the original Rust stream. This method will first flush any data remaining in the FFmpeg AVIOContext buffer.

Note: This method will fail if the type T provided does not exactly match the type used to construct the StreamIo.

You can inspect the configuration of a Context using the input() and output() methods. Both return a &Definition struct.

A Definition contains:

• format: The format::Sample type.
• channel_layout: The ChannelLayout.
• rate: The sample rate (u32).

The Error type implements From<c_int> and From<Error> for c_int. This allows for seamless conversion between FFmpeg's integer error codes and the Rust Error enum.

• Error::from(c_int): Converts an FFmpeg error integer into the appropriate Error variant. If the integer represents a POSIX error wrapped in AVERROR, it becomes Error::Other { errno }.
• c_int::from(Error): Converts an Error variant back into its corresponding FFmpeg integer code.

To read media files, use the input functions. These functions open the file and automatically call avformat_find_stream_info to probe the stream information.

• input(path): The simplest way to open a file for reading. The format is automatically detected.
• input_with_dictionary(path, options): Opens a file with specific FFmpeg format options provided via a Dictionary.
• input_with_interrupt(path, closure): Opens a file with an interrupt callback. The closure should return true to abort a stalled or blocking operation (like a network read). This is useful for preventing hangs.
• input_with_interrupt_and_dictionary(path, closure, options): Combines interrupt handling and custom format options.
• input_from_stream(custom_io, filename, options): Opens an input from a custom context::StreamIo (e.g., memory buffers or custom network protocols).