> ## 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. # Ambient Web Component - API Reference > Properties, methods, and events for every Ambient Web Component Complete API documentation for all components in the Corti Ambient Web Component library. ## Component Overview The library provides two ways to use components: 1. **``** - Opinionated, all-in-one component (recommended for most use cases) 2. **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 `` parent component to provide context. They cannot be used standalone. ## Events Events should be subscribed to on `` or `` 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 | *** ## `` 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`](/api-reference/streams) | - | ✅ | `{ 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. | *** ## `` Context provider component that manages authentication, configuration, and shared state. Required parent for all modular components. All modular components must be children of `` to receive context. ### 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. | | `ambientConfig` | [`StreamConfig`](/api-reference/streams) | - | ✅ | `{ mode: { type: "facts", outputLocale: "en" }, transcription: { primaryLanguage: "en" } }` | ❌ | Stream configuration. Must be set via JavaScript property. | | `virtualMode` | Boolean | `virtualMode` | ✅ | `false` | ❌ | Enables virtual mode — captures tab/window/app audio mixed with microphone input. | | `languages` | String\[] | `languages` | ✅ | `LANGUAGES_SUPPORTED_EU`
or `LANGUAGES_SUPPORTED_US` | ❌ | List of all language codes available.
Auto-loaded based on region (EU or US). | | `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"`. | | `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. | | `noWrapper` | Boolean | `noWrapper` | ✅ | `false` | ❌ | When `true`, removes the default wrapper styling. Useful for custom layouts. | *** ## `` Standalone recording button component with audio visualization. Must be a child of ``. ### 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.
**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. | *** ## `` Settings menu component with device, language, and virtual mode selectors. Must be a child of ``. ### Properties | Property | Type | Attribute | Writable | Default | Required | Description | | ----------------- | --------- | ----------------- | -------- | --------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- | | `settingsEnabled` | String\[] | `settingsEnabled` | ✅ | `["device", "language", "virtualMode"]` | ❌ | Which settings should be available. Options: `"device"`, `"language"`, `"keybinding"`, `"virtualMode"`. | *** ## `` Device selection dropdown component. Must be a child of ``. ### Properties | Property | Type | Attribute | Writable | Default | Required | Description | | ---------- | ------- | ---------- | -------- | ------- | -------- | ------------------------------------------ | | `disabled` | Boolean | `disabled` | ✅ | `false` | ❌ | When `true`, disables the device selector. | *** ## `` Language selection dropdown component. Must be a child of ``. ### Properties | Property | Type | Attribute | Writable | Default | Required | Description | | ---------- | ------- | ---------- | -------- | ------- | -------- | -------------------------------------------- | | `disabled` | Boolean | `disabled` | ✅ | `false` | ❌ | When `true`, disables the language selector. | *** ## `` Keybinding configuration component for setting keyboard shortcuts. Supports both push-to-talk and toggle-to-talk keybindings. Must be a child of ``. ### 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. | *** ## `` Virtual mode toggle component. Must be a child of ``. ### Properties | Property | Type | Attribute | Writable | Default | Required | Description | | ---------- | ------- | ---------- | -------- | ------- | -------- | ------------------------------------------------ | | `disabled` | Boolean | `disabled` | ✅ | `false` | ❌ | When `true`, disables the virtual mode 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} ``` * **String attributes**: Use the attribute value directly ```html theme={null} ``` * **Array attributes**: Use comma-separated values ```html theme={null} ``` * **Object/Complex types**: Must be set via JavaScript properties, not attributes ```javascript theme={null} ambient.authConfig = { refreshAccessToken: async () => {...} }; ambient.ambientConfig = { transcription: { primaryLanguage: 'en' }, mode: { type: 'facts', outputLocale: 'en' } }; ``` ## See also * [Overview](/sdk/ambient/overview) -- installation, quickstart, and usage modes * [Authentication](/sdk/ambient/authentication) -- access tokens and automatic refresh * [Proxy](/sdk/ambient/proxy) -- route WebSocket traffic through your own server * [Styling](/sdk/ambient/styling) -- CSS custom properties and theming