audio - sound: what is playing, the volume, the codec's power, a test tone

Version reported by audio version. Implementation shape: shell built-in, asking the board's audio driver over IPC - audio-driver on x86, pwm-audio on the Pis. The driver owns the controller; the shell owns the words.

Status, as built and honest (2026-10-10)

Built, run in QEMU, and heard on every board with an audio output. In QEMU (intel-hda with the hda-output codec, mixer=on) every verb in section 1 answers as section 2 says, and the WAV QEMU writes agrees - the level follows the volume, volume 0 and mute are silent, a tone lasts as long as asked and q cuts it short (osdev test audio). On hardware: the Dell Wyse 5070 and the HP T630 through audio-driver, speaker and headphones on each; the Pi 4 and the Pi 2 through pwm-audio, which drives the 3.5 mm jack by PWM. The VisionFive 2 Lite has no audio output, and audio answers no audio hardware on this machine. A codec not in the driver's table of verified codecs is surveyed and not played on, and every verb below says so (section 4).

The verbs in section 1 are built, and the volume, the mute and the output survive a reboot (section 5). hardware, outputs, output, debug, system sounds and the keyboard shortcuts were built on 2026-10-09 (feat/audio-finish) and run in QEMU, which has ONE audio controller with ONE output - so the reports, the in-use marks and a refused name are shown there; a second controller and switching between two outputs are not, until hardware with them. That is all of the surface the operator agreed except audio hardware use, which waits for a machine with two audio devices a driver can play on; that word answers not built rather than being mistaken for a fault.

1. Verbs

mute and unmute are two verbs, not two spellings: two distinct actions, so rule 3's ban on synonyms does not apply.

Volume is 0 to 100, and 0 is not mute. Both are silent, and they stay separate states: mute keeps the volume and unmute returns to it. On x86 the scale is linear in the codec's own amplifier steps, which are even steps of decibels, so equal steps of volume sound like equal changes; audio info shows the step. The Pis have no amplifier: pwm-audio scales the samples by the square of the volume, for the same reason.

2. What each action answers

Every change of state is READ BACK from the codec before it is reported: - verified when the codec agrees, - unverified (the codec could not be asked) when it could not be asked, - unconfirmed (this codec does not report it, so it cannot say) when the codec does not model the change at all (QEMU's codec reports no power states, so audio off is unconfirmed there), and FAILED - the codec reads back something else when it disagrees.

3. Pipes (rule 12)

status and info start pipes, as labelled lines: audio status | match volume, audio info | write /audio-info.txt. outputs pipes as records - output, plugged, in_use - so audio outputs | count is how many there are; debug pipes as text (audio debug codec | write /codec.txt captures a new machine's codec); hardware pipes as records too - device, kind, made_by, driver, state, in_use. The actions refuse with a sentence naming the reports. Piping sound IN will be refused in the design: a pipe carries 16 KiB, a tenth of a second of sound, so play takes a PATH and the file is the adapter (docs/audio.md).

4. Failure says which half failed

An absent, wedged or restarting driver makes audio return with a loud sentence, never hang: every ask is bounded, and every answer is immediate by design - a tone is started and answered, then followed with status (sdk/audio's wire protocol, which is tagged so a late answer is never read as the next one).

5. Settings that survive a reboot: the driver's settings file

The volume, the mute and the output are kept on disk, in the driver's own folder (docs/filesystem-layout.md): /system/services/audio-driver/settings on the PCs and /system/services/pwm-audio/settings on the Pis. Plain labelled lines, readable with read /system/services/audio-driver/settings:

volume 60
muted no
output headphone

• The driver owns the file and its folder. It makes the folder at its first write. It reads the file once when it comes up and writes it after a change the codec did not contradict - a setting the codec refused is not written. on and off are NOT kept: audio comes up on at every boot.
• Never written while a tone plays. A write blocks the driver, and a slow one mid-tone would starve the sound; a change made during a tone is written when it ends.
• Bounded and tolerant. The file is read in one piece, at most 256 bytes; a line the driver does not know is ignored and said once in the log; no file means the defaults (volume 50, unmuted). Where fs is absent - no data disk - or does not answer, the driver says so once, carries on with what it holds, and says a failed write once rather than on every change.
• system sounds off is written when they are switched off; no line means on, the default.
• output is written only once one has been chosen with audio output; until then the driver plays through the first output its survey found. At boot it is restored if the codec still has an output of that kind, and the log says so either way. The Pis' jack is one output, so pwm-audio keeps no line.

6. Tab completion and words from elsewhere (rules 8 and 9)

audio completes its BUILT verbs, and off completes hard. The words people bring from other systems are hints, never aliases: beep and speaker-test point to audio tone, amixer and alsamixer to audio volume, and aplay to audio play. audio play completes a PATH, which is why audio is not among the commands whose arguments are keywords only.