@corti/dictation-web 0.0.0-test.562 → 0.0.0-test.571

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. package/README.md +164 -112
  2. package/dist/bundle.js +1416 -546
  3. package/dist/components/audio-visualiser.d.ts +3 -2
  4. package/dist/components/audio-visualiser.js +15 -12
  5. package/dist/components/audio-visualiser.js.map +1 -1
  6. package/dist/components/corti-dictation.d.ts +26 -13
  7. package/dist/components/corti-dictation.js +70 -21
  8. package/dist/components/corti-dictation.js.map +1 -1
  9. package/dist/components/device-selector.d.ts +6 -16
  10. package/dist/components/device-selector.js +27 -58
  11. package/dist/components/device-selector.js.map +1 -1
  12. package/dist/components/keybinding-selector.d.ts +14 -0
  13. package/dist/components/keybinding-selector.js +81 -0
  14. package/dist/components/keybinding-selector.js.map +1 -0
  15. package/dist/components/language-selector.d.ts +8 -17
  16. package/dist/components/language-selector.js +26 -52
  17. package/dist/components/language-selector.js.map +1 -1
  18. package/dist/components/mode-selector.d.ts +14 -0
  19. package/dist/components/mode-selector.js +73 -0
  20. package/dist/components/mode-selector.js.map +1 -0
  21. package/dist/components/recording-button.d.ts +8 -14
  22. package/dist/components/recording-button.js +155 -96
  23. package/dist/components/recording-button.js.map +1 -1
  24. package/dist/components/settings-menu.d.ts +4 -2
  25. package/dist/components/settings-menu.js +34 -14
  26. package/dist/components/settings-menu.js.map +1 -1
  27. package/dist/constants.d.ts +5 -0
  28. package/dist/constants.js +5 -0
  29. package/dist/constants.js.map +1 -1
  30. package/dist/contexts/dictation-context.d.ts +24 -14
  31. package/dist/contexts/dictation-context.js +128 -46
  32. package/dist/contexts/dictation-context.js.map +1 -1
  33. package/dist/controllers/devices-controller.d.ts +26 -0
  34. package/dist/controllers/devices-controller.js +99 -0
  35. package/dist/controllers/devices-controller.js.map +1 -0
  36. package/dist/controllers/dictation-controller.d.ts +29 -0
  37. package/dist/controllers/dictation-controller.js +179 -0
  38. package/dist/controllers/dictation-controller.js.map +1 -0
  39. package/dist/controllers/keybinding-controller.d.ts +17 -0
  40. package/dist/controllers/keybinding-controller.js +80 -0
  41. package/dist/controllers/keybinding-controller.js.map +1 -0
  42. package/dist/controllers/languages-controller.d.ts +26 -0
  43. package/dist/controllers/languages-controller.js +83 -0
  44. package/dist/controllers/languages-controller.js.map +1 -0
  45. package/dist/controllers/media-controller.d.ts +24 -0
  46. package/dist/controllers/media-controller.js +115 -0
  47. package/dist/controllers/media-controller.js.map +1 -0
  48. package/dist/index.d.ts +9 -7
  49. package/dist/index.js +30 -20
  50. package/dist/index.js.map +1 -1
  51. package/dist/src/components/audio-visualiser.d.ts +1 -0
  52. package/dist/src/components/audio-visualiser.js +6 -3
  53. package/dist/src/components/audio-visualiser.js.map +1 -1
  54. package/dist/src/components/corti-dictation.d.ts +21 -6
  55. package/dist/src/components/corti-dictation.js +25 -2
  56. package/dist/src/components/corti-dictation.js.map +1 -1
  57. package/dist/src/components/recording-button.d.ts +4 -0
  58. package/dist/src/components/recording-button.js +34 -10
  59. package/dist/src/components/recording-button.js.map +1 -1
  60. package/dist/src/components/settings-menu.js +1 -1
  61. package/dist/src/components/settings-menu.js.map +1 -1
  62. package/dist/src/constants.js +24 -6
  63. package/dist/src/constants.js.map +1 -1
  64. package/dist/src/contexts/dictation-context.d.ts +19 -5
  65. package/dist/src/contexts/dictation-context.js +32 -12
  66. package/dist/src/contexts/dictation-context.js.map +1 -1
  67. package/dist/src/controllers/DictationController.d.ts +5 -0
  68. package/dist/src/controllers/DictationController.js +27 -8
  69. package/dist/src/controllers/DictationController.js.map +1 -1
  70. package/dist/src/controllers/MediaController.d.ts +6 -0
  71. package/dist/src/controllers/MediaController.js +17 -1
  72. package/dist/src/controllers/MediaController.js.map +1 -1
  73. package/dist/src/styles/ComponentStyles.js +5 -5
  74. package/dist/src/styles/ComponentStyles.js.map +1 -1
  75. package/dist/src/styles/audio-visualiser.js +1 -1
  76. package/dist/src/styles/audio-visualiser.js.map +1 -1
  77. package/dist/src/styles/buttons.js +12 -12
  78. package/dist/src/styles/buttons.js.map +1 -1
  79. package/dist/src/styles/callout.js +7 -7
  80. package/dist/src/styles/callout.js.map +1 -1
  81. package/dist/src/styles/select.js +8 -8
  82. package/dist/src/styles/select.js.map +1 -1
  83. package/dist/src/styles/settings-menu.js +4 -4
  84. package/dist/src/styles/settings-menu.js.map +1 -1
  85. package/dist/src/types.d.ts +5 -0
  86. package/dist/src/types.js.map +1 -1
  87. package/dist/src/utils/converters.js +4 -1
  88. package/dist/src/utils/converters.js.map +1 -1
  89. package/dist/src/utils/events.d.ts +11 -4
  90. package/dist/src/utils/events.js.map +1 -1
  91. package/dist/src/utils/languages.js +2 -1
  92. package/dist/src/utils/languages.js.map +1 -1
  93. package/dist/src/utils/media.d.ts +1 -1
  94. package/dist/src/utils/media.js +13 -1
  95. package/dist/src/utils/media.js.map +1 -1
  96. package/dist/src/utils/token.d.ts +1 -1
  97. package/dist/src/utils/token.js +12 -11
  98. package/dist/src/utils/token.js.map +1 -1
  99. package/dist/styles/buttons.js +1 -2
  100. package/dist/styles/buttons.js.map +1 -1
  101. package/dist/styles/component-styles.d.ts +3 -0
  102. package/dist/styles/component-styles.js +32 -0
  103. package/dist/styles/component-styles.js.map +1 -0
  104. package/dist/styles/keybinding-selector.d.ts +2 -0
  105. package/dist/styles/keybinding-selector.js +72 -0
  106. package/dist/styles/keybinding-selector.js.map +1 -0
  107. package/dist/styles/mode-selector.d.ts +2 -0
  108. package/dist/styles/mode-selector.js +54 -0
  109. package/dist/styles/mode-selector.js.map +1 -0
  110. package/dist/styles/select.d.ts +1 -1
  111. package/dist/styles/select.js +6 -10
  112. package/dist/styles/select.js.map +1 -1
  113. package/dist/styles/settings-menu.js +9 -1
  114. package/dist/styles/settings-menu.js.map +1 -1
  115. package/dist/tsconfig.stories.tsbuildinfo +1 -1
  116. package/dist/types.d.ts +3 -1
  117. package/dist/types.js.map +1 -1
  118. package/dist/utils/events.d.ts +12 -3
  119. package/dist/utils/events.js +14 -0
  120. package/dist/utils/events.js.map +1 -1
  121. package/dist/utils/keybinding.d.ts +49 -0
  122. package/dist/utils/keybinding.js +140 -0
  123. package/dist/utils/keybinding.js.map +1 -0
  124. package/dist/utils/languages.d.ts +4 -3
  125. package/dist/utils/languages.js.map +1 -1
  126. package/dist/utils/token.d.ts +1 -1
  127. package/dist/utils/token.js +12 -11
  128. package/dist/utils/token.js.map +1 -1
  129. package/package.json +9 -8
