@wcstack/speech

@wcstack/speech

@wcstack/speech is a headless Web Speech component pair for the wcstack ecosystem.

These are not visual UI widgets. They are async primitive nodes that turn the browser's Web Speech APIs into reactive state — the same way @wcstack/fetch turns a network request into reactive state and @wcstack/geolocation turns the device's location into reactive state.

The package ships two complementary tags, the two halves of the same protocol:

Tag	API	Direction	Protocol role
<wcs-speak>	SpeechSynthesis (TTS)	state → speech	command-token (state drives speech)
<wcs-listen>	SpeechRecognition (STT)	speech → state	event-token (recognition flows to state)

Their coexistence in one package is the point: <wcs-speak> is a perfect showcase of command-driven output, <wcs-listen> of event-driven input. Wire them together for a speak ⇄ listen loop.

Both follow the CSBC (Core / Shell / Binding Contract) architecture:

• Core (SpeakCore / ListenCore) wraps the native API, normalizes data, manages lifecycle/permission, and never throws (failures surface through error).
• Shell (<wcs-speak> / <wcs-listen>) connects that state to DOM attributes, lifecycle, and declarative commands.
• Binding Contract (static wcBindable) declares observable properties, writable inputs, and callable commands.

Install

npm install @wcstack/speech

Or buildless via CDN (registers both tags):

<script type="module" src="https://esm.run/@wcstack/speech/auto"></script>

---

<wcs-speak> — text to speech

Two ways to speak

<wcs-speak> exposes the same action through two surfaces that differ in when they fire:

<!-- 1. Reactive: speaks whenever `status` changes (same value is NOT re-spoken). -->
<wcs-speak data-wcs="say: status"></wcs-speak>

<!-- 2. Imperative: speaks on demand, even the same text again, via the command token. -->
<wcs-speak data-wcs="command.speak: $command.announce"></wcs-speak>

// state
export default {
  $commandTokens: ["announce"],
  status: "Ready.",
  onClick() {
    this.$command.announce.emit("Button clicked again.");  // imperative — re-speaks same text
  },
};

Surface	Fires when	Same value re-speaks?	Use for
say (reactive input)	the bound value changes	no (guarded)	status / a11y announcements
speak (imperative command)	the command is invoked	yes	"speak this on click", "say it again"

Tip: wire say through a \|debounce filter when binding to a rapidly-changing source (e.g. an <input> value), or it will speak on every keystroke. Set the manual attribute to mute the say path entirely (also the hook for muting speech while listening — see the echo example).

Word-boundary highlighting

charIndex / spokenWord update as each word is spoken — bind them to highlight the currently-spoken word (karaoke-style).

Attributes / Inputs

Attribute	Input	Type	Default	Meaning
—	say	string	—	reactive: writing a new value speaks it
rate	rate	number	1	speech rate (0.1–10)
pitch	pitch	number	1	pitch (0–2)
volume	volume	number	1	volume (0–1)
voice	voice	string	—	voice selected by name
lang	lang	string	—	BCP-47 language tag
manual	manual	boolean	false	mute the say path

Observable Properties (outputs)

Property	Type	Meaning
voices	SpeechVoiceInfo[]	available voices (populated asynchronously)
speaking	boolean	an utterance is being spoken
paused	boolean	speech is paused
pending	boolean	utterances are queued
charIndex	number | null	offset of the word being spoken
spokenWord	string | null	the word being spoken
error	WcsSpeakErrorDetail | null	last failure
unsupported	boolean	SpeechSynthesis is unavailable

Commands

Command	Meaning
speak(text)	queue an utterance (uses current rate/pitch/… attributes)
cancel()	clear the queue and stop
pause() / resume()	suspend / resume

Optional DOM triggering

With autoTrigger on (default), clicking an element carrying data-speaktarget="<id>" speaks its data-speaktext (or its text content) through the <wcs-speak id="<id>">.

<wcs-speak id="tts"></wcs-speak>
<button data-speaktarget="tts" data-speaktext="Hello!">Speak</button>

---

<wcs-listen> — speech to text

<!-- Auto-start on connect; bind the transcript to state -->
<wcs-listen lang="en-US" interim data-wcs="finalTranscript: transcript; interimTranscript: draft"></wcs-listen>

<!-- Manual, continuous, command-driven -->
<wcs-listen manual continuous max-restarts="5"
  data-wcs="command.start: $command.listen; finalTranscript: transcript; listening: isListening"></wcs-listen>

Like <wcs-geo>, it has two phases: a one-shot recognition (default) and a continuous session (continuous attribute). The browser still ends a session on silence; auto-restart bridges that, but is opt-in via max-restarts — continuous alone (with the default max-restarts="0") does not restart on silence. Set max-restarts="5" to bridge up to 5 silences. This bound is deliberate: unbounded restart is an infinite-loop / quota-exhaustion risk.

Microphone auto-start. Without manual, <wcs-listen> calls start() on connect — placing the tag in the DOM begins recognition (a permission prompt, then continuous capture). Add manual to require an explicit start() / DOM-trigger / trigger write instead. Mirrors <wcs-geo>'s manual convention, but mind that microphone capture is more privacy-sensitive.

Attributes / Inputs

Attribute	Input	Type	Default	Meaning
lang	lang	string	—	BCP-47 language tag
continuous	continuous	boolean	false	keep the session open & auto-restart on end
interim	interim	boolean	false	emit live interim transcripts
max-restarts	maxRestarts	number	0	cap on automatic restarts (continuous)
manual	manual	boolean	false	do not auto-start on connect
—	trigger	boolean	—	momentary: false→true starts a session

Observable Properties (outputs)

Property	Type	Meaning
interimTranscript	string	live, not-yet-final text
finalTranscript	string	accumulated final text
result	WcsListenResultDetail | null	latest result (transcript / confidence / alternatives / isFinal)
listening	boolean	a session is active
permission	"prompt"|"granted"|"denied"|"unsupported"	microphone permission
error	WcsListenErrorDetail | null	last failure
unsupported	boolean	SpeechRecognition is unavailable

Commands

Command	Meaning
start()	begin a session (resets transcripts)
stop()	stop gracefully (no auto-restart)
abort()	stop immediately

Optional DOM triggering

Clicking an element with data-listentarget="<id>" toggles start() / stop() on the target <wcs-listen>.

---

Notes & limitations

• Secure context required. Both APIs need HTTPS or localhost; <wcs-listen> additionally needs microphone permission.
• Browser support. SpeechSynthesis is broad; SpeechRecognition is Chrome-only (vendor-prefixed webkitSpeechRecognition) — <wcs-listen> reports unsupported elsewhere.
• SpeechSynthesis is a global singleton. <wcs-speak> does not cancel() on disconnect (that would stop other instances); call cancel() explicitly to stop audio. A disconnected element stops tracking but any in-flight utterance finishes.
• Echo loop. When wiring <wcs-listen> → state → <wcs-speak>, mute speaking while listening (e.g. bind manual) so the synthesized audio is not re-recognized. See the echo example.

Headless usage (SpeakCore / ListenCore)

Both Cores are framework-agnostic and usable without the custom elements, via bind() from @wc-bindable/core:

import { SpeakCore } from "@wcstack/speech";
const core = new SpeakCore();
core.speak("Hello, world.");

License

MIT