game_toolkit_audio/

lib.rs

//! Audio subsystem built on [`kira`].
//!
//! Load static sound buffers (from disk or bytes) and play them on the main track. Every play
//! call returns a [`SoundHandle`] that controls that instance: volume (instant or faded), pause,
//! resume, stop, and whether it's still playing. [`PlayOptions`] covers looping, a start volume
//! and deferred start in one call:
//!
//! ```no_run
//! # use game_toolkit_audio::{Audio, PlayOptions};
//! # fn demo(audio: &mut Audio, music: game_toolkit_audio::SoundId) -> anyhow::Result<()> {
//! // Background music: loop at 30% volume, starting as soon as audio is available.
//! let handle = audio.play_with(music, PlayOptions::looped().volume(0.3).deferred())?;
//! handle.pause();
//! handle.resume();
//! handle.fade_volume(0.0, std::time::Duration::from_secs(2));
//! # Ok(()) }
//! ```
//!
//! Audio generated while it plays (a synthesizer, an emulated sound chip) goes through
//! [`Audio::play_stream`], or [`Audio::play_stereo_stream`] for separate left and right channels. With the `synth` feature, [`Audio::play_synth`] plays chiptune
//! music written in tracker notation live on the built-in synth, and [`Synth`] renders effects
//! and jingles to PCM (see [`synth`]). Mixer tracks, spatial audio and file streaming are not wrapped;
//! [`kira`] is re-exported for anything beyond this API, and [`SoundHandle::with_kira`]
//! reaches the underlying handle.
//!
//! On the web, browsers keep an `AudioContext` suspended until the first user gesture, and kira
//! offers no way to resume it. [`Audio`] therefore opens the backend lazily there: sounds can be
//! loaded right away, but playback only starts once [`Audio::start`] has run (the toolkit's core
//! calls it on the first key press, click or touch, or sooner if the page already had a gesture
//! and the browser lets audio start). Until then plays fail with
//! [`AudioError::NotStarted`], unless they were [`PlayOptions::deferred`], which queues them.
//!
//! [`Audio::suspend`] pauses everything at once. On the web, the toolkit's core also
//! suspends the `AudioContext` while the game's canvas is detached from the page (see
//! `DetachHandle`), since the game gets no frames then to do it itself.

#![forbid(unsafe_code)]

use std::collections::HashMap;
#[cfg(not(target_arch = "wasm32"))]
use std::path::Path;
use std::sync::Arc;

use anyhow::{Result, anyhow};
use kira::sound::static_sound::{StaticSoundData, StaticSoundSettings};
use kira::track::{TrackBuilder, TrackHandle};
use kira::{AudioManager, AudioManagerSettings, Decibels, Frame, Tween};

mod handle;
use handle::Slot;
pub use handle::SoundHandle;
mod stream;
pub use kira;
pub use stream::{AudioStream, StereoStream, StreamHandle};
use stream::{Source, StreamData};

#[cfg(target_arch = "wasm32")]
mod web;
#[cfg(target_arch = "wasm32")]
pub use web::DetachHandle;

#[cfg(target_arch = "wasm32")]
type Backend = web::WebBackend;
#[cfg(not(target_arch = "wasm32"))]
type Backend = kira::DefaultBackend;

#[cfg(feature = "synth")]
mod music;
#[cfg(feature = "synth")]
use music::PreparedSynth;
#[cfg(feature = "synth")]
pub use music::SynthHandle;
#[cfg(feature = "synth")]
pub mod synth;
#[cfg(feature = "synth")]
pub use synth::Synth;
#[cfg(feature = "synth")]
pub use synthie;

#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub struct SoundId(pub u32);

/// Why a sound didn't play.
#[derive(Debug)]
#[non_exhaustive]
pub enum AudioError {
    /// Audio hasn't started yet: on the web, the player hasn't pressed a key, clicked or
    /// touched the page. Not a real failure; try again later, check [`Audio::is_started`]
    /// first, or play with [`PlayOptions::deferred`] to queue the sound.
    NotStarted,
    /// The [`SoundId`] wasn't returned by this [`Audio`].
    UnknownSound(SoundId),
    /// kira refused to play the sound (e.g. its sound limit was reached).
    Backend(String),
}

