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

# API Reference

> Properties, methods, and events for every Dictation Web Component

Complete API documentation for all components in the Corti Dictation Web Component library.

## Component Overview

The library provides two ways to use components:

1. **`<corti-dictation>`** - Opinionated, all-in-one component (recommended for most use cases)
2. **Modular Components** - Individual components for custom UI implementations

<Warning>Modular components (`dictation-recording-button`, `dictation-settings-menu`, `dictation-device-selector`, `dictation-language-selector`) **require** a `<dictation-root>` parent component to provide context. They cannot be used standalone.</Warning>

## Events

<Info>Events should be subscribed to on `<corti-dictation>` or `<dictation-root>` components only. Individual modular components do not dispatch these events directly.</Info>

All events bubble and can be listened to on the root component:

| Event | Description | Detail |
| - | - | - |
| `ready` | Fired once the component is ready. | No detail |
| `recording-state-changed` | Fired when the recording state changes. | `detail.state` (string): The new recording state. One of: `"stopped"`, `"recording"`, `"initializing"`, `"stopping"`<br />`detail.connection` (string, optional): WebSocket connection state. One of: `"CONNECTING"`, `"OPEN"`, `"CLOSING"`, `"CLOSED"`, or `null`<br />`detail.processing` (boolean, optional): Whether audio is still being processed by the server. When `true`, the server is still processing previously sent audio and may send back additional transcript events even after recording has stopped |
| `recording-devices-changed` | Fired when the user switches recording devices or the list of recording devices changes. | `detail.devices` (MediaDeviceInfo\[]): Full list of available recording devices<br />`detail.selectedDevice` (MediaDeviceInfo): Currently selected device |
| `languages-changed` | Fired when the list of available languages changes or a language is selected. | `detail.languages` (string\[]): Array of available language codes<br />`detail.selectedLanguage` (string): Currently selected language code |
| `language-changed` | **⚠️ DEPRECATED** - Fired when the selected language changes. Use `languages-changed` instead. | `detail.language` (string): The selected language code |
| `transcript` | Fired when a new transcript is received. | `detail.type` (string): Always `"transcript"`<br />`detail.data.text` (string): Transcript with punctuation applied and command phrases removed<br />`detail.data.rawTranscriptText` (string): Raw transcript without punctuation or command phrase removal<br />`detail.data.start` (number): Start time of the transcript segment in seconds<br />`detail.data.end` (number): End time of the transcript segment in seconds<br />`detail.data.isFinal` (boolean): Whether this is a final transcript (false indicates interim result) |
| `command` | Fired whenever a new command is detected. | `detail.type` (string): Always `"command"`<br />`detail.data.id` (string): Command identifier<br />`detail.data.variables` (object, optional): Command variables as key-value pairs, where values can be string or null<br />`detail.data.rawTranscriptText` (string): Raw transcript text that triggered the command<br />`detail.data.start` (number): Start time of the command segment in seconds<br />`detail.data.end` (number): End time of the command segment in seconds |
| `audio-level-changed` | Fired when the input audio level changes. | `detail.audioLevel` (number): The current audio level, ranging from 0 to 1 |
| `audio-event` | Fired when an audio health event is received from the server (e.g. silence detection, noise level warnings). | `detail.type` (string): Always `"audioEvent"`<br />`detail.event` (string): The audio event type (e.g. `"speechQualityIssueDetected"`, `"speechQualityIssueRecovered"`, `"longSilenceDetected"`, `"longSilenceRecovered"`)<br />`detail.message` (string, optional): Human-readable description of the event |
| `usage` | Fired when usage information is received from the server. | `detail.type` (string): Always `"usage"`<br />`detail.credits` (number): The amount of credits used for this stream |
| `delta-usage` | Fired when incremental usage information is received while the stream is active. | `detail.type` (string): Always `"delta_usage"`<br />`detail.credits` (number): Approximate credits consumed since recording started |
| `network-activity` | Fired when network activity occurs (data sent or received). | `detail.direction` (string): Direction of network activity, either `"sent"` or `"received"`<br />`detail.data` (unknown): The data that was sent or received |
| `stream-closed` | **⚠️ DEPRECATED** - Fired when the WebSocket stream is closed. Use `recording-state-changed` event with `detail.connection` field instead. | `detail` (unknown): WebSocket close event data, typically containing close code and reason |
| `error` | Fired on error. | `detail.message` (string): Error message describing what went wrong |
| `keybinding-changed` | Fired when the keybinding configuration changes. | `detail.key` (string \| null \| undefined): The raw key from the keyboard event (e.g., `"k"`, `"Meta"`, ``"`"``)<br />`detail.code` (string \| null \| undefined): The raw code from the keyboard event (e.g., `"KeyK"`, `"MetaLeft"`, `"Backquote"`)<br />`detail.keybinding` (string \| null): The normalized keybinding value displayed in the UI (e.g., `"k"`, `"Cmd"` on Mac, `"Space"`)<br />`detail.type` (string \| undefined): The type of keybinding, either `"push-to-talk"` or `"toggle-to-talk"` |
| `keybinding-activated` | Fired when a keybinding is activated (key pressed). This event is cancelable - call `event.preventDefault()` to prevent the keybinding from triggering recording. | `detail.keyboardEvent` (KeyboardEvent): The original keyboard event that triggered the keybinding. |

