Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Audio

The audio engine plays everything a game needs: continuous tones placed in 3D space, short blips and sound effects, sample files, a looping background track and a master effect chain. A separate FFT analyser turns sample data into frequency bands for audio-reactive visuals.

For whole songs, instrument patches, MIDI and the DAW, see Music. For the microphone, see Input and Microphone.

Things to know first:

  • The runtime opens the audio device when the program starts. With no output device, the audio_* builtins silently do nothing.
  • Times are in seconds. Arguments shown in a signature are optional from the point where a default is listed.
  • Audio is native only: in the browser build the FFT builtins do nothing and some calls take fewer arguments (noted below).
  • Because these examples make sound, they are ling-gui programs. The FFT example at the end runs anywhere.

Summary

Builtin中文日本語한국어ไทยPurpose
audio_volume(level)音量音量음량ระดับเสียงMaster volume
audio_bgm(path, volume)背景乐BGM배경음악เพลงประกอบLoop a WAV as background music
audio_bgm_volume(level)背景乐音量BGM音量배경음악음량ระดับเพลงประกอบBackground-music volume
audio_tone(slot, x, y, z, w, freq, amp, lfo_rate, lfo_depth, wave, duty)音调音調음조เสียงโทนContinuous positional oscillator
audio_glide(amp_ms, freq_ms)————Smoothing time for tone changes
audio_listener(cos_yaw, sin_yaw, cos_pitch, sin_pitch)音频监听音声リスナー오디오리스너ผู้ฟังListener orientation
audio_blip(freq, duration, wave, amp)提示音ビープ音효과음เสียงบี๊บShort interface blip
ui_sound(name)界面音UI音인터페이스음เสียงปุ่มBuilt-in interface sound
audio_sfx(x, y, z, w, freq, amp, duration, wave)音效空間効果音공간효과음เสียงเอฟเฟกต์Positional one-shot effect
morph_note(x, y, z, w, freq, amp, duration, material, morph)变形音モーフ音모프음โน้ตมอร์ฟPhysical/digital morph note
audio_stop_sfx()停止音效効果音停止효과음정지หยุดเอฟเฟกต์ทั้งหมดStop all one-shot voices
audio_sample_load(path)载入采样サンプル読込샘플로드โหลดตัวอย่างเสียงDecode a sound file
audio_sample_play(id, x, y, z, w, volume, loop, pitch)播放采样サンプル再生샘플재생เล่นตัวอย่างเสียงPlay a sample in 3D
audio_sample_play_flat(id, volume, loop, pitch)————Play a sample without positioning
audio_sample_stop(voice)停止采样サンプル停止샘플정지หยุดตัวอย่างเสียงStop a sample voice
audio_sample_duration(id)采样时长サンプル長さ샘플길이ความยาวตัวอย่างเสียงLength of a sample
audio_fx_delay(time, feedback, mix)回声ディレイ効果딜레이เสียงสะท้อนMaster echo
audio_fx_reverb(mix)混响リバーブ리버브เสียงก้องMaster reverb
audio_fx_lowpass(cutoff)低通滤波ローパス저역통과กรองความถี่ต่ำMaster low-pass filter
fft_push(samples)频谱输入FFT入力FFT입력วิเคราะห์เสียงFeed samples to the analyser
fft_bands(n)频段周波数帯주파수대แถบความถี่Log-spaced frequency bands
fft_beat()节拍检测ビート検出비트จังหวะเสียงIs there a beat now?
fft_beat_ratio()节拍比ビート比비트비율อัตราจังหวะBeat strength
fft_rms()均方根二乗平均RMS레벨ระดับRMSOverall loudness
fft_dominant_freq()主频主要周波数주파수ความถี่หลักStrongest frequency in Hz

How the engine mixes

One output stream carries four kinds of sound:

  • Tones: long-lived oscillators in numbered slots, placed in space (audio_tone).
  • One-shots: blips (audio_blip, ui_sound), positional effects (audio_sfx) and morph notes (morph_note).
  • Samples: decoded files played in 3D or flat (audio_sample_*).
  • Background music: one looping WAV (audio_bgm).

