# Audio Peripheral Domain: virtual hardware: audio. Function: normative. ## Machine contract The peripheral mixes **32 PCM voices** into stereo output at **48000 Hz**: 12 Music A, 12 Music B, and 8 SFX. Groups never borrow voices. Mono and stereo samples each consume one logical voice. Music groups have independent resident bank selection, sequence, tempo, loop, volume, pause, automation and effects. A shared Rust engine performs desktop, headless and offline execution; the host owns physical scheduling and the output device. The authoritative binary format, instrument/event model, numerical rules and new high-level ABI are in [Audio banks and sequences](05a-audio-bank-format.md). SoundBank and MusicBank each have 16 independent resident slots. A MusicBank contains exactly one complete composition and every required instrument/sample. Loading is explicit and atomic. PCM16_LE and IMA_ADPCM_WAV4 are selected per sample, decoded completely during loading and resident as PCM16. The mixer never decodes assets or loads a bank implicitly. ## SFX controls and status Existing audio play/control identities keep their single current meaning; no legacy voice/format path is provided. `audio.play(bank,sample,voice,volume,pan, pitch,loop)` and `audio.play_sample(sample,voice,volume,pan,pitch)` address SFX local voices **0..7**. The latter selects resident SoundBank 0 with looping off. A play replaces that voice. Stop is immediate/idempotent and setters do not start an inactive voice. No allocation/stealing of another SFX voice occurs. Volume and pan/balance are 0..255; bank slots are 0..15 and sample indices 0..65535. Pitch is finite and positive; loop is exactly 0 or 1. Validate before narrowing. Structural type/capability checks precede operational validation; voice precedes resource lookup, and invalid commands never consume quota. All operations require AUDIO and return one status at five logical cycles: 0 OK (admitted asynchronously), 1 VOICE_INVALID (direct SFX play/stop/setters), 2 SAMPLE_NOT_FOUND, 3 ARG_RANGE_INVALID (including high-level group/bus/send selectors), 4 ASSET_NOT_FOUND (reserved), 5 NO_EFFECT (reserved), 6 BANK_INVALID, 7 COMMAND_LIMIT. Loading/decoding remains asset-manager work. ## Playback and signal Immutable samples are referenced without PCM copies per voice. Source-rate ratio and pitch advance a fractional cursor with linear interpolation. Loop bounds are validated decoded frames, start inclusive/end exclusive; playback begins at zero and preserves an intro. Loop-off ends at the full sample length. Interpolation wraps at loop-end when looping. A finite large rate must wrap safely without an infinite position. Empty nonlooped samples are inactive without reading memory. Mono uses equal-power pan; stereo balance preserves its original two channels at center. Instrument/track/group, Music Bus, SFX Bus and master gains compose before final saturation. The three groups each have shared low-pass/delay processing and selective sends; no per-voice DSP chain exists. Fade, envelope, LFO, portamento and musical event timing use the audio timeline, independently of the game frame. ## Ownership, replacement and real-time processing Unload/replacement invalidates the old bank instance. Its active groups/voices stop on audio consumption, and stale queued plays cannot restart it. Failed replacement preparation preserves the old bank. Developers can fade/stop first. Old references stay valid until reclaimed safely outside the callback; buffers already delivered to a physical device cannot be recalled. Music invalidation clears only affected group effect history. Already mixed SFX delay tails may end naturally while their source voices are stopped. The callback must not allocate, deallocate a last runtime owner, block, perform I/O, decode assets, or execute unbounded event/control work. Samples, MusicBanks, invalidation tokens, command vectors and prepared DSP storage follow bounded retirement/service rules. Host service runs while guest execution is paused or backpressured. Absence/failure of an output device must not deadlock publication. Headless conformance executes the shared engine with explicit frame advancement; silent command consumption alone is not evidence of sequencer or PCM behavior. Headless pause/resume publishes global audio pause state immediately, so explicit audio rendering does not need another VM/graphics tick to observe that control. ## 4 Admission, publication and backpressure A logical frame admits at most **1,024 commands**, shared by guest SFX, music, bus and effect commands. Bank unload is an asset-owner action outside this admission quota, as specified in the audio-bank ABI. Invalid calls do not consume quota. An excess call returns `COMMAND_LIMIT`; a rejected stop requires a guest retry. Quota depends on the logical frame, not the device callback speed or number of physical host ticks. Except for the lifecycle prefix publication defined below, commands remain staged until successful logical-frame completion: explicit `FRAME_SYNC` or the runtime's implicit frame end when the entry function returns (`EndOfRom`). An aborted/faulted frame or `HALT` cancels its unpublished commands. Debugger stepping preserves staging and publishes at either successful completion boundary. The transport holds **one pending frame batch**, in addition to producer staging and a batch already taken by the mixer. The guest waits for pending publication to be consumed before advancing further; the host continues handling events. Accepted commands must not be silently dropped because a device queue is full. The audio callback must not wait on a producer lock: if a short publication critical section is busy, it retries on a later buffer. Lifecycle callbacks have independent staging and one independent pending publication slot. Callback admission is bounded to **1,024 guest commands per callback**. This prevents an occupied frame slot or exhausted frame quota from blocking callback controls. A successful callback publishes without requiring `FRAME_SYNC`; a failed callback cancels its staged commands. Pending frame publication precedes subsequent lifecycle publication; guest frames do not advance while either publication slot is occupied. A successful lifecycle boundary publishes the interrupted frame's staged prefix **before** the callback commands, together in the lifecycle delivery. This explicit early-publication boundary preserves emission order: `play` before Home followed by `stop` in the callback must remain stopped after resume. An absent optional callback still completes this boundary. The combined delivery holds at most **2,048 commands**: up to 1,024 from the interrupted frame plus 1,024 from the callback. Flushing a prefix does **not** replenish that frame's admission quota. The resumed frame retains its admitted-command count across repeated pause/resume transitions until normal frame completion, abort or session reset. The prefix is not published again when the frame completes. Failed callbacks cancel their unpublished commands and prefix. A later fault in the resumed frame cannot roll back a prefix already published at the earlier lifecycle boundary. ## 5 Pause, reset and sessions Home and debugger pause stop progression of Game voices, preserving their position. Resume continues from that position. Callback commands are applied before resumed PCM generation. Pause state and session invalidation are internal controls independent of guest quota and pending batch capacity. Reset, termination, crash or cartridge replacement ends the audio session, stops all its voices and invalidates its pending/staged commands. Internal session generations prevent old deliveries from restarting playback. Ending a session may cancel previously admitted commands. Silence is guaranteed from processing the transition in the mixer; buffers already submitted to a physical device cannot be recalled. ## Qualification Functional, ownership and allocation tests must cover 32 **stereo** voices, two independent compositions plus SFX, DSP/automation, malformed banks and continuous replacement. Report cartridge bytes, decoded PCM and actual resident/retired/DSP memory separately. Historical 16-voice measurements do not qualify this contract. Hardware ARM/battery qualification requires an identified physical target.