# gizlang/player

gizlang/media: audio and video files and streams, decoded by the ffmpeg program (ffprobe tells their kind, length and size). A Player plays one: a thread of its own reads its sound into a Voice of the program's Output (gizlang/audio), and another reads its pictures as RGBA at their time; the program shows the latest that next() gives. Both keep to one clock, which starts at play and stops at pause. decodeAudio gives a whole file's sound at once (Web Audio's decodeAudioData).

```gizlang
import * as Player from "gizlang/player";
```

## Types

### `Info`

```gizlang
type Info = { duration: f64; width: i64; height: i64; rate: f64; audio: bool; video: bool; }
```

What a media file holds: its length in seconds (0 when it streams), and its picture's size and rate (0 with none).

- `duration`: `f64`
- `width`: `i64`
- `height`: `i64`
- `rate`: `f64`
- `audio`: `bool`
- `video`: `bool`

### `Frame`

```gizlang
type Frame = { time: f64; bitmap: Bitmap; }
```

A picture of the video and the time it shows, in seconds.

- `time`: `f64`
- `bitmap`: `gizlang_graphics.Bitmap`

### `Stop`

```gizlang
type Stop = { now: bool; }
```

What the program tells a player's threads: stop.

- `now`: `bool`

### `Player`

```gizlang
class Player { url: string; soundUrl: Option<string> = undefined; pictureUrl: Option<string> = undefined; info: Info; at: f64 = 0.0; started: i64 = -1; volumeLevel: f64 = 1.0; stops: Vec<Task.Channel<Stop>> = []; frames: Option<Task.Channel<Frame>> = undefined; voice: Option<Audio.Voice> = undefined; constructor(url: string, info: Info) { this.url = url; this.info = info; } time(): f64 { const t = this.started <0 ? this.at: this.at + f64(Task.now() - this.started) / 1000.0; return this.info.duration> 0.0 && t> this.info.duration ? this.info.duration: t; } ended(): bool { return this.info.duration> 0.0 && this.time()> = this.info.duration; } paused(): bool { return this.started <0; } play(): void { if (this.started> = 0) { return; } this.started = Task.now(); const from = this.at; const url = this.url; const info = this.info; const start = this.started; const soundUrl = this.soundUrl ?? url; const pictureUrl = this.pictureUrl ?? url; if (info.audio) { this.voice = Audio.voice(); if (this.voice !== undefined) { this.voice!.volume(this.volumeLevel); const stop = Task.crossing<Stop>(1); this.stops.push(stop); const voice = this.voice!; Task.thread((): void => { sound(soundUrl, from, start, voice, stop); }); } } if (info.video && info.width> 0) { const frames = Task.crossing<Frame>(2); this.frames = frames; const stop = Task.crossing<Stop>(1); this.stops.push(stop); Task.thread((): void => { pictures(pictureUrl, from, start, info, frames, stop); }); } } pause(): void { if (this.started <0) { return; } this.at = this.time(); this.started = -1; for (const stop of this.stops) { Task.trySend(stop, { now: true }); } this.stops = []; if (this.frames !== undefined) { Task.close(this.frames!); this.frames = undefined; } if (this.voice !== undefined) { this.voice!.end(); this.voice = undefined; } } seek(seconds: f64): void { const playing = this.started> = 0; this.pause(); this.at = seconds <0.0 ? 0.0: seconds; if (playing) { this.play(); } } volume(level: f64): void { this.volumeLevel = level; if (this.voice !== undefined) { this.voice!.volume(level); } } next(): Option<Bitmap> { let out: Option<Bitmap> = undefined; if (this.frames === undefined) { return out; } let got = Task.tryReceive(this.frames!); while (got !== undefined) { out = got!.bitmap; got = Task.tryReceive(this.frames!); } return out; } }
```

A file or stream that plays.

- `url`: `string`
- `soundUrl`: `_gizlang_sdk_core.Option<string>` — Where its sound and its pictures are, when they are separate files (a page's MediaSource): its URL when
undefined. A video-only or audio-only file gives its one stream.
- `pictureUrl`: `_gizlang_sdk_core.Option<string>`
- `info`: `gizlang_media.Info`
- `at`: `f64` — Where the clock stood at the last play or pause, in seconds, and the monotonic ms when it last started (-1:
paused).
- `started`: `i64`
- `volumeLevel`: `f64`
- `stops`: `Vec<gizlang_task.Channel<gizlang_media.Stop>>`
- `frames`: `_gizlang_sdk_core.Option<gizlang_task.Channel<gizlang_media.Frame>>`
- `voice`: `_gizlang_sdk_core.Option<gizlang_audio.Voice>`

## Functions

### `probe`

```gizlang
function probe(url: string): Info throws string
```

What the file or stream at URL holds; throws why when ffprobe cannot read it (or is not installed).

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

### `decodeAudio`

```gizlang
function decodeAudio(data: bytes): bytes throws string
```

The sound of DATA (a whole audio or video file) as interleaved stereo f32 at 48 kHz; throws why ffmpeg cannot.

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

### `constructor`

```gizlang
constructor(url: string, info: Info)
```

A player of URL, which probe described as INFO, paused at its start.

Effects: fail, read, write, alloc.

## Methods

### `Player.time`

```gizlang
time(): f64
```

The clock: seconds into the media.

Effects: fail, read, io, alloc.

### `Player.ended`

```gizlang
ended(): bool
```

Whether it played to its end.

Effects: fail, read, io, alloc.

### `Player.paused`

```gizlang
paused(): bool
```

Whether it is paused (or not started).

Effects: fail, read.

### `Player.play`

```gizlang
play(): void
```

Plays from the clock's time.

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

### `Player.pause`

```gizlang
pause(): void
```

Stops the clock and the threads.

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

### `Player.seek`

```gizlang
seek(seconds: f64): void
```

Moves the clock to SECONDS, playing on from there if it played.

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

### `Player.volume`

```gizlang
volume(level: f64): void
```

Plays its sound at LEVEL, from 0 (silent) to 1 (as recorded).

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

### `Player.next`

```gizlang
next(): Option<Bitmap>
```

The picture due at the clock's time, when one came since the last call: the latest.

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

