GizStack
View .mdOpen in ChatGPTOpen in Claude

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.

gizlang
import * as Audio from "gizlang/audio";

Types

Pcm

gizlang
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.Native
  • fd: i64
  • capture: bool
  • period: i64
  • buffer: i64
  • at: u64
  • room: i64

Card

gizlang
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: i64
  • name: string
  • playback: bool
  • capture: bool

Level

gizlang
type Level = { volume: i64; on: bool; }

A mixer's level: its VOLUME (0-100) and whether it is ON (not muted).

  • volume: i64
  • on: bool

Note

gizlang
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: i64
  • kind: i64
  • samples: bytes
  • volume: f64

Voice

gizlang
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: i64
  • mixer: gizlang_task.Channel<gizlang_audio.Note>

Echoless

gizlang
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

gizlang
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

gizlang
function open(capture: bool, card: i64 = 0, device: i64 = 0): Pcm throws string

The 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

gizlang
function pcmPath(capture: bool, card: i64 = 0, device: i64 = 0): string

The path of the PCM stream open opens; open it O_RDWR | O_CLOEXEC.

Effects: fail, alloc.

openDevice

gizlang
function openDevice(fd: i64, capture: bool): Pcm throws string

The 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

gizlang
function cards(): Vec<Card>

The machine's sound cards.

Effects: fail, io, alloc.

level

gizlang
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

gizlang
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

gizlang
function served(): bool

Whether 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

gizlang
function echoless(): Echoless throws string

Opens 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

gizlang
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

gizlang
function listen(): Listening throws string

The microphone, read on a thread of its own; throws why it cannot open.

Effects: fail, read, write, io, alloc.

listenDevice

gizlang
function listenDevice(fd: i64): Listening throws string

The microphone open on FD, as listen gives it; the listening owns FD.

Effects: fail, write, io, alloc.

Methods

Pcm.write

gizlang
function Pcm.write(self: Pcm, samples: bytes): void throws string

Plays 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

gizlang
function Pcm.read(self: Pcm, frames: i64): bytes throws string

Up to FRAMES recorded frames, waiting for at least one period. An overrun starts the stream again.

Effects: fail, io, alloc.

Pcm.delay

gizlang
function Pcm.delay(self: Pcm): i64

The frames written and not yet heard: how far behind what the program writes the sound is.

Effects: fail, io, alloc.

Pcm.close

gizlang
function Pcm.close(self: Pcm): void

Stops the stream at once and closes the device.

Effects: fail, io, alloc.

Echoless.close

gizlang
function Echoless.close(self: Echoless): void

Closes the echo canceller; what still plays or records through it ends.

Effects: fail, read, write, console, io, alloc.

Voice.play

gizlang
function Voice.play(self: Voice, samples: bytes): void

Queues SAMPLES (interleaved stereo f32, little-endian) to play after what the voice queued before.

Effects: fail, io, alloc.

Voice.volume

gizlang
function Voice.volume(self: Voice, volume: f64): void

The voice's volume, 0 to 1.

Effects: fail, io, alloc.

Voice.end

gizlang
function Voice.end(self: Voice): void

Ends the voice: what it queued is dropped.

Effects: fail, io, alloc.

Listening.taken

gizlang
function Listening.taken(self: Listening): bytes

The sound that came since the last call, as interleaved stereo f32.

Effects: fail, write, io, alloc.

Listening.stop

gizlang
function Listening.stop(self: Listening): void

Stops the thread and closes the microphone.

Effects: fail, io, alloc.

Constants

RATE

gizlang
const RATE = 48000

The rate, channels and bytes of a frame of every stream.

CHANNELS

gizlang
const CHANNELS = 2

The channels of every stream: stereo.

FRAME_BYTES

gizlang
const FRAME_BYTES = 4

The bytes of one frame: two channels of 16-bit little-endian samples.