bookclerk_libav

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Decoders-only FFmpeg for the audio formats Bookclerk's own decoders do not cover: AC-3 and E-AC-3, Windows Media Audio (v1, v2, Pro and Lossless) and AMR (narrowband and wideband).

The build script compiles a pinned FFmpeg release with nothing but those decoders, their demuxers (ASF, raw AC-3/E-AC-3, raw AMR and ISO-BMFF for 3GP) and the AC-3 parser, and links it statically. A small C shim (src/shim.c) is the only code that touches FFmpeg's structs, so this crate never depends on their layout.

The media worker is the only user: it decodes untrusted files with Demuxer and Decoder inside its confinement, the same as every other codec. FFmpeg is LGPL-2.1-or-later in this configuration; see docs/contributing/licensing.md.

Unix and Windows (MSVC) only: on other targets the crate is empty, and the libav feature of bookclerk-media that pulls it in stays off there.

Item Kind Summary
Source trait A seekable byte source a Demuxer reads from.
CodecConfig struct What a decoder needs to know about a track.
Frame struct One decoded frame: interleaved 32-bit float samples in -1.0..=1.0.
Decoder struct An FFmpeg audio decoder for one track.
Track struct The audio track a Demuxer chose.
Packet struct One demuxed packet of the chosen track.
Demuxer struct An FFmpeg demuxer over a byte source, reading one audio track.
Error enum Why a call into FFmpeg failed.
Codec enum A codec this build decodes.
sniff function Whether head, the first bytes of a file, starts a container that only this crate reads: ASF, raw AMR (#!AMR) or a raw AC-3/E-AC-3 stream (sync word 0x0B77 at offset 0).
FFMPEG_VERSION constant The FFmpeg release this crate builds, as configure names it.
MAX_EXTRADATA constant Most bytes of codec setup data accepted from a container (1 MiB), matching the shim's own limit.
SNIFF_LEN constant Bytes sniff needs to decide.

Modules

  • fixtures: Small audio files in every format this crate decodes, for tests here and in the crates that use it.

Traits

Source

pub trait Source: Read + Seek + Send {}

A seekable byte source a Demuxer reads from.

Implemented by: T

Structs

CodecConfig

pub struct CodecConfig {
    pub codec: Codec,
    pub sample_rate: u32,
    pub channels: u16,
    pub block_align: u32,
    pub bit_rate: u64,
    pub extradata: Vec<u8>,
}

What a decoder needs to know about a track.

Fields

  • codec: The codec.
  • sample_rate: Stated sample rate in Hz, or 0 when the stream carries its own.
  • channels: Stated channel count, or 0 when the stream carries its own.
  • block_align: Bytes per coded block (WMA needs it), or 0.
  • bit_rate: Stated bit rate in bits per second (WMA needs it), or 0.
  • extradata: Codec setup bytes from the container (WMA needs them), at most MAX_EXTRADATA.

CodecConfig::bare

pub fn bare(codec: Codec) -> Self

A config for codec with nothing stated: enough for AC-3, E-AC-3 and AMR, whose streams describe themselves.

Implements: Clone, Debug, Eq, PartialEq

Frame

pub struct Frame<'a> {
    pub samples: &'a [f32],
    pub frames: usize,
    pub channels: usize,
    pub sample_rate: u32,
    pub channel_mask: u64,
}

One decoded frame: interleaved 32-bit float samples in -1.0..=1.0.

Fields

  • samples: frames * channels samples, channel-interleaved.
  • frames: Samples per channel.
  • channels: Interleaved channels, 1 to 8, in FFmpeg's default order for the count (left, right, centre, LFE, …).
  • sample_rate: Sample rate in Hz.
  • channel_mask: Speaker positions in WAVE bit numbering (bit 0 front left, 1 front right, 2 centre, 3 LFE, …), one bit per channel in interleaved order; 0 when the decoder states none.

Implements: Clone, Copy, Debug

Decoder

pub struct Decoder {
    /* private fields */
}

An FFmpeg audio decoder for one track.

Decoder::new

pub fn new(config: &CodecConfig) -> Result<Self, Error>

Opens a decoder for config.

Errors

Error::Unsupported when FFmpeg will not open the codec with these parameters, Error::Arguments for out-of-range values, or Error::OutOfMemory.

Decoder::decode

