Crate babycat

Crate babycat 

Source
Expand description

Babycat: Audio analysis made easy.

Babycat is a library that makes it easy to decode and manipulate many audio files at once.

Babycat is built on top of a lot of other Rust and C libraries, such as:

Babycat provides a consistent audio API for performing many tasks. You are viewing Babycat’s Rust documentation, but Babycat also has bindings for C, Python, and WebAssembly.

§Terminology

Babycat uses the same audio terminology as the Apple Core Audio API:

  • A channel is a discrete track of monophonic audio. A monophonic stream has one channel. A stereo stream has two channels. An audio stream that contains 5.1 surround sound will have five normal channels and one Low Frequency Enhancement (LFE) channel.
  • A sample is single numerical value in a single audio channel in an audio stream.
  • A frame is a collection of samples from the same point in time–one sample for each channel.
  • The frame rate (or sample rate) for a stream is the number of frames per second (hertz) of uncompressed audio.

Babycat stores audio as a single array of interleaved samples from channels. A waveform with two channels (e.g. left and right) are stored as:

§Resampling backends

Babycat has the ability to resample audio from one frame rate to another. There are several resampling backends available: Current valid values include:

  • RESAMPLE_MODE_LIBSAMPLERATE: This uses libsamplerate at the SRC_SINC_BEST_QUALITY setting. This is the highest-quality resampler currently offered by Babycat, although it is slightly slower than the other resamplers. This resampler is only available when Babycat is compiled with the Cargo feature enable-libsamplerate enabled. This feature is enabled by default in Babycat’s C, Python, and Rust frontends. The libsamplerate resampler is currently unavailable in Babycat’s WebAssembly frontend because libsamplerate’s dependency on libc makes it hard to compile it to the wasm32-unknown-unknown target.

  • RESAMPLE_MODE_BABYCAT_LANCZOS: A Lanczos resampler to use when compiling to targets like wasm32-unknown-unknown where libsamplerate cannot be compiled to. This is a simple impmenentation of a Lanczos resampler. This is the fastest (and lowest-quality) resampler available in Babycat.

  • RESAMPLE_MODE_BABYCAT_SINC: This is an implementation of a sinc resampler as described by Stanford professor Julius O. Smith. The speed and quality of this resampler is in between the above two.

§Examples

Decode multiple audio files in parallel.

use babycat::{WaveformArgs, Waveform};
use babycat::batch::waveforms_from_files;

// These are test files in the Babycat Git repository.
let filenames = &[
   "audio-for-tests/andreas-theme/track.flac",
   "audio-for-tests/blippy-trance/track.wav",
   "audio-for-tests/voxel-revolution/track.flac",
];

// Perform the following transformations on EACH track.
let waveform_args = WaveformArgs {
    // Upsample the audio to 48khz.
    frame_rate_hz: 48000,
    // Average all audio channels into a single monophonic channel.
    convert_to_mono: true,
    // Only select the first 60 seconds of audio.
    end_time_milliseconds: 60000,
    // If a track is shorter than 60 seconds, pad it with silence.
    zero_pad_ending: true,
    ..Default::default()
};
let batch_args = Default::default();

// Read and decode the tracks in parallel.
let batch = waveforms_from_files(
   filenames,
   waveform_args,
   batch_args,
);

// Iterate over the results.
for named_result in batch {
    match &named_result.result {
        Ok(waveform) => {
            // Do further processing.
            waveform.to_interleaved_samples();
        }
        Err(err) => {
            // Handle decoding errors.
        }
    }
}

Modules§

assertions
Custom assertions and other testing utilities.
batch
Functions that use multithreading to manipulate multiple audio files in parallel.
build_info
Information about compile-time features and licensing.
constants
decoder
Iterators that decode encoded audio files or streams into a Source yielding f32 samples.
display
Utilities for rendering objects as strings.
source
Iterators over audio.
units
Functions for converting from one unit of measurement to another.

Structs§

BatchArgs
Configures multithreading in Babycat.
Waveform
Represents a fixed-length audio waveform as a Vec<f32>.
WaveformArgs
Specifies what transformations to apply to the audio during the decoding process.
WaveformNamedResult
WaveformSource
A wrapper for Waveform that turns it into a consumable Source iterator.

Enums§

Error

Traits§

Sample
Signal
A trait that describes common properties of all digital audio signals.
Source
A sample iterator created by an audio decoder.

Type Aliases§

WaveformResult