Struct babycat::FloatWaveform

pub struct FloatWaveform { /* fields omitted */ }

Represents a fixed-length audio waveform as a Vec<f32>.

Implementations

impl FloatWaveform

pub fn from_encoded_bytes(
    encoded_bytes: &[u8],
    decode_args: DecodeArgs
) -> Result<Self, Error>

Decodes audio stored in an in-memory byte array.

Examples

use babycat::FloatWaveform;

let encoded_bytes: Vec<u8> = std::fs::read("audio-for-tests/andreas-theme/track.mp3").unwrap();

let decode_args = Default::default();

let waveform = FloatWaveform::from_encoded_bytes(
    &encoded_bytes,
    decode_args,
).unwrap();
assert_eq!(
    format!("{:?}", waveform),
    "FloatWaveform { frame_rate_hz: 44100, num_channels: 2, num_frames: 9586944}"
);

pub fn from_encoded_bytes_with_hint(
    encoded_bytes: &[u8],
    decode_args: DecodeArgs,
    file_extension: &str,
    mime_type: &str
) -> Result<Self, Error>

Decodes audio in an in-memory byte array, using user-specified encoding hints.

pub fn from_file(filename: &str, decode_args: DecodeArgs) -> Result<Self, Error>

Decodes audio stored in a local file.

Examples

Decode one audio file with the default decoding arguments:

use babycat::{DecodeArgs, FloatWaveform};

let waveform = FloatWaveform::from_file(
   "audio-for-tests/circus-of-freaks/track.mp3",
    Default::default(),
).unwrap();

assert_eq!(
    format!("{:?}", waveform),
    "FloatWaveform { frame_rate_hz: 44100, num_channels: 2, num_frames: 2492928}"
);

Decode only the first 30 seconds and upsample to 48khz:

use babycat::{DecodeArgs, FloatWaveform};

let decode_args = DecodeArgs {
    end_time_milliseconds: 30000,
    frame_rate_hz: 48000,
    ..Default::default()
};
let waveform = FloatWaveform::from_file(
   "audio-for-tests/circus-of-freaks/track.mp3",
    decode_args,
).unwrap();

assert_eq!(
    format!("{:?}", waveform),
    "FloatWaveform { frame_rate_hz: 48000, num_channels: 2, num_frames: 1440000}"
);

pub fn from_many_files(
    filenames: &[&str],
    decode_args: DecodeArgs,
    batch_args: BatchArgs
) -> Vec<NamedResult<Self, Error>>

Decodes a list of audio files in parallel.

Examples

(Attempt to) decode three files:

In this example, we process three filenames and demonstrate how to handle errors. The first two files are successfully processed, and we catch a Error::FileNotFound error when processing the third file.

use babycat::{Error, FloatWaveform, NamedResult};

let filenames = &[
    "audio-for-tests/andreas-theme/track.mp3",
    "audio-for-tests/blippy-trance/track.mp3",
    "does-not-exist",
];
let decode_args = Default::default();
let batch_args = Default::default();
let batch = babycat::FloatWaveform::from_many_files(
    filenames,
    decode_args,
    batch_args
);

fn display_result(nr: &NamedResult<FloatWaveform, Error>) -> String {
    match &nr.result {
        Ok(waveform) => format!("\nSuccess: {}:\n{:?}", nr.name, waveform),
        Err(err) => format!("\nFailure: {}:\n{}", nr.name, err),
    }
}
assert_eq!(
    display_result(&batch[0]),
     "
Success: audio-for-tests/andreas-theme/track.mp3:
FloatWaveform { frame_rate_hz: 44100, num_channels: 2, num_frames: 9586944}",
);
assert_eq!(
    display_result(&batch[1]),
     "
Success: audio-for-tests/blippy-trance/track.mp3:
FloatWaveform { frame_rate_hz: 44100, num_channels: 2, num_frames: 5294592}",
);
assert_eq!(
    display_result(&batch[2]),
     "
Failure: does-not-exist:
Cannot find the given filename does-not-exist.",
);

pub fn from_encoded_stream<R: 'static + Read>(
    encoded_stream: R,
    decode_args: DecodeArgs
) -> Result<Self, Error>

Decodes audio from an input stream.

FloatWaveform will take ownership of the stream and read it until the end. Therefore, you cannot provide an infinte-length stream.

pub fn from_encoded_stream_with_hint<R: 'static + Read>(
    encoded_stream: R,
    decode_args: DecodeArgs,
    file_extension: &str,
    mime_type: &str
) -> Result<Self, Error>