impl std::fmt::Display for AudioError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::NotStarted => f.write_str("audio not started yet (waiting for a user gesture)"),
            Self::UnknownSound(id) => write!(f, "unknown SoundId {id:?}"),
            Self::Backend(e) => write!(f, "kira play: {e}"),
        }
    }
}

impl std::error::Error for AudioError {}

/// How to play a sound: see [`Audio::play_with`]. The default plays once at the sound's own
/// volume, and fails with [`AudioError::NotStarted`] before audio is available.
#[derive(Copy, Clone, Debug, PartialEq)]
pub struct PlayOptions {
    /// Loop the whole sound until stopped.
    pub looped: bool,
    /// Linear amplitude (`1.0` is the sound's own level, `0.0` silence).
    pub volume: f32,
    /// If audio hasn't started yet (web, before the first user gesture), queue the sound and
    /// start it once audio starts, instead of failing with [`AudioError::NotStarted`]. Meant
    /// for music and ambience; a one-shot effect would play late, out of context.
    pub deferred: bool,
}

impl Default for PlayOptions {
    fn default() -> Self {
        Self {
            looped: false,
            volume: 1.0,
            deferred: false,
        }
    }
}

impl PlayOptions {
    /// Options for a sound that loops until stopped.
    pub fn looped() -> Self {
        Self {
            looped: true,
            ..Self::default()
        }
    }

    /// Set [`PlayOptions::volume`].
    pub fn volume(self, volume: f32) -> Self {
        Self { volume, ..self }
    }

    /// Set [`PlayOptions::deferred`].
    pub fn deferred(self) -> Self {
        Self {
            deferred: true,
            ..self
        }
    }
}

/// The open output: kira's manager and the bus every sound plays on.
struct Manager {
    kira: AudioManager<Backend>,
    /// A sub track between the sounds and the main track, so [`Audio::suspend`] can pause
    /// them all at once (kira's main track can't pause).
    bus: TrackHandle,
}

pub struct Audio {
    manager: Option<Manager>,
    /// Set by [`Audio::suspend`]; applied to the bus once audio starts.
    suspended: bool,
    #[cfg(target_arch = "wasm32")]
    detach: DetachHandle,
    sounds: HashMap<SoundId, StaticSoundData>,
    next_id: u32,
    /// Main-track gain, remembered so a volume set before [`Audio::start`] still applies.
    master_volume: Decibels,
    /// [`PlayOptions::deferred`] sounds waiting for [`Audio::start`].
    queued: Vec<(StaticSoundData, SoundHandle)>,
    /// [`PlayOptions::deferred`] streams waiting for [`Audio::start`].
    queued_streams: Vec<StreamData>,
    /// [`PlayOptions::deferred`] synths waiting for [`Audio::start`].
    #[cfg(feature = "synth")]
    queued_synths: Vec<PreparedSynth>,
}

impl Audio {
    /// Create the audio subsystem. On native targets this opens the output device immediately;
    /// on the web it defers that to [`Audio::start`].
    pub fn new() -> Result<Self> {
        let mut audio = Self {
            manager: None,
            suspended: false,
            #[cfg(target_arch = "wasm32")]
            detach: DetachHandle::default(),
            sounds: HashMap::new(),
            next_id: 1,
            master_volume: Decibels::IDENTITY,
            queued: Vec::new(),
            queued_streams: Vec::new(),
            #[cfg(feature = "synth")]
            queued_synths: Vec::new(),
        };
        if !cfg!(target_arch = "wasm32") {
            audio.start()?;
        }
        Ok(audio)
    }

