# Corti Dictation Web Component [![Published on npm](https://img.shields.io/npm/v/@corti/dictation-web.svg?logo=npm)](https://www.npmjs.com/package/@corti/dictation-web) [![License: MIT](https://img.shields.io/npm/l/%40corti%2Fdictation-web)](https://opensource.org/licenses/MIT) [![Get Support on Discord](https://img.shields.io/badge/Discord-Get%20Support-5865F2.svg?logo=discord&logoColor=fff)](https://discord.com/invite/zXeXHgnZXX) [![Live Demo](https://img.shields.io/badge/Live%20Demo-blue.svg?logo=rocket&logoColor=fff)](https://codepen.io/hccullen/pen/OPJmxQR) ## Overview The **Corti Dictation Web Component** is a web component that enables real-time speech-to-text dictation using Corti's Dictation API. It provides a simple interface for capturing audio, streaming it to the API, and handling transcripts. This library offers two approaches: - **Opinionated Component**: Use `` for a complete, ready-to-use solution with built-in UI - **Modular Components**: Use individual components for maximum flexibility and custom UI implementations > **Note:** 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. ## Component Architecture ### Opinionated Component **``** - A complete, ready-to-use component that includes: - Recording button with visual feedback - Settings menu for device, language, and keybinding selection - Automatic state management - Built-in styling and theming - Support for both push-to-talk and toggle-to-talk keybindings simultaneously - Keyboard shortcut (keybinding) support This is the easiest way to get started and works out of the box. ### Modular Components For more control and flexibility, you can use individual components: - **``** - Context provider that manages authentication, configuration, and shared state - **``** - Standalone recording button with audio visualization - **``** - Settings menu with device, language, and keybinding selectors - **``** - Device selection dropdown - **``** - Language selection dropdown - **``** - Keybinding configuration component for keyboard shortcuts (supports both push-to-talk and toggle-to-talk) These components share state through a context system, allowing you to build custom UIs while leveraging the same underlying functionality. ## Installation Install the package using your preferred package manager: ```bash # npm npm i @corti/dictation-web # yarn yarn add @corti/dictation-web # pnpm pnpm add @corti/dictation-web # bun bun add @corti/dictation-web ``` Then import the module in your code. You can either use a side-effect import to auto-register the component: ```js // Side-effect import - automatically registers the component import '@corti/dictation-web'; ``` Or import the component class directly: ```js // Named import - register the component manually if needed import { CortiDictation } from '@corti/dictation-web'; ``` Alternatively, use a CDN to start quickly (not recommended for production): ```html ``` ## Demo 🚀 [Hosted Demo](https://codepen.io/hccullen/pen/OPJmxQR) ## Quick Start Here's a simple example to get you started: ```html ``` ### Modular Example For more control, use individual components to build a custom UI: ```html

``` ### Keyboard Shortcuts (Keybindings) The component supports both push-to-talk and toggle-to-talk keybindings simultaneously. You can configure separate keybindings for each behavior: **Toggle-to-Talk Keybinding (default: `Enter`):** - Pressing the key toggles recording on/off - Works like clicking the button **Push-to-Talk Keybinding (default: `Space`):** - Keydown starts recording - Keyup stops recording - Works like press-and-hold You can use either key names (from `event.key`) or key codes (from `event.code`): ```html

``` Keybindings are platform-aware: - Keybindings are automatically ignored when typing in input fields, textareas, or contenteditable elements - Both key names (e.g., `"k"`, `"Meta"`, `"Space"`) and key codes (e.g., `"KeyK"`, `"MetaLeft"`, `"Space"`) are supported - Both keybindings can be active at the same time - **Note:** If both keybindings are set to the same key, toggle-to-talk takes priority ## Documentation For more detailed information, see: - **[API Reference](docs/API_REFERENCE.md)** - Complete API documentation for properties, methods, and events - **[Authentication Guide](docs/AUTHENTICATION.md)** - How to set up authentication with tokens and refresh mechanisms - **[Styling Guide](docs/styling.md)** - Customize the component's appearance with CSS variables and themes - **[Examples](demo/README.md)** - Practical usage examples and demos - **[Development Guide](docs/DEV_README.md)** - Information for contributors and developers