audio

Kind	ffi-c
Categories	multimedia audio
Keywords	audio sound music playback recording miniaudio

Cross-platform audio playback and recording for Kit using miniaudio

Files

File	Description
`kit.toml`	Package manifest with metadata and dependencies
`src/audio.kit`	Playback, recording, waveforms, noise, and 3D audio
`tests/audio.test.kit`	Tests for error types, constants, and note frequencies
`examples/basic.kit`	Load and play sounds with generated tone fallback
`examples/music.kit`	Music player with volume, pitch, pan, and seek
`examples/spatial.kit`	3D spatial audio with panning and distance
`examples/synthesis.kit`	Generate waveforms, noise, and play melodies
`LICENSE`	MIT license file

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-audio.git

Usage

import Kit.Audio

License

MIT License - see LICENSE for details.

Exported Functions & Types

`AudioError`

Audio error type with specific variants for different failure modes.

Variants

AudioInitError {message}

AudioLoadError {message}

AudioCreateError {message}

`waveform-sine`

Waveform type: sine wave

Produces a smooth, pure tone with a single frequency component. Mathematically defined as $y(t) = A \sin(2\pi f t)$ where $A$ is amplitude and $f$ is frequency.

`waveform-square`

Waveform type: square wave

Produces a harsh tone alternating between maximum and minimum values. Contains odd harmonics: $y(t) = \frac{4A}{\pi}\sum_{k=1,3,5...}^{\infty}\frac{\sin(2\pi kft)}{k}$

`waveform-triangle`

Waveform type: triangle wave

Produces a softer tone than square wave with linearly ramping values. Contains odd harmonics with faster decay: $y(t) = \frac{8A}{\pi^2}\sum_{k=1,3,5...}^{\infty}\frac{(-1)^{(k-1)/2}\sin(2\pi kft)}{k^2}$

`waveform-sawtooth`

Waveform type: sawtooth wave

Produces a bright, buzzy tone with a linear ramp from minimum to maximum. Contains all harmonics: $y(t) = \frac{2A}{\pi}\sum_{k=1}^{\infty}\frac{(-1)^{k+1}\sin(2\pi kft)}{k}$

`noise-white`

Noise type: white noise

Produces random noise with equal energy across all frequencies. Each sample is independent with uniform spectral density.

`noise-pink`

Noise type: pink noise

Produces noise with equal energy per octave (1/f spectrum). Sounds less harsh than white noise, more natural. Power spectral density decreases by 3 dB per octave.

`noise-brownian`

Noise type: brownian noise (red noise)

Produces noise with power spectral density decreasing by 6 dB per octave. Lower frequencies dominate, creating a softer, deeper sound than pink noise.

`init`

init

Initialize the audio engine.

This must be called before any other audio operations. The engine manages the audio device, mixer, and all audio resources.

Returns: AudioResult {ptr: Ptr} - Ok with engine handle on success,Err with message on failure

() -> Result {ptr: Ptr} AudioError

match init()
  | Ok engine ->
    # Use engine for audio operations
    shutdown engine
  | Err err ->
    print "Failed to initialize: ${err}"

`shutdown`

shutdown

Shutdown the audio engine and release all resources.

This stops all playing sounds and frees the audio device. Should be called when audio is no longer needed.

Parameters:

- engine - Engine handle returned from init()

{ptr: Ptr} -> Unit

match init()
  | Ok engine ->
    # ... use engine ...
    shutdown engine
  | Err err -> print err

`get-volume`

get-volume

Get the master volume level.

Parameters:

- engine - Engine handle

Returns: Float - Master volume (0.0 = silent, 1.0 = normal, >1.0 = amplified)

{ptr: Ptr} -> Float

`set-volume`

set-volume

Set the master volume level.

Affects all sounds playing through this engine. Values above 1.0 will amplify the audio signal but may cause clipping.

Parameters:

- engine - Engine handle
- volume - Float - Volume level (0.0 = silent, 1.0 = normal, >1.0 = amplified)

{ptr: Ptr} -> Float -> Unit

set-volume engine 0.5  # Half volume
set-volume engine 1.5  # 50% amplification

`get-sample-rate`

get-sample-rate

Get the audio engine's sample rate in Hz.

Common sample rates are 44100 Hz (CD quality) and 48000 Hz (professional audio).

Parameters:

- engine - Engine handle

Returns: Int - Sample rate in Hz (e.g., 44100, 48000)

{ptr: Ptr} -> Int

`get-channels`

get-channels

Get the number of audio channels.

Parameters:

- engine - Engine handle

Returns: Int - Number of channels (1 = mono, 2 = stereo)

{ptr: Ptr} -> Int

`load`

load

Load a sound file into memory for low-latency playback.

The entire file is decoded immediately. Best for short sounds like effects, UI sounds, and samples that need instant playback. For large files like music, use load-stream instead.

Supported formats: WAV, MP3, FLAC, OGG Vorbis

Parameters:

- engine - Engine handle
- path - String - File path to audio file

Returns: AudioResult {ptr: Ptr} - Ok with sound handle on success,Err with message on failure

{ptr: Ptr} -> String -> Result {ptr: Ptr} AudioError

match load engine "explosion.wav"
  | Ok sound ->
    play sound
    free sound
  | Err err ->
    print "Load failed: ${err}"

`load-stream`

load-stream

Load a sound file for streaming playback.

Audio is decoded on-the-fly during playback, reducing memory usage. Ideal for large files like background music and long recordings. Has slightly higher CPU usage than pre-decoded sounds.

