Crate vorbis_rs

Safe, ergonomic, and high-quality Rust bindings to the vorbisfile, libvorbisenc, and libvorbis C libraries.

These bindings depend on the accompanying low-level FFI bindings at the ogg_next_sys and aotuv_lancer_vorbis_sys crates, which link to the latest versions of the upstream libogg and patched upstream libvorbis codebases, respectively. The upstream libvorbis codebase is patched with the latest aoTuV and Lancer patches, which improve coding efficiency and performance.

Known limitations

Decoding chained Ogg Vorbis streams (i.e., with several consecutive logical bitstreams) is not supported for now. These are seldom found, however. Feel free to file an issue or open a pull request if you are interested in chained stream support.

Seeking is also not supported, although it’d be a welcome addition.

Features

• stream-serial-rng (enabled by default): adds the VorbisEncoderBuilder::new convenience method, which automatically configures such a builder with suitable random Ogg stream serial numbers. This feature pulls dependencies on random number generation crates.

Examples

The following example transcodes an Ogg Vorbis file to another in-memory Ogg Vorbis stream, showing how the API offered by this crate works together to achieve this task.

let mut source_ogg = File::open("audio.ogg")?;
let mut transcoded_ogg = vec![];

let mut decoder = VorbisDecoder::new(&mut source_ogg)?;
let mut encoder = VorbisEncoderBuilder::new(
    decoder.sampling_frequency(),
    decoder.channels(),
    &mut transcoded_ogg
)?
.build()?;

while let Some(decoded_block) = decoder.decode_audio_block()? {
    encoder.encode_audio_block(decoded_block.samples())?;
}

// The encoder is automatically finished on drop, so calling finish explicitly is
// only needed if you want to handle any errors
encoder.finish()?;

// Do whatever you want with transcoded_ogg now

Structs

VorbisAudioSamples

Contains a block of audio samples. This struct is returned by a VorbisDecoder.

VorbisDecoder

A decoder that turns a perceptually-encoded, non-chained Ogg Vorbis stream into blocks of planar, single-precision float audio samples.

VorbisEncoder

An encoder that transforms blocks of planar, single-precision float audio samples to a perceptually-encoded Ogg Vorbis stream. Instances of this encoder can be obtained from a VorbisEncoderBuilder.

VorbisEncoderBuilder

Builds a VorbisEncoder with configurable Vorbis encoding and Ogg stream encapsulation options.

VorbisLibraryError

An error condition reported by one of the libogg, libvorbis, libvorbisenc or vorbisfile C libraries during encoding or decoding operations.

Enums

VorbisBitrateManagementStrategy

Represents a bitrate management strategy that a Vorbis encoder can use.

VorbisError

An error condition that may happen during an encoding or decoding operation.

VorbisLibrary

Represents an Ogg Vorbis C library that participates in audio encoding or decoding operations, and may be responsible for a VorbisLibraryError.

VorbisLibraryErrorKind

A category of VorbisLibraryError.