gizlang/audio
sound out and in through the kernel's ALSA PCM interface (/dev/snd/pcmC0D0p and pcmC0D0c), the same on Linux and on GizOS: 48 kHz, two channels, 16-bit little-endian samples, interleaved. A Pcm is one stream of one device. A program plays through one Output: a thread of its own mixes every Voice into the device, so the sounds of a program (a page's media and its Web Audio) play together. A device another program holds gives no Output. On a Linux desktop the sound server (PipeWire) holds the devices and mixes every program: the Output and the microphone go through it (its pw-cat, in the same format), so the desktop's chosen speakers and microphone sound.
import * as Audio from "gizlang/audio";Types
Pcm
type Pcm = { native: Native; fd: i64; capture: bool; period: i64; buffer: i64; at: u64; room: i64; }One open PCM stream: playback, or (CAPTURE) recording.
native:gizlang_native.Nativefd:i64capture:boolperiod:i64buffer:i64at:u64room:i64
Card
type Card = { index: i64; name: string; playback: bool; capture: bool; }A sound card: its number, its name, and whether its device 0 plays and records.
index:i64name:stringplayback:boolcapture:bool
Level
type Level = { volume: i64; on: bool; }A mixer's level: its VOLUME (0-100) and whether it is ON (not muted).
volume:i64on:bool
Note
type Note = { voice: i64; kind: i64; samples: bytes; volume: f64; }What a Voice sends the mixer: samples to queue (interleaved stereo f32 as bytes), a volume, or its end.
voice:i64kind:i64samples:bytesvolume:f64
Voice
type Voice = { id: i64; mixer: Task.Channel<Note>; }A sound of the program that plays with the others: its number on the program's Output.
id:i64mixer:gizlang_task.Channel<gizlang_audio.Note>
Echoless
type Echoless = { module: string; }The sound server's echo canceller between the desktop's microphone and speakers, for this program while it is
open: what the program plays is taken out of what it records, so a program that talks back through speakers does
not hear itself. module is the server's number of it.
module:string
Listening
type Listening = { blocks: Task.Channel<bytes>; stops: Task.Channel<bool>; }The microphone read on a thread of its own: its sound comes on blocks as interleaved stereo f32 (10 ms each; a slow
reader misses some, never waits), until stop.
blocks:gizlang_task.Channel<bytes>stops:gizlang_task.Channel<bool>
Functions
open
function open(capture: bool, card: i64 = 0, device: i64 = 0): Pcm throws stringThe PCM stream of card CARD, device DEVICE: playback, or recording when CAPTURE. Throws why it cannot: no device, held by another program (EBUSY), or no 48 kHz stereo 16-bit mode.
Effects: fail, io, alloc.
pcmPath
function pcmPath(capture: bool, card: i64 = 0, device: i64 = 0): stringThe path of the PCM stream open opens; open it O_RDWR | O_CLOEXEC.
Effects: fail, alloc.
openDevice
function openDevice(fd: i64, capture: bool): Pcm throws stringThe PCM stream open on FD (which another process may have opened and handed over), recording when CAPTURE, as open gives it; the stream owns FD.
Effects: fail, io, alloc.
cards
function cards(): Vec<Card>The machine's sound cards.
Effects: fail, io, alloc.
level
function level(capture: bool = false, card: i64 = 0): Option<Level>CARD's playback level, or its recording level when CAPTURE; none when the card has no such mixer.
Effects: fail, io, alloc.
setLevel
function setLevel(volume: i64, on: bool, capture: bool = false, card: i64 = 0): Option<Level>Sets CARD's playback level (its recording level when CAPTURE) to VOLUME (0-100) and ON; the level after.
Effects: fail, io, alloc.
served
function served(): boolWhether a desktop's sound server runs for this user: the devices are its, and pw-cat plays and records through it.
Effects: fail, io, alloc.
echoless
function echoless(): Echoless throws stringOpens the echo canceller (WebRTC's, through the sound server's pactl, with its gain control: it sets the voice's level knowing what is echo, so the program adds no gain); the program's voices and listening that start after it go through it. The cancellers of programs that ended without closing theirs (Ctrl-C) are closed first. Throws why there is none (no sound server, or one without the module).
Effects: fail, read, write, console, io, alloc.
voice
function voice(): Option<Voice>A new Voice on the program's Output, which starts with the first; none when the device cannot be opened.
Effects: fail, read, write, io, alloc.
listen
function listen(): Listening throws stringThe microphone, read on a thread of its own; throws why it cannot open.
Effects: fail, read, write, io, alloc.
listenDevice
function listenDevice(fd: i64): Listening throws stringThe microphone open on FD, as listen gives it; the listening owns FD.
Effects: fail, write, io, alloc.
Methods
Pcm.write
function Pcm.write(self: Pcm, samples: bytes): void throws stringPlays SAMPLES (whole frames), waiting while the device's buffer is full. A gap (an underrun) starts the stream again.
Effects: fail, io, alloc.
Pcm.read
function Pcm.read(self: Pcm, frames: i64): bytes throws stringUp to FRAMES recorded frames, waiting for at least one period. An overrun starts the stream again.
Effects: fail, io, alloc.
Pcm.delay
function Pcm.delay(self: Pcm): i64The frames written and not yet heard: how far behind what the program writes the sound is.
Effects: fail, io, alloc.
Pcm.close
function Pcm.close(self: Pcm): voidStops the stream at once and closes the device.
Effects: fail, io, alloc.
Echoless.close
function Echoless.close(self: Echoless): voidCloses the echo canceller; what still plays or records through it ends.
Effects: fail, read, write, console, io, alloc.
Voice.play
function Voice.play(self: Voice, samples: bytes): voidQueues SAMPLES (interleaved stereo f32, little-endian) to play after what the voice queued before.
Effects: fail, io, alloc.
Voice.volume
function Voice.volume(self: Voice, volume: f64): voidThe voice's volume, 0 to 1.
Effects: fail, io, alloc.
Voice.end
function Voice.end(self: Voice): voidEnds the voice: what it queued is dropped.
Effects: fail, io, alloc.
Listening.taken
function Listening.taken(self: Listening): bytesThe sound that came since the last call, as interleaved stereo f32.
Effects: fail, write, io, alloc.
Listening.stop
function Listening.stop(self: Listening): voidStops the thread and closes the microphone.
Effects: fail, io, alloc.
Constants
RATE
const RATE = 48000The rate, channels and bytes of a frame of every stream.
CHANNELS
const CHANNELS = 2The channels of every stream: stereo.
FRAME_BYTES
const FRAME_BYTES = 4The bytes of one frame: two channels of 16-bit little-endian samples.