euphorium 0.2.0

Painless audio playback for native and web platforms
Documentation

Euphorium

Painless audio playback for native and web platforms.

A small Rust audio player built on top of rodio and CPAL.

Installation

cargo add euphorium

Usage

use euphorium::{SoundAsset, Soundscape, SoundscapeError, SoundSource};

fn main() -> Result<(), SoundscapeError> {
    // One Soundscape owns the output and every sound in the application.
    let soundscape = Soundscape::new();
    let music = soundscape.create_group("music")?;
    let battle = music.create_group("battle")?;
    let theme = battle.create_sound("theme", SoundSource::file("audio.mp3"))?;

    // Group volume multiplies each descendant's local volume.
    music.set_volume(0.8)?;
    theme.set_volume(0.5)?;
    theme.set_speed(1.25)?;

    theme.play()?;
    theme.try_seek_secs(30.0)?;
    theme.wait_until_end()?;
    Ok(())
}

fn play_embedded_audio(audio: &'static [u8]) -> Result<(), SoundscapeError> {
    let soundscape = Soundscape::new();
    let sound = soundscape.create_sound("embedded", SoundSource::static_bytes(audio))?;
    sound.play()?;
    Ok(())
}

fn where_is_my_audio_at(soundscape: &Soundscape) -> Result<(), SoundscapeError> {
    let sound = soundscape.find_sound("music/battle/theme").expect("theme exists");
    sound.pause()?;
    sound.resume()?;
    println!("{} / {}", sound.position_formatted()?, sound.duration_formatted()?);
    Ok(())
}

fn play_my_audio_cross_platform() -> Result<(), SoundscapeError> {
    // Use file path "assets/music.mp3" on native and URL "audio.mp3" on web.
    let asset = SoundAsset::new("assets/music.mp3", "audio.mp3");
    let soundscape = Soundscape::new();
    let sound = soundscape.create_sound("music", SoundSource::asset(asset))?;
    sound.play()?;

    // Call this from the application's update loop. It completes browser loads
    // and reports asynchronous failures for every sound in one place.
    for failure in soundscape.update() {
        eprintln!("sound {:?} failed: {}", failure.sound, failure.error);
    }
    Ok(())
}

Typed sound keys

Use a typed scene when the application has sounds that must always exist:

use euphorium::{Soundscape, SoundscapeError, SoundSource};

euphorium::sound_key! {
    enum AppSound {
        Preview => "preview",
        BattleTheme => "music/battle/theme",
    }
}

fn audio_scene(preview: SoundSource, theme: SoundSource) -> Result<Soundscape<AppSound>, SoundscapeError> {
    Soundscape::<AppSound>::builder()
        .sound(AppSound::Preview, preview)
        .sound(AppSound::BattleTheme, theme)
        .build()
}

fn play_theme(soundscape: &Soundscape<AppSound>) -> Result<(), SoundscapeError> {
    // Typed lookup is total: every key was validated by build().
    soundscape.sound(AppSound::BattleTheme).play()
}

Required sounds cannot be removed, including through recursive group removal, so typed lookup continues returning Sound rather than Option<Sound>. Runtime-created sounds remain available through soundscape.find_sound("path/to/sound").

Use .placeholder(AppSound::Preview) when a particular key should exist before its resource is known. Use .build_with_placeholders() to create empty sounds for every key that has not received an explicit source. Empty sounds return SoundscapeError::NoAudioSource from play() until set_source() assigns one.

Browsers require audio output to be opened in response to a user gesture. Start playback from a click, pointer, or keyboard event when possible.

Please find these examples for more guidance.

Feature flags

Feature Enables
cli (default) euphorium <PATH>
mp3 (default) MP3 decoding
flac FLAC decoding
mp4 MP4 decoding
vorbis Vorbis decoding
wav (default) WAV decoding
asio ASIO backend
jack JACK backend
nightly AudioWorklet backend

Motivation

rodio and CPAL are both great libraries, but they are not very ergonomic to use. Here are some issues that I have encountered while using them:

  1. There is no Null backend, so you must forever live with Option<MixerDeviceSink>.
  2. rodio::Player::try_seek deadlocks on WASM and some specific threading setups.
  3. rodio seems to prioritize correctness, which is fine, but you end up needing to wrap a lot of code yourself to get predictable behavior e.g. setting time position or playback speed when no audio is playing.
  4. rodio does not officially support AudioWorklet while CPAL does.
  5. No convenience code in rodio for native and web audio resource handling, causing a ton of #[cfg(target_arch = "wasm32")].
  6. No waveform visualization.
  7. Concurrent playback normally requires callers to own and synchronize a collection of players.

Development

This repository uses mise.

mise bootstrap
mise install
mise run check

License

Licensed under either of:

at your option.