pub fn decode<F>(&mut self, packet: &[u8], on_frame: F) -> Result<(), Error>
where
    F: FnMut(Frame<'_>),

Decodes one packet, calling on_frame for each frame it gives.

Errors

Error::Decode when the decoder rejects the packet (the caller may skip it and go on), Error::Layout for a frame outside the shim's limits, or Error::OutOfMemory.

Decoder::drain

pub fn drain<F>(&mut self, on_frame: F) -> Result<(), Error>
where
    F: FnMut(Frame<'_>),

Ends the stream: hands back the frames a delayed decoder (WMA v1, v2 and lossless) still holds, then resets it so later packets, as after a seek, decode from a clean state.

Errors

Error::Decode when the decoder refuses the end of stream, Error::Layout for a frame outside the shim's limits, or Error::OutOfMemory. The decoder is reset either way.

Decoder::flush

pub fn flush(&mut self)

Drops buffered decoder state, as after a seek.

Implements: Drop, Send, Sync

Track

pub struct Track {
    pub config: CodecConfig,
    pub time_base: (u32, u32),
    pub duration: Option<u64>,
    pub start: i64,
}

The audio track a Demuxer chose.

Fields

  • config: What a Decoder needs for it.
  • time_base: Seconds per timestamp tick: time_base.0 / time_base.1, both positive.
  • duration: Length in ticks, when the container states it.
  • start: First timestamp in ticks.

Implements: Clone, Debug, Eq, PartialEq

Packet

pub struct Packet<'a> {
    pub data: &'a [u8],
    pub pts: i64,
    pub duration: u64,
}

One demuxed packet of the chosen track.

Fields

  • data: The coded bytes, valid until the next demuxer call.
  • pts: Presentation timestamp in ticks (may be negative or missing as i64::MIN for some streams).
  • duration: Length in ticks, or 0 when not stated.

Implements: Clone, Copy, Debug

Demuxer

pub struct Demuxer {
    /* private fields */
}

An FFmpeg demuxer over a byte source, reading one audio track.

Demuxer::open

pub fn open(source: Box<dyn Source>) -> Result<Self, Error>

Opens the container in source and picks its best audio track.

Errors

Error::Demux when no enabled demuxer recognises the bytes or the header is broken, Error::Unsupported when there is no audio track in a codec this build decodes, or Error::OutOfMemory.

Demuxer::track

pub fn track(&self) -> &Track

The chosen audio track.

Demuxer::next_packet

pub fn next_packet(&mut self) -> Result<Option<Packet<'_>>, Error>

Reads the chosen track's next packet.

Returns

The packet, or None at the end of the stream.

Errors

Error::Demux when the container is broken (or the source failed), or Error::OutOfMemory.

Demuxer::seek

pub fn seek(&mut self, ts: i64) -> Result<(), Error>

Seeks to the last key point at or before ts (in track ticks).

Errors

Error::Demux when the container cannot seek there.

Implements: Drop, Send, Sync

Enums

Error

pub enum Error {
    Arguments,
    OutOfMemory,
    Unsupported,
    Decode,
    Demux,
    Layout,
}

Why a call into FFmpeg failed.

Variants

  • Arguments: A value handed to the shim was out of range.
  • OutOfMemory: An allocation failed.
  • Unsupported: This build has no decoder or demuxer for the input.
  • Decode: The decoder rejected a packet as corrupt.
  • Demux: The demuxer failed.
  • Layout: A decoded frame had a channel count, rate or length outside the shim's limits.

Implements: Clone, Copy, Debug, Display, Eq, Error, PartialEq

Codec

pub enum Codec {
    Ac3,
    Eac3,
    WmaV1,
    WmaV2,
    WmaPro,
    WmaLossless,
    AmrNb,
    AmrWb,
}

A codec this build decodes.

Variants

  • Ac3: Dolby Digital (AC-3).
  • Eac3: Dolby Digital Plus (E-AC-3).
  • WmaV1: Windows Media Audio 1.
  • WmaV2: Windows Media Audio 2.
  • WmaPro: Windows Media Audio 9 Professional.
  • WmaLossless: Windows Media Audio 9 Lossless.
  • AmrNb: Adaptive Multi-Rate narrowband (8 kHz speech).
  • AmrWb: Adaptive Multi-Rate wideband (16 kHz speech).

Codec::ALL

pub const ALL: [Codec; 8] = _

Every codec, in the shim's numbering order.

Codec::number

pub fn number(self) -> u8

The shim's number for this codec (1 to 8).

Codec::from_number

pub fn from_number(number: u8) -> Option<Self>

The codec with shim number number, if any.

Codec::name

pub fn name(self) -> &'static str

FFmpeg's short name for the decoder (ac3, wmav2, amrwb, …).

Implements: Clone, Copy, Debug, Eq, Hash, PartialEq

Functions

sniff

pub fn sniff(head: &[u8]) -> bool

Whether head, the first bytes of a file, starts a container that only this crate reads: ASF, raw AMR (#!AMR) or a raw AC-3/E-AC-3 stream (sync word 0x0B77 at offset 0).

Callers check this before handing the file to another demuxer, which might otherwise mistake a raw stream for MPEG audio while hunting for frame syncs.

Constants

FFMPEG_VERSION

pub const FFMPEG_VERSION: &str = "9.0.2";

The FFmpeg release this crate builds, as configure names it.

MAX_EXTRADATA

pub const MAX_EXTRADATA: usize = _;

Most bytes of codec setup data accepted from a container (1 MiB), matching the shim's own limit.

SNIFF_LEN

pub const SNIFF_LEN: usize = 16;

Bytes sniff needs to decide.

Generated from crates/bookclerk-libav at main · View as Markdown