package/README.md CHANGED
@@ -9,157 +9,209 @@
9
9
 
10
10
  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.
11
11
 
12
- > **Note:** OAuth 2.0 authentication is not handled by this library. The client must provide an API key or authorization token before using the component.
12
+ This library offers two approaches:
13
+ - **Opinionated Component**: Use `<corti-dictation>` for a complete, ready-to-use solution with built-in UI
14
+ - **Modular Components**: Use individual components for maximum flexibility and custom UI implementations
15
+
16
+ > **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.
17
+
18
+ ## Component Architecture
19
+
20
+ ### Opinionated Component
21
+
22
+ **`<corti-dictation>`** - A complete, ready-to-use component that includes:
23
+ - Recording button with visual feedback
24
+ - Settings menu for device, language, mode, and keybinding selection
25
+ - Automatic state management
26
+ - Built-in styling and theming
27
+ - Support for toggle-to-talk and push-to-talk modes
28
+ - Keyboard shortcut (keybinding) support
29
+
30
+ This is the easiest way to get started and works out of the box.
31
+
32
+ ### Modular Components
33
+
34
+ For more control and flexibility, you can use individual components:
35
+
36
+ - **`<dictation-root>`** - Context provider that manages authentication, configuration, and shared state
37
+ - **`<dictation-recording-button>`** - Standalone recording button with audio visualization
38
+ - **`<dictation-settings-menu>`** - Settings menu with device, language, mode, and keybinding selectors
39
+ - **`<dictation-device-selector>`** - Device selection dropdown
40
+ - **`<dictation-language-selector>`** - Language selection dropdown
41
+ - **`<dictation-mode-selector>`** - Mode selection component (toggle-to-talk or push-to-talk)
42
+ - **`<dictation-keybinding-selector>`** - Keybinding configuration component for keyboard shortcuts
43
+
44
+ These components share state through a context system, allowing you to build custom UIs while leveraging the same underlying functionality.
13
45
 
