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

# Voice

> Voice turns one short recording into its transcript and, on request, a note in the speaker's own words. It keeps neither the recording nor the text. It uses the plan's file-processing allowance and charges no credits.

Concept · files

> **Use when**
>
> A person says a note instead of typing it, for example what new Files are and how to tag them. Also when you must turn a short recording into words.

> **Looking for something else?**
>
> Reading or searching audio Files already in the project (card [Search](https://docs.pnbr.io/concepts/search.md), card [File](https://docs.pnbr.io/concepts/file.md)). Long recordings and live conversation, which Voice does not do. A change that needs a decision (card [Approval](https://docs.pnbr.io/concepts/approval.md)).

## For

Voice listens to one recording and gives back what was said. The transcript is
the words, with clean punctuation. A note is the speaker's own sentences, cleaned of filler and false
starts, with every name, number, date and requested tag kept exactly as
spoken. The first use is the Note field of an upload. A person says "these are
all Global Leadership Summit decks, tag them GLS". They read the note and edit
it. It then steers how Penumbra files the new Files (card [File](https://docs.pnbr.io/concepts/file.md)).

Penumbra adds the project's own words to what it listens for. These are the
labels of the project's organizer setup and the names of its collections (card
collection). Your own terms come first. Voice stores nothing about the
recording. It writes one row of counts that the plan's allowance reads.

## Use when

* A person wants to say a note instead of typing it.
* You hold a short recording and need its words.
* A name or tag must be spelled the way the project spells it.

## Not this

* Audio Files that are already in the project: search them or read them (card
  search, card [File](https://docs.pnbr.io/concepts/file.md)).
* A call or a conversation: Voice takes one finished recording, not a stream.
* A recording over 4 MiB, about four minutes: make a shorter one.

## Rules

1. `voice.1` One call takes one recording of at most 4 MiB, as webm, ogg, mp4,
   m4a, mp3 or wav. **Enforced:** the API reads the first bytes. It refuses a
   recording that is not its declared type with `audio_type_unsupported` (415),
   an empty one with `audio_empty` and a larger one with `audio_too_large`
   (413). **Your job:** the SDK refuses these before it sends. Fix the file and
   send it again.
2. `voice.2` Ask for a note only when you want one. **Your job:** the default is
   the transcript alone. Pass `purpose: "note"` to also get a short note. The
   note is `null` when you did not ask.
3. `voice.3` Name the terms that must be spelled right. **Your job:** pass up to
   50 terms of at most 100 characters each, as `vocabulary`. **Enforced:**
   Penumbra adds the project's organizer
   labels and collection names after yours, drops repeats and stops at 100 terms.
4. `voice.4` Nothing about the recording is kept. **Enforced:** Voice stores
   neither the audio nor the text and writes neither to a log. **Your job:** keep
   the text yourself if you need it. A second call listens again and may word
   it differently.
5. `voice.5` Voice needs authority to add Files. **Enforced:** a project editor,
   admin or owner may use it. A key needs `voice.audio.transcribe`,
   `files.file.inspect` and `workspace.collection.list`, because Voice reads
   the project's words as the caller. A viewer, a key without the scope and any
   access limited to a View are refused with `voice_transcribe_requires_editor`
   or `voice_transcribe_requires_scope` (403).
6. `voice.6` Voice uses the plan's file-processing allowance and no credits.
   **Enforced:** when the period's allowance is used up and no credit is left,
   nothing is sent. The call answers `platform_allowance_exhausted` (402) and
   points to Billing. A failed call is not counted. **Your job:** tell the
   person to type the note, or to add credit or wait for the next period.
7. `voice.7` Read the answer before you send again. **Enforced:** a recording
   with no human voice in it answers `audio_no_speech` (422), and one that the
   model declines answers `audio_refused` (422). Make a new recording for
   either. A `language` the model does not take answers `language_unsupported`
   (422, field `language`): leave `language` out, or send a supported BCP-47
   code such as `en-US`. When Voice cannot listen, it answers `voice_unavailable` (503) with
   `retry_after_seconds`, and nothing was kept. **Your job:** wait that long and
   send the same recording again.
8. `voice.8` A person reads the note before it is used. **Your job:** show the
   person the note and let them edit it. A transcript can mishear a name, and a
   note that steers how Files are tagged should say what the person meant.

## Failure signs

* A call is refused as too large or the wrong type: rule [voice.1](https://docs.pnbr.io/concepts/voice.md#rule-voice-1).
* The note is `null`: rule [voice.2](https://docs.pnbr.io/concepts/voice.md#rule-voice-2).
* A name comes back spelled wrongly: rule [voice.3](https://docs.pnbr.io/concepts/voice.md#rule-voice-3).
* You look for yesterday's transcript: rule [voice.4](https://docs.pnbr.io/concepts/voice.md#rule-voice-4).
* A key is refused with a 403: rule [voice.5](https://docs.pnbr.io/concepts/voice.md#rule-voice-5).
* A call is refused with a 402 that points to Billing: rule [voice.6](https://docs.pnbr.io/concepts/voice.md#rule-voice-6).
* A call is refused with a 422 or a 503: rule [voice.7](https://docs.pnbr.io/concepts/voice.md#rule-voice-7).

## Doors

| Door | Call |
| - | - |
| SDK | `project.voice.transcribe(audio, { purpose, language, vocabulary, contentType })` |
| HTTP | `POST /v1/orgs/{org}/projects/{project}/voice/transcriptions`, a multipart form with the part `audio` |
| CLI | No command. Voice capture is an App and SDK surface by design. |
| MCP | No tool. No Kit names the scope. |

## Keep going

[File](https://docs.pnbr.io/concepts/file.md) · [Collection](https://docs.pnbr.io/concepts/collection.md) · [Credential](https://docs.pnbr.io/concepts/credential.md) · [Project](https://docs.pnbr.io/concepts/project.md) · [Approval](https://docs.pnbr.io/concepts/approval.md)

Penumbra Grammar 0.6.26


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