> ## Documentation Index
> Fetch the complete documentation index at: https://assemblyai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Audio & volume

> Configure a voice agent's input and output audio encoding and playback volume.

A voice agent's audio configuration covers the input encoding (microphone), the output encoding (agent speech), and the playback volume. These fields live on the agent under `input.format`, `output.format`, and `output.volume`, set when you [create](/voice-agents/voice-agent-api/create-agent) or [update](/voice-agents/voice-agent-api/manage-agents) it, or inline over the WebSocket via [`session.update`](/voice-agents/voice-agent-api/session-configuration).

This page covers how to **configure** the encoding and volume. For how to actually stream and play the audio bytes, see [Stream audio](/voice-agents/voice-agent-api/audio-format).

## Encoding

The encoding determines the sample rate and bit depth. Input and output encodings are independent and can differ. Both default to `audio/pcm` (24 kHz) if omitted.

| Encoding     | Sample rate | Best for                                                 |
| ------------ | ----------- | -------------------------------------------------------- |
| `audio/pcm`  | 24,000 Hz   | Default. Highest quality, ideal for browser and app use. |
| `audio/pcmu` | 8,000 Hz    | Telephony (G.711 μ-law).                                 |
| `audio/pcma` | 8,000 Hz    | Telephony (G.711 A-law).                                 |

For telephony, use `audio/pcmu` or `audio/pcma` (8 kHz) to match the phone network and avoid resampling. See [Connect to Twilio](/voice-agents/voice-agent-api/connect-to-twilio) for a full phone integration.

Set `format.encoding` under `input` and `output`. You can also pass an explicit `sample_rate` inside `format`:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://agents.assemblyai.com/v1/agents \
    -H "Authorization: $ASSEMBLYAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Support Assistant",
      "system_prompt": "You are a friendly support agent. Keep replies under two sentences.",
      "voice": { "voice_id": "ivy" },
      "input":  { "format": { "encoding": "audio/pcmu", "sample_rate": 8000 } },
      "output": { "format": { "encoding": "audio/pcmu", "sample_rate": 8000 } }
    }'
  ```

  ```python Python theme={null}
  # pip install requests
  import os
  import requests

  resp = requests.post(
      "https://agents.assemblyai.com/v1/agents",
      headers={"Authorization": os.environ["ASSEMBLYAI_API_KEY"]},
      json={
          "name": "Support Assistant",
          "system_prompt": "You are a friendly support agent. Keep replies under two sentences.",
          "voice": {"voice_id": "ivy"},
          "input": {"format": {"encoding": "audio/pcmu", "sample_rate": 8000}},
          "output": {"format": {"encoding": "audio/pcmu", "sample_rate": 8000}},
      },
  )
  resp.raise_for_status()
  print(resp.json())
  ```

  ```javascript Node.js theme={null}
  // Node 18+ has fetch built in
  const res = await fetch("https://agents.assemblyai.com/v1/agents", {
    method: "POST",
    headers: {
      Authorization: process.env.ASSEMBLYAI_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Support Assistant",
      system_prompt: "You are a friendly support agent. Keep replies under two sentences.",
      voice: { voice_id: "ivy" },
      input: { format: { encoding: "audio/pcmu", sample_rate: 8000 } },
      output: { format: { encoding: "audio/pcmu", sample_rate: 8000 } },
    }),
  });
  const data = await res.json();
  console.log(data);
  ```
</CodeGroup>

| Field                    | Type    | Required | Notes                                                            |
| ------------------------ | ------- | -------- | ---------------------------------------------------------------- |
| `input.format.encoding`  | string  | No       | `audio/pcm`, `audio/pcmu`, or `audio/pcma`. Default `audio/pcm`. |
| `output.format.encoding` | string  | No       | Same values as input. Default `audio/pcm`.                       |
| `format.sample_rate`     | integer | No       | Sample rate in Hz. Determined by the encoding if omitted.        |

## Volume

Adjust the playback volume of the agent's speech via `output.volume`. Accepts a number from `0` (silent) to `100` (loudest). If omitted, the voice plays at its native level.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://agents.assemblyai.com/v1/agents/$AGENT_ID \
    -H "Authorization: $ASSEMBLYAI_API_KEY" -H "Content-Type: application/json" \
    -d '{ "output": { "volume": 60 } }'
  ```

  ```python Python theme={null}
  # pip install requests
  import os
  import requests

  resp = requests.put(
      f"https://agents.assemblyai.com/v1/agents/{os.environ['AGENT_ID']}",
      headers={"Authorization": os.environ["ASSEMBLYAI_API_KEY"]},
      json={"output": {"volume": 60}},
  )
  resp.raise_for_status()
  print(resp.json())
  ```

  ```javascript Node.js theme={null}
  // Node 18+ has fetch built in
  const res = await fetch(
    `https://agents.assemblyai.com/v1/agents/${process.env.AGENT_ID}`,
    {
      method: "PUT",
      headers: {
        Authorization: process.env.ASSEMBLYAI_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ output: { volume: 60 } }),
    },
  );
  const data = await res.json();
  console.log(data);
  ```
</CodeGroup>

| Field           | Type           | Required | Notes                                                          |
| --------------- | -------------- | -------- | -------------------------------------------------------------- |
| `output.volume` | number \| null | No       | `0` (silent) to `100` (loudest). `null` plays at native level. |

<Note>
  When configured **inline** via [`session.update`](/voice-agents/voice-agent-api/session-configuration#mutability-after-sessionready), `output.voice` and `output.format` are **immutable** after `session.ready` and must be set on your first update. `output.volume` is the exception: it can be changed mid-session, and the new value applies to subsequent `reply.audio` chunks.
</Note>