> For a complete page index of the Captain API documentation, fetch https://docs.captain.dev/llms.txt?excludeSpec=true

# Audio

> How Captain indexes audio files. Clips of up to 80 seconds, each with a transcript and a short description of the sound, so podcasts, calls and recordings are searchable by what was said.

## Agent Quick Reference - Audio

* Extensions: `.mp3`, `.wav`, `.m4a`, `.ogg`, `.flac`, `.aac`, `.wma`. Normalised to a standard MP3 first (short MP3 and WAV files skip this).
* Segmented into contiguous clips of up to 80 s (fixed windows). Each clip gets one native embedding from the audio itself, a transcript slice, and a short description: for speech, the kind of recording and character of the speech; for music, genre, mood, instruments, tempo and vocals. The description never invents dialogue or lyrics.
* Transcript: one speech-to-text pass over the whole file, language detected automatically; force it with `transcription_language`. Word timings slice it per clip. No speaker labels.
* Query hit: `modality: "audio"`, content `[Audio: name]` + description + `Transcript: …`; time range at `location.start_seconds` / `location.end_seconds` (v3) or `metadata.startSec` / `endSec` (v2).
* Billing: 5 credits per minute of audio. Upload limits by route on File Size Limits.
* `mask_pii`: audio is not masked. A request with `mask_pii: true` skips audio files: they are not indexed, and the job lists them as skipped.

Captain indexes audio as clips of up to 80 seconds. Each clip has a time range, a native
embedding of the audio, a transcript slice and a short description of the sound. This page
covers how a file is cut, what each clip contains, what a result contains, and the limits.

## This is useful for

* Sales and support calls, where a sentence and its playback offset are the answer
* Podcasts and meeting recordings, searchable by anything said in them
* Voice notes and dictation from the field
* Music and sound libraries, found by how they sound rather than by a file name

## What one file becomes

The file is normalised to a standard MP3 (short MP3 and WAV files skip that step) and cut
into contiguous clips of up to 80 seconds. Each clip gets a native embedding of the audio,
a transcript slice and a short description, stored together on one record.

## How audio is chunked

#### Clips with a time range

Clips are contiguous 80-second windows; the last one is shorter. The window is shorter
than for video because there is no picture to locate a moment by. Every clip carries
`location.start_seconds` and `location.end_seconds` on the v3 query, or
`metadata.startSec` and `metadata.endSec` on v2.

#### Transcript

Speech-to-text runs once over the whole file. Word timings give each clip the words
spoken inside its window. Language is detected automatically, or set with
`transcription_language`. There are no speaker labels.

#### Description

Each clip's description states what kind of recording it is and the character of the
speech. For music it states genre, mood, instruments, tempo and vocals. The description
does not contain dialogue or lyrics; spoken words are in the transcript.

#### Two signals on one record

The native embedding matches the sound (a jingle, a siren, a style of music). The
transcript and description are stored as text on the same record. The result text is
`[Audio: file name]`, then the description, then `Transcript: …`.

## Limits and billing

Audio is billed at 5 credits per minute, summed per job. Size limits depend on the route: 100
MB through the direct upload endpoint, 500 MB from the dashboard, and no upload limit from a
cloud storage connector. A two-hour recording is usually under 100 MB as MP3 and over it as
WAV; send WAV files from a bucket or the dashboard. Collections that contain media rerank by
default; see [Multimodal Search](/guides/multimodal-search) and
[File Size Limits](/guides/file-size-limits).

## Examples

#### What was said about the renewal price

Goal: return the clip of a sales call where pricing was discussed, with the offset to
play from.

**`request`**

```json title="request"
{
  "query": "renewal price increase",
  "limit": 3,
  "filter": {
    "account": {
      "$eq": "northwind"
    }
  }
}
```

**`result (one item)`**

```json title="result (one item)"
{
  "modality": "audio",
  "text": "[Audio: 2026-09-12-northwind.mp3]\nSpeech: a two-person business call, calm, one speaker doing most of the talking.\nTranscript: ...so the renewal would come in at eight percent above this year's rate, which we can hold flat if you commit to two years...",
  "location": {
    "start_seconds": 1520.0,
    "end_seconds": 1600.0
  }
}
```

The transcript slice contains the words. `location.start_seconds` is the playback
offset.

#### A podcast archive

Goal: search a set of episodes by what was said, with no single episode taking the whole
result page.

**`request`**

```json title="request"
{
  "query": "why they moved off the monolith",
  "limit": 5,
  "max_chunks_per_document": 2
}
```

The transcript text matches the question. `max_chunks_per_document` limits each episode
to two clips in the result. The description marks intro music as music, so it can be
filtered out.

#### A music library with no lyrics

Goal: find tracks by how they sound.

**`request`**

```json title="request"
{
  "query": "upbeat acoustic guitar, no vocals",
  "limit": 10
}
```

The native embedding matches the sound, and the description names the genre and
instruments as text.

See [Supported File Types](/guides/supported-file-types#audio) for the extension table and
[Video](/guides/file-types/video) for files with a picture.