Decodes audio from an input stream, using a user-specified decoding hint.

pub fn from_frames_of_silence(
    frame_rate_hz: u32,
    num_channels: u32,
    num_frames: u64
) -> Self

Creates a silent waveform measured in frames.

Examples

This creates a FloatWaveform containing one second of silent stereo audio.

use babycat::FloatWaveform;

let waveform = FloatWaveform::from_frames_of_silence(44100, 2, 44100);
assert_eq!(
    format!("{:?}", waveform),
    "FloatWaveform { frame_rate_hz: 44100, num_channels: 2, num_frames: 44100}"
);

pub fn from_milliseconds_of_silence(
    frame_rate_hz: u32,
    num_channels: u32,
    duration_milliseconds: u64
) -> Self

Create a silent waveform measured in milliseconds.

Examples

This creates a FloatWaveform containing one second of silent stereo audio.

use babycat::FloatWaveform;

let waveform = FloatWaveform::from_milliseconds_of_silence(44100, 2, 1000);
assert_eq!(
    format!("{:?}", waveform),
    "FloatWaveform { frame_rate_hz: 44100, num_channels: 2, num_frames: 44100}"
);

pub fn resample(&self, frame_rate_hz: u32) -> Result<Self, Error>

Resamples the waveform.

use babycat::FloatWaveform;

let waveform = FloatWaveform::from_file(
    "audio-for-tests/circus-of-freaks/track.mp3",
    Default::default()
).unwrap();
assert_eq!(
   format!("{:?}", waveform),
   "FloatWaveform { frame_rate_hz: 44100, num_channels: 2, num_frames: 2492928}"
);

let upsampled = waveform.resample(96000).unwrap();
assert_eq!(
   format!("{:?}", upsampled),
   "FloatWaveform { frame_rate_hz: 96000, num_channels: 2, num_frames: 5426783}"
);

let downsampled = waveform.resample(8252).unwrap();
assert_eq!(
   format!("{:?}", downsampled),
   "FloatWaveform { frame_rate_hz: 8252, num_channels: 2, num_frames: 466478}"
);

pub fn resample_by_mode(
    &self,
    frame_rate_hz: u32,
    resample_mode: u32
) -> Result<Self, Error>

Resamples the audio using a specific resampler.

pub fn to_wav_buffer(&self) -> Result<Vec<u8>, Error>

Encdoes the waveform into a WAV-encoded byte array.

pub fn to_wav_file(&self, filename: &str) -> Result<(), Error>

Writes the waveform to the filesystem as a WAV file.

Trait Implementations

impl Clone for FloatWaveform

fn clone(&self) -> FloatWaveform

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FloatWaveform

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for FloatWaveform

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl From<FloatWaveform> for IntWaveform

fn from(item: FloatWaveform) -> Self

Performs the conversion.

impl From<IntWaveform> for FloatWaveform

fn from(item: IntWaveform) -> Self

Performs the conversion.

impl PartialEq<FloatWaveform> for FloatWaveform

fn eq(&self, other: &FloatWaveform) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &FloatWaveform) -> bool

This method tests for !=.

impl Serialize for FloatWaveform

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.

impl Waveform<f32> for FloatWaveform

fn new(
    frame_rate_hz: u32,
    num_channels: u32,
    interleaved_samples: Vec<f32>
) -> Self

Constructs a FloatWaveform from an already-decoded vector of 32-bit float samples.

Examples

This creates a FloatWaveform containing one second of silent stereo audio. Note that the input vector contains 88,200 audio samples–which we divide into 44,100 frames containing two samples each.

use babycat::{FloatWaveform, Waveform};

let frame_rate_hz = 44100;
let num_channels = 2;
let raw_uncompressed_audio: Vec<f32> = vec![0.0_f32; 88200];
let waveform = FloatWaveform::new(frame_rate_hz, num_channels, raw_uncompressed_audio);
assert_eq!(
    format!("{:?}", waveform),
    "FloatWaveform { frame_rate_hz: 44100, num_channels: 2, num_frames: 44100}"
);

fn interleaved_samples(&self) -> &[f32]

Returns of channel-interleaved samples.

fn frame_rate_hz(&self) -> u32

The frame rate (or sample rate) of the audio in memory.

fn num_channels(&self) -> u32

The number of audio channels.

fn num_frames(&self) -> u64

The number of frames in the audio.

impl StructuralPartialEq for FloatWaveform