Euphorium
Painless audio playback for native and web platforms.
A small Rust audio player built on top of rodio and CPAL.
Installation
Usage
use ;
Typed sound keys
Use a typed scene when the application has sounds that must always exist:
use ;
sound_key!
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:
- There is no Null backend, so you must forever live with
Option<MixerDeviceSink>. rodio::Player::try_seekdeadlocks on WASM and some specific threading setups.- 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.
- rodio does not officially support AudioWorklet while CPAL does.
- No convenience code in rodio for native and web audio resource handling, causing a ton of
#[cfg(target_arch = "wasm32")]. - No waveform visualization.
- Concurrent playback normally requires callers to own and synchronize a collection of players.
Development
This repository uses mise.
License
Licensed under either of:
at your option.