    /// Open the output device if it isn't open yet, and start any [`PlayOptions::deferred`]
    /// sounds queued until then. Idempotent. On the web this must run inside a user-gesture
    /// handler, otherwise the browser keeps the `AudioContext` muted.
    pub fn start(&mut self) -> Result<()> {
        if self.manager.is_some() {
            return Ok(());
        }
        #[cfg_attr(not(target_arch = "wasm32"), allow(unused_mut))]
        let mut settings = AudioManagerSettings::<Backend>::default();
        #[cfg(target_arch = "wasm32")]
        {
            settings.backend_settings = self.detach.clone();
        }
        let mut kira = AudioManager::<Backend>::new(settings)
            .map_err(|e| anyhow!("kira AudioManager init: {e}"))?;
        kira.main_track()
            .set_volume(self.master_volume, Tween::default());
        let mut bus = kira
            .add_sub_track(TrackBuilder::new())
            .map_err(|e| anyhow!("kira bus track: {e}"))?;
        if self.suspended {
            bus.pause(Tween::default());
        }
        self.manager = Some(Manager { kira, bus });
        for (data, handle) in std::mem::take(&mut self.queued) {
            self.start_queued(data, &handle);
        }
        for data in std::mem::take(&mut self.queued_streams) {
            if !data.handle().is_finished() {
                self.start_stream(data);
            }
        }
        #[cfg(feature = "synth")]
        for prepared in std::mem::take(&mut self.queued_synths) {
            if !prepared.handle().is_finished() {
                self.start_synth(prepared);
            }
        }
        Ok(())
    }

    fn start_queued(&mut self, data: StaticSoundData, handle: &SoundHandle) {
        let mut slot = handle.lock();
        let Slot::Pending { volume, paused } = &*slot else {
            return; // stopped while queued
        };
        let (volume, paused) = (*volume, *paused);
        // An instant volume change replaces the start volume; a fade starts from it once
        // the sound plays, over the duration that was asked for.
        let (data, fade) = match volume {
            Some((db, duration)) if duration.is_zero() => (data.volume(db), None),
            Some((db, duration)) => (data, Some((db, duration))),
            None => (data, None),
        };
        match self.play_now(data) {
            Ok(mut kira) => {
                if let Some((db, duration)) = fade {
                    kira.set_volume(db, handle::tween(duration));
                }
                if paused {
                    kira.pause(Tween::default());
                }
                *slot = Slot::Playing(kira);
            }
            Err(e) => {
                log::warn!("queued sound failed to start: {e}");
                *slot = Slot::Cancelled;
            }
        }
    }

    /// Whether the output device is open, i.e. [`Audio::play`] can produce sound. Always
    /// `true` natively; on the web, `false` until the first user gesture.
    pub fn is_started(&self) -> bool {
        self.manager.is_some()
    }

    /// Load a sound file from disk. Not available on the web; use [`Audio::load_sound_bytes`].
    #[cfg(not(target_arch = "wasm32"))]
    pub fn load_sound(&mut self, path: impl AsRef<Path>) -> Result<SoundId> {
        let data = StaticSoundData::from_file(path.as_ref())
            .map_err(|e| anyhow!("kira load {}: {e}", path.as_ref().display()))?;
        Ok(self.insert(data))
    }

    /// Decode an encoded sound file (wav, ogg, flac, mp3) held in memory.
    pub fn load_sound_bytes(&mut self, bytes: impl Into<Vec<u8>>) -> Result<SoundId> {
        let data = StaticSoundData::from_cursor(std::io::Cursor::new(bytes.into()))
            .map_err(|e| anyhow!("kira decode: {e}"))?;
        Ok(self.insert(data))
    }

    fn insert(&mut self, data: StaticSoundData) -> SoundId {
        let id = SoundId(self.next_id);
        self.next_id += 1;
        self.sounds.insert(id, data);
        id
    }

    /// Play a loaded sound once, at its own volume. The returned [`SoundHandle`] controls this
    /// instance (volume, pause, stop, `is_playing`); dropping it lets the sound play out.
    ///
    /// Fails with [`AudioError::NotStarted`] on the web until the player's first key press,
    /// click or touch (check [`Audio::is_started`]), so don't `?` it in `update`. For music
    /// that should start as soon as it can, use [`Audio::play_with`] and
    /// [`PlayOptions::deferred`].
    pub fn play(&mut self, id: SoundId) -> Result<SoundHandle, AudioError> {
        self.play_with(id, PlayOptions::default())
    }

