API Reference

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

Component Overview

The library provides two ways to use components:

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

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.

Events

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

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"` `detail.connection` (string, optional): WebSocket connection state. One of: `"CONNECTING"`, `"OPEN"`, `"CLOSING"`, `"CLOSED"`, or `null` `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 `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 `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"` `detail.data.text` (string): Transcript with punctuation applied and command phrases removed `detail.data.rawTranscriptText` (string): Raw transcript without punctuation or command phrase removal `detail.data.start` (number): Start time of the transcript segment in seconds `detail.data.end` (number): End time of the transcript segment in seconds `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"` `detail.data.id` (string): Command identifier `detail.data.variables` (object, optional): Command variables as key-value pairs, where values can be string or null `detail.data.rawTranscriptText` (string): Raw transcript text that triggered the command `detail.data.start` (number): Start time of the command segment in seconds `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"` `detail.event` (string): The audio event type (e.g. `"speechQualityIssueDetected"`, `"speechQualityIssueRecovered"`, `"longSilenceDetected"`, `"longSilenceRecovered"`) `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"` `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"` `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"` `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"`, "`") `detail.code` (string \| null \| undefined): The raw code from the keyboard event (e.g., `"KeyK"`, `"MetaLeft"`, `"Backquote"`) `detail.keybinding` (string \| null): The normalized keybinding value displayed in the UI (e.g., `"k"`, `"Cmd"` on Mac, `"Space"`) `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. 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.
`devices`	Array	-	✅	`auto-loaded`	❌	List of all available recording devices (MediaDeviceInfo[]). Auto-loaded asynchronously from browser’s 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"`.
`dictationConfig`	`TranscribeConfig`	-	✅	`{ 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. If empty, settings are disabled. Options: `"device"`, `"language"`, `"keybinding"`.
`languagesSupported`	String[]	`languagesSupported`	✅	`LANGUAGES_SUPPORTED_EU` or `LANGUAGES_SUPPORTED_US`	❌	List of all language codes available. Auto-loaded based on region (EU or US).
`pushToTalkKeybinding`	String	`pushToTalkKeybinding`	✅	`"Space"` (if in settingsEnabled)	❌	Push-to-talk keyboard shortcut. Keydown starts recording, keyup stops recording. Single key only. 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. 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. Should only be used for debugging.
`allowButtonFocus`	Boolean	`allowButtonFocus`	✅	`false`	❌	When `false` (default), prevents the start/stop 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. Default behavior: The connection opens automatically when the user clicks to start recording for the first time. When to use: Pre-establish the connection before recording starts (e.g., to reduce first-record latency). 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. Default behavior: The connection opens automatically on first recording and remains open after recording stops for reuse. When to use: Receive `"usage"` stats (between `"end"` and `"ended"`), or when you’re completely done (unmount, navigation, freeing resources). 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.

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