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

# Audio JS package

> Compress LiveKit Agents call recordings to Opus audio in Ogg files with @braintrust/audio v0.1.0, which the TypeScript SDK loads automatically.

> [!WARNING]
>
> **Early development notice:** `@braintrust/audio` is in early development (alpha). Expect backwards-incompatible changes between releases until v1.0.

The `@braintrust/audio` package compresses voice recordings that Braintrust instrumentation captures, such as [LiveKit Agents](https://docs.braintrust.dev/integrations/agent-frameworks/livekit-agents.md#audio-attachments-typescript-auto) call audio. With the package installed, recordings upload as Opus audio in Ogg files (`audio/ogg`) instead of raw PCM.

## Installation

We strongly recommend using `@braintrust/audio` to compress recordings and reduce upload size. Install the package alongside `braintrust` v3.41.0 or later. It requires Node.js 20 or later.

```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
npm install @braintrust/audio
```

```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pnpm add @braintrust/audio
```

## Quick start

Braintrust finds and loads `@braintrust/audio` from `node_modules` automatically, so you don't import it in your code. Once you [turn on LiveKit Agents audio recording](https://docs.braintrust.dev/integrations/agent-frameworks/livekit-agents.md#audio-attachments-typescript-auto) with `BRAINTRUST_CAPTURE_USER_AUDIO_ATTACHMENTS` or `BRAINTRUST_CAPTURE_AGENT_AUDIO_ATTACHMENTS`, recordings upload as Opus audio in Ogg files.

If you deploy a bundle without `node_modules`, import the package in your app so your bundler includes it:

```javascript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import "@braintrust/audio";
```

If the package is missing, fails to load, doesn't match your `braintrust` version, or the `audio` options contain an unsupported value, recordings upload as raw PCM and Braintrust logs a warning that explains why.

## Configuration

To change the encoding, pass `audio` options for the `livekit` integration to `configureInstrumentation()` from `braintrust/instrumentation`. Call it in a separate file, and load that file before the hook.

```javascript title="configure.mjs" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import { configureInstrumentation } from "braintrust/instrumentation";

configureInstrumentation({
  integrations: {
    livekit: {
      audio: {
        codec: { name: "opus", options: { bitrate: 32_000 } },
        container: { name: "ogg" },
      },
    },
  },
});
```

| Setting | Default | Description |
| - | - | - |
| `codec.name` | `"opus"` | `"opus"`, or `"pcm"` to always record raw PCM, even when `@braintrust/audio` is installed. |
| `codec.options.bitrate` | `64000` | Target bitrate in whole bits per second, from `500` to `512000`. |
| `codec.options.complexity` | `5` | Encoder effort, from `0` (fastest) to `10`. |
| `codec.options.application` | `"audio"` | Encoder tuning: `"audio"`, `"voip"` (favors speech), or `"lowdelay"`. |
| `container.name` | `"ogg"` | File format for Opus audio. `"ogg"` is the only value. |

See [Compress recordings](https://docs.braintrust.dev/integrations/agent-frameworks/livekit-agents.md#compress-recordings-typescript-auto) for how these settings apply to LiveKit Agents.

## Source code

For the complete source code, visit the [Braintrust JavaScript SDK repository](https://github.com/braintrustdata/braintrust-sdk-javascript/tree/main/integrations/audio).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.