Lily Audio API

Sound effects and music playback with ADSR support.

Voice-based synth with 8 stereo voices and per-sound ADSR settings. The mixer renders signed 16-bit stereo at 44.1 kHz and resamples to the active output device when needed.

Structs

`SoundTag`

struct SoundTag {
}

Number of concurrent hardware/software voices. Voice index in the range 0..VOICE_COUNT-1. MIDI note number.

Valid range: 0..127.

Standards and references:

MIDI tuning standard MIDI

`Adsr`

struct Adsr {

Attack time in milliseconds.

    attack: Int

Decay time in milliseconds.

    decay: Int

Release time in milliseconds.

    release: Int

Sustain level in the normalized range 0.0..1.0.

    sustain: Float
}

`SoundDefinition`

struct SoundDefinition {
    adsr: Adsr
    gate_duration: Int
    root_note: Note
}

Per-resource playback definition.

adsr: Envelope used when the voice is triggered.
root_note: Natural pitch of the source sample.
gate_duration: Optional auto-release time in milliseconds. 0 keeps the voice held until an explicit note_off.

Distinct Types

`Voice`

type Voice = Int

`Note`

type Note = Int

`SoundId`

type SoundId = Res<SoundTag>

Enums

`VoiceState`

enum VoiceState {

Voice is available and not currently assigned.

    Idle

Voice is actively playing (attack/decay/sustain stage).

    Playing

Playback is paused and can be resumed from the same position.

    Paused

Release phase is running until the voice becomes idle.

    Releasing
}

Loaded/registered sound resource handle.

Functions

`stream_ogg_vorbis`

fn stream_ogg_vorbis(
  id: Voice,
  note: Note,
  resource_id: SoundId,
  sound: SoundDefinition,
  volume: Float
)

Start streaming an OGG Vorbis resource on a voice.

id: Target voice index.
note: Playback note used for pitch transposition.
resource_id: Sound resource handle.
sound: ADSR + root note definition.
volume: Linear gain, expected range 0.0..1.0.

`load_ogg_vorbis_mono`

fn load_ogg_vorbis_mono(
  resource_id: SoundId,
  sound: SoundDefinition
)

Load a mono OGG Vorbis file into a static buffer. Mono content is duplicated to stereo.

`load_ogg_vorbis_stereo`

fn load_ogg_vorbis_stereo(
  resource_id: SoundId,
  sound: SoundDefinition
)

Load a stereo OGG Vorbis file into a static buffer.

`load_wav_mono`

fn load_wav_mono(resource_id: SoundId, sound: SoundDefinition)

Load a mono WAV file into a static buffer. Mono content is duplicated to stereo.

`load_wav_stereo`

fn load_wav_stereo(resource_id: SoundId, sound: SoundDefinition)

Load a stereo WAV file into a static buffer.

`trig`

fn trig(
  id: Voice,
  resource_id: SoundId,
  volume: Float
)

Trigger a sound at its root note.

Equivalent to note_on with sound.root_note.

`one_shot`

fn one_shot(
  id: Voice,
  resource_id: SoundId,
  volume: Float
)

Trigger a sound at its root note and rely on its gate duration for release.

`note_on`

fn note_on(
  id: Voice,
  note: Note,
  resource_id: SoundId,
  volume: Float
)

Start playback at a specific note. Pitch is transposed relative to sound.root_note.

`note_off`

fn note_off(id: Voice)

Release a voice into the ADSR release stage.

`stop`

fn stop(id: Voice)

Stop a voice immediately and mark it idle.

`pause`

fn pause(id: Voice)

Pause playback without releasing the voice.

`resume`

fn resume(id: Voice)

Resume a paused voice from its paused position.

`get_voice_state`

fn get_voice_state(id: Voice) -> VoiceState

Get the current state of a voice.

`get_playback_time`

fn get_playback_time(id: Voice) -> Float

Get current playback position in seconds.

Streaming: position within the stream.
Static buffers: elapsed playback time.

`get_playback_duration`

fn get_playback_duration(id: Voice) -> Float

Get total duration in seconds.

Streaming: total stream duration from metadata.
Static buffers: total buffer duration.

`get_playback_progress`

fn get_playback_progress(id: Voice) -> Float

Get normalized playback progress in the range 0.0..1.0.

Streaming: progress through stream.
Static buffers: progress through buffer.

`get_active_voice_count`

fn get_active_voice_count() -> Int

Get the number of active voices. Active = Playing, Paused, or Releasing.

`set_volume`

fn set_volume(id: Voice, volume: Float)

Change voice volume. 0.0 = silent, 1.0 = full scale.

`set_pan`

fn set_pan(id: Voice, pan: Float)

Set stereo pan position. -1.0 = left, 0.0 = center, 1.0 = right.

`set_playback_rate`

fn set_playback_rate(id: Voice, playback_rate: Float)

Change playback rate. 0.5 = half speed, 1.0 = normal, 2.0 = double speed.