Awedio  

A low-overhead and adaptable audio playback library for Rust.

By default supports playing mp3, wav, flac, aac, ogg, qoa and all other formats supported by Symphonia.

Examples

Play a single sound file:

let (mut manager, backend) = awedio::start()?;
manager.play(awedio::sounds::open_file("test.wav")?);

Play a sound with adjustable volume controllable after playback has started:

use awedio::Sound;
let (mut manager, backend) = awedio::start()?;
let (sound, mut controller) = awedio::sounds::SineWav::new(400.0)
    .with_adjustable_volume_of(0.25)
    .pausable()
    .controllable();
manager.play(Box::new(sound));
std::thread::sleep(std::time::Duration::from_millis(100));
controller.set_volume(0.5);
std::thread::sleep(std::time::Duration::from_millis(100));
controller.set_paused(true);

Design Goals

• Modular design. Easy to add new backends, wrappers and decoders.
• Very low overhead. For example, a Wav file with i16 samples with the same same sample rate as the output device will have samples sent to the backend unchanged.
• Only pay the performance cost of features if they are needed. For example pausability, volume adjustment, or controlling a sound after playback has started are all added to a Sound only as needed. This is done by wrapping types that implement Sound similar to Iterator in the standard library.
• Usable in low resource environments such as the esp32 microcontroller. Currently does require std.
• Samples are i16 for simplicity at least for now (if this prevents you from using this library please let me know your use case)

API Overview

• Sound trait - Provides samples of a sound to be played. Has functions to modify sounds with wrappers.
• Manager - Play Sounds to a backend.
• SoundList - A sequence of Sounds to play one after the other.

Current backends

• cpal - For popular environments such as Linux, Windows, Mac OS, Android... Enabled by the cpal feature (on by default).
• esp32 - For esp32 microcontrollers using esp-idf. Implemented in its own crate.

Backends are implemented by pulling samples from a [BackendSource] such as the Renderer.

Cargo Features

• async: Enable async features that depend on tokio-sync
• cpal: Enable the cpal backend.
• symphonia-all: Enable all formats and codecs supported by Symphonia
• symphonia-: All feature flags of symphonia are re-exported with the symphonia- prefix.
• hound-wav: Enable wav decoding using Hound
• rmp3-mp3: Enable mp3 decoding using rmp3
• qoa: Enable qoa decoding using qoaudio

By default all features are enabled excluding hound-wav and rmp3-mp3 since symphonia handles those formats by default.

Depending libraries should disable default features.

Motivation

Built for creating activities for 10 Buttons, a screen-less tablet for kids. Purposefully kept generic to be usable in other contexts.

Alternatives and Inspiration

Thanks to the following audio playback libraries which inspired and were a reference for this library:

• Rodio
  • Very popular crate for audio playback with Rust.
  • Tightly coupled to cpal. Awedio allows for easy integration with cpal or other backends.
  • Has a Sink which is similar to SoundList::new().pausable().with_adjustable_volume().controllable()...
  • Mixer converts everything to an f32. Awedio uses i16 consistently.
  • Sources have the concept of a frame length where metadata should not change but this does not work well for some wrappers such as Speed.
  • Uses the standard Iterator trait for its Source. Awedio's Sound is its own enum that handles Metadata Changes, Pausing and Finishing sounds.
  • Does not have a way to propagate errors through Sources. Awedio's sound returns a result so errors can be explicitly handled if desired.
• Kira
  • Has very nice API for tweening and effects.
  • Sound trait requires a left/right track instead of supporting 1 or N tracks.
  • Samples are all f32. Thus frames are always 8 bytes. A frame for a mono Sound in awedio is only 2 bytes.
  • Uses symphonia for audio format parsing and has several internal buffers requiring more memory. Awedio optionally uses symphonia or other decoding crates with less buffering required.
  • All samples are resampled based on the timestamp and sample rate. Awedio only resamples if the source and output rates do not match.

License

This project is licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.