🥮 mooncakes.io

    audio

    audio encoder for wav/ogg

    moonbit
    audio
    mixer
    wav
    ogg
    Download zip
    Author
    Version
    0.1.1
    License
    Apache-2.0
    Repository
    Last updated
    5 months ago
    Downloads
    2K

    #mizchi/audio-mpt

    WIP audio library for MoonBit.

    #Goal

    • Provide mixer/decoder/playback primitives for games
    • Keep API backend-agnostic for js/native/wasm

    #Package

    • mizchi/audio-mpt

    #Status

    • Boilerplate only
    • See TODO.md for the implementation plan

    AudioError

    source
    pub suberror AudioError {
      InvalidFormat(String)
      DecodeFailed(String)
    }

    Audio subsystem errors.
    impl Show for AudioError

    AssetCache

    source
    pub(all) struct AssetCache {
      entries : Map[String, CacheEntry]
      total_bytes : Int
      max_bytes : Int
      max_entries : Int
      access_counter : Int
    } derive(Show)

    LRU asset cache for audio buffers.

    AudioBackendHooks

    source
    pub(all) struct AudioBackendHooks {
      initialize : (Int, Int) -> Unit
      write : (FixedArray[Float], Int) -> Unit
      suspend : () -> Unit
      resume_playback : () -> Unit
      close : () -> Unit
      report_consumed : () -> Int
    }

    Backend hooks for platform-specific audio output.

    AudioBuffer

    source
    pub(all) struct AudioBuffer {
      channels : Int
      sample_rate : Int
      data : FixedArray[Float]
    } derive(Eq, Show)

    PCM audio buffer with interleaved sample data.

    AudioCommand

    source
    pub(all) enum AudioCommand {
      PlaySource(AudioSource, Float, Float, Bool)
      PauseVoice(VoiceId)
      ResumeVoice(VoiceId)
      StopVoice(VoiceId)
      SeekVoice(VoiceId, Int)
      SetVoiceGain(VoiceId, Float)
      SetVoicePan(VoiceId, Float)
      SetMasterGain(Float)
    } derive(Show)

    Commands for controlling the audio mixer from any thread.

    AudioRuntime

    source
    pub(all) struct AudioRuntime {
      mixer : Mixer
      output_buffer : FixedArray[Float]
      frames_per_tick : Int
      tick_count : Int
      initialized : Bool
      command_queue : CommandQueue
      latency_monitor : LatencyMonitor
    }

    High-level audio runtime that integrates the mixer with backend hooks.

    AudioSource

    source
    pub(all) enum AudioSource {
      Buffer(AudioBuffer)
      Stream(StreamingSource)
    } derive(Show)

    Audio source: either a complete buffer or a streaming source.

    BiquadState

    source
    pub(all) struct BiquadState {
      b0 : Float
      b1 : Float
      b2 : Float
      a1 : Float
      a2 : Float
      z1 : Float
      z2 : Float
    } derive(Show)

    Biquad filter state (Direct Form II Transposed).

    BitReader

    source
    type BitReader derive(Show)

    LSB-first bit reader for Vorbis bitstream parsing.

    CacheEntry

    source
    pub(all) struct CacheEntry {
      buffer : AudioBuffer
      policy : CachePolicy
      byte_size : Int
      last_access : Int
    } derive(Show)

    Single entry in the asset cache.

    CachePolicy

    source
    pub(all) enum CachePolicy {
      AlwaysCache
      Normal
      StreamPrefer
    } derive(Eq, Show)

    Cache eviction policy for audio assets.

    CommandQueue

    source
    pub(all) struct CommandQueue {
      commands : Array[AudioCommand]
      pending_ids : Array[VoiceId]
    }

    Queue of audio commands to be flushed on the mixer thread.

    DelayState

    source
    pub(all) struct DelayState {
      buffer : FixedArray[Float]
      write_pos : Int
      delay_samples : Int
      feedback : Float
      mix : Float
    } derive(Show)

    Delay effect state.

    EffectNode

    source
    pub(all) enum EffectNode {
      Lowpass(BiquadState)
      Highpass(BiquadState)
      Delay(DelayState)
    } derive(Show)

    Effect node in the processing chain.

    Envelope

    source
    pub(all) struct Envelope {
      config : EnvelopeConfig
      sample_rate : Int
      phase : EnvelopePhase
      level : Float
      phase_position : Int
      release_start_level : Float
    } derive(Show)

    ADSR envelope state machine.

    EnvelopeConfig

    source
    pub(all) struct EnvelopeConfig {
      attack : Float
      decay : Float
      sustain : Float
      release_time : Float
    } derive(Eq, Show)

    ADSR envelope configuration.

    EnvelopePhase

    source
    pub(all) enum EnvelopePhase {
      Attack
      Decay
      Sustain
      Release
      Done
    } derive(Eq, Show)

    Envelope phase in ADSR state machine.

    LatencyMonitor

    source
    pub(all) struct LatencyMonitor {
      frames_written : Int
      ticks_elapsed : Int
      drift_frames_val : Int
      underrun_count : Int
      max_drift : Int
    }

    Monitors audio latency and drift between producer and consumer.

    Mixer

    source
    pub(all) struct Mixer {
      voices : Array[Voice]
      master_gain : Float
      channels : Int
      sample_rate : Int
      resample_quality : ResampleQuality
      next_voice_id : Int
    }

    Multi-voice mixer with master gain.

    OggDemuxer

    source
    type OggDemuxer derive(Show)

    OGG container demuxer.

    OggPage

    source
    type OggPage derive(Show)

    OGG page header.

    PullCallback

    source
    pub(all) struct PullCallback((FixedArray[Float], Int) -> Int)

    Callback that pulls audio data into a buffer. Returns frames actually written.

    ResampleQuality

    source
    pub(all) enum ResampleQuality {
      Nearest
      Linear
      Cubic
    } derive(Eq, Show)

    Resampling quality presets.

    RingBuffer

    source
    pub(all) struct RingBuffer {
      data : FixedArray[Float]
      capacity : Int
      channels : Int
      write_pos : Int
      read_pos : Int
      frames_available : Int
    } derive(Show)

    Ring buffer for streaming audio data.

    StreamingSource

    source
    pub(all) struct StreamingSource {
      ring : RingBuffer
      pull : PullCallback
      channels : Int
      sample_rate : Int
      ended : Bool
      total_pulled : Int
    }

    Streaming audio source backed by a ring buffer.

    Voice

    source
    pub(all) struct Voice {
      id : VoiceId
      source : AudioSource
      position : Float
      gain : Float
      pan : Float
      state : VoiceState
      looping : Bool
      sample_rate : Int
      loop_start : Int
      loop_end : Int
      envelope : Envelope?
      effects : Array[EffectNode]
    } derive(Show)

    A single voice playing an audio source.

    VoiceId

    source
    pub(all) struct VoiceId(Int) derive(Compare, Eq, Hash, Show)

    Stable voice identifier.

    VoiceState

    source
    pub(all) enum VoiceState {
      Playing
      Paused
      Stopped
    } derive(Eq, Show)

    Voice playback state.

    VorbisCodebook

    source
    type VorbisCodebook derive(Show)

    A Vorbis codebook for Huffman decoding and VQ lookup.

    VorbisFloorConfig

    source
    type VorbisFloorConfig derive(Show)

    Vorbis floor type 1 configuration.

    VorbisInfo

    source
    type VorbisInfo derive(Show)

    Vorbis stream configuration parsed from headers.

    VorbisMapping

    source
    type VorbisMapping derive(Show)

    Vorbis channel mapping.

    VorbisMode

    source
    type VorbisMode derive(Show)

    Vorbis mode configuration.

    VorbisResidueConfig

    source
    type VorbisResidueConfig derive(Show)

    Vorbis residue configuration.

    add_voice

    source
    fn add_voice(mixer : Mixer, voice : Voice) -> VoiceId

    Add a voice to the mixer. Returns the voice ID.

    audio_tick

    source
    fn audio_tick(rt : AudioRuntime) -> Unit

    Run one game tick: flush commands, mix audio, write to backend, track latency.

    biquad_process

    source
    fn biquad_process(state : BiquadState, input : Float) -> Float

    Process one sample through a biquad filter (Direct Form II Transposed).

    cache_clear

    source
    fn cache_clear(cache : AssetCache) -> Unit

    Clear all entries from the cache.

    cache_evict

    source
    fn cache_evict(cache : AssetCache, key : String) -> Bool

    Evict a specific key from the cache. Returns true if found and removed.

    cache_get

    source
    fn cache_get(cache : AssetCache, key : String) -> AudioBuffer?

    Get a cached audio buffer by key. Returns None if not found.

    cache_put

    source
    fn cache_put(cache : AssetCache, key : String, buffer : AudioBuffer, policy? : CachePolicy) -> Unit

    Put an audio buffer into the cache. Evicts entries if needed.

    collect_stopped

    source
    fn collect_stopped(mixer : Mixer) -> Unit

    Remove stopped voices from the mixer.

    decode_ogg

    source
    fn decode_ogg(raw : Bytes) -> AudioBuffer raise AudioError

    Top-level OGG/Vorbis decode function. Decodes an OGG/Vorbis file from raw bytes into an AudioBuffer.

    decode_wav

    source
    fn decode_wav(raw : Bytes) -> AudioBuffer raise AudioError

    Decode a WAV file from raw bytes into an AudioBuffer. Supports PCM format (format=1), 8-bit and 16-bit.

    delay_process

    source
    fn delay_process(state : DelayState, input : Float) -> Float

    Process one sample through the delay effect. Ring buffer: write_pos always points to the oldest sample (delay_samples ago).

    drift_frames

    source
    fn drift_frames(monitor : LatencyMonitor) -> Int

    Get current drift in frames.

    drift_secs

    source
    fn drift_secs(monitor : LatencyMonitor, sample_rate : Int) -> Float

    Get current drift in seconds.

    duration_secs

    source
    fn duration_secs(buf : AudioBuffer) -> Float

    Duration of the buffer in seconds.

    effect_process

    source
    fn effect_process(node : EffectNode, sample : Float) -> Float

    Process one sample through an effect node.

    effects_chain_process

    source
    fn effects_chain_process(effects : Array[EffectNode], sample : Float) -> Float

    Process one sample through an entire effects chain.

    enqueue

    source
    fn enqueue(queue : CommandQueue, cmd : AudioCommand, mixer : Mixer) -> VoiceId?

    Enqueue a command. For PlaySource, returns the pre-allocated VoiceId.

    envelope_release

    source
    fn envelope_release(env : Envelope) -> Unit

    Trigger the release phase of the envelope.

    envelope_reset

    source
    fn envelope_reset(env : Envelope) -> Unit

    Reset the envelope to the beginning of the attack phase.

    envelope_tick

    source
    fn envelope_tick(env : Envelope) -> Float

    Advance envelope by one sample and return the current gain level.

    find_voice

    source
    fn find_voice(mixer : Mixer, id : VoiceId) -> Voice?

    Find a voice by its ID. Returns None if not found.

    flush_commands

    source
    fn flush_commands(queue : CommandQueue, mixer : Mixer) -> Unit

    Flush all commands to the mixer. Processes in FIFO order.

    frame_count

    source
    fn frame_count(buf : AudioBuffer) -> Int

    Number of frames in the buffer.

    get_audio_backend_hooks

    source
    fn get_audio_backend_hooks() -> AudioBackendHooks

    Get a reference to the current backend hooks.

    get_sample

    source
    fn get_sample(buf : AudioBuffer, frame : Int, channel : Int) -> Float

    Get sample value at (frame, channel). Interleaved layout.

    highpass_coefficients

    source
    fn highpass_coefficients(cutoff_hz : Float, sample_rate : Int, q? : Float) -> BiquadState

    Compute highpass biquad filter coefficients (RBJ Audio EQ Cookbook).

    lowpass_coefficients

    source
    fn lowpass_coefficients(cutoff_hz : Float, sample_rate : Int, q? : Float) -> BiquadState

    Compute lowpass biquad filter coefficients (RBJ Audio EQ Cookbook).

    new_asset_cache

    source
    fn new_asset_cache(max_bytes : Int, max_entries : Int) -> AssetCache

    Create a new asset cache with given limits.

    new_audio_buffer

    source
    fn new_audio_buffer(channels : Int, sample_rate : Int, frames : Int) -> AudioBuffer

    Create a new AudioBuffer with zeroed samples.

    new_audio_runtime

    source
    fn new_audio_runtime(sample_rate : Int, tps : Int) -> AudioRuntime

    Create a new audio runtime. sample_rate: output sample rate (e.g. 44100) tps: ticks per second (e.g. 60 for 60fps game loop)

    new_command_queue

    source
    fn new_command_queue() -> CommandQueue

    Create a new empty command queue.

    new_delay

    source
    fn new_delay(delay_ms : Float, sample_rate : Int, feedback? : Float, mix? : Float) -> DelayState

    Create a new delay effect.

    new_envelope

    source
    fn new_envelope(config : EnvelopeConfig, sample_rate : Int) -> Envelope

    Create a new ADSR envelope.

    new_latency_monitor

    source
    fn new_latency_monitor() -> LatencyMonitor

    Create a new latency monitor.

    new_mixer

    source
    fn new_mixer(sample_rate : Int, resample_quality? : ResampleQuality) -> Mixer

    Create a new stereo mixer at the given sample rate.

    new_ring_buffer

    source
    fn new_ring_buffer(capacity : Int, channels : Int) -> RingBuffer

    Create a new ring buffer with the given capacity in frames.

    new_streaming_source

    source
    fn new_streaming_source(pull : PullCallback, channels : Int, sample_rate : Int, buffer_frames? : Int) -> StreamingSource

    Create a new streaming audio source.

    new_voice

    source
    fn new_voice(mixer : Mixer, source : AudioSource, gain? : Float, pan? : Float, looping? : Bool, envelope? : Envelope?) -> Voice

    Create a new voice from an audio source.

    new_voice_from_buffer

    source
    fn new_voice_from_buffer(mixer : Mixer, buffer : AudioBuffer, gain? : Float, pan? : Float, looping? : Bool, envelope? : Envelope?) -> Voice

    Create a new voice from an AudioBuffer (convenience wrapper).

    new_voice_with_loop

    source
    fn new_voice_with_loop(mixer : Mixer, source : AudioSource, loop_start : Int, loop_end : Int, gain? : Float, pan? : Float, looping? : Bool) -> Voice

    Create a new voice with loop points from an audio source.

    pan_gains

    source
    fn pan_gains(pan : Float) -> (Float, Float)

    Compute constant-power pan gains for left and right channels. pan: -1.0 (full left) to 1.0 (full right), 0.0 = center.

    pause_voice

    source
    fn pause_voice(mixer : Mixer, id : VoiceId) -> Bool

    Pause a playing voice. Returns true if state changed.

    play_sound

    source
    fn play_sound(rt : AudioRuntime, buffer : AudioBuffer, gain? : Float, pan? : Float, looping? : Bool) -> VoiceId

    Play a sound buffer through the runtime. Returns voice ID.

    queue_length

    source
    fn queue_length(queue : CommandQueue) -> Int

    Number of pending commands.

    read_source_sample

    source
    fn read_source_sample(source : AudioSource, frame : Int, channel : Int) -> Float

    Read a sample from an audio source at the given frame and channel.

    reset_audio_backend_hooks

    source
    fn reset_audio_backend_hooks() -> Unit

    Reset hooks to no-op defaults.

    reset_latency_monitor

    source
    fn reset_latency_monitor(monitor : LatencyMonitor) -> Unit

    Reset all counters.

    resume_voice

    source
    fn resume_voice(mixer : Mixer, id : VoiceId) -> Bool

    Resume a paused voice. Returns true if state changed.

    ring_available

    source
    fn ring_available(rb : RingBuffer) -> Int

    Number of frames available for reading.

    ring_consume

    source
    fn ring_consume(rb : RingBuffer, frames : Int) -> Unit

    Consume (advance read_pos) the given number of frames.

    ring_free

    source
    fn ring_free(rb : RingBuffer) -> Int

    Number of frames of free space for writing.

    ring_peek

    source
    fn ring_peek(rb : RingBuffer, frame_offset : Int, channel : Int) -> Float

    Peek at a sample at the given frame offset from read_pos.

    ring_reset

    source
    fn ring_reset(rb : RingBuffer) -> Unit

    Reset the ring buffer to empty state.

    ring_write

    source
    fn ring_write(rb : RingBuffer, src : FixedArray[Float], frames : Int) -> Int

    Write frames into the ring buffer. Returns number of frames actually written.

    seek_voice

    source
    fn seek_voice(mixer : Mixer, id : VoiceId, frame : Int) -> Bool

    Seek a voice to a given frame position. Returns true if voice was found.

    set_audio_backend_hooks

    source
    fn set_audio_backend_hooks(hooks : AudioBackendHooks) -> Unit

    Set the audio backend hooks.

    set_sample

    source
    fn set_sample(buf : AudioBuffer, frame : Int, channel : Int, value : Float) -> Unit

    Set sample value at (frame, channel). Interleaved layout.

    source_channels

    source
    fn source_channels(source : AudioSource) -> Int

    Get the channel count of an audio source.

    source_frame_count

    source
    fn source_frame_count(source : AudioSource) -> Int

    Get the frame count of an audio source.

    source_sample_rate

    source
    fn source_sample_rate(source : AudioSource) -> Int

    Get the sample rate of an audio source.

    stop_voice

    source
    fn stop_voice(mixer : Mixer, id : VoiceId) -> Bool

    Stop a voice. Returns true if voice was found.

    streaming_available

    source
    fn streaming_available(source : StreamingSource) -> Int

    Number of frames available in the streaming source.

    streaming_fill

    source
    fn streaming_fill(source : StreamingSource, min_frames : Int) -> Unit

    Fill the streaming source's ring buffer until at least min_frames are available.

    tick

    source
    fn tick(mixer : Mixer, frames : Int, output : FixedArray[Float]) -> Unit

    Mix all playing voices into the output buffer for the given number of frames. Output is interleaved stereo (2 channels). Buffer must have length >= frames * 2.

    underrun_count

    source
    fn underrun_count(monitor : LatencyMonitor) -> Int

    Get underrun count.

    update_latency

    source
    fn update_latency(monitor : LatencyMonitor, frames_this_tick : Int, consumed : Int) -> Unit

    Update latency tracking after a tick. frames_this_tick: frames produced this tick. consumed: frames consumed by backend since last update.

    voice_position

    source
    fn voice_position(mixer : Mixer, id : VoiceId) -> Float?

    Get the current position of a voice in frames.

    voice_state

    source
    fn voice_state(mixer : Mixer, id : VoiceId) -> VoiceState?

    Get the current state of a voice.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io