# Frames

> The Frame base class, frame categories and common frame options, from @pipedog/core/frames/frames.

Source: https://polvallverdu.github.io/pipedog/docs/api/frames/



```ts
import { ControlFrame, DataFrame, Frame, SystemFrame } from "@pipedog/core/frames/frames";
```

See [Frames](https://polvallverdu.github.io/pipedog/docs/concepts/frames.md) for how the categories are processed.

## Frame [#frame]

The base class of every frame. Its fields are set automatically.

| Option | Type | Required | Description |
|---|---|---|---|
| `id` | `number` | yes |  |
| `name` | `string` | yes |  |
| `pts` | `number \| null` | yes |  |
| `broadcastSiblingId` | `number \| null` | yes |  |
| `metadata` | `Record<string, unknown>` | yes |  |
| `transportSource` | `string \| null` | yes |  |
| `transportDestination` | `string \| null` | yes |  |
| `interruptible` | `boolean` | yes |  |
| `toString` | `() => string` | yes |  |

## SystemFrame, DataFrame, ControlFrame [#systemframe-dataframe-controlframe]

The three base categories add no fields: they only decide how frames are queued and whether
interruptions drop them. `SystemFrame`s are processed with high priority and never dropped;
`DataFrame`s and `ControlFrame`s are processed in order and dropped on interruption unless
`interruptible` is `false`.

## TextFrame [#textframe]

| Option | Type | Required | Description |
|---|---|---|---|
| `text` | `string` | yes |  |
| `skipTts` | `boolean \| null` | yes |  |
| `includesInterFrameSpaces` | `boolean` | yes |  |
| `appendToContext` | `boolean` | yes |  |
| `toString` | `() => string` | yes |  |
| `id` | `number` | yes |  |
| `name` | `string` | yes |  |
| `pts` | `number \| null` | yes |  |
| `broadcastSiblingId` | `number \| null` | yes |  |
| `metadata` | `Record<string, unknown>` | yes |  |
| `transportSource` | `string \| null` | yes |  |
| `transportDestination` | `string \| null` | yes |  |
| `interruptible` | `boolean` | yes |  |

Constructor options:

| Option | Type | Required | Description |
|---|---|---|---|
| `text` | `string` | yes | The text content. |

## Audio frames [#audio-frames]

`InputAudioRawFrame` (a system frame) and `OutputAudioRawFrame` (a data frame) share the
`AudioRawFrame` mixin. Their options:

| Option | Type | Required | Description |
|---|---|---|---|
| `audio` | `Uint8Array<ArrayBufferLike>` | yes | Raw audio bytes in PCM format (16-bit little endian). |
| `sampleRate` | `number` | yes | Audio sample rate in Hz. |
| `numChannels` | `number` | yes | Number of audio channels. |

## Lifecycle frames [#lifecycle-frames]

`StartFrame` starts the pipeline. `EndFrame` (control, uninterruptible) ends it gracefully,
`CancelFrame` (system) stops it immediately; both take an optional `reason`:

| Option | Type | Required | Description |
|---|---|---|---|
| `reason` | `unknown` | no | Optional reason for pushing an end frame. |

## ErrorFrame [#errorframe]

| Option | Type | Required | Description |
|---|---|---|---|
| `error` | `string` | yes | Description of the error that occurred. |
| `processor` | `FrameProcessor \| null \| undefined` | no | The frame processor that generated the error. |
| `exception` | `unknown` | no | The exception that occurred. |
| `category` | `ErrorCategory \| null \| undefined` | no | What kind of failure this was. |

## MetricsFrame [#metricsframe]

| Option | Type | Required | Description |
|---|---|---|---|
| `data` | `MetricsData[]` | yes | List of metrics data collected by the processor. |