    /// Play a loaded sound with [`PlayOptions`]: looping, a start volume, and whether to
    /// queue it until audio starts.
    pub fn play_with(
        &mut self,
        id: SoundId,
        options: PlayOptions,
    ) -> Result<SoundHandle, AudioError> {
        let data = self
            .sounds
            .get(&id)
            .ok_or(AudioError::UnknownSound(id))?
            .clone();
        self.play_data(data, options)
    }

    /// Play mono PCM samples (`-1.0..=1.0`) directly, e.g. a buffer rendered by
    /// [`Synth`]. The samples are duplicated to both channels. Fails like [`Audio::play`]
    /// before audio has started.
    pub fn play_samples(
        &mut self,
        samples: &[f32],
        sample_rate: u32,
    ) -> Result<SoundHandle, AudioError> {
        self.play_samples_with(samples, sample_rate, PlayOptions::default())
    }

    /// [`Audio::play_samples`] with [`PlayOptions`].
    pub fn play_samples_with(
        &mut self,
        samples: &[f32],
        sample_rate: u32,
        options: PlayOptions,
    ) -> Result<SoundHandle, AudioError> {
        let frames: Arc<[Frame]> = samples
            .iter()
            .map(|&s| Frame { left: s, right: s })
            .collect();
        let data = StaticSoundData {
            sample_rate,
            frames,
            settings: StaticSoundSettings::default(),
            slice: None,
        };
        self.play_data(data, options)
    }

    fn play_data(
        &mut self,
        data: StaticSoundData,
        options: PlayOptions,
    ) -> Result<SoundHandle, AudioError> {
        let mut data = data.volume(amplitude_to_db(options.volume));
        if options.looped {
            data = data.loop_region(..);
        }
        if self.manager.is_none() && options.deferred {
            let handle = SoundHandle::pending();
            self.queued.push((data, handle.clone()));
            return Ok(handle);
        }
        self.play_now(data).map(SoundHandle::playing)
    }

    fn play_now(
        &mut self,
        data: StaticSoundData,
    ) -> Result<kira::sound::static_sound::StaticSoundHandle, AudioError> {
        self.manager
            .as_mut()
            .ok_or(AudioError::NotStarted)?
            .bus
            .play(data)
            .map_err(|e| AudioError::Backend(e.to_string()))
    }

    /// Play audio generated while it plays, such as a synthesizer or an emulated sound
    /// chip: `stream` is asked for mono samples at `sample_rate` as the mixer needs them,
    /// on the audio thread, and resampled to the output rate. It plays until stopped
    /// through the returned handle. Fails like [`Audio::play`] before audio has started.
    pub fn play_stream(
        &mut self,
        stream: impl AudioStream,
        sample_rate: u32,
    ) -> Result<StreamHandle, AudioError> {
        self.play_stream_with(stream, sample_rate, PlayOptions::default())
    }

    /// [`Audio::play_stream`] with [`PlayOptions`]. `volume` and `deferred` apply;
    /// `looped` has no meaning for a stream, which runs until stopped.
    pub fn play_stream_with(
        &mut self,
        stream: impl AudioStream,
        sample_rate: u32,
        options: PlayOptions,
    ) -> Result<StreamHandle, AudioError> {
        self.start_or_queue(Source::mono(Box::new(stream)), sample_rate, options)
    }

    /// Like [`Audio::play_stream`], for a stereo source: `stream` fills `[left, right]` frames.
    pub fn play_stereo_stream(
        &mut self,
        stream: impl StereoStream,
        sample_rate: u32,
    ) -> Result<StreamHandle, AudioError> {
        self.play_stereo_stream_with(stream, sample_rate, PlayOptions::default())
    }

    /// [`Audio::play_stereo_stream`] with [`PlayOptions`], as for [`Audio::play_stream_with`].
    pub fn play_stereo_stream_with(
        &mut self,
        stream: impl StereoStream,
        sample_rate: u32,
        options: PlayOptions,
    ) -> Result<StreamHandle, AudioError> {
        self.start_or_queue(Source::Stereo(Box::new(stream)), sample_rate, options)
    }