14
46
  ## Installation
15
47
 
16
- Include the Web Component in your project by importing the JavaScript module:
48
+ Install the package using your preferred package manager:
17
49
 
18
- ```html
50
+ ```bash
51
+ # npm
19
52
  npm i @corti/dictation-web
53
+
54
+ # yarn
55
+ yarn add @corti/dictation-web
56
+
57
+ # pnpm
58
+ pnpm add @corti/dictation-web
59
+
60
+ # bun
61
+ bun add @corti/dictation-web
20
62
  ```
21
63
 
22
- Then import the module like so:
64
+ Then import the module in your code. You can either use a side-effect import to auto-register the component:
23
65
 
24
66
  ```js
25
- // Import the Corti Dictation Web Component
67
+ // Side-effect import - automatically registers the component
26
68
  import '@corti/dictation-web';
27
69
  ```
28
70
 
29
- Alternatively, use a CDN to start quickly (not recommended).
71
+ Or import the component class directly:
72
+
73
+ ```js
74
+ // Named import - register the component manually if needed
75
+ import { CortiDictation } from '@corti/dictation-web';
76
+ ```
77
+
78
+ Alternatively, use a CDN to start quickly (not recommended for production):
30
79
 
31
80
  ```html
32
81
  <script
33
- src="https://cdn.jsdelivr.net/npm/@corti/dictation-web/dist/bundle.min.js"
34
- preload
82
+ src="https://cdn.jsdelivr.net/npm/@corti/dictation-web/dist/bundle.js"
35
83
  type="module"
36
84
  ></script>
37
85
  ```
38
86
 
39
- ## Usage
40
-
41
- ### Demo
87
+ ## Demo
42
88
 
43
89
  🚀 [Hosted Demo](https://codepen.io/hccullen/pen/OPJmxQR)
44
90
 
45
- ### Basic Example
91
+ ## Quick Start
92
+
93
+ Here's a simple example to get you started:
46
94
 
47
95
  ```html
48
96
  <!DOCTYPE html>
49
97
  <html lang="en">
50
- <body>
51
- <corti-dictation id="dictation"></corti-dictation>
52
- <textarea
53
- id="transcript"
54
- placeholder="Transcript will appear here..."
55
- ></textarea>
56
-
57
- <script>
58
- import '@corti/dictation-web';
59
- const dictationEl = document.getElementById('dictation');
60
- dictationEl.addEventListener('ready', () => {
61
- dictationEl.setAccessToken('YOUR_AUTH_TOKEN'); // Note: Never hardcode tokens
62
- });
63
- dictationEl.addEventListener('transcript', e => {
64
- document.getElementById('transcript').value += e.detail.data.text + ' ';
65
- });
66
- </script>
67
- </body>
98
+ <body>
99
+ <corti-dictation id="dictation"></corti-dictation>
100
+ <textarea
101
+ id="transcript"
102
+ placeholder="Transcript will appear here..."
103
+ ></textarea>
104
+
105
+ <script type="module">
106
+ import '@corti/dictation-web';
107
+
108
+ const dictationEl = document.getElementById('dictation');
109
+ const transcriptEl = document.getElementById('transcript');
110
+
111
+ dictationEl.addEventListener('ready', () => {
112
+ dictationEl.accessToken = 'YOUR_AUTH_TOKEN'; // Note: Never hardcode tokens
113
+ });
114
+
115
+ dictationEl.addEventListener('transcript', (e) => {
116
+ if (e.detail.data.isFinal) {
117
+ transcriptEl.value += e.detail.data.text + ' ';
118
+ }
119
+ });
120
+ </script>
121
+ </body>
68
122
  </html>
