Ambient Web Component - API Reference - Corti API Documentation

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

Component Overview

The library provides two ways to use components:

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

Modular components (ambient-recording-button, ambient-settings-menu, ambient-device-selector, ambient-language-selector, ambient-keybinding-selector, ambient-virtual-mode-selector) require a <ambient-root> parent component to provide context. They cannot be used standalone.

Events

Events should be subscribed to on <corti-ambient> or <ambient-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
`transcript`	Fired when new transcript segment(s) are received.	`detail.type` (string): Always `"transcript"` `detail.data` (array): Transcript segments. Each segment includes `transcript` (string), `time.start` / `time.end` (number), `speakerId` (number), and `participant.channel` (number)
`facts`	Fired when new facts are received.	`detail.type` (string): Always `"facts"` `detail.fact` (array): Fact items with `text` (string), `group` (string), `id` (string), `source` (string), and `isDiscarded` (boolean)
`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
`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.
`virtual-mode-changed`	Fired when virtual mode is toggled.	`detail.enabled` (boolean): Whether virtual mode is now enabled

`<corti-ambient>`

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.
`interactionId`	String	`interactionId`	✅	-	✅	Interaction ID for the ambient session. Required before starting recording.
`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"`.
`ambientConfig`	`StreamConfig`	-	✅	`{ mode: { type: "facts", outputLocale: "en" }, transcription: { primaryLanguage: "en" } }`	❌	Stream configuration. Must be set via JavaScript property. For `type: "facts"`, `outputLocale` is required.
`virtualMode`	Boolean	`virtualMode`	✅	`false`	❌	Enables virtual mode — captures tab/window/app audio mixed with microphone input.
`settingsEnabled`	String[]	`settingsEnabled`	✅	`["device", "language", "virtualMode"]`	❌	Which settings should be available in the UI. If empty, settings are disabled. Options: `"device"`, `"language"`, `"keybinding"`, `"virtualMode"`.
`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.
`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. Requires `interactionId` to be set.
`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.

`<ambient-root>`

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

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