***

## `<corti-dictation>`

The main opinionated component that includes all functionality with a built-in UI.

### Properties

| Property | Type | Attribute | Writable | Default | Required | Description |
| - | - | - | - | - | - | - |
| `accessToken` | String | `accessToken` | ✅ | - | ✅\* | Latest access token for authentication.<br />Required if no other authentication or proxy methods provided. |
| `authConfig` | Object | - | ✅ | - | ✅\* | Authentication configuration with optional refresh mechanism.<br />Must be set via JavaScript property.<br />Required if no other authentication or proxy methods provided. |
| `socketUrl` | String | `socketUrl` | ✅ | - | ✅\* | WebSocket URL for proxy connection.<br />When provided, uses proxy client instead of direct client.<br />Required if no other authentication or proxy methods provided. |
| `socketProxy` | Object | - | ✅ | - | ✅\* | Socket proxy configuration object.<br />Must be set via JavaScript property.<br />Required if no other authentication or proxy methods provided. |
| `analytics` | Object | - | ✅ | - | ❌ | Extra keys on [`x-corti-analytics`](/sdk/js/overview#analytics).<br />Must be set via JavaScript property.<br />Keys and values are lowercased.<br />`web_component` (`@corti/dictation-web`) and `web_component_version` are reserved. |
| `devices` | Array | - | ✅ | `auto-loaded` | ❌ | List of all available recording devices (MediaDeviceInfo\[]).<br />Auto-loaded asynchronously from browser's audio input devices. Must be set via JavaScript property. |
| `selectedDevice` | Object | - | ✅ | - | ❌ | The selected device used for recording (MediaDeviceInfo).<br />Must be set via JavaScript property. |
| `recordingState` | String | - | ❌ | `"stopped"` | ❌ | Current state of recording: `"stopped"`, `"recording"`, `"initializing"`, `"stopping"`. |
| `version` | String | - | ❌ | package version | ❌ | Installed package version. Read-only. Not an HTML attribute. |
| `dictationConfig` | [`TranscribeConfig`](/api-reference/transcribe) | - | ✅ | `{ automaticPunctuation: false, primaryLanguage: "en", spokenPunctuation: true }` | ❌ | Transcription config. Must be set via JavaScript property. |
| `settingsEnabled` | String\[] | `settingsEnabled` | ✅ | `["device", "language"]` | ❌ | Which settings should be available in the UI.<br />If empty, settings are disabled.<br />Options: `"device"`, `"language"`, `"keybinding"`. |
| `languagesSupported` | String\[] | `languagesSupported` | ✅ | from [`GET /languages/`](/api-reference/languages/list-languages) | ❌ | Language codes shown in the selector.<br />Loaded with `endpoint=transcribe` when authenticated.<br />Falls back to the region list if there is no auth or the request fails.<br />Set this to use your own list. |
| `pushToTalkKeybinding` | String | `pushToTalkKeybinding` | ✅ | `"Space"` (if in settingsEnabled) | ❌ | Push-to-talk keyboard shortcut.<br />Keydown starts recording, keyup stops recording.<br />Single key only.<br />**Note:** If both keybindings are set to the same key, toggle-to-talk takes priority. |
| `toggleToTalkKeybinding` | String | `toggleToTalkKeybinding` | ✅ | `"Enter"` (if in settingsEnabled) | ❌ | Toggle-to-talk keyboard shortcut.<br />Pressing the key toggles recording on/off.<br />Single key only.<br />**Note:** If both keybindings are set to the same key, toggle-to-talk takes priority. |
| `debug_displayAudio` | Boolean | `debug-display-audio` | ✅ | `false` | ❌ | Overrides device selection and uses getDisplayMedia to stream system audio.<br />Should only be used for debugging. |
| `allowButtonFocus` | Boolean | `allowButtonFocus` | ✅ | `false` | ❌ | When `false` (default), prevents the start/stop button from taking focus when clicked.<br />Set to `true` to allow focus. |

### Methods

| Method | Description |
| - | - |
| `startRecording()` | Starts a recording. |
| `stopRecording()` | Stops a recording. |
| `toggleRecording()` | Starts or stops recording. Convenience method. |
| `openConnection()` | Opens the WebSocket connection to the server without starting recording.<br />**Default behavior:** The connection opens automatically when the user clicks to start recording for the first time.<br />**When to use:** Pre-establish the connection before recording starts (e.g., to reduce first-record latency).<br />Can only be called when recording is stopped and all audio processing is complete. Returns a Promise. |
| `closeConnection()` | Properly closes the WebSocket connection by sending an `"end"` message and waiting for the `"ended"` response.<br />**Default behavior:** The connection opens automatically on first recording and remains open after recording stops for reuse.<br />**When to use:** Receive `"usage"` stats (between `"end"` and `"ended"`), or when you're completely done (unmount, navigation, freeing resources).<br />Can only be called when recording is stopped and all audio processing is complete. Returns a Promise. |
| `setAccessToken(token: string)` | **⚠️ DEPRECATED** - Sets the access token. Use `accessToken` property instead. |
| `setAuthConfig(config: BearerOptions)` | **⚠️ DEPRECATED** - Sets the auth configuration. Use `authConfig` property instead. |

***

## `<dictation-root>`

Context provider component that manages authentication, configuration, and shared state. Required parent for all modular components.

<Warning>All modular components must be children of `<dictation-root>` to receive context.</Warning>

### Properties

| Property | Type | Attribute | Writable | Default | Required | Description |
| - | - | - | - | - | - | - |
| `accessToken` | String | `accessToken` | ✅ | - | ✅\* | Latest access token for authentication. Required if no other authentication or proxy methods provided. |
| `authConfig` | Object | - | ✅ | - | ✅\* | Authentication configuration with optional refresh mechanism. Must be set via JavaScript property. Required if no other authentication or proxy methods provided. |
| `socketUrl` | String | `socketUrl` | ✅ | - | ✅\* | WebSocket URL for proxy connection. When provided, uses proxy client instead of direct client. Required if no other authentication or proxy methods provided. |
| `socketProxy` | Object | - | ✅ | - | ✅\* | Socket proxy configuration object. Must be set via JavaScript property. Required if no other authentication or proxy methods provided. |
| `analytics` | Object | - | ✅ | - | ❌ | Extra keys on [`x-corti-analytics`](/sdk/js/overview#analytics). Must be set via JavaScript property. Keys and values are lowercased. `web_component` (`@corti/dictation-web`) and `web_component_version` are reserved. |
| `dictationConfig` | [`TranscribeConfig`](/api-reference/transcribe) | - | ✅ | `{ automaticPunctuation: false, primaryLanguage: "en", spokenPunctuation: true }` | ❌ | Transcription config. Must be set via JavaScript property. |
| `languages` | String\[] | `languages` | ✅ | from [`GET /languages/`](/api-reference/languages/list-languages) | ❌ | Language codes shown in the selector. Loaded with `endpoint=transcribe` when authenticated. Falls back to the region list if there is no auth or the request fails. Set this to use your own list. |
| `devices` | Array | - | ✅ | `auto-loaded` | ❌ | List of all available recording devices (MediaDeviceInfo\[]). Auto-loaded asynchronously from browser's available audio input devices. Must be set via JavaScript property. |
| `selectedDevice` | Object | - | ✅ | - | ❌ | The selected device used for recording (MediaDeviceInfo). Must be set via JavaScript property. |
| `recordingState` | String | - | ❌ | `"stopped"` | ❌ | Current state of recording: `"stopped"`, `"recording"`, `"initializing"`, `"stopping"`. |
| `version` | String | - | ❌ | package version | ❌ | Installed package version. Read-only. Not an HTML attribute. |
| `pushToTalkKeybinding` | String | `pushToTalkKeybinding` | ✅ | `"Space"` (if in settingsEnabled) | ❌ | Push-to-talk keyboard shortcut. Keydown starts recording, keyup stops recording. Single key only (e.g., `"Space"`, `"k"`, `"meta"`, `"ctrl"`, `"KeyK"`, `"Space"`). Supports both key names (from `event.key`) and key codes (from `event.code`). Combinations are not supported. **Note:** If both keybindings are set to the same key, toggle-to-talk takes priority. |
| `toggleToTalkKeybinding` | String | `toggleToTalkKeybinding` | ✅ | `"Enter"` (if in settingsEnabled) | ❌ | Toggle-to-talk keyboard shortcut. Pressing the key toggles recording on/off. Single key only (e.g., `` ` ``, `"k"`, `"meta"`, `"ctrl"`, `"KeyK"`, `"Backquote"`). Supports both key names (from `event.key`) and key codes (from `event.code`). Combinations are not supported. **Note:** If both keybindings are set to the same key, toggle-to-talk takes priority. |
| `debug_displayAudio` | Boolean | `debug-display-audio` | ✅ | - | ❌ | Overrides device selection and uses getDisplayMedia to stream system audio. Should only be used for debugging. |
| `noWrapper` | Boolean | `noWrapper` | ✅ | `false` | ❌ | When `true`, removes the default wrapper styling. Useful for custom layouts. |

***

## `<dictation-recording-button>`

Standalone recording button component with audio visualization.

<Warning>Must be a child of `<dictation-root>`.</Warning>

### Properties

| Property | Type | Attribute | Writable | Default | Required | Description |
| - | - | - | - | - | - | - |
| `allowButtonFocus` | Boolean | `allowButtonFocus` | ✅ | `false` | ❌ | When `false` (default), prevents the button from taking focus when clicked. Set to `true` to allow focus. |

### Methods

| Method | Description |
| - | - |
| `startRecording()` | Starts a recording. |
| `stopRecording()` | Stops a recording. |
| `toggleRecording()` | Starts or stops recording. Convenience method. |
| `openConnection()` | Opens the WebSocket connection to the server without starting recording.<br />**Default behavior:** Opens automatically on the first user action to start recording.<br />**When to use:** Pre-establish before recording starts (e.g., reduce first-record latency).<br />Can only be called when recording is stopped and all audio processing is complete. Returns a Promise. |
| `closeConnection()` | Properly closes the WebSocket connection by sending an "end" message and waiting for the "ended" response.<br />**Default behavior:** The connection opens automatically on first recording and remains open after recording stops for reuse.<br />**When to use:** Receive "usage" stats (between "end" and "ended"), or when you're completely done (unmount, navigation, freeing resources).<br />Can only be called when recording is stopped and all audio processing is complete. Returns a Promise. |

***

## `<dictation-settings-menu>`

Settings menu component with device and language selectors.

<Warning>Must be a child of `<dictation-root>`.</Warning>

### Properties

| Property | Type | Attribute | Writable | Default | Required | Description |
| - | - | - | - | - | - | - |
| `settingsEnabled` | String\[] | `settingsEnabled` | ✅ | `["device", "language"]` | ❌ | Which settings should be available. If empty array, menu is hidden. Options: `"device"`, `"language"`, `"keybinding"`. |

***

## `<dictation-device-selector>`

Device selection dropdown component.

<Warning>Must be a child of `<dictation-root>`.</Warning>

### Properties

| Property | Type | Attribute | Writable | Default | Required | Description |
| - | - | - | - | - | - | - |
| `disabled` | Boolean | `disabled` | ✅ | `false` | ❌ | When `true`, disables the device selector. |

***

## `<dictation-language-selector>`

Language selection dropdown component.

<Warning>Must be a child of `<dictation-root>`.</Warning>

### Properties

| Property | Type | Attribute | Writable | Default | Required | Description |
| - | - | - | - | - | - | - |
| `disabled` | Boolean | `disabled` | ✅ | `false` | ❌ | When `true`, disables the language selector. |

***

## `<dictation-keybinding-selector>`

Keybinding configuration component for setting keyboard shortcuts. Supports both push-to-talk and toggle-to-talk keybindings.

<Warning>Must be a child of `<dictation-root>`.</Warning>

### Properties

| Property | Type | Attribute | Writable | Default | Required | Description |
| - | - | - | - | - | - | - |
| `keybindingType` | String | `keybindingType` | ✅ | `"toggle-to-talk"` | ❌ | The type of keybinding to configure. One of: `"push-to-talk"` or `"toggle-to-talk"`. |
| `disabled` | Boolean | `disabled` | ✅ | `false` | ❌ | When `true`, disables the keybinding selector. |

***

## Attribute Formatting

When using attributes (instead of JavaScript properties), follow these guidelines:

* **Boolean attributes**: Use the attribute name to set `true`, omit it to set `false`
  ```html theme={null}
  <corti-dictation debug-display-audio></corti-dictation> <!-- true -->
  <corti-dictation></corti-dictation> <!-- false -->
  ```

* **String attributes**: Use the attribute value directly
  ```html theme={null}
  <corti-dictation accessToken="YOUR_TOKEN"></corti-dictation>
  ```

* **Array attributes**: Use comma-separated values
  ```html theme={null}
  <corti-dictation settingsEnabled="device,language,keybinding"></corti-dictation>
  <corti-dictation languagesSupported="en,da,sv"></corti-dictation>
  ```

* **Object/Complex types**: Must be set via JavaScript properties, not attributes
  ```javascript theme={null}
  dictation.authConfig = { refreshAccessToken: async () => {...} };
  dictation.dictationConfig = { primaryLanguage: 'en' };
  ```

## See also

* [Overview](/sdk/dictation/overview) -- installation, quickstart, and usage modes
* [Authentication](/sdk/dictation/authentication) -- access tokens and automatic refresh
* [Styling](/sdk/dictation/styling) -- CSS custom properties and theming


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