> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# Audio

Audio flows agent-side as raw bytes. The messaging system does no STT, transcoding, or VAD.

| Step | Direction       | Message                      | Notes                                          |
| ---- | --------------- | ---------------------------- | ---------------------------------------------- |
| 1    | Sidecar → agent | `AgentResponse.audio_config` | Format (encoding, sample rate, channels).      |
| 2    | Sidecar → agent | `AgentResponse.audio_chunk`  | Raw bytes. `done` marks end-of-utterance.      |
| 3    | Agent → sidecar | `AgentResponse.transcript`   | STT result; platform replaces the placeholder. |

#### Node

**`AudioStreamConfig`**

| Field            | Type   | Required | Notes                                                      |
| ---------------- | ------ | -------- | ---------------------------------------------------------- |
| `encoding`       | string | yes      | One of the `AudioEncoding` values below.                   |
| `sampleRate`     | number | yes      | Hz: 8000 (telephony), 16000 (speech), 48000 (browser).     |
| `channels`       | number | yes      | 1 = mono (speech default), 2 = stereo.                     |
| `language`       | string | no       | BCP-47 hint for STT (e.g. `en-US`).                        |
| `conversationId` | string | yes      | Links audio to a conversation.                             |
| `source`         | string | no       | Origin: `browser`, `twilio`, `vonage`, `mobile`, `upload`. |
| `userId`         | string | no       | Speaking user's identity.                                  |

**`AudioChunk`**

| Field      | Type                   | Required | Notes                                     |
| ---------- | ---------------------- | -------- | ----------------------------------------- |
| `data`     | `Buffer \| Uint8Array` | yes      | Raw audio bytes. Empty when `done: true`. |
| `sequence` | number                 | no       | Monotonic ordering counter.               |
| `done`     | boolean                | no       | `true` = end of segment, run STT now.     |

**`AudioEncoding`**

| Value       | Use                                       |
| ----------- | ----------------------------------------- |
| `LINEAR16`  | PCM signed 16-bit LE. Universal baseline. |
| `MULAW`     | G.711 mu-law. Twilio / telephony (8 kHz). |
| `OPUS`      | Raw Opus frames. Low-latency codec.       |
| `MP3`       | MP3. Batch uploads, pre-recorded.         |
| `WEBM_OPUS` | WebM/Opus. Browser MediaRecorder default. |
| `OGG_OPUS`  | OGG/Opus. Firefox MediaRecorder.          |
| `FLAC`      | FLAC lossless. High-quality uploads.      |
| `AAC`       | AAC. iOS native recording.                |

Use `audioAsReadable()` to feed Mastra's `voice.listen()`:

```typescript
import { audioEncodingToFiletype } from '@astropods/messaging';

conversation.on('audioConfig', async (config) => {
  const audioStream = conversation.audioAsReadable();
  const filetype = audioEncodingToFiletype(config.encoding);  // 'webm' for WEBM_OPUS
  const transcript = await agent.voice.listen(audioStream, { filetype });
  conversation.sendTranscript(config.conversationId, transcript);
});
```

#### Python

**`AudioStreamConfig`**

| Field             | Type   | Required | Notes                                                      |
| ----------------- | ------ | -------- | ---------------------------------------------------------- |
| `encoding`        | enum   | yes      | One of the `AudioEncoding` values below.                   |
| `sample_rate`     | int32  | yes      | Hz: 8000 (telephony), 16000 (speech), 48000 (browser).     |
| `channels`        | int32  | yes      | 1 = mono (speech default), 2 = stereo.                     |
| `language`        | string | no       | BCP-47 hint for STT (e.g. `en-US`).                        |
| `conversation_id` | string | yes      | Links audio to a conversation.                             |
| `source`          | string | no       | Origin: `browser`, `twilio`, `vonage`, `mobile`, `upload`. |
| `user_id`         | string | no       | Speaking user's identity.                                  |

**`AudioChunk`**

| Field      | Type  | Required | Notes                                    |
| ---------- | ----- | -------- | ---------------------------------------- |
| `data`     | bytes | yes      | Raw audio bytes. Empty when `done=True`. |
| `sequence` | int64 | no       | Monotonic ordering counter.              |
| `done`     | bool  | no       | `True` = end of segment, run STT now.    |

**`AudioEncoding`** (access via `AudioEncoding.LINEAR16` etc.)

| Value                            | Use                                       |
| -------------------------------- | ----------------------------------------- |
| `AUDIO_ENCODING_UNSPECIFIED` (0) | Do not use.                               |
| `LINEAR16` (1)                   | PCM signed 16-bit LE. Universal baseline. |
| `MULAW` (2)                      | G.711 mu-law. Twilio / telephony (8 kHz). |
| `OPUS` (3)                       | Raw Opus frames. Low-latency codec.       |
| `MP3` (4)                        | MP3. Batch uploads, pre-recorded.         |
| `WEBM_OPUS` (5)                  | WebM/Opus. Browser MediaRecorder default. |
| `OGG_OPUS` (6)                   | OGG/Opus. Firefox MediaRecorder.          |
| `FLAC` (7)                       | FLAC lossless. High-quality uploads.      |
| `AAC` (8)                        | AAC. iOS native recording.                |

Buffer chunks per conversation and run STT when `done` arrives. See the [web worked example](/messaging-sdk/examples#web-chat) for a complete loop.

## Next steps

* [Sending a response](/messaging-sdk/responses): the `Transcript` shape you send back
* [Worked examples](/messaging-sdk/examples): audio handling inside a browser-chat agent