# Transcription

> Real-time speech-to-text from the glasses microphone.

Source: https://docs.glassly.ai/app-devs/core-concepts/microphone/speech-to-text/

`session.transcription` turns what the user says into text. Register a handler and
you start getting results; the SDK handles the subscription for you.

```typescript
session.transcription.on((data) => {
  if (data.isFinal) {
    session.display.render([{type: "text", id: "msg", box: {x: 0, y: 0, w: 576, h: 288}, text: data.text}]);
  }
});
```

Transcription needs the `MICROPHONE` permission in your
[manifest](https://docs.glassly.ai/app-devs/core-concepts/miniapp-manifest.md). Without it the phone drops
the subscription, no events arrive, and [`onPermissionError`](https://docs.glassly.ai/app-devs/core-concepts/permissions.md#permission-errors) fires with
`PERMISSION_NOT_DECLARED`.

## Results

Each event is a `TranscriptionData`:

| Field | Type | Notes |
|---|---|---|
| `text` | `string` | The transcribed text so far. |
| `isFinal` | `boolean` | `false` for interim results that keep updating, `true` once the utterance is settled. |
| `language` | `string?` | The detected language (when auto-detecting). |
| `speakerId` | `string?` | A stable enrolled-speaker id (`spk_…`) when on-device voice recognition resolved the voice, otherwise the provider's anonymous diarization label, otherwise absent. `session.speakers` resolves an id to a display name (requires the `SPEAKERS` permission); display names never ride along with transcription events. |
| `isUser` | `boolean?` | On final segments only: `true` when on-device voice recognition confirms the device owner spoke, `false` for a confidently different voice, absent when there's no confident determination. |

Interim results stream as the user speaks and get replaced; wait for `isFinal` if
you only want settled text.

## Targeting languages

`on()` auto-detects the language. To listen for specific ones, use
`forLanguage()` with BCP-47 tags:

```typescript
// One language.
session.transcription.forLanguage("en-US", (data) => { /* … */ });

// Several at once.
session.transcription.forLanguage(["en-US", "es-ES"], (data) => { /* … */ });
```

Each call is independent, and you can have several active at the same time.

## Requiring on-device transcription

Pass `{forceLocal: true}` as the final argument to route that subscription
through on-device STT and suppress cloud transcript delivery:

```typescript
session.transcription.on(handler, {forceLocal: true});
session.transcription.forLanguage("en-US", handler, {forceLocal: true});
```

This requires a downloaded local STT model. Cloud transcripts are suppressed
for the local-only subscription, even while other miniapps continue using cloud
transcription. Routing is per listener, so a default listener on the same stream
can continue receiving cloud transcription.

## On-device fallback

When cloud transcription is unavailable, a default listener keeps receiving
results from the on-device model if one is downloaded. That covers a lost cloud
connection and the account's plan running out of transcription minutes. Pass
`{localFallback: false}` to receive nothing until the cloud is back instead:

```typescript
session.transcription.on(handler, {localFallback: false});
```

A quota stop leaves the cloud connection up, so check
[`session.cloud.isQuotaBlocked("transcription")`](https://docs.glassly.ai/app-devs/core-concepts/cloud.md)
to tell it apart from an outage. Hosts that predate `localFallback` always fall
back, and `forceLocal` ignores it.

## Configuring

`configure()` tunes the recognizer and applies to subsequent results. It
returns a promise that rejects if the runtime can't apply the config, so a
setting the platform silently ignored doesn't stay silent.

```typescript
await session.transcription.configure({
  languageHints: ["en", "ja"],     // ISO 639-1 hints to improve detection
  vocabulary: ["Glassly", "HIPAA"], // boost domain terms
  diarization: true,                // tag speakers when the provider supports it
});
```

Cloud transcription runs diarization unconditionally today, so `diarization`
has no effect there yet; it's accepted for forward compatibility with
providers where it's optional.

## Cleaning up

Every subscription returns an unsubscribe function. `stop()` tears down every
subscription this module owns at once:

```typescript
const off = session.transcription.on(handler);
off();                       // drop this one

session.transcription.stop(); // drop all of them
```

`session.transcription.hasPermission` tells you whether `MICROPHONE` is declared
in your manifest. It does not tell you whether the user granted the OS prompt: if
they denied it, your handler never fires. See
[Permissions](https://docs.glassly.ai/app-devs/core-concepts/permissions.md).

Transcription is for text. For raw audio frames or voice-activity detection, use
[`session.mic`](https://docs.glassly.ai/app-devs/core-concepts/microphone/audio-chunks.md). For translated
text, use [`session.translation`](https://docs.glassly.ai/app-devs/core-concepts/translation.md). Subscribing
to one does not subscribe you to the others.
