Skip to main content
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
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:
EventDescriptionDetail
readyFired once the component is ready.No detail
recording-state-changedFired 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-changedFired 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-changedFired 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
transcriptFired 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)
commandFired 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-changedFired when the input audio level changes.detail.audioLevel (number): The current audio level, ranging from 0 to 1
usageFired when usage information is received from the server.detail.type (string): Always "usage"
detail.credits (number): The amount of credits used for this stream
network-activityFired 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
errorFired on error.detail.message (string): Error message describing what went wrong
keybinding-changedFired 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-activatedFired 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

PropertyTypeAttributeWritableDefaultRequiredDescription
accessTokenStringaccessToken✅-✅*Latest access token for authentication.
Required if no other authentication or proxy methods provided.
authConfigObject-✅-✅*Authentication configuration with optional refresh mechanism.
Must be set via JavaScript property.
Required if no other authentication or proxy methods provided.
socketUrlStringsocketUrl✅-✅*WebSocket URL for proxy connection.
When provided, uses proxy client instead of direct client.
Required if no other authentication or proxy methods provided.
socketProxyObject-✅-✅*Socket proxy configuration object.
Must be set via JavaScript property.
Required if no other authentication or proxy methods provided.
devicesArray-✅auto-loaded❌List of all available recording devices (MediaDeviceInfo[]).
Auto-loaded asynchronously from browser’s audio input devices. Must be set via JavaScript property.
selectedDeviceObject-✅-❌The selected device used for recording (MediaDeviceInfo).
Must be set via JavaScript property.
recordingStateString-❌"stopped"❌Current state of recording: "stopped", "recording", "initializing", "stopping".
dictationConfigTranscribeConfig-✅{ automaticPunctuation: false, primaryLanguage: "en", spokenPunctuation: true }❌Transcription config. Must be set via JavaScript property.
settingsEnabledString[]settingsEnabled✅["device", "language"]❌Which settings should be available in the UI.
If empty, settings are disabled.
Options: "device", "language", "keybinding".
languagesSupportedString[]languagesSupported✅LANGUAGES_SUPPORTED_EU
or LANGUAGES_SUPPORTED_US		❌List of all language codes available.
Auto-loaded based on region (EU or US).
pushToTalkKeybindingStringpushToTalkKeybinding✅"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.
toggleToTalkKeybindingStringtoggleToTalkKeybinding✅"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_displayAudioBooleandebug-display-audio✅false❌Overrides device selection and uses getDisplayMedia to stream system audio.
Should only be used for debugging.
allowButtonFocusBooleanallowButtonFocus✅false❌When false (default), prevents the start/stop button from taking focus when clicked.
Set to true to allow focus.

​
Methods

MethodDescription
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.

​
Properties

PropertyTypeAttributeWritableDefaultRequiredDescription
accessTokenStringaccessToken✅-✅*Latest access token for authentication. Required if no other authentication or proxy methods provided.
authConfigObject-✅-✅*Authentication configuration with optional refresh mechanism. Must be set via JavaScript property. Required if no other authentication or proxy methods provided.
socketUrlStringsocketUrl✅-✅*WebSocket URL for proxy connection. When provided, uses proxy client instead of direct client. Required if no other authentication or proxy methods provided.
socketProxyObject-✅-✅*Socket proxy configuration object. Must be set via JavaScript property. Required if no other authentication or proxy methods provided.
dictationConfigTranscribeConfig-✅{ automaticPunctuation: false, primaryLanguage: "en", spokenPunctuation: true }❌Transcription config. Must be set via JavaScript property.
languagesString[]languages✅LANGUAGES_SUPPORTED_EU
or LANGUAGES_SUPPORTED_US		❌List of all language codes available.
Auto-loaded based on region (EU or US).
devicesArray-✅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.
selectedDeviceObject-✅-❌The selected device used for recording (MediaDeviceInfo). Must be set via JavaScript property.
recordingStateString-❌"stopped"❌Current state of recording: "stopped", "recording", "initializing", "stopping".
pushToTalkKeybindingStringpushToTalkKeybinding✅"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.
toggleToTalkKeybindingStringtoggleToTalkKeybinding✅"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_displayAudioBooleandebug-display-audio✅-❌Overrides device selection and uses getDisplayMedia to stream system audio. Should only be used for debugging.
noWrapperBooleannoWrapper✅false❌When true, removes the default wrapper styling. Useful for custom layouts.

​
<dictation-recording-button>

Standalone recording button component with audio visualization.
Must be a child of <dictation-root>.

​
Properties

PropertyTypeAttributeWritableDefaultRequiredDescription
allowButtonFocusBooleanallowButtonFocus✅false❌When false (default), prevents the button from taking focus when clicked. Set to true to allow focus.

​
Methods

MethodDescription
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: Opens automatically on the first user action to start recording.
When to use: Pre-establish before recording starts (e.g., 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.

​
<dictation-settings-menu>

Settings menu component with device and language selectors.
Must be a child of <dictation-root>.

​
Properties

PropertyTypeAttributeWritableDefaultRequiredDescription
settingsEnabledString[]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.
Must be a child of <dictation-root>.

​
Properties

PropertyTypeAttributeWritableDefaultRequiredDescription
disabledBooleandisabled✅false❌When true, disables the device selector.

​
<dictation-language-selector>

Language selection dropdown component.
Must be a child of <dictation-root>.

​
Properties

PropertyTypeAttributeWritableDefaultRequiredDescription
disabledBooleandisabled✅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.
Must be a child of <dictation-root>.

​
Properties

PropertyTypeAttributeWritableDefaultRequiredDescription
keybindingTypeStringkeybindingType✅"toggle-to-talk"❌The type of keybinding to configure. One of: "push-to-talk" or "toggle-to-talk".
disabledBooleandisabled✅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 
    <corti-dictation debug-display-audio></corti-dictation> <!-- true -->
<corti-dictation></corti-dictation> <!-- false -->
  • String attributes: Use the attribute value directly 
    <corti-dictation accessToken="YOUR_TOKEN"></corti-dictation>
  • Array attributes: Use comma-separated values 
    <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 
    dictation.authConfig = { refreshAccessToken: async () => {...} };
dictation.dictationConfig = { primaryLanguage: 'en' };

​
See also

  • Overview — installation, quickstart, and usage modes
  • Authentication — access tokens and automatic refresh
  • Styling — CSS custom properties and theming