xuko_audio/

lib.rs

//! Small wrapper around [`rodio`] for use with [xuko-ecs](https://crates.io/crates/xuko-ecs)

use xuko_core::bytes::Bytes;

pub use std::time::Duration;

pub(crate) fn decode<B: AsRef<[u8]>>(buffer: B) -> Result<impl rodio::Source, AudioError> {
    let cursor = std::io::BufReader::new(std::io::Cursor::new(buffer.as_ref().to_vec()));
    let source = rodio::Decoder::try_from(cursor)?;
    Ok(source)
}

/// An error that can occur when using [`AudioPlayer`] or [`AudioSink`]
#[derive(Debug, thiserror::Error)]
pub enum AudioError {
    /// I/O Error.
    #[error("IO Error: {0}")]
    IOError(#[from] std::io::Error),

    /// Error that occurs when opening a stream.
    #[error("Stream error: {0}")]
    StreamError(#[from] rodio::StreamError),

    /// Error that occurs when decoding a sound buffer.
    #[error("Decoder error: {0}")]
    DecoderError(#[from] rodio::decoder::DecoderError),

    /// Error that occurs when playing a sound.
    #[error("Play error: {0}")]
    PlayError(#[from] rodio::PlayError),

    /// Error that occurs when setting the position of the sink.
    #[error("Seek error: {0}")]
    SeekError(#[from] rodio::source::SeekError),
}

/// Structure to construct [`AudioSink`]s
pub struct AudioPlayer {
    buffer: Bytes,
}

impl AudioPlayer {
    /// Create an [`AudioPlayer`] from a buffer
    pub fn new<B: AsRef<[u8]>>(buffer: B) -> Self {
        Self {
            buffer: Bytes::from(buffer),
        }
    }

    /// Create the [`AudioSink`], this can be called multiple times to reuse the audio buffer
    pub fn spawn(&self, settings: PlaybackSettings) -> Result<AudioSink, AudioError> {
        AudioSink::new(&self.buffer, settings)
    }
}

/// Audio stream
pub struct AudioSink {
    sink: rodio::Sink,
    _stream_handle: rodio::OutputStream,
}

impl AudioSink {
    pub(crate) fn new(buffer: &[u8], settings: PlaybackSettings) -> Result<Self, AudioError> {
        let mut stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
        stream_handle.log_on_drop(false);

        let sink = rodio::Sink::connect_new(stream_handle.mixer());
        sink.append(decode(buffer.to_vec())?);
        sink.pause();
        let _ = sink.try_seek(Duration::new(0, 0));

        let s = Self {
            sink,
            _stream_handle: stream_handle,
        };
        settings.apply(&s);

        Ok(s)
    }

    /// Append a stream to the [`AudioSink`]
    pub fn add(&mut self, buffer: &[u8]) -> Result<(), AudioError> {
        self.sink.append(decode(buffer.to_vec())?);
        Ok(())
    }

    /// Seek to `pos` in the audio stream
    pub fn seek(&self, pos: Duration) -> Result<(), AudioError> {
        self.sink.try_seek(pos).map_err(AudioError::SeekError)
    }

    /// Get the position the audio stream is at
    pub fn get_pos(&self) -> Duration {
        self.sink.get_pos()
    }

    /// Plays the audio stream, no effect if it is already playing
    pub fn play(&self) {
        self.sink.play();
    }

    /// Pauses the audio stream, no effect if it is already paused
    pub fn pause(&self) {
        self.sink.pause();
    }

    /// Returns whether the audio stream is paused or not
    pub fn is_paused(&self) -> bool {
        self.sink.is_paused()
    }

    /// Toggle between playing and paused
    pub fn pause_play(&self) {
        if self.sink.is_paused() {
            self.sink.play();
        } else {
            self.sink.pause();
        }
    }

    /// Blocks the current thread until the sound finishes
    pub fn sleep_until_end(&self) {
        self.sink.sleep_until_end();
    }

    /// Get the volume of the audio stream, in decibels
    pub fn volume(&self) -> f32 {
        Volume::linear_to_decibels(self.sink.volume())
    }

    /// Set the volume of the audio stream to `value`, returns the previous volume
    pub fn set_volume(&self, value: Volume) -> f32 {
        let previous = self.volume();
        self.sink.set_volume(value.to_linear());
        previous
    }

    /// Get the speed of the audio stream
    pub fn speed(&self) -> f32 {
        self.sink.speed()
    }

    /// Set the speed of the audio stream to `value`, returns the previous speed
    pub fn set_speed(&self, value: f32) -> f32 {
        let previous = self.speed();
        self.sink.set_speed(value);
        previous
    }

    /// Stops all audio playback
    pub fn stop(&self) {
        self.sink.stop();
    }
}

/// Volume for [`AudioSink`]
#[derive(Default, Clone, Copy, PartialEq, PartialOrd)]
pub enum Volume {
    #[default]
    /// Muted volume
    Muted,
    /// The volume in decibels
    Decibels(f32),
}

impl Volume {
    /// Convert linear volume to decibels volume
    pub fn linear_to_decibels(x: f32) -> f32 {
        20.0 * x.abs().log10()
    }

    /// Convert decibels volume to linear volume
    pub fn decibels_to_linear(x: f32) -> f32 {
        10.0f32.powf(x / 20.0)
    }

    /// Convert this [`Volume`] to linear
    pub fn to_linear(&self) -> f32 {
        match self {
            Self::Muted => Self::decibels_to_linear(f32::NEG_INFINITY),
            Self::Decibels(d) => Self::decibels_to_linear(*d),
        }
    }
}

/// Options for creating a [`AudioSink`]
#[derive(Clone, Copy)]
pub struct PlaybackSettings {
    /// Volume of the [`AudioSink`]
    pub volume: Volume,
    /// Speed of the [`AudioSink`]
    pub speed: f32,
}

impl PlaybackSettings {
    /// Apply the [`PlaybackSettings`] on a [`AudioSink`]
    pub fn apply(&self, sink: &AudioSink) {
        sink.set_volume(self.volume);
        sink.set_speed(self.speed);
    }
}

impl Default for PlaybackSettings {
    fn default() -> Self {
        Self {
            volume: Volume::Decibels(0.0),
            speed: 1.0,
        }
    }
}