The listener is the camera. Pan is equal-power left/right from the sound’s position relative to the camera, and level falls off with distance. set_camera_pos moves the listener; audio_listener turns it. The final mix is soft-clipped, so loud mixes distort gently instead of clipping hard.

Tone slots grow on demand. There are 32 blip voices, 64 effect voices, 32 morph voices and 64 sample voices; when a pool is full, the oldest voice is dropped.

Volume and background music

audio_volume(level)

Master gain for everything this engine mixes (default 0.7; 1.0 is unity). It does not affect the music engine, which has its own music_volume.

audio_bgm(path, volume) and audio_bgm_volume(level)

audio_bgm loads a WAV file and loops it as background music (default volume 0.5). A second call replaces the track. If the file can’t be read, an error goes to standard error and the program continues in silence. The path is used exactly as given. For MP3, OGG, FLAC or AAC, use audio_sample_load or music_load.

audio_bgm_volume changes the level without reloading.

bind start = do {
    audio_volume(0.6)
    audio_bgm("theme.wav", 0.4)
    audio_bgm_volume(0.15)
}

Tones

audio_tone(slot, x, y, z, w, freq, amp, lfo_rate, lfo_depth, wave, duty)

Creates or retunes a continuous oscillator. Reusing a slot updates that tone in place, and frequency and amplitude glide to their new values, so you can call it every frame.

ParameterDefaultMeaning
slot0Tone slot number.
x, y, z0World position of the source.
w1Fourth-dimension value. It drives a slow sub-oscillator that cross-modulates the tone; 0 disables it.
freq220Frequency in Hz.
amp0.15Amplitude. Pass 0 to silence the slot (there is no delete).
lfo_rate0.5Vibrato speed in Hz.
lfo_depth0.02Vibrato depth as a fraction of freq.
wave"sine""sine", "square", "saw", "triangle" or "noise" (stepped noise pitched at freq).
duty0.5Square pulse width, for example 0.125, 0.25, 0.5, 0.75 for chiptune voices.

audio_glide(amp_ms, freq_ms)

Sets how long tone amplitude and frequency take to glide to a new value, in milliseconds (0 or less keeps the default). A chiptune player that updates tones once per frame sounds smoother at about 10 ms.

audio_listener(cos_yaw, sin_yaw, cos_pitch, sin_pitch)

Turns the listener. Pass the same four numbers you give set_camera (defaults 1, 0, 1, 0). Call it each frame when the camera turns.

bind start = do {
    open_window(640, 360, "Tones")
    audio_tone(0, 0, 0, 6, 0, 261.63, 0.10, 0.5, 0.01)
    audio_tone(1, 0, 0, 6, 0, 440.0, 0.06, 0, 0, "square", 0.25)
    bind yaw = 0.0
    while window_is_open() {
        bind yaw = yaw + 0.01
        set_camera(cos(yaw), sin(yaw), 1, 0)
        audio_listener(cos(yaw), sin(yaw), 1, 0)
        fill(10, 12, 28)
        present()
    }
}

One-shot sounds

audio_blip(freq, duration, wave, amp)

A short, non-positional blip with a fast attack and decay. Defaults: freq 660 Hz, duration 0.08 s (minimum 0.01), wave "sine", amp 0.25. Wave names: "sine", "square" ("sq"), "saw" ("sawtooth"), "tri" ("triangle"), "noise". Unknown names play a sine.

ui_sound(name)

One of the built-in interface sounds: "click" (default), "hover", "confirm", "error", "toggle", "tick". Any other name plays "click".

audio_sfx(x, y, z, w, freq, amp, duration, wave)

A synthesised one-shot at a world position, panned and attenuated like a tone. Defaults: position 0, w 1, freq 440, amp 0.3, duration 0.15, wave "sine".

morph_note(x, y, z, w, freq, amp, duration, material, morph)

A “yin-yang” note that blends a physical model with a digital one. material is 0 bowed string, 1 plucked, 2 blown, 3 struck metal. morph goes from 0 (light, acoustic) to 1 (dark, digital: FM, bit crush, drive). Defaults: freq 220, amp 0.3, duration 0.6.

