Crate vorbis_rs

source ·
Expand description

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