AntOS Library — audio (reference)

The audio library's design and native core — system audio for scripts. The script-facing API is luau_audio.

What it is

The scripting entry point to system audio. Its concrete surface today is the buzzer — a single audio.buzzer(...) call that queues or immediately plays a tone (or a default chirp), non-blocking, for cues and simple melodies. It is named audio, not buzzer, because it is the home for the rest of system audio as that reaches scripting.

Design notes

• The buzzer is namespaced under audio.buzzer — deliberately not audio.tone/audio.beep. The buzzer is one device; claiming generic top-level names for it would block the real audio path later. So the buzzer's calls all carry the buzzer prefix (audio.buzzer, audio.buzzerReady, audio.buzzerClear), and the bare audio.* namespace stays reserved for sampled playback and the Tempest/Pulse voices.
• One call, progressive defaults — audio.buzzer([freq[, ms[, now]]]) collapses the old tone/beep/now trio into a single function: omit the frequency for a chirp, the duration for a short default, the now flag to queue rather than interrupt. Fewer names, same expressiveness.
• Buzzer via Clicky on the CM5 — the tone queue is DeMon's, the precise timing is Clicky's (over UART2). Tones are fire-and-forget: the core plays the queue against real time while the script runs on.

Stage-synced cues

Beyond fire-and-forget tones, audio can schedule playback against the stage tick instead of wall-clock, so a sound lands on the exact frame its animation does — the audio cousin of timeline. This is the "audio-sync" role, folded in here rather than made a separate library, because it is a scheduling layer over the same playback, not a new device.

• A cue is a sound (a buzzer tone today, a sample later) scheduled at a tick or a musical beat; it fires in the React phase of its target tick, so footfalls, hit-sounds, and UI blips line up with the frames that cause them.
• A tempo / beat clock counts in stage ticks, so rhythm-locked playback stays in step with the simulation.
• The timing is deterministic — the trigger is tick-locked (a cue on tick N always fires on tick N, and re-fires there on replay); only the audio output is real-time, as mixing must be.

The scheduling verbs (audio.cue, audio.tempo, audio.beat) are a timing layer, not device names, so they sit at the top level without touching the audio.* reservation for sampled playback and the voices; the buzzer stays under audio.buzzer, and cues schedule whatever playback exists.

Native core — libantos_audio

Currently the buzzer tone queue and play-out (the former sys_buzzer); on the CM5 that's the DeMon→Clicky protocol. No Luau dependency. Sample/mixer paths, when added, sit behind the same core and surface as new audio.* calls.

Related

• luau_audio — the script API · Pulse · audio (the audio subsystem) · DeMon / Clicky · AntOS Libraries hub