audio_stop_sfx()

Stops every one-shot effect, morph note and sample voice at once, so tails don’t leak across a scene change. Tones, background music and the music engine keep playing.

bind start = do {
    ui_sound("confirm")
    audio_blip(880, 0.06, "square", 0.2)
    audio_sfx(1.5, 0, 4, 1, 330, 0.3, 0.2, "triangle")
    morph_note(0, 0, 5, 1, 220, 0.3, 1.2, 1, 0.4)
}

Samples

audio_sample_load(path)

Decodes a WAV, FLAC, OGG, MP3 or AAC file into memory, mixed down to mono. If the path doesn’t exist as given, it is tried relative to the script’s folder. Returns a sample id (from 0), or -1 on failure or when there is no audio device.

audio_sample_play(id, x, y, z, w, volume, loop, pitch)

Plays a loaded sample at a world position, panned and attenuated relative to the listener. volume defaults to 1, loop above 0.5 loops, and pitch is a playback-rate multiplier (2 is an octave up, 0.5 an octave down). w has no audible effect on samples. Returns a voice id, or 0 on failure. In the browser build the signature is (id, x, y, z, w, volume, loop), without pitch.

audio_sample_play_flat(id, volume, loop, pitch)

Plays a sample with no pan and no distance falloff. Use it for narration, voice-over and interface cues. Returns a voice id, or 0.

audio_sample_stop(voice) and audio_sample_duration(id)

audio_sample_stop stops a voice returned by a play call. audio_sample_duration returns a sample’s length in seconds (0 for an unknown id), handy for pacing a cut-scene to the clip that was actually loaded.

bind start = do {
    bind step = audio_sample_load("step.ogg")
    bind hum = audio_sample_load("hum.wav")
    audio_sample_play(step, 1.0, 0.0, 3.0, 1.0, 0.8, 0, 1.2)
    bind v = audio_sample_play_flat(hum, 0.5, 1, 1.0)
    print(audio_sample_duration(hum))
    audio_sample_stop(v)
}

Master effects

The master chain is delay, then reverb, then a low-pass filter. All three start off or fully open.

BuiltinParameters
audio_fx_delay(time, feedback, mix)Echo time in seconds (default 0.3), feedback 0 to 0.95 (default 0.3), wet mix 0 to 1 (default 0.3; 0 turns it off).
audio_fx_reverb(mix)Reverb wet mix, 0 to 1 (default 0.3).
audio_fx_lowpass(cutoff)0 to 1. 1 is open; lower values muffle the mix, for an underwater feel. The filter glides to the new value.
bind start = do {
    audio_fx_delay(0.35, 0.4, 0.25)
    audio_fx_reverb(0.4)
    audio_fx_lowpass(0.15)
}

FFT analysis

The FFT analyser works on samples you give it. Push a block of mono samples (numbers between -1 and 1, at 44.1 kHz) with fft_push, then read the results:

BuiltinReturns
fft_bands(n)A list of n log-spaced magnitude bands (default 32), bass first.
fft_beat()true when the latest block is a beat.
fft_beat_ratio()Beat strength: 1 is at the detection threshold, above 1 is a strong beat.
fft_rms()Root-mean-square level of the signal.
fft_dominant_freq()The strongest frequency in Hz.

This program builds a 1000 Hz sine wave and analyses it. The answer is close to 1000, limited by the analyser’s frequency resolution:

bind start = do {
    bind samples = []
    bind i = 0
    while i < 4096 {
        bind samples = samples.push(sin(i * 6.2831853 * 1000 / 44100))
        bind i = i + 1
    }
    fft_push(samples)
    print(round(fft_dominant_freq()))
    print(round(fft_rms() * 1000) / 1000)
    bind bands = fft_bands(8)
    bind loudest = 0
    bind k = 1
    while k < len(bands) {
        if bands[k] > bands[loudest] {
            bind loudest = k
        }
        bind k = k + 1
    }
    print("loudest band: " + str(loudest))
}
991
0.707
loudest band: 4

To react to a song that is playing, use music_fft(track, bands) on the Music page; for the microphone, mic_fft on Input and Microphone.