Supported formats: WAV, MP3, FLAC, OGG Vorbis

Parameters:

- engine - Engine handle
- path - String - File path to audio file

Returns: AudioResult {ptr: Ptr} - Ok with sound handle on success,Err with message on failure

{ptr: Ptr} -> String -> Result {ptr: Ptr} AudioError

match load-stream engine "music.mp3"
  | Ok music ->
    set-looping music true
    play music
  | Err err ->
    print "Load failed: ${err}"

`free`

free

Free a sound and release its resources.

The sound is stopped if currently playing. The handle becomes invalid and should not be used after this call.

Parameters:

- sound - Sound handle returned from load() or load-stream()

{ptr: Ptr} -> Unit

`play`

play

Start playing a sound.

If the sound is already playing, it continues from current position. Use stop() first to restart from the beginning.

Parameters:

- sound - Sound handle

Returns: Unit

{ptr: Ptr} -> Unit

`stop`

stop

Stop a playing sound and reset to beginning.

Parameters:

- sound - Sound handle

Returns: Unit

{ptr: Ptr} -> Unit

`is-playing?`

is-playing?

Check if a sound is currently playing.

Parameters:

- sound - Sound handle

Returns: Bool - true if sound is playing, false otherwise

{ptr: Ptr} -> Bool

`sound-volume`

sound-volume

Get the volume of a specific sound.

This is independent of the master volume set on the engine. Final output volume is: master_volume × sound_volume.

Parameters:

- sound - Sound handle

Returns: Float - Volume level (0.0 = silent, 1.0 = normal, >1.0 = amplified)

{ptr: Ptr} -> Float

`set-sound-volume`

set-sound-volume

Set the volume of a specific sound.

This is independent of the master volume. Values above 1.0 will amplify the sound but may cause clipping.

Parameters:

- sound - Sound handle
- volume - Float - Volume level (0.0 = silent, 1.0 = normal, >1.0 = amplified)

{ptr: Ptr} -> Float -> Unit

set-sound-volume footstep 0.3  # Quiet footsteps
set-sound-volume explosion 1.5  # Loud explosion

`pitch`

pitch

Get the pitch/playback speed of a sound.

Parameters:

- sound - Sound handle

Returns: Float - Pitch multiplier (1.0 = normal, 2.0 = octave up, 0.5 = octave down)

{ptr: Ptr} -> Float

`set-pitch`

set-pitch

Set the pitch/playback speed of a sound.

Affects both frequency and duration. A pitch of 2.0 plays at double speed and one octave higher. A pitch of 0.5 plays at half speed and one octave lower. For musical intervals, use $2^{n/12}$ where n is semitones (e.g., 1.059463 for one semitone up).

Parameters:

- sound - Sound handle
- pitch - Float - Pitch multiplier (1.0 = normal, 2.0 = octave up, 0.5 = octave down)

{ptr: Ptr} -> Float -> Unit

set-pitch sound 1.0     # Normal speed
set-pitch sound 2.0     # Double speed, octave up
set-pitch sound 0.5     # Half speed, octave down
set-pitch sound 1.05946 # One semitone up

`pan`

pan

Get the stereo panning position of a sound.

Parameters:

- sound - Sound handle

Returns: Float - Pan position (-1.0 = full left, 0.0 = center, 1.0 = full right)

{ptr: Ptr} -> Float

`set-pan`

set-pan

Set the stereo panning position of a sound.

Only affects stereo output. For mono output, pan is ignored.

Parameters:

- sound - Sound handle
- pan - Float - Pan position (-1.0 = full left, 0.0 = center, 1.0 = full right)

{ptr: Ptr} -> Float -> Unit

set-pan sound -1.0  # Full left
set-pan sound 0.0   # Center
set-pan sound 1.0   # Full right
set-pan sound 0.5   # Slight right

`is-looping?`

is-looping?

Check if a sound is set to loop.

Parameters:

- sound - Sound handle

Returns: Bool - true if sound loops, false otherwise

{ptr: Ptr} -> Bool

`set-looping`

set-looping

Enable or disable looping for a sound.

When looping is enabled, the sound automatically restarts from the beginning when it reaches the end.

Parameters:

- sound - Sound handle
- looping - Bool - true to enable looping, false to disable

{ptr: Ptr} -> Bool -> Unit

set-looping background-music true  # Loop forever
set-looping sound-effect false     # Play once

`seek`

seek

Jump to a specific position in the sound.

Parameters:

- sound - Sound handle
- seconds - Float - Position in seconds from the start

{ptr: Ptr} -> Float -> Unit

seek sound 0.0   # Jump to beginning
seek sound 30.0  # Jump to 30 seconds
seek sound (length sound - 5.0)  # Jump to 5 seconds before end

`length`

length

Get the total duration of a sound in seconds.

Parameters:

- sound - Sound handle

Returns: Float - Duration in seconds

{ptr: Ptr} -> Float

`position`

position

Get the current playback position in seconds.

Parameters:

- sound - Sound handle

Returns: Float - Current position in seconds from the start

{ptr: Ptr} -> Float

`at-end?`

at-end?

Check if a sound has finished playing.

Returns true when playback reaches the end of a non-looping sound. Always returns false for looping sounds.

Parameters:

- sound - Sound handle

Returns: Bool - true if sound has finished, false otherwise

{ptr: Ptr} -> Bool

`play-oneshot`

Play a sound file immediately (fire and forget).

{ptr: Ptr} -> String -> Unit