feat(audio): add guest voice controls and reliable lifecycle delivery
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-10-14 09:08:27 +01:00
parent 3899b7f12c
commit e0e01ed1de
23 changed files with 1442 additions and 482 deletions
+58 -188
View File
@@ -1,225 +1,95 @@
# Audio Peripheral (Audio System)
# Audio Peripheral
Domain: virtual hardware: audio
Function: normative
Didactic companion: [`../learn/mental-model-audio.md`](../runtime/learn/mental-model-audio.md)
Didactic companion: [Audio admission and lifecycle delivery](../../../discussion/lessons/DSC-0055-guest-audio-voice-control/LSN-0069-audio-admission-needs-a-delivery-boundary-and-independent-lifecycle-control.md).
## 1 Scope
## 1 Scope and machine limits
This chapter defines the runtime-facing audio contract of PROMETEU.
The AUDIO peripheral provides command-driven PCM playback on **16 explicitly selected voices**. Each voice plays one immutable mono PCM16 sample, with independent volume, stereo pan, playback rate and optional looping. The output target is **48,000 Hz stereo**, with saturating mixing. Hosts may use normalized floating-point device buffers to represent that output.
The AUDIO peripheral is responsible for sound generation and mixing under explicit machine limits.
The guest controls playback at logical-frame boundaries. The host renders samples independently of the 60 Hz game loop. These are separate clocks: a successful syscall admits a command, without promising that sound has already reached the device or a fixed latency in milliseconds.
Core contract:
This surface does not define playback handles, completion queries/events, automatic voice allocation, music sequencing, synthesis, streaming, envelopes or background audio producers.
- command-driven control from the game loop;
- fixed output format;
- finite voice count;
- deterministic voice conflict policy;
- explicit cost in cycles and certification surface.
## 2 Guest ABI v1
## 2 General Architecture
Every entry requires capability `AUDIO`, returns exactly one `status:int`, and has fixed syscall cost **5 cycles**, including operational rejection. Structural ABI misuse follows the VM trap policy. Mixing time is host work, not the syscall's logical cycle charge.
The audio system is composed of:
| Identity | ID | Arguments in order |
| --- | --- | --- |
| `audio.play_sample` | `0x3001` | `sample:int, voice:int, volume:int, pan:int, pitch:number` |
| `audio.play` | `0x3002` | `bank:int, sample:int, voice:int, volume:int, pan:int, pitch:number, loop:int` |
| `audio.stop` | `0x3003` | `voice:int` |
| `audio.set_volume` | `0x3004` | `voice:int, volume:int` |
| `audio.set_pan` | `0x3005` | `voice:int, pan:int` |
| `audio.set_pitch` | `0x3006` | `voice:int, pitch:number` |
- **Voices (channels)** — independent players
- **Samples** — PCM data
- **Mixer** — summation of voices
- **Output** — PCM stereo buffer
`number` means the existing VM numeric carriers accepted by audio playback, including integer and floating-point values; it is not a new ABI type. `play_sample` uses bank 0 and looping off. Both plays use internal priority 0. The public API has no priority argument.
Timing boundary:
### 2.1 Ranges and validation
- game sends commands at **60 Hz**;
- audio generates PCM at **48 kHz**.
- Voice: integer **0..15**.
- Bank: integer **0..15**, referring to an installed sound bank. Validate before narrowing; 256 must never alias bank 0.
- Sample index: integer **0..65535**; the sample must exist in the selected bank.
- Volume: integer **0..255**. Zero silences output while playback position continues advancing.
- Pan: integer **0..255**, from fully left to fully right. The mixer uses equal-power gains `sqrt(1-pan/255)` and `sqrt(pan/255)`.
- Pitch: **finite and strictly positive**; 1 means original speed. NaN, infinity, zero and negative values are rejected. No 0.25..4 restriction is imposed. Setters and plays use the same range.
- Loop: integer **0 or 1**, meaning off or on. Other values are rejected, without normalization.
## 3 Output Format
Structural type/shape/capability checks precede operational validation. Validate voice first, then other arguments/resources, then command admission. Rejection must not alter playback state or enqueue a command. When multiple operational errors exist, voice takes precedence; bank validity precedes sample lookup for bank playback.
- Sample rate: **48,000 Hz**
- Format: **PCM16 stereo (signed i16)**
- Clipping: saturation/clamp
### 2.2 Status values
## 4 Voices
| Value | Name | Meaning |
| --- | --- | --- |
| 0 | `OK` | Command admitted; application is asynchronous |
| 1 | `VOICE_INVALID` | Voice outside 0..15 |
| 2 | `SAMPLE_NOT_FOUND` | Sample absent from the selected installed bank |
| 3 | `ARG_RANGE_INVALID` | Invalid sample index, volume, pan, pitch or loop value |
| 4 | `ASSET_NOT_FOUND` | Reserved existing status |
| 5 | `NO_EFFECT` | Reserved existing status; inactive-voice controls do not use it |
| 6 | `BANK_INVALID` | Invalid or uninstalled sound bank |
| 7 | `COMMAND_LIMIT` | Current guest batch already admitted 1,024 commands |
### 4.1 Quantity
Stop and setters can return 0, 1, 3 where applicable, or 7. Stopping an inactive voice or changing its parameters succeeds. No helper based on the driver's former activity mirror is exposed as a playback-completion query.
```
MAX_VOICES = 16
```
## 3 Ordering and voice reuse
Each voice:
Commands in a published batch apply in emission order before a subsequent output buffer. The API does not promise sample offsets within a buffer.
- plays **1 sample at a time**
- is independent
- is mixed into the final output
A play explicitly replaces the selected voice, resets its position, and supplies every playback parameter. There is no automatic stealing of another voice. `play(A), stop, play(B)` on one voice leaves B playing. A setter following play changes that playback without resetting position. Stop is idempotent, releases the sample and silences the voice. Setters on inactive voices do not establish defaults for future plays.
### 4.2 Voice State
## 4 Admission, publication and backpressure
Each voice maintains:
A logical frame admits at most **1,024 commands**, shared by both plays and all four controls. 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.
- `sample_id`
- `pos` (fractional position in the sample)
- `rate` (pitch)
- `volume` (0..255)
- `pan` (0..255, left→right)
- `loop_mode` (off / on)
- `loop_start`, `loop_end`
- `priority` (optional)
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.
### 4.3 Voice Conflict
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.
If all voices are occupied:
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.
- an explicit policy is applied:
- `STEAL_OLDEST`
- `STEAL_QUIETEST`
- `STEAL_LOWEST_PRIORITY`
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.
## 5 Samples
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.1 Format
## 5 Pause, reset and sessions
PROMETEU samples:
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.
- **PCM16 mono**
- own sample_rate (e.g., 22050, 44100, 48000)
- immutable data at runtime
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.
Fields:
## 6 Samples, interpolation and ownership
- `sample_rate`
- `frames_len`
- `loop_start`, `loop_end` (optional)
Samples are immutable PCM16 mono, with a source sample rate and optional loop bounds. Linear interpolation uses fractional playback position. Playback rate combines source/output sample-rate ratio and pitch. Looping uses the sample's valid loop interval, or the full sample when no valid interval is present. Loop steps may cross multiple repetitions; finite positive pitch must not accidentally terminate a short loop or produce an infinite position.
### 5.2 Command Surface
Unloading or replacing a bank does not interrupt a sample already retained by an admitted command or mixer voice. New plays resolve the current bank. Memory can remain retained until the command is cancelled or the playback ends, stops, is replaced, or its session ends. The driver must not retain a second sample reference indefinitely after the mixer observes natural completion.
Representative command surface:
## 7 Host responsibilities and evidence
```text
audio.play(sample, voice, volume, pan, pitch, priority)
audio.stop(voice)
audio.setVolume(voice, value)
audio.setPan(voice, value)
audio.setPitch(voice, value)
audio.isPlaying(voice)
```
The desktop host consumes batches, mixes PCM and schedules the physical output. If no output device is available, it consumes committed batches silently. A failed or stalled device is diagnosed and detached so pending publication cannot block the guest indefinitely. The desktop implementation treats two seconds without callback progress as a stalled output.
## 6 Pitch and Interpolation
- `rate = 1.0` → normal speed
- `rate > 1.0` → higher pitch
- `rate < 1.0` → lower pitch
As position becomes fractional:
- **linear interpolation** is used between two neighboring samples
## 7 Mixer
For each output frame (48kHz):
1. For each active voice:
- read sample at current position
- apply pitch
- apply volume
- apply pan → generates L/R
2. Sum all voices
3. Apply clamp
4. Write to the stereo buffer
Cost depends on:
- number of active voices
- use of interpolation
## 8 Synchronization with the Game
- Game runs at **60Hz**
- Audio generates data at **48kHz**
Every frame (60Hz):
- game sends commands:
- play
- stop
- set_volume
- set_pan
- set_pitch
The audio applies these commands and continues playing.
## 9 Host Responsibilities
The PROMETEU machine defines the audio model, commands, and limits.
The host is responsible for:
- choosing the concrete audio backend;
- scheduling buffer delivery;
- keeping PCM output continuous without changing logical behavior.
## 10 Audio and CAP
Audio participates in the Execution CAP:
- mixing cost per frame
- cost per active voice
- command cost
Example:
```
Frame 1024:
voices_active: 9
mix_cycles: 410
audio_commands: 6
```
## 11 Syscall Return and Fault Policy
`audio` follows status-first policy for operations with operational failure modes.
Fault boundary:
- `Trap`: structural ABI misuse (type/arity/capability/shape mismatch);
- `status`: operational failure;
- `Panic`: internal invariant break only.
### 11.1 MVP return shape
In the current MVP:
- `audio.play` returns `status:int`;
- `audio.play_sample` returns `status:int`.
ABI `audio.play`:
1. `bank_id: int` — index of the sound bank
2. `sample_id: int` — index of the sample within the bank
3. `voice_id: int` — index of the voice to use (0..15)
4. `volume: int` — volume level (0..255)
5. `pan: int` — panning (0..255)
6. `pitch: float` — playback rate
7. `loop_mode: int` — `0` for Off, `1` for On
Return-shape matrix in v1 syscall surface:
| Syscall | Return | Policy basis |
| --------------------- | ------------ | -------------------------------------- |
| `audio.play` | `status:int` | operational rejection is observable |
| `audio.play_sample` | `status:int` | operational rejection is observable |
### 11.2 Minimum status table for `play`/`play_sample`
- `0` = `OK`
- `1` = `VOICE_INVALID`
- `2` = `SAMPLE_NOT_FOUND`
- `3` = `ARG_RANGE_INVALID`
- `5` = `NO_EFFECT`
- `6` = `BANK_INVALID`
Operational rules:
- no fallback to default bank when a bank id cannot be resolved;
- no silent no-op for invalid `voice_id`;
- invalid `voice_id` must return `VOICE_INVALID`, not `ARG_RANGE_INVALID`;
- invalid numeric ranges (e.g. `volume`, `pan`, `pitch`) must return explicit status.
Headless execution consumes committed batches silently and preserves incomplete frame/callback staging. It validates admission and runtime behavior, without proving audible output. Synthetic mixer tests establish signal behavior; a real device smoke establishes stream initialization and callback consumption, while listening remains a separate observation. Bit-identical PCM across physical devices is not required.