Overview

sound is Lilush's audio module, aimed at game-engine use alongside term.gfx and the LEV runtime.

Why it talks to the kernel directly

Lilush links fully static against musl, and a static musl binary cannot dlopen. ALSA's entire plugin/config layer — including dmix, its software mixer, and the default device — is loaded through dlopen, so it is unavailable to Lilush regardless of which audio library we link. Linking libasound or vendoring a library like miniaudio would still be limited to raw hw: device access and drag in a heavy dependency for no capability gain.

So sound talks to the kernel PCM interface directly: ioctl() on /dev/snd/pcmC*D*p, using the structures and ioctl numbers from <sound/asound.h> (shipped by the build container's linux-headers). Zero third-party dependencies, static by construction, and the device fd plugs straight into LEV's wait_writable.

Two consequences follow from there being no dmix:

1. The device is held exclusively. While sound has the device open, other programs cannot play through it (and vice-versa). Stop other audio apps first.

2. All mixing happens in-process. That is exactly what sound.mixer is for — there is no system mixer to fall back on.

Architecture

Every Lua-facing sample buffer is interleaved float32 in [-1, 1]. Mixing accumulates in float and never clips intermediate sums; the single clamp to [-1, 1] happens in the device on write, where float is also converted to the hardware format (s16) if the card does not accept float directly. Frame offsets at the Lua boundary are 1-indexed, matching the rest of the codebase.

Quick start

local lev = require("lev")
local gfx = require("term.gfx")
local sound = require("sound")

local dev = assert(sound.open({ rate = 48000, channels = 2 }))
local mx = sound.mixer({ channels = dev:channels() })

local blip = assert(sound.synth.tone({ note = "A5", dur = 0.08, wave = "square", amp = 0.4 }))
local music = assert(sound.wav.load("music.wav", { rate = dev:rate() }))

lev.run(function()
    sound.run(dev, mx)                       -- dedicated audio writer task
    mx:play(music, { gain = 0.6, loop = true })

    gfx.loop({
        fps = 60,
        canvas = gfx.canvas({ width = 320, height = 200 }),
        display = true,
        render = function(c) --[[ draw ]] end,
        input = function(key)
            if key == " " then mx:play(blip, { pan = 0.3 }) end
        end,
    }):run()
end)

The frame loop drives visuals and just calls mx:play(); the sound.run writer task does the device I/O. Both run under one lev.run. Audio is fed on its own fd-driven schedule (not from update) because it must stay ahead of the hardware more reliably than frames are rendered.

sound.open(opts) → device | nil, err

Opens /dev/snd/pcmC<card>D<device>p, negotiates hardware/software parameters, and prepares the stream. opts (all optional):

Device methods: dev:fd(), dev:period(), dev:channels(), dev:rate(), dev:format() ("f32"/"s16"), dev:avail() (free frames), dev:write(buf) (→ frames written, or nil,"EAGAIN"/nil,"EPIPE"/nil,err), dev:recover() (re-prepare after an underrun), dev:start(), dev:drop(), dev:close(). Playback auto-starts once the ring buffer fills.

sound.buffer(frames [, channels=2]) → buffer

A block of interleaved float32 samples. Methods:

mix gains: none → unity; one → master volume; per-channel → pan. A mono source mixed into a stereo destination is duplicated to both channels.

Other core functions: sound.from_pcm(data, channels, fmt) (decode raw PCM bytes — "u8", "s16", "s24", "s32", "f32" — to a float buffer) and sound.resample(buf, src_rate, dst_rate) (linear resample).

sound.mixer(opts) → mixer

opts.channels (default 2) must match the output buffer / device channels.

• mx:play(buf, opts) → voice. opts: gain (default 1), pan (-1..1, equal-power), loop (bool). Voice: :stop(), :set_gain(g), :set_pan(p), :is_active().

• mx:fill(out, n) — clear out, mix every voice's next n frames into it, advancing playheads and reaping finished non-looping voices.

• mx:stop(id), mx:stop_all(), mx:active() (voice count).

sound.run(dev, mx) calls fill for you on a writer task; call fill directly only if you drive the device yourself.

sound.wav

• sound.wav.decode(data, opts) → buffer, info | nil, err

• sound.wav.load(path, opts) → buffer, info | nil, err

Supports uncompressed integer PCM (8/16/24/32-bit) and IEEE float32, including WAVE_FORMAT_EXTENSIBLE. opts.rate resamples to that rate (pass dev:rate() so assets play at the right pitch). info is { channels, rate, bits, frames }.

sound.synth

• sound.synth.tone(opts) → buffer | nil, err. opts: freq or note (e.g. "A4", "C#5"); dur (s, default 0.25); rate (48000); channels (2); wave ("sine"/"square"/"saw"/"triangle"/"noise"); amp (0.5); ADSR attack/decay/sustain(level)/release.

• sound.synth.note_freq(name) → Hz (12-TET, A4 = 440).

sound.speech

Built-in English text-to-speech: a deterministic Klatt-style formant synthesizer with voice presets and knobs (pitch, formant scale, rate, breathiness, robotic quantize). Mono output, resampled to opts.rate:

local buf = assert(sound.speech.say("Docking request granted.", {
    voice = "computer", rate = dev:rate(),
}))
mx:play(buf, { gain = 0.9 })

Full pipeline, phoneme-level API (phonemize/synth), knob semantics, and the tuning workflow: SPEECH.md.

Testing

Unit tests (buffer math, PCM decode, resample, WAV parsing, synth, mixer) need no hardware and run under the normal suite:

./run_tests.bash sound

Actual playback needs a real device. A manual smoke test lives at tests/sound/manual/smoke.lua — run it on a host with /dev/snd (and membership in the audio group). It sits in a subdirectory so run_tests.bash does not pick it up (the build container has no sound device):

lilush tests/sound/manual/smoke.lua