# Voice Transcription

Voice notes can be transcribed automatically. When a message with a voice recording is sent to a channel that has voice transcription turned on, Stream converts the speech to text in the background and stores the text on the recording's attachment. Clients receive it through a `message.updated` event, and it is part of the message in every later read.

**Voice transcription is in beta.** Stream enables it per app: [contact support](https://getstream.io/contact/support/) to turn it on.

Transcripts let people read a voice note when they can't play audio, and make voice notes accessible to users who are deaf or hard of hearing.

## How it works

1. A user sends a message with a `voiceRecording` [attachment](https://getstream.io/chat/docs/unity/send-message/#sending-messages-with-attachments). Stream's iOS, Android, React Native and React SDKs send recorded voice notes this way. The attachment needs an `asset_url`, usually the URL of a [file uploaded to Stream](https://getstream.io/chat/docs/unity/file-uploads/).

2. The message is delivered right away, as usual, without a transcript.

3. Stream transcribes the recording in the background. The transcript usually arrives shortly after the message itself.

4. The transcript is saved on the attachment as `voice_transcript`, and a `message.updated` event is sent to the channel (and to your webhooks) with the updated message. This event does not send a push notification.

Each voice recording in a message is transcribed separately. Messages in threads are transcribed like any other message.

## Enabling voice transcription

Voice transcription is off by default. Two settings must both be on:

1. **For your app.** Voice transcription has to be enabled for your app by Stream. [Contact support](https://getstream.io/contact/support/) to turn it on.

2. **For the channel type.** Set `voice_transcription` to `true` on each channel type whose voice notes you want transcribed. It is `false` for every built-in channel type.

```csharp label="C#"
await chat.UpdateChannelTypeAsync("messaging", new UpdateChannelTypeRequest
{
    VoiceTranscription = true,
});
```

### Turning it on or off for a single channel

A channel can override the channel type setting in either direction with `config_overrides.voice_transcription`. For example, keep it off for the channel type and turn it on only for selected channels. See [Channel-level settings](https://getstream.io/chat/docs/node/channel-level-settings/) for how overrides work.

```csharp label="C#"
await chat.UpdateChannelPartialAsync("<channel-type>", "<channel-id>", new UpdateChannelPartialRequest
{
    Set = new Dictionary<string, object>
    {
        { "config_overrides", new Dictionary<string, object> { { "voice_transcription", true } } },
    },
});
```

Turning voice transcription on does not transcribe voice notes that are already in the channel. Turning it off also stops transcriptions that are still pending.

## The transcript

The transcript is stored in the `voice_transcript` field of the voice recording attachment. This is how a message with a transcribed voice note looks, for example in the `message.updated` event or when you query the channel:

```json label="JSON"
{
  "id": "4f0c0a62-2f3b-4f6b-9a4d-1b7d5f0f3c21",
  "cid": "messaging:general",
  "type": "regular",
  "text": "",
  "user": { "id": "jane", "name": "Jane" },
  "created_at": "2026-11-13T09:41:07.123Z",
  "updated_at": "2026-11-13T09:41:08.456Z",
  "attachments": [
    {
      "type": "voiceRecording",
      "asset_url": "https://us-east.stream-io-cdn.com/.../voice-note.aac",
      "mime_type": "audio/aac",
      "file_size": 48213,
      "duration": 4.2,
      "voice_transcript": {
        "text": "Running ten minutes late, start without me.",
        "languages": [{ "code": "en" }]
      }
    }
  ]
}
```

| Field       | Type   | Description                                                                                     |
| ----------- | ------ | ----------------------------------------------------------------------------------------------- |
| `text`      | string | The transcribed text. Left out if the recording could not be transcribed or contains no speech. |
| `languages` | array  | The languages detected in the recording, as objects with a language `code` (for example `en`).  |
| `error`     | string | Set instead of `text` when the recording could not be transcribed. See [Errors](#errors) below. |

An attachment without a `voice_transcript` field has not been transcribed yet, or transcription is not enabled for its channel.

To show transcripts in your app, read `voice_transcript` from the voice recording attachment when you render the message, and re-render when the `message.updated` event for that message arrives.

### Errors

When a recording can't be transcribed, `voice_transcript.error` is set to one of these values. The message still gets a `message.updated` event, so your UI can stop waiting for a transcript.

| Error                | Meaning                                                                                                                     |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `unsupported_format` | The audio could not be decoded.                                                                                             |
| `too_large`          | The recording is larger than 25 MiB.                                                                                        |
| `fetch_failed`       | The file could not be downloaded from its `asset_url`, for example because the file was deleted or access to it was denied. |
| `invalid_response`   | The speech-to-text service returned a result that could not be used.                                                        |

These errors are final for that recording. Treat any other `error` value the same way, as a recording that could not be transcribed. Temporary problems, such as network errors or an outage of the file host or the speech-to-text service, are retried automatically and are not stored as errors. If the retries also fail, the attachment is left without a `voice_transcript`.

## Messages that are not transcribed

- Attachments of any type other than `voiceRecording`, and voice recordings without an `asset_url`.
- Messages in channels where voice transcription is off.
- Deleted messages, including messages deleted before their transcription finished.
- Messages that are not of type `regular` or `reply`, for example messages blocked by moderation, system messages and error messages.

## Editing messages

The transcript is managed by Stream. Clients can't set or change it: a `voice_transcript` sent in a request is ignored.

When a message is edited and the voice recording stays the same file, the transcript is kept, even though clients send the attachment back without it or with a newly signed `asset_url`. If the edit replaces the recording with a different file, the new file is transcribed.

If you already store your own transcript in a custom attachment field such as `transcript`, it is not affected.

## Supported formats and limits

- Recordings can be up to 25 MiB.
- The AAC voice notes recorded by Stream's iOS, Android and React Native SDKs are supported, as are common audio formats such as M4A, MP4, MP3, WAV, WebM, OGG and FLAC.
- The language is detected automatically. You don't need to set a language on the user or the channel.
- Transcription is not limited to a fixed list of languages. Stream does not restrict which languages are transcribed.

## Exports and usage

[Channel exports](https://getstream.io/chat/docs/node/exporting-channels/) include `voice_transcript` on voice recording attachments.

Voice transcription usage is measured in seconds of transcribed audio and reported as `transcription_seconds`. Each recording is rounded up to the next whole second.

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/unity/voice-transcription/](https://getstream.io/chat/docs/unity/voice-transcription/).