> ## 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
> Drop-in web component for real-time multi-speaker ambient streaming
The `@corti/ambient-web` package provides a set of custom elements that handle microphone management, audio streaming, transcript delivery, and facts on top of the Corti API. It works with any frontend framework or plain HTML.
**Package:** [@corti/ambient-web on npm](https://www.npmjs.com/package/@corti/ambient-web) | **Examples:** [corti-examples/ambient](https://github.com/corticph/corti-examples/tree/main/ambient)
The library provides two usage modes:
1. **``** -- opinionated, all-in-one component with built-in UI (recommended for most use cases)
2. **Modular components** -- individual building blocks (``, ``, etc.) for fully custom layouts
Looking for single-speaker dictation with voice commands? See the [Dictation Web Component](/sdk/dictation/overview).
OAuth 2.0 authentication is not handled by this library. The client must provide an authorization token or token refresh function while using the component. Each ambient session also requires an `interactionId`.
## Installation
```bash npm theme={null}
npm install @corti/ambient-web
```
```bash yarn theme={null}
yarn add @corti/ambient-web
```
```bash pnpm theme={null}
pnpm add @corti/ambient-web
```
```html CDN theme={null}
```
### Module import
```ts theme={null}
// Side-effect import -- registers all custom elements
import "@corti/ambient-web";
// Named imports -- access component classes directly
import { CortiAmbient } from "@corti/ambient-web";
```
## Quick start
```html theme={null}
Corti Ambient
```
The component handles microphone permissions, device selection, and audio streaming automatically. You only need to provide authentication, an interaction ID, and listen for events.
***
## Configuration
Set `ambientConfig` as a JavaScript property to configure the stream. The type matches the [`StreamConfig`](/api-reference/streams) from the Streams WebSocket API.
When using `mode.type: "facts"`, you must also set `mode.outputLocale` (the language for extracted facts).
```js theme={null}
const ambient = document.querySelector("corti-ambient");
ambient.ambientConfig = {
transcription: { primaryLanguage: "en" },
mode: { type: "facts", outputLocale: "en" },
};
```
The `interactionId` property is **required** — it identifies the session for the Streams API.
See the [Streams API Reference](/api-reference/streams) for the full configuration schema.
***
## Modular components
For custom UI layouts, use individual components inside an `` parent:
All modular components **require** an `` parent to provide context. They cannot be used standalone.
```html theme={null}
```
| Component | Description |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `` | Context provider. Same properties as `` (auth, config, interactionId, virtualMode, devices, keybindings). Add `noWrapper` attribute to remove default styling. |
| `` | Start/stop button with audio visualization. Supports `allowButtonFocus`. Has `startRecording()`, `stopRecording()`, `toggleRecording()`, `openConnection()`, `closeConnection()` methods. Requires `interactionId` on the root. |
| `` | Settings panel with device, language, and virtual mode selectors. Supports `settingsEnabled`. |
| `` | Standalone device dropdown. Supports `disabled`. |
| `` | Standalone language dropdown. Supports `disabled`. |
| `` | Keybinding configuration. Supports `keybindingType` (`"push-to-talk"` or `"toggle-to-talk"`) and `disabled`. |
| `` | Virtual mode toggle. Supports `disabled`. |
See the [API Reference](/sdk/ambient/reference) for full per-component property and method tables.
***
## Virtual mode
Virtual mode captures tab/window/app audio mixed with microphone input. Enable it via the `virtualMode` attribute or property, or let users toggle it from the settings menu when `settingsEnabled` includes `"virtualMode"` (included by default on ``).
***
## Keyboard shortcuts
The component supports two keybinding modes:
| Mode | Behavior | Default key |
| :----------------- | :---------------------------------- | :---------- |
| **Push-to-talk** | Hold key to record, release to stop | `Space` |
| **Toggle-to-talk** | Press to start, press again to stop | `Enter` |
Configure via attributes:
```html theme={null}
```
Keys are specified as `event.key` names (e.g. `"Space"`, `"k"`, `"Meta"`) or `event.code` values (e.g. `"KeyK"`, `"Backquote"`). Modifier combinations are not supported.
When both keybindings are set to the same key, toggle-to-talk takes priority.
### Preventing keybinding activation
Use the `keybinding-activated` event to conditionally block keybindings:
```js theme={null}
const ambient = document.querySelector("corti-ambient");
ambient.addEventListener("keybinding-activated", (event) => {
if (document.activeElement.tagName === "TEXTAREA") {
event.preventDefault(); // Don't trigger recording while typing
}
});
```
***
## Attribute formatting
| Type | Format | Example |
| :------ | :------------------------------- | :---------------------------------------------- |
| Boolean | Presence = true, absence = false | `` |
| String | Attribute value | `accessToken="token"` |
| Array | Comma-separated | `settingsEnabled="device,language,virtualMode"` |
| Object | JavaScript property only | `ambient.ambientConfig = { ... }` |
***
## Resources
* **[npm package](https://www.npmjs.com/package/@corti/ambient-web)** -- latest version and install info
* **[Examples](https://github.com/corticph/corti-examples/tree/main/ambient)** -- integration examples
* **[API Reference](/sdk/ambient/reference)** -- properties, methods, and events for every component
* **[Authentication Guide](/sdk/ambient/authentication)** -- access tokens and automatic refresh
* **[Proxy Guide](/sdk/ambient/proxy)** -- route WebSocket traffic through your own server
* **[Styling Guide](/sdk/ambient/styling)** -- CSS custom properties and theming
* **[Streams API Reference](/api-reference/streams/)** -- underlying WebSocket API specification
***
For support or questions, reach out through [help.corti.app](https://help.corti.app)