@adea-ai/app-framework 0.46.12 → 0.48.0
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.
- package/README.md +2 -1
- package/dist/app/application.d.ts +2 -1
- package/dist/app/application.js +27 -16
- package/dist/app/create-application.js +6 -3
- package/dist/appearance/appearance-host.d.ts +2 -1
- package/dist/appearance/appearance-host.js +28 -21
- package/dist/appearance/editor.js +21 -3
- package/dist/framework-source.json +1 -1
- package/dist/shell/app-shell.d.ts +1 -1
- package/dist/shell/app-shell.js +97 -87
- package/dist/shell/app-utilities.d.ts +1 -1
- package/dist/shell/app-utilities.js +42 -23
- package/dist/shell/media-query.js +12 -10
- package/dist/shell/navigation-drawer.d.ts +1 -1
- package/dist/shell/navigation-drawer.js +6 -4
- package/dist/shell/poll.js +9 -11
- package/dist/shell/settings-sections.d.ts +1 -1
- package/dist/views/app-about.d.ts +1 -1
- package/dist/views/app-about.js +1 -1
- package/dist/views/app-appearance.d.ts +2 -1
- package/dist/views/app-appearance.js +4 -4
- package/dist/views/app-help.d.ts +1 -1
- package/dist/views/app-help.js +1 -1
- package/dist/views/app-settings.d.ts +2 -1
- package/dist/views/app-settings.js +15 -10
- package/dist/views/appearance-surface.d.ts +1 -1
- package/dist/views/appearance-surface.js +116 -91
- package/dist/views/update-surface.d.ts +1 -1
- package/dist/views/update-surface.js +1 -1
- package/dist/voice/voice-build.d.ts +62 -0
- package/dist/voice/voice-build.js +247 -0
- package/dist/voice/voice-client.d.ts +130 -0
- package/dist/voice/voice-client.js +405 -0
- package/dist/voice/voice-controls.d.ts +43 -0
- package/dist/voice/voice-controls.js +313 -0
- package/dist/voice/voice-host.d.ts +29 -0
- package/dist/voice/voice-host.js +248 -0
- package/dist/voice/voice-protocol.d.ts +127 -0
- package/dist/voice/voice-protocol.js +120 -0
- package/dist/voice/voice-settings.d.ts +15 -0
- package/dist/voice/voice-settings.js +1095 -0
- package/dist/voice/voice.d.ts +5 -0
- package/dist/voice/voice.js +5 -0
- package/package.json +32 -14
- package/src/app/application.tsx +28 -32
- package/src/appearance/appearance-host.tsx +30 -19
- package/src/appearance/editor.ts +25 -3
- package/src/shell/app-shell.tsx +46 -37
- package/src/shell/app-utilities.tsx +38 -40
- package/src/shell/media-query.ts +15 -10
- package/src/shell/navigation-drawer.tsx +1 -1
- package/src/shell/poll.ts +9 -10
- package/src/shell/settings-sections.ts +1 -1
- package/src/views/app-appearance.tsx +4 -3
- package/src/views/app-settings.tsx +2 -1
- package/src/views/appearance-surface.tsx +46 -35
- package/src/voice/voice-client.ts +579 -0
- package/src/voice/voice-controls.tsx +354 -0
- package/src/voice/voice-protocol.ts +189 -0
- package/src/voice/voice-settings.tsx +879 -0
- package/src/voice/voice.ts +13 -0
- package/templates/application/AGENTS.md +29 -0
- package/templates/application/src/web/main.tsx +2 -2
- package/templates/application/tsconfig.json +1 -1
- package/templates/application/vite.config.ts +1 -1
|
@@ -0,0 +1,354 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The shared voice controls: a dictation button for a composer and a read-aloud action for a
|
|
3
|
+
* message. Both talk to a `VoiceClient` and read its capabilities, so an engine that cannot run
|
|
4
|
+
* here shows a disabled control with the reason instead of failing on click.
|
|
5
|
+
*/
|
|
6
|
+
import { ActionButton } from '@adea-ai/ui/components/composites/action-button'
|
|
7
|
+
import type { ButtonProps } from '@adea-ai/ui/components/ui/button'
|
|
8
|
+
import { VoiceError, type VoiceRoutingDecision } from '@adea-ai/voice/contract'
|
|
9
|
+
import { Mic, Square, Volume2 } from '@lucide/solid'
|
|
10
|
+
import { createEffect, createSignal, onCleanup, Show, type Accessor } from 'solid-js'
|
|
11
|
+
import type {
|
|
12
|
+
DictationHandle,
|
|
13
|
+
SpeechHandle,
|
|
14
|
+
VoiceCapabilitiesView,
|
|
15
|
+
VoiceClient,
|
|
16
|
+
VoicePlatformKind,
|
|
17
|
+
} from './voice-client'
|
|
18
|
+
|
|
19
|
+
const DESKTOP_ONLY_REASONS = new Set([
|
|
20
|
+
'unsupportedPlatform',
|
|
21
|
+
'unsupportedOperatingSystem',
|
|
22
|
+
'unsupportedDevice',
|
|
23
|
+
'providerNotRegistered',
|
|
24
|
+
])
|
|
25
|
+
|
|
26
|
+
/** Why a decision cannot run, in words for a tooltip; undefined when it can. */
|
|
27
|
+
function decisionReason(
|
|
28
|
+
decision: VoiceRoutingDecision,
|
|
29
|
+
platform: VoicePlatformKind,
|
|
30
|
+
desktopOnly: string
|
|
31
|
+
): string | undefined {
|
|
32
|
+
if (decision.route && decision.availability.status === 'available') return undefined
|
|
33
|
+
if (decision.availability.status === 'available') return desktopOnly
|
|
34
|
+
const { reason, message } = decision.availability.unavailable
|
|
35
|
+
return platform === 'web' && DESKTOP_ONLY_REASONS.has(reason) ? desktopOnly : message
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* One capabilities request per client, shared by every control on screen (a read-aloud action
|
|
40
|
+
* on each message must not probe the engines once per message). A settings change drops it.
|
|
41
|
+
*/
|
|
42
|
+
const sharedCapabilities = new WeakMap<VoiceClient, Promise<VoiceCapabilitiesView>>()
|
|
43
|
+
const watched = new WeakSet<VoiceClient>()
|
|
44
|
+
|
|
45
|
+
function capabilitiesOf(client: VoiceClient): Promise<VoiceCapabilitiesView> {
|
|
46
|
+
if (!watched.has(client)) {
|
|
47
|
+
watched.add(client)
|
|
48
|
+
client.settings.subscribe(() => sharedCapabilities.delete(client))
|
|
49
|
+
}
|
|
50
|
+
let pending = sharedCapabilities.get(client)
|
|
51
|
+
if (!pending) {
|
|
52
|
+
pending = client.capabilities()
|
|
53
|
+
pending.catch(() => sharedCapabilities.delete(client))
|
|
54
|
+
sharedCapabilities.set(client, pending)
|
|
55
|
+
}
|
|
56
|
+
return pending
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Tracks whether a kind can run with the client's current settings. */
|
|
60
|
+
function createAvailability(
|
|
61
|
+
client: Accessor<VoiceClient | undefined>,
|
|
62
|
+
kind: 'speechToText' | 'textToSpeech',
|
|
63
|
+
desktopOnly: string
|
|
64
|
+
): Accessor<{ ready: boolean; reason?: string }> {
|
|
65
|
+
const [state, setState] = createSignal<{ ready: boolean; reason?: string }>({ ready: false })
|
|
66
|
+
createEffect(client, (current) => {
|
|
67
|
+
if (!current) {
|
|
68
|
+
setState({ ready: true, reason: desktopOnly })
|
|
69
|
+
return
|
|
70
|
+
}
|
|
71
|
+
let generation = 0
|
|
72
|
+
let alive = true
|
|
73
|
+
const check = () => {
|
|
74
|
+
const mine = ++generation
|
|
75
|
+
capabilitiesOf(current).then(
|
|
76
|
+
(view) => {
|
|
77
|
+
if (!alive || mine !== generation) return
|
|
78
|
+
setState({ ready: true, reason: decisionReason(view[kind], view.platform, desktopOnly) })
|
|
79
|
+
},
|
|
80
|
+
(error: unknown) => {
|
|
81
|
+
if (!alive || mine !== generation) return
|
|
82
|
+
setState({ ready: true, reason: VoiceError.wrapping(error).message })
|
|
83
|
+
}
|
|
84
|
+
)
|
|
85
|
+
}
|
|
86
|
+
check()
|
|
87
|
+
const unsubscribe = current.settings.subscribe(check)
|
|
88
|
+
return () => {
|
|
89
|
+
alive = false
|
|
90
|
+
unsubscribe()
|
|
91
|
+
}
|
|
92
|
+
})
|
|
93
|
+
return state
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
export type DictationState = 'idle' | 'starting' | 'listening' | 'stopping'
|
|
97
|
+
|
|
98
|
+
export type DictationCallbacks = Readonly<{
|
|
99
|
+
/** Every partial (`final` false) and the final text (`final` true). */
|
|
100
|
+
onText?(text: string, final: boolean): void
|
|
101
|
+
/** The final text, when the person chose to send after dictating. */
|
|
102
|
+
onFinal?(text: string): void
|
|
103
|
+
}>
|
|
104
|
+
|
|
105
|
+
export type Dictation = Readonly<{
|
|
106
|
+
state: Accessor<DictationState>
|
|
107
|
+
/** The latest partial, then the final text. */
|
|
108
|
+
partial: Accessor<string>
|
|
109
|
+
/** A short message for the last failure; cleared when a dictation starts. */
|
|
110
|
+
error: Accessor<string | undefined>
|
|
111
|
+
/** Asks for permission when needed, then dictates. Resolves with the final text, if any. */
|
|
112
|
+
start(callbacks?: DictationCallbacks): Promise<string | undefined>
|
|
113
|
+
/** Finishes listening and keeps what was said. */
|
|
114
|
+
stop(): Promise<void>
|
|
115
|
+
/** Stops listening and drops the text, silently. */
|
|
116
|
+
cancel(): Promise<void>
|
|
117
|
+
}>
|
|
118
|
+
|
|
119
|
+
/** The dictation state machine behind `DictationButton`, for apps that draw their own status. */
|
|
120
|
+
export function createDictation(client: VoiceClient | undefined): Dictation {
|
|
121
|
+
const [state, setState] = createSignal<DictationState>('idle')
|
|
122
|
+
const [partial, setPartial] = createSignal('')
|
|
123
|
+
const [error, setError] = createSignal<string>()
|
|
124
|
+
let handle: DictationHandle | undefined
|
|
125
|
+
let cancelled = false
|
|
126
|
+
|
|
127
|
+
const start = async (callbacks: DictationCallbacks = {}) => {
|
|
128
|
+
if (!client || state() !== 'idle') return undefined
|
|
129
|
+
cancelled = false
|
|
130
|
+
setError(undefined)
|
|
131
|
+
setPartial('')
|
|
132
|
+
setState('starting')
|
|
133
|
+
try {
|
|
134
|
+
const permission = await client.permission(false)
|
|
135
|
+
const granted = permission.state === 'prompt' ? await client.permission(true) : permission
|
|
136
|
+
if (granted.state === 'denied') throw new VoiceError('denied')
|
|
137
|
+
if (cancelled) throw new VoiceError('cancelled')
|
|
138
|
+
const started = await client.dictate({
|
|
139
|
+
onPartial: (text) => {
|
|
140
|
+
if (cancelled) return
|
|
141
|
+
setPartial(text)
|
|
142
|
+
callbacks.onText?.(text, false)
|
|
143
|
+
},
|
|
144
|
+
})
|
|
145
|
+
handle = started
|
|
146
|
+
if (cancelled) void started.cancel().catch(() => undefined)
|
|
147
|
+
else setState((current) => (current === 'starting' ? 'listening' : current))
|
|
148
|
+
const text = await started.result
|
|
149
|
+
setPartial(text)
|
|
150
|
+
callbacks.onText?.(text, true)
|
|
151
|
+
if (client.settings.read().settings.dictation.autoSend) callbacks.onFinal?.(text)
|
|
152
|
+
return text
|
|
153
|
+
} catch (failure) {
|
|
154
|
+
const typed = VoiceError.wrapping(failure)
|
|
155
|
+
if (typed.code === 'no_speech') setError("Didn't catch that")
|
|
156
|
+
else if (typed.code !== 'cancelled') setError(typed.message)
|
|
157
|
+
return undefined
|
|
158
|
+
} finally {
|
|
159
|
+
handle = undefined
|
|
160
|
+
setState('idle')
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
const stop = async () => {
|
|
165
|
+
const current = handle
|
|
166
|
+
if (!current || state() !== 'listening') return
|
|
167
|
+
setState('stopping')
|
|
168
|
+
try {
|
|
169
|
+
await current.end()
|
|
170
|
+
} catch (failure) {
|
|
171
|
+
setError(VoiceError.wrapping(failure).message)
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
const cancel = async () => {
|
|
176
|
+
if (state() === 'idle') return
|
|
177
|
+
cancelled = true
|
|
178
|
+
try {
|
|
179
|
+
await handle?.cancel()
|
|
180
|
+
} catch {
|
|
181
|
+
// Cancelling is best effort: the session ends either way.
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
onCleanup(() => void cancel())
|
|
186
|
+
return { state, partial, error, start, stop, cancel }
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
export type DictationButtonProps = {
|
|
190
|
+
client?: VoiceClient
|
|
191
|
+
onText(text: string, final: boolean): void
|
|
192
|
+
onFinal?(text: string): void
|
|
193
|
+
disabled?: boolean
|
|
194
|
+
size?: ButtonProps['size']
|
|
195
|
+
/** Share a dictation made with `createDictation` to draw its status elsewhere. */
|
|
196
|
+
dictation?: Dictation
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/** A microphone button: click to dictate, click again to finish, Escape to cancel. */
|
|
200
|
+
export function DictationButton(props: DictationButtonProps) {
|
|
201
|
+
const dictation = props.dictation ?? createDictation(props.client)
|
|
202
|
+
const availability = createAvailability(
|
|
203
|
+
() => props.client,
|
|
204
|
+
'speechToText',
|
|
205
|
+
'Dictation is available in ADEA Desktop'
|
|
206
|
+
)
|
|
207
|
+
const active = () => dictation.state() !== 'idle'
|
|
208
|
+
const unavailable = () => !active() && availability().reason
|
|
209
|
+
const disabled = () =>
|
|
210
|
+
!active() &&
|
|
211
|
+
(Boolean(props.disabled) || !availability().ready || Boolean(availability().reason))
|
|
212
|
+
|
|
213
|
+
const onKey = (event: KeyboardEvent) => {
|
|
214
|
+
if (event.key !== 'Escape') return
|
|
215
|
+
event.preventDefault()
|
|
216
|
+
void dictation.cancel()
|
|
217
|
+
}
|
|
218
|
+
createEffect(active, (isActive) => {
|
|
219
|
+
if (!isActive) return
|
|
220
|
+
document.addEventListener('keydown', onKey)
|
|
221
|
+
return () => document.removeEventListener('keydown', onKey)
|
|
222
|
+
})
|
|
223
|
+
|
|
224
|
+
const tooltip = () => {
|
|
225
|
+
const state = dictation.state()
|
|
226
|
+
if (state === 'listening') return 'Stop dictation'
|
|
227
|
+
if (state === 'starting') return 'Starting dictation'
|
|
228
|
+
if (state === 'stopping') return 'Finishing dictation'
|
|
229
|
+
return unavailable() || dictation.error() || 'Dictate'
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
const click = () => {
|
|
233
|
+
const state = dictation.state()
|
|
234
|
+
if (state === 'listening') return void dictation.stop()
|
|
235
|
+
if (state !== 'idle') return
|
|
236
|
+
void dictation.start({
|
|
237
|
+
onText: (text, final) => props.onText(text, final),
|
|
238
|
+
onFinal: (text) => props.onFinal?.(text),
|
|
239
|
+
})
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
return (
|
|
243
|
+
<>
|
|
244
|
+
<ActionButton
|
|
245
|
+
type="button"
|
|
246
|
+
variant={dictation.state() === 'listening' ? 'subtle' : 'ghost'}
|
|
247
|
+
size={props.size ?? 'icon-sm'}
|
|
248
|
+
aria-label={dictation.state() === 'listening' ? 'Stop dictation' : 'Dictate'}
|
|
249
|
+
aria-pressed={dictation.state() === 'listening' ? 'true' : 'false'}
|
|
250
|
+
tooltip={tooltip()}
|
|
251
|
+
busy={dictation.state() === 'starting' || dictation.state() === 'stopping'}
|
|
252
|
+
busyLabel={dictation.state() === 'starting' ? 'Starting dictation' : 'Finishing dictation'}
|
|
253
|
+
disabled={disabled()}
|
|
254
|
+
data-state={dictation.state()}
|
|
255
|
+
onClick={click}
|
|
256
|
+
>
|
|
257
|
+
<Show when={dictation.state() === 'listening'} fallback={<Mic aria-hidden="true" />}>
|
|
258
|
+
<Square aria-hidden="true" />
|
|
259
|
+
</Show>
|
|
260
|
+
</ActionButton>
|
|
261
|
+
<span class="sr-only" role="status">
|
|
262
|
+
{dictation.error() ?? ''}
|
|
263
|
+
</span>
|
|
264
|
+
</>
|
|
265
|
+
)
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
/** The read-aloud playing anywhere in the app: starting another one stops it first. */
|
|
269
|
+
let currentReading: { stop(): Promise<void> } | undefined
|
|
270
|
+
|
|
271
|
+
export type ReadAloudButtonProps = {
|
|
272
|
+
client?: VoiceClient
|
|
273
|
+
text: string | (() => string)
|
|
274
|
+
locale?: string
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
/** A message action that reads its text aloud, and stops it on a second click. */
|
|
278
|
+
export function ReadAloudButton(props: ReadAloudButtonProps) {
|
|
279
|
+
const availability = createAvailability(
|
|
280
|
+
() => props.client,
|
|
281
|
+
'textToSpeech',
|
|
282
|
+
'Read aloud is available in ADEA Desktop'
|
|
283
|
+
)
|
|
284
|
+
const [speaking, setSpeaking] = createSignal(false)
|
|
285
|
+
const [error, setError] = createSignal<string>()
|
|
286
|
+
let handle: SpeechHandle | undefined
|
|
287
|
+
let mine: { stop(): Promise<void> } | undefined
|
|
288
|
+
|
|
289
|
+
const stop = async () => {
|
|
290
|
+
const current = handle
|
|
291
|
+
setSpeaking(false)
|
|
292
|
+
if (current) await current.cancel().catch(() => undefined)
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
const start = async () => {
|
|
296
|
+
const client = props.client
|
|
297
|
+
const text = (typeof props.text === 'function' ? props.text() : props.text).trim()
|
|
298
|
+
if (!client || !text) return
|
|
299
|
+
setError(undefined)
|
|
300
|
+
const previous = currentReading
|
|
301
|
+
const self = { stop }
|
|
302
|
+
mine = self
|
|
303
|
+
currentReading = self
|
|
304
|
+
setSpeaking(true)
|
|
305
|
+
try {
|
|
306
|
+
if (previous && previous !== self) await previous.stop()
|
|
307
|
+
if (currentReading !== self) return
|
|
308
|
+
const started = await client.speak(text, props.locale ? { locale: props.locale } : {})
|
|
309
|
+
handle = started
|
|
310
|
+
if (currentReading !== self || !speaking()) {
|
|
311
|
+
await started.cancel().catch(() => undefined)
|
|
312
|
+
return
|
|
313
|
+
}
|
|
314
|
+
await started.done
|
|
315
|
+
} catch (failure) {
|
|
316
|
+
const typed = VoiceError.wrapping(failure)
|
|
317
|
+
if (typed.code !== 'cancelled') setError(typed.message)
|
|
318
|
+
} finally {
|
|
319
|
+
if (currentReading === self) currentReading = undefined
|
|
320
|
+
if (mine === self) {
|
|
321
|
+
handle = undefined
|
|
322
|
+
setSpeaking(false)
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
onCleanup(() => {
|
|
328
|
+
if (mine && currentReading === mine) {
|
|
329
|
+
currentReading = undefined
|
|
330
|
+
void mine.stop()
|
|
331
|
+
}
|
|
332
|
+
})
|
|
333
|
+
|
|
334
|
+
const reason = () => availability().reason
|
|
335
|
+
const label = () => (speaking() ? 'Stop reading' : 'Read aloud')
|
|
336
|
+
return (
|
|
337
|
+
<ActionButton
|
|
338
|
+
type="button"
|
|
339
|
+
variant="ghost"
|
|
340
|
+
size="icon-xs"
|
|
341
|
+
data-slot="message-action"
|
|
342
|
+
aria-label={label()}
|
|
343
|
+
aria-pressed={speaking() ? 'true' : 'false'}
|
|
344
|
+
tooltip={speaking() ? label() : (reason() ?? error() ?? label())}
|
|
345
|
+
tooltipSide="bottom"
|
|
346
|
+
disabled={!speaking() && (!availability().ready || Boolean(reason()))}
|
|
347
|
+
onClick={() => void (speaking() ? stop() : start())}
|
|
348
|
+
>
|
|
349
|
+
<Show when={speaking()} fallback={<Volume2 aria-hidden="true" />}>
|
|
350
|
+
<Square aria-hidden="true" />
|
|
351
|
+
</Show>
|
|
352
|
+
</ActionButton>
|
|
353
|
+
)
|
|
354
|
+
}
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The framework's voice service boundary: the names, inputs and events a renderer and a desktop
|
|
3
|
+
* shell exchange, whatever transport carries them (the framework service registry in Cortana,
|
|
4
|
+
* Adea's own command channel). The speech engines, routing, error vocabulary and privacy rules
|
|
5
|
+
* are `@adea-ai/voice`'s; this file only fixes the shape of the conversation and validates every
|
|
6
|
+
* value that crosses it.
|
|
7
|
+
*/
|
|
8
|
+
import { VoiceError, type VoiceErrorCode } from '@adea-ai/voice/contract'
|
|
9
|
+
import { validateVoiceSettings, type VoiceSettings } from '@adea-ai/voice/settings'
|
|
10
|
+
|
|
11
|
+
export const VOICE_SERVICES = {
|
|
12
|
+
capabilities: 'voice.capabilities',
|
|
13
|
+
permission: 'voice.permission',
|
|
14
|
+
dictateStart: 'voice.dictate-start',
|
|
15
|
+
dictateEnd: 'voice.dictate-end',
|
|
16
|
+
dictateCancel: 'voice.dictate-cancel',
|
|
17
|
+
speak: 'voice.speak',
|
|
18
|
+
speakStop: 'voice.speak-stop',
|
|
19
|
+
voices: 'voice.voices',
|
|
20
|
+
locales: 'voice.locales',
|
|
21
|
+
installAssets: 'voice.install-assets',
|
|
22
|
+
installCancel: 'voice.install-cancel',
|
|
23
|
+
releaseAssets: 'voice.release-assets',
|
|
24
|
+
events: 'voice.events',
|
|
25
|
+
} as const
|
|
26
|
+
export type VoiceServiceName = (typeof VOICE_SERVICES)[keyof typeof VOICE_SERVICES]
|
|
27
|
+
|
|
28
|
+
/** The system voice reading an utterance aloud, as the helper resolved it. */
|
|
29
|
+
export type VoiceSpeechVoice = Readonly<{
|
|
30
|
+
/** The voice identifier (what the settings' `tts.voice` can pin). */
|
|
31
|
+
id: string
|
|
32
|
+
name: string
|
|
33
|
+
/** The voice's own locale, e.g. `es-MX` when `es-419` was asked for. */
|
|
34
|
+
language: string
|
|
35
|
+
/** The same value as `language`, as the voice list items name it (helpers after 0.3.0). */
|
|
36
|
+
locale?: string
|
|
37
|
+
quality: 'default' | 'enhanced' | 'premium' | 'unknown'
|
|
38
|
+
}>
|
|
39
|
+
|
|
40
|
+
/** Pushed from the shell to the renderer through `voice.events` (a long poll with a cursor). */
|
|
41
|
+
export type VoiceEvent =
|
|
42
|
+
| { readonly type: 'dictation-partial'; readonly id: string; readonly text: string }
|
|
43
|
+
| { readonly type: 'dictation-final'; readonly id: string; readonly text: string }
|
|
44
|
+
| {
|
|
45
|
+
readonly type: 'dictation-failed'
|
|
46
|
+
readonly id: string
|
|
47
|
+
readonly code: VoiceErrorCode
|
|
48
|
+
readonly message: string
|
|
49
|
+
}
|
|
50
|
+
| { readonly type: 'dictation-cancelled'; readonly id: string }
|
|
51
|
+
| {
|
|
52
|
+
readonly type: 'speech-started'
|
|
53
|
+
readonly id: string
|
|
54
|
+
/** The voice speaking, when the helper reports it (helpers after 0.2.0). */
|
|
55
|
+
readonly voice?: VoiceSpeechVoice
|
|
56
|
+
}
|
|
57
|
+
| { readonly type: 'speech-finished'; readonly id: string }
|
|
58
|
+
| { readonly type: 'speech-cancelled'; readonly id: string }
|
|
59
|
+
| {
|
|
60
|
+
readonly type: 'speech-failed'
|
|
61
|
+
readonly id: string
|
|
62
|
+
readonly code: VoiceErrorCode
|
|
63
|
+
readonly message: string
|
|
64
|
+
}
|
|
65
|
+
| { readonly type: 'install-progress'; readonly id: string; readonly fraction: number | null }
|
|
66
|
+
| { readonly type: 'install-finished'; readonly id: string }
|
|
67
|
+
| {
|
|
68
|
+
readonly type: 'install-failed'
|
|
69
|
+
readonly id: string
|
|
70
|
+
readonly code: VoiceErrorCode
|
|
71
|
+
readonly message: string
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
export type VoiceEventBatch = Readonly<{ cursor: number; events: readonly VoiceEvent[] }>
|
|
75
|
+
|
|
76
|
+
/** Largest text one read-aloud request may carry (about 30 minutes of speech). */
|
|
77
|
+
export const MAX_SPEAK_CHARACTERS = 20_000
|
|
78
|
+
/** A long poll returns after this long with no events, so a transport never idles out. */
|
|
79
|
+
export const EVENTS_WAIT_MS = 25_000
|
|
80
|
+
|
|
81
|
+
/** Malformed input is the caller's mistake: a typed `bad_request`, never a bare failure. */
|
|
82
|
+
const bad = (message: string) => new VoiceError('bad_request', message)
|
|
83
|
+
|
|
84
|
+
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
85
|
+
value !== null && typeof value === 'object' && !Array.isArray(value)
|
|
86
|
+
|
|
87
|
+
function onlyKeys(value: Record<string, unknown>, allowed: readonly string[]): void {
|
|
88
|
+
for (const key of Object.keys(value))
|
|
89
|
+
if (!allowed.includes(key)) throw bad(`Unexpected field ${key}`)
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
function optionalLocale(value: unknown): string | undefined {
|
|
93
|
+
if (value === undefined) return undefined
|
|
94
|
+
if (typeof value !== 'string' || value.length === 0 || value.length > 64)
|
|
95
|
+
throw bad('Invalid locale')
|
|
96
|
+
const [canonical] = Intl.getCanonicalLocales(value)
|
|
97
|
+
if (!canonical) throw bad('Invalid locale')
|
|
98
|
+
return canonical
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** Settings always cross the boundary whole and are re-validated on the shell side. */
|
|
102
|
+
function settings(value: unknown): VoiceSettings {
|
|
103
|
+
const read = validateVoiceSettings(value)
|
|
104
|
+
if (read.issues.length > 0) throw bad(`Invalid voice settings: ${read.issues.join('; ')}`)
|
|
105
|
+
return read.settings
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
const id = (value: unknown): string => {
|
|
109
|
+
if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(value)) throw bad('Invalid id')
|
|
110
|
+
return value
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
export const parseVoiceInput = {
|
|
114
|
+
capabilities(value: unknown): { settings: VoiceSettings; locale?: string } {
|
|
115
|
+
if (!isRecord(value)) throw bad('Invalid request')
|
|
116
|
+
onlyKeys(value, ['settings', 'locale'])
|
|
117
|
+
const locale = optionalLocale(value.locale)
|
|
118
|
+
return { settings: settings(value.settings), ...(locale ? { locale } : {}) }
|
|
119
|
+
},
|
|
120
|
+
permission(value: unknown): { request: boolean } {
|
|
121
|
+
if (!isRecord(value)) throw bad('Invalid request')
|
|
122
|
+
onlyKeys(value, ['request'])
|
|
123
|
+
if (value.request !== undefined && typeof value.request !== 'boolean')
|
|
124
|
+
throw bad('Invalid request')
|
|
125
|
+
return { request: value.request === true }
|
|
126
|
+
},
|
|
127
|
+
dictateStart(value: unknown): { settings: VoiceSettings; locale?: string } {
|
|
128
|
+
return parseVoiceInput.capabilities(value)
|
|
129
|
+
},
|
|
130
|
+
dictation(value: unknown): { id: string } {
|
|
131
|
+
if (!isRecord(value)) throw bad('Invalid request')
|
|
132
|
+
onlyKeys(value, ['id'])
|
|
133
|
+
return { id: id(value.id) }
|
|
134
|
+
},
|
|
135
|
+
speak(value: unknown): {
|
|
136
|
+
settings: VoiceSettings
|
|
137
|
+
text: string
|
|
138
|
+
locale?: string
|
|
139
|
+
queue: 'replace' | 'after-current'
|
|
140
|
+
} {
|
|
141
|
+
if (!isRecord(value)) throw bad('Invalid request')
|
|
142
|
+
onlyKeys(value, ['settings', 'text', 'locale', 'queue'])
|
|
143
|
+
if (
|
|
144
|
+
typeof value.text !== 'string' ||
|
|
145
|
+
value.text.trim().length === 0 ||
|
|
146
|
+
value.text.length > MAX_SPEAK_CHARACTERS
|
|
147
|
+
)
|
|
148
|
+
throw bad('Invalid text')
|
|
149
|
+
if (value.queue !== undefined && value.queue !== 'replace' && value.queue !== 'after-current')
|
|
150
|
+
throw bad('Invalid queue')
|
|
151
|
+
const locale = optionalLocale(value.locale)
|
|
152
|
+
return {
|
|
153
|
+
settings: settings(value.settings),
|
|
154
|
+
text: value.text,
|
|
155
|
+
...(locale ? { locale } : {}),
|
|
156
|
+
queue: (value.queue as 'replace' | 'after-current' | undefined) ?? 'replace',
|
|
157
|
+
}
|
|
158
|
+
},
|
|
159
|
+
none(value: unknown): null {
|
|
160
|
+
if (
|
|
161
|
+
value !== null &&
|
|
162
|
+
value !== undefined &&
|
|
163
|
+
!(isRecord(value) && Object.keys(value).length === 0)
|
|
164
|
+
)
|
|
165
|
+
throw bad('Invalid request')
|
|
166
|
+
return null
|
|
167
|
+
},
|
|
168
|
+
voices(value: unknown): { settings: VoiceSettings; locale?: string } {
|
|
169
|
+
return parseVoiceInput.capabilities(value)
|
|
170
|
+
},
|
|
171
|
+
installAssets(value: unknown): { locale: string } {
|
|
172
|
+
if (!isRecord(value)) throw bad('Invalid request')
|
|
173
|
+
onlyKeys(value, ['locale'])
|
|
174
|
+
const locale = optionalLocale(value.locale)
|
|
175
|
+
if (!locale) throw bad('Invalid locale')
|
|
176
|
+
return { locale }
|
|
177
|
+
},
|
|
178
|
+
/** Removing a model names one locale, like an install. */
|
|
179
|
+
releaseAssets(value: unknown): { locale: string } {
|
|
180
|
+
return parseVoiceInput.installAssets(value)
|
|
181
|
+
},
|
|
182
|
+
events(value: unknown): { after: number } {
|
|
183
|
+
if (!isRecord(value)) throw bad('Invalid request')
|
|
184
|
+
onlyKeys(value, ['after'])
|
|
185
|
+
if (!Number.isSafeInteger(value.after) || (value.after as number) < 0)
|
|
186
|
+
throw bad('Invalid cursor')
|
|
187
|
+
return { after: value.after as number }
|
|
188
|
+
},
|
|
189
|
+
}
|