# 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.