69
123
  ```
70
124
 
71
- ## API Reference
72
-
73
- ### Properties
74
-
75
- | Property | Type | Description |
76
- | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
77
- | `devices` | Array | List of available recording devices. |
78
- | `selectedDevice` | Object | The selected device used for recording (MediaDeviceInfo). |
79
- | `recordingState` | String | Current state of recording (`stopped`, `recording`, `initializing` and `stopping`, ). |
80
- | `dictationConfig` | Object | Configuration settings for dictation. |
81
- | `settingsEnabled` | Array | Which settings should be available in the UI. If an empty array is passed, the settings will be disabled entirely. Options are `language` and `devices` |
82
- | `languagesSupported` | String[] | List of all language codes available for use with the Web Component. |
83
- | `debug_displayAudio` | Boolean | Overrides any device selection and instead uses getDisplayMedia to stream system audio. Should only be used for debugging |
84
- | `preventButtonFocus` | Boolean | When `true` (default), prevents the start/stop button from taking focus when clicked, allowing textareas or other input elements to maintain focus. Set to `false` to allow the button to receive focus on click. |
85
-
86
- ### Methods
87
-
88
- | Method | Description |
89
- | -------------------------------------- | ---------------------------------------------------------------- |
90
- | `startRecording()` | Starts a recording. |
91
- | `stopRecording()` | Stops a recording. |
92
- | `toggleRecording()` | Starts or stops recording. Convenience layer on top of the start/stop methods. |
93
- | `setAccessToken(access_token: string)` | Set the latest access token. This will return the server config. |
94
- | `setAuthConfig(config: AuthConfig)` | Set authentication configuration with optional refresh mechanism. |
95
-
96
- ### Events
97
-
98
- | Event | Description |
99
- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
100
- | `ready` | Fired once the component is ready. |
101
- | `recording-state-changed` | Fired when the recording state changes. `detail.state` contains the new state. |
102
- | `recording-devices-changed` | Fired when the user switches recording devices or the list of recording devices changes. `detail.devices` contains the full devices list. `detail.selectedDevice` contains the current selected device. |
103
- | `transcript` | Fired when a new transcript is received. `detail.data.text` contains the transcribed text. |
104
- | `command` | Fired whenever a new command is detected. |
105
- | `audio-level-changed` | Fired when the input audio level changes. `detail.audioLevel` contains the new level. |
106
- | `usage` | Fired when usage information is received from the server. `detail.credits` contains the usage data. |
107
- | `stream-closed` | Fired when the WebSocket stream is closed. `detail` contains the close event data. |
108
- | `error` | Fired on error. `detail` contains the full error. |
109
-
110
- ## Authentication
111
-
112
- This library supports multiple authentication methods:
113
-
114
- ### Basic Bearer Token
115
- ```javascript
116
- dictation.setAccessToken('YOUR_JWT_TOKEN');
125
+ ### Modular Example
126
+
127
+ For more control, use individual components to build a custom UI:
128
+
129
+ ```html
130
+ <!DOCTYPE html>
131
+ <html lang="en">
132
+ <body>
133
+ <dictation-root id="dictationRoot">
134
+ <dictation-recording-button></dictation-recording-button>
135
+ <dictation-settings-menu settingsEnabled="device,language,mode,keybinding"></dictation-settings-menu>
136
+ </dictation-root>
137
+
138
+ <textarea
139
+ id="transcript"
140
+ placeholder="Transcript will appear here..."
141
+ ></textarea>
142
+
143
+ <script type="module">
144
+ import '@corti/dictation-web';
145
+
146
+ const root = document.getElementById('dictationRoot');
147
+ const transcriptEl = document.getElementById('transcript');
148
+
149
+ root.addEventListener('ready', () => {
150
+ root.accessToken = 'YOUR_AUTH_TOKEN'; // Note: Never hardcode tokens
151
+ });
152
+
153
+ root.addEventListener('transcript', (e) => {
154
+ if (e.detail.data.isFinal) {
155
+ transcriptEl.value += e.detail.data.text + ' ';
156
+ }
157
+ });
158
+ </script>
159
+ </body>
160
+ </html>
117
161
  ```
118
162
 