    fn start_or_queue(
        &mut self,
        source: Source,
        sample_rate: u32,
        options: PlayOptions,
    ) -> Result<StreamHandle, AudioError> {
        let pending = self.manager.is_none();
        if pending && !options.deferred {
            return Err(AudioError::NotStarted);
        }
        let (data, handle) = StreamData::new(source, sample_rate, options.volume, pending);
        if pending {
            self.queued_streams.push(data);
        } else {
            self.start_stream(data);
        }
        Ok(handle)
    }

    fn start_stream(&mut self, data: StreamData) {
        let handle = data.handle().clone();
        let Some(manager) = self.manager.as_mut() else {
            return;
        };
        match manager.bus.play(data) {
            Ok(()) => handle.mark_started(),
            Err(e) => {
                log::warn!("stream failed to start: {e}");
                handle.stop();
            }
        }
    }

    /// Play a [`synth::Song`] live on the synth, for music: the song is sequenced
    /// sample-accurately on the audio thread, so tempo and drums stay tight whatever the
    /// frame rate. The returned [`SynthHandle`] controls volume (ducking), pause and stop, and
    /// sends live [`synth::AudioEvent`]s.
    ///
    /// [`PlayOptions`] apply as for other sounds: [`PlayOptions::looped`] loops the song,
    /// otherwise it plays once (whatever the song's own [`synth::Song::looped`] says), and
    /// `volume` and `deferred` work as usual. A song that plays once ends by itself
    /// after its release and effect tails ([`SynthHandle::is_finished`] turns `true`); a
    /// looping one plays until stopped. Dropping the last handle stops the synth either way.
    /// Fails like [`Audio::play`] before audio has started.
    ///
    /// ```no_run
    /// # use game_toolkit_audio::{Audio, PlayOptions};
    /// use game_toolkit_audio::synth::{ChannelNo, DrumHit, Preset, Song, Tempo};
    /// # fn demo(audio: &mut Audio) -> anyhow::Result<()> {
    /// let song = Song::new(Tempo::bpm(140.0, 4))
    ///     .patch(Preset::C64Bass.params())
    ///     .lane(ChannelNo(0), "E2@0 . E3 . E2 . E3 . G2 . G3 . A2 . A3 -")?
    ///     .lane(ChannelNo(3), "k h s h k h s h k h s h k k s o")?;
    /// let music = audio.play_synth(song, PlayOptions::looped().volume(0.4).deferred())?;
    /// let _ = music.drum(DrumHit::Crash); // a live hit on a game event
    /// music.fade_volume(0.1, std::time::Duration::from_millis(300)); // duck
    /// # Ok(()) }
    /// ```
    #[cfg(feature = "synth")]
    pub fn play_synth(
        &mut self,
        mut song: synth::Song,
        options: PlayOptions,
    ) -> Result<SynthHandle, AudioError> {
        song.looped = options.looped;
        let data =
            synthie::kira::SynthSoundData::new().with_sequencer(synth::SongPlayer::new(song));
        self.play_synth_sound(data, options)
    }

    /// [`Audio::play_synth`] for a synth set up by hand: start patches per channel, a custom
    /// [`synthie::prelude::Sequencer`] instead of a song, another channel count, or none at
    /// all to play it only from [`SynthHandle`] events. `options.looped` has no meaning here;
    /// the sequencer decides.
    #[cfg(feature = "synth")]
    pub fn play_synth_sound<S, const N: usize>(
        &mut self,
        data: synthie::kira::SynthSoundData<S, N>,
        options: PlayOptions,
    ) -> Result<SynthHandle, AudioError>
    where
        S: synthie::prelude::Sequencer + Send + 'static,
    {
        let pending = self.manager.is_none();
        if pending && !options.deferred {
            return Err(AudioError::NotStarted);
        }
        let data = data.with_volume(amplitude_to_db(options.volume));
        let prepared = PreparedSynth::new(data, pending);
        let handle = prepared.handle().clone();
        if pending {
            self.queued_synths.push(prepared);
        } else {
            self.start_synth(prepared);
        }
        Ok(handle)
    }

