# gizhw:audio

PCM sound on any platform. `devices` lists each sound device by an id the platform gives and a name; `open` takes the id, the direction and the wanted rate, channels and sample format. Linux plays and captures through ALSA (gizhw:alsa). A platform without a backend fails each call with the class and the platform named.

```gizlang
import * as Audio from "gizhw:audio";
```

## Types

### `Info`

```gizlang
type Info = { id: string; name: string; }
```

A sound device: `id` opens it (an ALSA PCM name on Linux, "default" first), `name` is the card's own name.

- `id`: `string`
- `name`: `string`

### `Wanted`

```gizlang
type Wanted = { rate: i64; channels: i64; format: string; }
```

What open asks for: a rate in Hz, a channel count and a sample format; "s16le" (16-bit little-endian, the
channels interleaved) is the one every backend gives.

- `rate`: `i64`
- `channels`: `i64`
- `format`: `string`

### `Stream`

```gizlang
type Stream
```

An open stream: its direction and the rate, channels and format of its frames.

- `capture`: `bool`
- `rate`: `i64`
- `channels`: `i64`
- `format`: `string`

## Functions

### `devices`

```gizlang
function devices(sys: System): Vec<Info> throws string
```

The sound devices of this machine: the platform's default device first, then one for each card.

Effects: fail, io.

### `open`

```gizlang
function open(sys: System, id: string, capture: bool, wanted: Wanted): Stream throws string
```

The sound device `id` (from `devices`), open for capture or for playback.

Effects: fail, io.

## Methods

### `Stream.frameBytes`

```gizlang
function Stream.frameBytes(self: Stream): i64
```

The bytes of one frame (all channels of one instant).

Effects: fail.

### `Stream.play`

```gizlang
function Stream.play(self: Stream, samples: bytes): i64 throws string
```

Plays `samples` (whole frames); gives the frames played.

Effects: fail, io.

### `Stream.capture`

```gizlang
function Stream.capture(self: Stream, frames: i64): bytes throws string
```

Captures `frames` frames; gives their bytes.

Effects: fail, io.

### `Stream.close`

```gizlang
function Stream.close(self: Stream): void
```

Closes the stream.

Effects: fail, io.