119
- ### With Refresh Token Support
120
-
121
- The library can automatically refresh tokens when they expire:
122
-
123
- ```javascript
124
- dictation.setAuthConfig({
125
- // This function runs before any API call when the access_token is near expiration
126
- refreshAccessToken: async (refreshToken?: string) => {
127
- // Custom refresh logic -- get new access_token from server
128
- // if accessToken is not passed to AuthConfig, refreshToken will be `undefined` for the first call,
129
- // then it will be the refreshToken returned from the previous token request
130
- const response = await fetch("https://your-auth-server/token", {
131
- method: "POST",
132
- headers: { "Content-Type": "application/json" },
133
- body: JSON.stringify({ refreshToken }),
134
- });
135
-
136
- const result = await response.json();
137
-
138
- // Return in the expected format
139
- return {
140
- accessToken: result.accessToken,
141
- refreshToken: result.refreshToken,
142
- };
143
- }
144
- });
163
+ ### Dictation Modes
164
+
165
+ The component supports two dictation modes:
166
+
167
+ **Toggle-to-Talk (default):**
168
+ - Click or tap the recording button to start recording
169
+ - Click or tap again to stop recording
170
+ - Press the keybinding to toggle recording state
171
+
172
+ ```html
173
+ <corti-dictation mode="toggle-to-talk"></corti-dictation>
174
+ ```
175
+
176
+ **Push-to-Talk:**
177
+ - Press and hold the recording button to record
178
+ - Release to stop recording
179
+ - Press and hold the keybinding to record (keydown starts, keyup stops)
180
+
181
+ ```html
182
+ <corti-dictation mode="push-to-talk"></corti-dictation>
145
183
  ```
146
184
 
147
- The refresh mechanism automatically handles token renewal when the access token is near expiration, ensuring uninterrupted dictation sessions.
185
+ ### Keyboard Shortcuts (Keybindings)
148
186
 
149
- ## Usage Examples
187
+ Configure keyboard shortcuts to start/stop recording. You can use either key names (from `event.key`) or key codes (from `event.code`):
150
188
 
151
- Explore practical implementations and usage examples in the [Demo Folder](https://github.com/corticph/dictation-web/tree/main/demo). These demos can also be run locally.
189
+ ```html
190
+ <!-- Use backtick key (default) - key name -->
191
+ <corti-dictation keybinding="`"></corti-dictation>
152
192
 
153
- ## Styling
193
+ <!-- Use 'k' key - key name -->
194
+ <corti-dictation keybinding="k"></corti-dictation>
154
195
 
155
- ![UI Overview](https://github.com/corticph/dictation-web/blob/main/docs/ui.png)
196
+ <!-- Use Meta key (Cmd on Mac, Meta elsewhere) - key name -->
197
+ <corti-dictation keybinding="meta"></corti-dictation>
156
198
 
157
- The default UI is designed to be slotted into existing applications seamlessly, however, it also supports custom styling as well as theming. The UI can be fully customized using CSS properties. Refer to our [Styling Guide](https://github.com/corticph/dictation-web/blob/main/docs/styling.md) for detailed instructions.
199
+ <!-- Use key codes instead of key names -->
200
+ <corti-dictation keybinding="Backquote"></corti-dictation> <!-- backtick -->
201
+ <corti-dictation keybinding="KeyK"></corti-dictation> <!-- 'k' key -->
202
+ <corti-dictation keybinding="MetaLeft"></corti-dictation> <!-- Meta key -->
203
+ ```
158
204
 
159
- ## License
205
+ Keybindings are platform-aware:
206
+ - Keybindings are automatically ignored when typing in input fields, textareas, or contenteditable elements
207
+ - Both key names (e.g., `"k"`, `"Meta"`) and key codes (e.g., `"KeyK"`, `"MetaLeft"`) are supported
160
208
 
161
- This Web Component library is licensed under MIT.
209
+ ## Documentation
162
210
 
163
- ## Support
211
+ For more detailed information, see:
164
212
 
165
- For issues or questions, contact **Corti Support** at [help@corti.ai](mailto:help@corti.ai) or [join our Discord](https://discord.com/invite/zXeXHgnZXX).
213
+ - **[API Reference](docs/API_REFERENCE.md)** - Complete API documentation for properties, methods, and events
214
+ - **[Authentication Guide](docs/AUTHENTICATION.md)** - How to set up authentication with tokens and refresh mechanisms
215
+ - **[Styling Guide](docs/styling.md)** - Customize the component's appearance with CSS variables and themes
216
+ - **[Examples](demo/README.md)** - Practical usage examples and demos
217
+ - **[Development Guide](docs/DEV_README.md)** - Information for contributors and developers