    #[cfg(feature = "synth")]
    fn start_synth(&mut self, prepared: PreparedSynth) {
        let handle = prepared.handle().clone();
        let Some(manager) = self.manager.as_mut() else {
            return;
        };
        match manager.bus.play(prepared) {
            Ok(()) => handle.mark_started(),
            Err(e) => {
                log::warn!("synth failed to start: {e}");
                handle.stop();
            }
        }
    }

    /// Master volume on the default main track, as a linear amplitude
    /// (`1.0` is unity gain, `0.0` is silence). Converted to decibels for kira.
    pub fn set_master_volume(&mut self, volume: f32) {
        self.master_volume = amplitude_to_db(volume);
        if let Some(manager) = self.manager.as_mut() {
            manager
                .kira
                .main_track()
                .set_volume(self.master_volume, Tween::default());
        }
    }

    /// Pause everything that's playing (sounds, streams, synths) until [`Audio::resume`],
    /// e.g. for a pause menu or when the host page hides the game. Sounds started while
    /// suspended wait too. Works before audio has started: it then starts suspended.
    ///
    /// Independent of the per-sound [`SoundHandle::pause`], and of the toolkit suspending the
    /// web output while the canvas is detached from the page (`DetachHandle`, web only):
    /// reattaching the canvas doesn't undo a suspend.
    pub fn suspend(&mut self) {
        self.set_suspended(true);
    }

    /// Undo [`Audio::suspend`]: everything it paused continues where it left off.
    pub fn resume(&mut self) {
        self.set_suspended(false);
    }

    /// Whether [`Audio::suspend`] is in effect.
    pub fn is_suspended(&self) -> bool {
        self.suspended
    }

    fn set_suspended(&mut self, suspended: bool) {
        if self.suspended == suspended {
            return;
        }
        self.suspended = suspended;
        if let Some(manager) = self.manager.as_mut() {
            if suspended {
                manager.bus.pause(Tween::default());
            } else {
                manager.bus.resume(Tween::default());
            }
        }
    }

    /// Web only: the handle that suspends the output while the game's canvas is detached
    /// from the page. The toolkit's core drives it; see [`DetachHandle`].
    #[cfg(target_arch = "wasm32")]
    pub fn detach_handle(&self) -> DetachHandle {
        self.detach.clone()
    }
}

/// Linear amplitude (`1.0` unity, `0.0` silence) to kira's decibels.
pub(crate) fn amplitude_to_db(volume: f32) -> Decibels {
    if volume <= 0.0 {
        Decibels::SILENCE
    } else {
        Decibels::from(20.0 * volume.log10())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn amplitude_to_db_maps_unity_and_silence() {
        assert_eq!(amplitude_to_db(1.0), Decibels::IDENTITY);
        assert_eq!(amplitude_to_db(0.0), Decibels::SILENCE);
        assert!((amplitude_to_db(0.5).0 + 6.02).abs() < 0.01);
    }

    #[test]
    fn play_options_builders() {
        let o = PlayOptions::looped().volume(0.25).deferred();
        assert!(o.looped && o.deferred);
        assert_eq!(o.volume, 0.25);
        assert_eq!(PlayOptions::default().volume, 1.0);
    }

    #[test]
    fn suspend_before_start_is_remembered() {
        let mut audio = Audio {
            manager: None,
            suspended: false,
            #[cfg(target_arch = "wasm32")]
            detach: DetachHandle::default(),
            sounds: HashMap::new(),
            next_id: 1,
            master_volume: Decibels::IDENTITY,
            queued: Vec::new(),
            queued_streams: Vec::new(),
            #[cfg(feature = "synth")]
            queued_synths: Vec::new(),
        };
        assert!(!audio.is_suspended());
        audio.suspend();
        audio.suspend();
        assert!(audio.is_suspended());
        audio.resume();
        assert!(!audio.is_suspended());
    }
}