@cutos/speech-synthesis

Browser-side text-to-speech SDK for CUTOS 4.0 LWA applications. It wraps the standard Web Speech API (window.speechSynthesis) and uses voices exposed by the current browser or Windows WebView runtime.

This is an npm SDK, not a CUTOS Capability/Provider:

• no Device Provider or .drv package;
• no Gateway service;
• no CUTOS Server request; and
• no required network connection.

For offline speech, install a compatible local Windows voice and prefer a voice returned with localService: true.

Installation

npm install @cutos/speech-synthesis

The package has no runtime npm dependencies.

Quick Start

Call speak() from a user action, such as a button click. Some Chromium and WebView runtimes block automatically started speech.

import { SpeechSynthesizer } from '@cutos/speech-synthesis'

if (!SpeechSynthesizer.isSupported()) {
  throw new Error('This CUTOS Runtime does not expose the Web Speech API.')
}

const speech = new SpeechSynthesizer()
const voices = await speech.ready()
const voice = voices.find(item => item.localService && item.lang.toLowerCase().startsWith('zh'))

await speech.speak({
  text: '欢迎使用 CUTOS',
  lang: 'zh-CN',
  voiceURI: voice?.voiceURI,
  rate: 1,
  pitch: 1,
  volume: 1
})

API

SpeechSynthesizer.isSupported()

Returns true only when both speechSynthesis and SpeechSynthesisUtterance are exposed by the current runtime. Constructing SpeechSynthesizer when unsupported throws SpeechSynthesisUnavailableError.

new SpeechSynthesizer()

Creates a wrapper around the browser-global speech synthesis queue. The browser owns that queue, so use one application-level instance rather than creating multiple competing instances.

ready(timeoutMs?: number)

Returns Promise<SpeechVoiceInfo[]>. Voice enumeration is asynchronous in many Windows WebView runtimes; this method waits for voiceschanged for up to 1500 ms by default, then returns the currently available voice list. It does not guarantee that a voice is installed.

getVoices(query?: VoiceQuery)

Returns serializable metadata for the currently available voices.

const allVoices = speech.getVoices()
const localChineseVoices = speech.getVoices({ lang: 'zh-CN', localOnly: true })

interface VoiceQuery {
  lang?: string       // prefix match, for example "zh" or "en-US"
  localOnly?: boolean // only voices whose runtime reports localService: true
}

interface SpeechVoiceInfo {
  name: string
  lang: string
  voiceURI: string
  localService: boolean
  default: boolean
}

localService is supplied by the underlying runtime. Treat it as a useful preference, not an absolute guarantee about how a voice vendor implements synthesis.

speak(options)

Queues one utterance and returns Promise<SpeechResult> when it completes. Text is trimmed and cannot be empty. If voiceURI is supplied, it must identify a voice returned by getVoices().

const result = await speech.speak({
  text: 'CUTOS is ready.',
  lang: 'en-US',
  voiceURI: selectedVoice.voiceURI,
  rate: 1,
  pitch: 1,
  volume: 0.9
})

console.log(result.elapsedTime, result.charIndex)

interface SpeakOptions {
  text: string
  lang?: string
  voiceURI?: string
  rate?: number   // 0.1–10, default 1
  pitch?: number  // 0–2, default 1
  volume?: number // 0–1, default 1
}

interface SpeechResult {
  status: 'completed'
  elapsedTime: number // seconds reported by the browser when available
  charIndex: number
}

Calling speak() while another SDK utterance is active first cancels that utterance. The earlier promise rejects with SPEECH_CANCELLED; the new utterance then starts.

Playback Controls And State

speech.pause()
speech.resume()
speech.cancel()

const state = speech.getState()
// { supported: true, speaking, pending, paused }

cancel() stops the active SDK utterance and rejects its pending speak() promise with SPEECH_CANCELLED.

Events

const off = speech.on('boundary', event => {
  console.log(event.charIndex, event.elapsedTime)
})

off()
// or: speech.off('boundary')

Supported event names are start, end, pause, resume, boundary, error, and cancel.

interface SpeechEvent {
  type: SpeechEventType
  timestamp: number
  charIndex?: number
  elapsedTime?: number
  error?: string
  text?: string
}

Errors

All operational SDK errors extend SpeechSynthesisError and expose a stable code.

| Code | Meaning | | --- | --- | | EMPTY_TEXT | speak() received empty or whitespace-only text. | | VOICE_NOT_FOUND | voiceURI is not present in the current voice list. | | SPEECH_CANCELLED | cancel() or a later speak() cancelled the active utterance. | | SPEECH_ERROR or browser value | The Web Speech API reported a synthesis error. |

SpeechSynthesisUnavailableError is thrown when the runtime has no Web Speech API implementation.

Offline Windows Requirements

• The LWA must run in a Windows CUTOS Runtime whose WebView exposes the Web Speech API.
• Windows must have a language speech voice installed and visible to that WebView.
• The SDK never uploads text or downloads voice data.
• Do not select voices named Online when offline operation is a requirement; prefer a listed local voice and validate it on the target Runtime.

Use demo-speech-synthesis to inspect the actual voice list and validate speech on a target device before release.