Skip to main content
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, card File). Long recordings and live conversation, which Voice does not do. A change that needs a decision (card Approval).

​
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). 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).
  • 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.
  • The note is null: rule voice.2.
  • A name comes back spelled wrongly: rule voice.3.
  • You look for yesterday’s transcript: rule voice.4.
  • A key is refused with a 403: rule voice.5.
  • A call is refused with a 402 that points to Billing: rule voice.6.
  • A call is refused with a 422 or a 503: rule voice.7.

​
Doors

​
Keep going

File · Collection · Credential · Project · Approval