@gjsify/speech-recognition 0.0.0-stage → 0.64.33-next.323

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# @gjsify/speech-recognition
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+W3C Web Speech `SpeechRecognition` for GJS, recognized **on this machine**: the streaming zipformer of [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) through [`@gjsify/sherpa-native`](../sherpa-native#readme), with speech boundaries from [`@gjsify/vad`](../vad#readme) and audio from [`@gjsify/media-capture`](../media-capture#readme). Nothing talks to a recognition service. Linux x64 only today. Tier 3 (experimental, [ADR 0003](../../../docs/adr/0003-package-tiering.md)) until promoted. This is step 3 of [ADR 0127](../../../docs/adr/0127-speech-recognition-on-local-engines.md).
+
+Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
+
+## Installation
+
+```bash
+gjsify install @gjsify/speech-recognition
+```
+
+## Usage
+
+The model is not bundled. `available()` and `install()` are the spec's on-device additions (Web Speech draft of 27 Oct 2026):
+
+```typescript
+import '@gjsify/speech-recognition/register';
+
+const options = { langs: ['de-DE'], processLocally: true };
+if ((await SpeechRecognition.available(options)) === 'downloadable') {
+    await SpeechRecognition.install(options);
+}
+
+const recognition = new SpeechRecognition();
+recognition.lang = 'de-DE';
+recognition.interimResults = true;
+recognition.continuous = true;
+recognition.onresult = (event) => {
+    const result = event.results[event.resultIndex];
+    console.log(result.isFinal ? 'final:' : 'interim:', result[0].transcript);
+};
+recognition.onerror = (event) => console.warn(event.error, event.message);
+recognition.start();   // default capture device, 16 kHz mono
+// …
+recognition.stop();    // delivers the pending utterance, then `end`
+```
+
+Without `/register`, import the classes: `import { SpeechRecognition } from '@gjsify/speech-recognition'`.
+
+## Surface
+
+| Member | Behavior here |
+|---|---|
+| `start()` / `stop()` / `abort()` | per spec; `start()` while running throws `InvalidStateError`. `stop()` still delivers the pending utterance, `abort()` drops it |
+| `start(track)` | the track is validated, but a real `MediaStreamTrack` fires `audio-capture` (not supported yet) |
+| `lang`, `continuous`, `interimResults`, `maxAlternatives` | per spec. In continuous mode later transcripts are space-prefixed |
+| `processLocally` | **always `true`**; setting `false` throws `NotSupportedError`. The spec default is `false`; ADR 0127 decision 3 overrides it, since there is no remote engine to fall back to |
+| `phrases` | a plain array of `SpeechRecognitionPhrase` (`boost` in [0, 10]). The zipformer has no hotwords, so a non-empty list fires error `phrases-not-supported` |
+| `grammars`, `serviceURI` | not implemented |
+| `SpeechRecognition.available({ langs, processLocally })` | worst status over `langs`: `available` < `downloading` < `downloadable` < `unavailable`. A missing **engine** is `unavailable`, so a prompt never fetches a model for nothing. Invalid BCP 47 rejects with `SyntaxError` |
+| `SpeechRecognition.install({ langs, processLocally })` | `true` once cached; `false` for empty or unsupported `langs`. `processLocally` is ignored |
+| events | `start`, `audiostart`, `soundstart`, `speechstart`, `speechend`, `soundend`, `audioend`, `result`, `nomatch`, `error`, `end` |
+
+Errors use the spec vocabulary plus `language-not-supported` (no model for `lang`), `phrases-not-supported`, `audio-capture` and `service-not-allowed`.
+
+`hasRecognitionBackend()` / `describeRecognitionBackend()` say whether, and why not, an engine is there. `createFakeRecognizerEngine()` and the `engine` / `vad` / `source` members of `SpeechRecognitionInit` let an app test its handling without a model, a microphone or sound.
+
+## Finalizing
+
+The VAD (300 ms of silence) is the primary finalizer, so a final result lands roughly 300 ms after the speaker stops plus decoding. When the VAD model is not cached, the zipformer's own endpoint detection finalizes instead, which is later and less steady.
+
+## Latency budget and engine candidates
+
+[Lotse](https://github.com/JumpLink/lotse) needs a spoken conversation mode with **500 ms from end of speech to text**. Its measurements on an i9-10900K / RX 6600 (2026-10-28 to 30), as recorded in ADR 0127:
+
+| Engine / model | WER | end-to-end | footprint |
+|---|---|---|---|
+| whisper.cpp `large-v3-turbo` q5_0, Vulkan, GPU idle | 7.3 % / 10.8 % | 428 / 457 ms | 548 MB model |
+| the same, GPU computing | 7.3 % / 10.8 % | 1170 / 1420 ms | 548 MB model |
+| sherpa-onnx `parakeet-tdt-0.6b-v3` int8, CPU | 12.0 % / 13.1 % | 239 / 339 ms | 641 MB, 1.1 GB RSS |
+| sherpa-onnx streaming `zipformer-de-kroko`, CPU | 15.3 % / 16.5 % | 32 / 53 ms | 68 MB |
+| whisper.cpp CPU, `small` and up | — | 2–18 s | misses the budget |
+
+This package ships the **streaming zipformer** row: it is the only candidate that yields interim results and needs no GPU. Measured for `zipformer-de-kroko`: about **32 ms after the end of speech**, 183 MB RSS, CPU only. The whisper-native backend (accurate finals) and the machine-fit choice between backends are later ADR 0127 steps and not part of this package.
+
+## Model
+
+`sherpa-onnx-streaming-zipformer-de-kroko-2025-08-06`, four files fetched through [`@gjsify/model-store`](../model-store#readme) (size and SHA-256 verified before a file reaches its place), cached under `models/speech/`. The licence is Kroko's community licence (advertised as CC-BY-SA; the model card says `license: other`), so the entry is marked `redistributable: false` — gjsify downloads it from upstream and never bundles it.
+
+## Tests
+
+No test plays or records sound. The session logic runs on a fake engine and a fake VAD; the GStreamer path reads `audiotestsrc`/`filesrc` into a `fakesink`-style reader. The real-engine suite skips unless the prebuild and the cached model are there, and no CI job downloads a model. Accuracy is asserted as "the final contains these words", never an exact string.
+
+| Variable | Effect |
+|---|---|
+| `GJSIFY_SPEECHREC_TEST_WAV` | a 16 kHz mono WAV with speech, for the real-engine suite |
+| `GJSIFY_SPEECHREC_EXPECT` | comma-separated words the final must contain |
+
+## License
+
+MIT

package/globals.mjs

@@ -0,0 +1,26 @@
+/**
+ * Re-exports the browser's own Web Speech recognition globals; the sherpa-onnx GJS backend
+ * stays GJS-only.
+ *
+ * `@gjsify/resolve-npm/runtime-aliases.mjs` routes `@gjsify/speech-recognition` here whenever
+ * `gjsify.runtimes.<target> === "native"`, so every root export a consumer may import must
+ * be answerable from here or the routed bundle dies with `MISSING_EXPORT`.
+ */
+
+export const SpeechRecognition = globalThis.SpeechRecognition ?? globalThis.webkitSpeechRecognition;
+export const SpeechRecognitionEvent = globalThis.SpeechRecognitionEvent;
+export const SpeechRecognitionErrorEvent = globalThis.SpeechRecognitionErrorEvent;
+export const SpeechRecognitionResult = globalThis.SpeechRecognitionResult;
+export const SpeechRecognitionResultList = globalThis.SpeechRecognitionResultList;
+export const SpeechRecognitionAlternative = globalThis.SpeechRecognitionAlternative;
+export const SpeechRecognitionPhrase = globalThis.SpeechRecognitionPhrase;
+
+/** Whether this host has a recognizer at all. In a browser: the browser's own. */
+export async function hasSpeechRecognitionBackend() {
+    return typeof SpeechRecognition === 'function';
+}
+
+/** Which backend recognizes, in words. In a browser: the browser's own. */
+export async function describeSpeechRecognitionBackend() {
+    return (await hasSpeechRecognitionBackend()) ? 'browser (native SpeechRecognition)' : 'none';
+}

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/backend.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{getLoadError as e,hasNativeSherpa as t,loadNativeSherpa as n}from"@gjsify/sherpa-native";import{hostOs as r}from"@gjsify/utils/core";function hasRecognitionBackend(){let e=r();return e===`darwin`||e===`win32`?!1:t()}function describeRecognitionBackend(){if(!hasRecognitionBackend()){let t=e();return`none: @gjsify/sherpa-native is not available on this host${t?` (${t.message})`:``}`}let t=n();return`sherpa-onnx ${t.version()} on onnxruntime ${t.onnxruntime_version()} (@gjsify/sherpa-native)`}function createSherpaEngine(e){let t=n();if(t===null)throw Error(describeRecognitionBackend());let r=new t.OnlineRecognizer({encoder:e.encoder,decoder:e.decoder,joiner:e.joiner,tokens:e.tokens,sample_rate:e.sampleRate,num_threads:e.numThreads??1,enable_endpoint:!0}),i=null,feed=t=>{let n=i;for(n.accept(e.sampleRate,t);n.is_ready();)n.decode();return{text:n.get_text(),endpoint:n.is_endpoint()}};return{open(){r.open(),i??=r.create_stream(null)},accept:feed,flushTail(){return feed(new Float32Array(Math.round(e.sampleRate*.5)))},detail(){try{let e=JSON.parse(i.get_json());return{tokens:e.tokens??[],timestamps:e.timestamps??[],logProbs:e.ys_probs??[]}}catch{return{tokens:[],timestamps:[],logProbs:[]}}},reset(){i.reset()},close(){i?.close(),i=null,r.close()}}}export{createSherpaEngine,describeRecognitionBackend,hasRecognitionBackend};

package/lib/esm/events.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{SpeechRecognitionResultList as e}from"./results.js";import{Event as t}from"@gjsify/dom-events";var SpeechRecognitionEvent=class extends t{resultIndex;results;constructor(t,n={}){super(t,n),this.resultIndex=n.resultIndex??0,this.results=n.results??new e}get[Symbol.toStringTag](){return`SpeechRecognitionEvent`}},SpeechRecognitionErrorEvent=class extends t{error;message;constructor(e,t){super(e,t),this.error=t.error,this.message=t.message??``}get[Symbol.toStringTag](){return`SpeechRecognitionErrorEvent`}};function defineEventHandler(e,t){let n=Symbol(`on${t}`);Object.defineProperty(e,`on${t}`,{configurable:!0,enumerable:!0,get(){return this[n]??null},set(e){this[n]&&this.removeEventListener(t,this[n]),this[n]=typeof e==`function`?e:null,this[n]&&this.addEventListener(t,this[n])}})}export{SpeechRecognitionErrorEvent,SpeechRecognitionEvent,defineEventHandler};

package/lib/esm/fake-engine.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";function createFakeRecognizerEngine(){let e=[],t=0,n={text:``},r=null,i={tokens:[],timestamps:[],logProbs:[]},a={samples:0,resets:0,tails:0,opened:!1,closed:!1},frame=e=>({text:e.text,endpoint:e.endpoint??!1});return{script(n){e=[...n],t=0},setTailText(e){r=e},setDetail(e){i={tokens:[],timestamps:[],logProbs:[],...e}},get samplesAccepted(){return a.samples},get resets(){return a.resets},get tailFlushes(){return a.tails},get opened(){return a.opened},get closed(){return a.closed},open(){a.opened=!0},accept(r){return a.samples+=r.length,t<e.length&&(n=e[t++]),frame(n)},flushTail(){return a.tails++,frame({text:r??n.text})},detail:()=>i,reset(){a.resets++,n={text:``},r=null},close(){a.closed=!0}}}export{createFakeRecognizerEngine};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import{createSherpaEngine as e,describeRecognitionBackend as t,hasRecognitionBackend as n}from"./backend.js";import{SpeechRecognitionAlternative as r,SpeechRecognitionPhrase as i,SpeechRecognitionResult as a,SpeechRecognitionResultList as o}from"./results.js";import{SpeechRecognitionErrorEvent as s,SpeechRecognitionEvent as c}from"./events.js";import{createFakeRecognizerEngine as l}from"./fake-engine.js";import{DEFAULT_RECOGNITION_MODEL as u,RECOGNITION_MODELS as d,findRecognitionModel as f,modelFor as p}from"./model-manifest.js";import{available as m,install as h,isModelCached as g,modelCacheDir as _,uninstall as v}from"./models.js";import{SpeechRecognition as y}from"./recognition.js";export{u as DEFAULT_RECOGNITION_MODEL,d as RECOGNITION_MODELS,y as SpeechRecognition,r as SpeechRecognitionAlternative,s as SpeechRecognitionErrorEvent,c as SpeechRecognitionEvent,i as SpeechRecognitionPhrase,a as SpeechRecognitionResult,o as SpeechRecognitionResultList,m as available,l as createFakeRecognizerEngine,e as createSherpaEngine,t as describeRecognitionBackend,f as findRecognitionModel,n as hasRecognitionBackend,h as install,g as isModelCached,_ as modelCacheDir,p as modelFor,v as uninstall};

package/lib/esm/model-manifest.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";const e=[`command`,`dictation`,`conversation`],t=`zipformer-de-kroko`,n=`https://huggingface.co/csukuangfj/sherpa-onnx-streaming-zipformer-de-kroko-2025-08-06/resolve/main`,r=[{id:`zipformer-de-kroko`,files:[{file:`encoder.onnx`,url:`${n}/encoder.onnx`,bytes:70091557,sha256:`6e83993d6967ec7a3498b055b7e85ace85b5d64d1b1e8773cb29a43a11f5edb5`},{file:`decoder.onnx`,url:`${n}/decoder.onnx`,bytes:617489,sha256:`94a29592b403c53fa2231b478637da1ab4abcef7f5e46e432098416a4a3ed562`},{file:`joiner.onnx`,url:`${n}/joiner.onnx`,bytes:336817,sha256:`28356bff070aea51ab1d725a3278e81d19f9300f860d3248a7014292264df15a`},{file:`tokens.txt`,url:`${n}/tokens.txt`,bytes:5606,sha256:`86e8370994ff2c01149ba8c4f8709aa93cdc18914b27a717e291e96faf39a6eb`}],license:`Kroko community model (advertised CC-BY-SA; the mirror declares none)`,redistributable:!1,description:`Kroko streaming zipformer, German (68 MB) — interim results on CPU, ~32 ms after end of speech.`,langs:[`de`],quality:`dictation`,sampleRate:16e3,hotwords:!1,encoder:`encoder.onnx`,decoder:`decoder.onnx`,joiner:`joiner.onnx`,tokens:`tokens.txt`}];function findRecognitionModel(e=t){return r.find(t=>t.id===e)}function modelFor(t,n=`command`){let i=t.split(`-`)[0].toLowerCase(),a=e.indexOf(n);return r.find(t=>t.langs.includes(i)&&e.indexOf(t.quality)>=a)}export{t as DEFAULT_RECOGNITION_MODEL,e as QUALITY_ORDER,r as RECOGNITION_MODELS,findRecognitionModel,modelFor};

package/lib/esm/models.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{hasRecognitionBackend as e}from"./backend.js";import{syntaxError as t}from"./results.js";import{DEFAULT_RECOGNITION_MODEL as n,RECOGNITION_MODELS as r,modelFor as i}from"./model-manifest.js";import{ModelStore as a}from"@gjsify/model-store";const o=new a({capability:`speech`,models:r,defaultModel:n});function modelCacheDir(){return o.cacheDir}function resolveRecognitionModel(e){let t=o.locate(e.id);if(t===void 0)throw Error(`Recognition model '${e.id}' is not cached (${o.cachePath(e.id)}) — await SpeechRecognition.install() first.`);return t.files}function isModelCached(e){return o.locate(e.id)!==void 0}function validateLanguageTag(e){try{if(typeof e!=`string`||e===``)throw RangeError(`empty`);new Intl.Locale(e)}catch{throw t(`'${e}' is not a valid BCP 47 language tag`)}}const s={available:0,downloading:1,downloadable:2,unavailable:3};function statusFor(t,n){let r=i(t,n);return r===void 0||!e()?`unavailable`:o.availability(r.id)}async function available(e){let t=e?.langs;if(!Array.isArray(t))throw TypeError(`available(): options.langs must be an array of BCP 47 tags`);for(let e of t)validateLanguageTag(e);if(t.length===0)return`unavailable`;let n=e.quality??`command`;return t.map(e=>statusFor(e,n)).reduce((e,t)=>s[t]>s[e]?t:e,`available`)}async function install(t){let n=t?.langs;if(!Array.isArray(n))throw TypeError(`install(): options.langs must be an array of BCP 47 tags`);for(let e of n)validateLanguageTag(e);if(n.length===0)return!1;let r=t.quality??`command`,a=n.map(e=>i(e,r));if(a.some(e=>e===void 0)||!e())return!1;let{onProgress:s}=t;try{for(let e of new Set(a))await o.install(e.id,{signal:t.signal,fetch:t.fetchImpl,monitor:s===void 0?void 0:t=>t.addEventListener(`downloadprogress`,t=>{let{receivedBytes:n,totalBytes:r}=t;s({modelId:e.id,received:n,total:r})})});return!0}catch{return!1}}function uninstall(e=n){o.require(e);try{return o.uninstall(e)}catch{return!1}}export{available,install,isModelCached,modelCacheDir,resolveRecognitionModel,uninstall,validateLanguageTag};

package/lib/esm/recognition.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{createSherpaEngine as e,hasRecognitionBackend as t}from"./backend.js";import{SpeechRecognitionAlternative as n,SpeechRecognitionResult as r,SpeechRecognitionResultList as i,namedError as a}from"./results.js";import{SpeechRecognitionErrorEvent as o,SpeechRecognitionEvent as s,defineEventHandler as c}from"./events.js";import{modelFor as l}from"./model-manifest.js";import{available as u,install as d,isModelCached as f,resolveRecognitionModel as p}from"./models.js";import{EventTarget as m}from"@gjsify/dom-events";import{openPcmSource as h}from"@gjsify/media-capture";import{available as g,createVad as _,toFloatSamples as v}from"@gjsify/vad";const y=[`audiostart`,`soundstart`,`speechstart`,`speechend`,`soundend`,`audioend`,`result`,`nomatch`,`error`,`start`,`end`],b=16e3;function systemLanguage(){try{return new Intl.DateTimeFormat().resolvedOptions().locale}catch{return`en-US`}}function mean(e){return e.length===0?0:e.reduce((e,t)=>e+t,0)/e.length}var SpeechRecognition=class extends m{lang=``;continuous=!1;interimResults=!1;maxAlternatives=1;unspokenPunctuation=!1;phrases=[];#e;#t=!1;#n=!1;#r=!1;#i=null;constructor(e={}){super(),this.#e=e}get processLocally(){return!0}set processLocally(e){if(!e)throw a(`SpeechRecognition.processLocally cannot be false: gjsify has no recognition service to reach`,`NotSupportedError`)}static available(e){return u(e)}static install(e){return d(e)}start(e){if(this.#t)throw a(`SpeechRecognition has already started`,`InvalidStateError`);let t=e;if(t!==void 0&&(t.kind!==`audio`||t.readyState!==`live`))throw a(`start(track) needs a live audio MediaStreamTrack`,`InvalidStateError`);this.#t=!0,this.#n=!1,this.#r=!1;let n={lang:this.lang||systemLanguage(),quality:`command`,continuous:this.continuous,interim:this.interimResults,phrases:this.phrases.length,track:t!==void 0};queueMicrotask(()=>{this.#s(n).catch(e=>{this.#o(`audio-capture`,e instanceof Error?e.message:String(e))})})}stop(){!this.#t||this.#n||(this.#n=!0,this.#i?.stop())}abort(){!this.#t||this.#r||(this.#n=!0,this.#r=!0,this.#i?.stop())}#a(e){this.dispatchEvent(new s(e))}#o(e,t){this.dispatchEvent(new o(`error`,{error:e,message:t})),this.#t&&(this.#t=!1,this.#a(`end`))}async#s(n){let r=l(n.lang,n.quality);if(r===void 0)return this.#o(`language-not-supported`,`No recognition model for '${n.lang}' at quality '${n.quality}'`);if(n.phrases>0&&!r.hotwords)return this.#o(`phrases-not-supported`,`Model '${r.id}' cannot be biased with phrases`);if(n.track)return this.#o(`audio-capture`,`start(track) is not supported yet — call start() for the default microphone`);let i;if(this.#e.engine!==void 0)i=this.#e.engine(r);else{if(!t()||!f(r))return this.#o(`service-not-allowed`,`Model '${r.id}' is not usable here — check SpeechRecognition.available() and install() it`);let n=p(r);i=e({encoder:n[r.encoder],decoder:n[r.decoder],joiner:n[r.joiner],tokens:n[r.tokens],sampleRate:r.sampleRate})}try{i.open()}catch(e){return this.#o(`service-not-allowed`,`The recognizer could not load: ${e instanceof Error?e.message:e}`)}let a=this.#c(),s;try{s=this.#e.source?.()??h({sampleRate:b,format:`S16LE`}),s.start?.()}catch(e){return i.close(),a?.close(),this.#o(`audio-capture`,e instanceof Error?e.message:String(e))}this.#i=s,this.#n&&s.stop(),this.#a(`start`);try{await this.#l(n,i,a,s)}catch(e){this.dispatchEvent(new o(`error`,{error:`audio-capture`,message:e instanceof Error?e.message:String(e)}))}finally{this.#i=null,s.stop(),a?.close(),i.close(),this.#t=!1,this.#a(`end`)}}#c(){try{if(this.#e.vad!==void 0){let e=this.#e.vad();return e?.open(),e}if(g()!==`available`)return null;let e=_({minSilenceMs:300});return e.open(),e}catch{return null}}async#l(e,t,a,c){let l=c.sampleRate??b,u=[],d=!1,f=!1,p=``,m=0,h=0,g=!1,list=e=>new i(e?[...u,e]:u),spaced=(e,t)=>t>0?` ${e}`:e,beginSound=()=>{f||(f=!0,this.#a(`soundstart`),this.#a(`speechstart`))},finalize=(i,a)=>{let o=(i?t.flushTail().text:a).trim(),c=t.detail();t.reset();let d=f;f&&(f=!1,this.#a(`speechend`),this.#a(`soundend`)),p=``;let _=h/l;if(h=m,o===``){d&&(this.#a(`nomatch`),e.continuous||(g=!0));return}let v=c.logProbs.map(e=>Math.exp(e)),y=c.timestamps,b=new r({alternatives:[new n(spaced(o,u.length),mean(v))],isFinal:!0,speechStartTime:_+(y.length>0?y[0]:0),speechEndTime:y.length>0?_+y[y.length-1]:m/l});u.push(b),this.dispatchEvent(new s(`result`,{resultIndex:u.length-1,results:list()})),e.continuous||(g=!0)},sawSpeechEnd=e=>e.some(e=>e.type===`speech-end`),sawSpeechStart=e=>e.some(e=>e.type===`speech-start`);for(;!g;){let i=await c.read();if(i===null||this.#r)break;d||(d=!0,this.#a(`audiostart`));let o=v(i,c.format??`S16LE`);m+=o.length;let f=a?a.accept(o):[],g=t.accept(o);if((sawSpeechStart(f)||g.text!==``)&&beginSound(),g.text!==``&&g.text!==p&&e.interim&&!g.endpoint){p=g.text;let e=new r({alternatives:[new n(spaced(g.text.trim(),u.length),0)],isFinal:!1,speechStartTime:h/l,speechEndTime:m/l});this.dispatchEvent(new s(`result`,{resultIndex:u.length,results:list(e)}))}sawSpeechEnd(f)?finalize(!0,g.text):g.endpoint&&finalize(!1,g.text)}if(!this.#r){if(!g&&d){a&&a.flush();let e=t.flushTail().text.trim();(f||e!==``)&&finalize(!1,e)}u.length===0&&this.dispatchEvent(new o(`error`,{error:`no-speech`,message:``}))}d&&this.#a(`audioend`)}};for(let e of y)c(SpeechRecognition.prototype,e);export{SpeechRecognition};

package/lib/esm/register.js

@@ -0,0 +1 @@
+import{SpeechRecognitionAlternative as e,SpeechRecognitionPhrase as t,SpeechRecognitionResult as n,SpeechRecognitionResultList as r}from"./results.js";import{SpeechRecognitionErrorEvent as i,SpeechRecognitionEvent as a}from"./events.js";import{SpeechRecognition as o}from"./recognition.js";const s=globalThis;s.SpeechRecognition===void 0&&(s.SpeechRecognition=o,s.SpeechRecognitionEvent=a,s.SpeechRecognitionErrorEvent=i,s.SpeechRecognitionResultList=r,s.SpeechRecognitionResult=n,s.SpeechRecognitionAlternative=e,s.SpeechRecognitionPhrase=t);

package/lib/esm/results.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";var SpeechRecognitionAlternative=class{transcript;confidence;constructor(e,t=0){this.transcript=e,this.confidence=t}get[Symbol.toStringTag](){return`SpeechRecognitionAlternative`}},SpeechRecognitionResult=class{isFinal;speechStartTime;speechEndTime;length;constructor(e){this.isFinal=e.isFinal,this.speechStartTime=e.speechStartTime??0,this.speechEndTime=e.speechEndTime??0,this.length=e.alternatives.length,e.alternatives.forEach((e,t)=>{Object.defineProperty(this,t,{value:e,enumerable:!0})})}item(e){return this[e]}get[Symbol.toStringTag](){return`SpeechRecognitionResult`}},SpeechRecognitionResultList=class{length;constructor(e=[]){this.length=e.length,e.forEach((e,t)=>{Object.defineProperty(this,t,{value:e,enumerable:!0})})}item(e){return this[e]}[Symbol.iterator](){let e=0;return{next:()=>e<this.length?{value:this.item(e++),done:!1}:{value:void 0,done:!0}}}get[Symbol.toStringTag](){return`SpeechRecognitionResultList`}},SpeechRecognitionPhrase=class{phrase;boost;constructor(e,t=1){if(!(t>=0&&t<=10))throw syntaxError(`SpeechRecognitionPhrase boost must be within [0, 10], got ${t}`);this.phrase=String(e),this.boost=t}get[Symbol.toStringTag](){return`SpeechRecognitionPhrase`}};function syntaxError(e){return namedError(e,`SyntaxError`)}function namedError(e,t){let n=globalThis.DOMException;if(n)return new n(e,t);let r=Error(e);return r.name=t,r}export{SpeechRecognitionAlternative,SpeechRecognitionPhrase,SpeechRecognitionResult,SpeechRecognitionResultList,namedError,syntaxError};

package/lib/types/backend.d.ts

@@ -0,0 +1,44 @@
+/** Whether this host has a native recognizer. Quiet; a QUERY, not a guarantee — a model still has to be cached. */
+export declare function hasRecognitionBackend(): boolean;
+/** The recognizer stack in words, and — when there is none — why. For a settings panel or a bug report. */
+export declare function describeRecognitionBackend(): string;
+/** What the engine knows about the utterance it is decoding. */
+export interface RecognizerFrame {
+    /** The hypothesis so far for the current utterance — interim, and it grows. */
+    text: string;
+    /** The model's own trailing-silence rule says the utterance ended. */
+    endpoint: boolean;
+}
+/** The token-level detail of the current utterance; any field may be absent. */
+export interface RecognizerDetail {
+    tokens: string[];
+    /** Seconds from the start of the current utterance. */
+    timestamps: number[];
+    /** Per-token log probabilities. */
+    logProbs: number[];
+}
+/** The seam the session talks to. */
+export interface RecognizerEngine {
+    /** Load the model. Throws when it cannot be opened. */
+    open(): void;
+    /** Feed mono float samples at the engine's rate and decode everything that became ready. */
+    accept(samples: Float32Array): RecognizerFrame;
+    /** Pad the tail with silence so the last tokens are emitted, and decode. */
+    flushTail(): RecognizerFrame;
+    /** Token detail of the current utterance. Call before {@link reset}. */
+    detail(): RecognizerDetail;
+    /** Start a new utterance. */
+    reset(): void;
+    /** Release the model. Idempotent. */
+    close(): void;
+}
+export interface SherpaEngineConfig {
+    encoder: string;
+    decoder: string;
+    joiner: string;
+    tokens: string;
+    sampleRate: number;
+    numThreads?: number;
+}
+/** A {@link RecognizerEngine} over `GjsifySherpa.OnlineRecognizer`. */
+export declare function createSherpaEngine(config: SherpaEngineConfig): RecognizerEngine;

package/lib/types/events.d.ts

@@ -0,0 +1,33 @@
+import { Event } from '@gjsify/dom-events';
+import { SpeechRecognitionResultList } from './results.js';
+export interface SpeechRecognitionEventInit {
+    resultIndex?: number;
+    results?: SpeechRecognitionResultList;
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+}
+export declare class SpeechRecognitionEvent extends Event {
+    /** The lowest index in `results` that changed. */
+    readonly resultIndex: number;
+    readonly results: SpeechRecognitionResultList;
+    constructor(type: string, init?: SpeechRecognitionEventInit);
+    get [Symbol.toStringTag](): string;
+}
+/** https://webaudio.github.io/web-speech-api/#enumdef-speechrecognitionerrorcode */
+export type SpeechRecognitionErrorCode = 'no-speech' | 'aborted' | 'audio-capture' | 'network' | 'not-allowed' | 'service-not-allowed' | 'language-not-supported' | 'phrases-not-supported';
+export interface SpeechRecognitionErrorEventInit extends SpeechRecognitionEventInit {
+    error: SpeechRecognitionErrorCode;
+    message?: string;
+}
+export declare class SpeechRecognitionErrorEvent extends Event {
+    readonly error: SpeechRecognitionErrorCode;
+    readonly message: string;
+    constructor(type: string, init: SpeechRecognitionErrorEventInit);
+    get [Symbol.toStringTag](): string;
+}
+/**
+ * Install an `on<type>` IDL attribute on a prototype: assigning a function adds it as the
+ * listener, reassigning replaces it, `null` removes it.
+ */
+export declare function defineEventHandler(proto: object, type: string): void;

package/lib/types/fake-engine.d.ts

@@ -0,0 +1,18 @@
+import type { RecognizerDetail, RecognizerEngine } from './backend.js';
+export interface FakeEngineStep {
+    text: string;
+    endpoint?: boolean;
+}
+export interface FakeRecognizerEngine extends RecognizerEngine {
+    /** Frames the next `accept()` calls answer, one per call; the last repeats. */
+    script(steps: readonly FakeEngineStep[]): void;
+    /** What `flushTail()` answers (default: the last text). */
+    setTailText(text: string): void;
+    setDetail(detail: Partial<RecognizerDetail>): void;
+    readonly samplesAccepted: number;
+    readonly resets: number;
+    readonly tailFlushes: number;
+    readonly opened: boolean;
+    readonly closed: boolean;
+}
+export declare function createFakeRecognizerEngine(): FakeRecognizerEngine;

package/lib/types/gst-source.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/index.d.ts

@@ -0,0 +1,13 @@
+export { SpeechRecognition } from './recognition.js';
+export type { PcmReader, SpeechRecognitionInit } from './recognition.js';
+export { SpeechRecognitionErrorEvent, SpeechRecognitionEvent } from './events.js';
+export type { SpeechRecognitionErrorCode, SpeechRecognitionErrorEventInit, SpeechRecognitionEventInit, } from './events.js';
+export { SpeechRecognitionAlternative, SpeechRecognitionPhrase, SpeechRecognitionResult, SpeechRecognitionResultList, } from './results.js';
+export { available, install, isModelCached, modelCacheDir, uninstall } from './models.js';
+export type { SpeechRecognitionAvailability, SpeechRecognitionInstallOptions, SpeechRecognitionOptions, } from './models.js';
+export { DEFAULT_RECOGNITION_MODEL, findRecognitionModel, modelFor, RECOGNITION_MODELS } from './model-manifest.js';
+export type { RecognitionModelEntry, RecognitionQuality } from './model-manifest.js';
+export { createSherpaEngine, describeRecognitionBackend, hasRecognitionBackend } from './backend.js';
+export type { RecognizerDetail, RecognizerEngine, RecognizerFrame, SherpaEngineConfig } from './backend.js';
+export { createFakeRecognizerEngine } from './fake-engine.js';
+export type { FakeEngineStep, FakeRecognizerEngine } from './fake-engine.js';

package/lib/types/model-manifest.d.ts

@@ -0,0 +1,25 @@
+import type { ModelEntry } from '@gjsify/model-store';
+/** The Web Speech `SpeechRecognitionQuality`, ordered. */
+export type RecognitionQuality = 'command' | 'dictation' | 'conversation';
+export declare const QUALITY_ORDER: readonly RecognitionQuality[];
+/** One fetchable streaming transducer. */
+export interface RecognitionModelEntry extends ModelEntry {
+    readonly description: string;
+    /** Primary language subtags this model recognizes (`de` covers `de-DE`, `de-AT`, …). */
+    readonly langs: readonly string[];
+    /** The best `quality` this model honestly serves; a request for more is `unavailable`. */
+    readonly quality: RecognitionQuality;
+    readonly sampleRate: number;
+    /** Whether `phrases` can bias it. False = error `phrases-not-supported`, as the spec says. */
+    readonly hotwords: boolean;
+    /** File names inside the entry, by role. */
+    readonly encoder: string;
+    readonly decoder: string;
+    readonly joiner: string;
+    readonly tokens: string;
+}
+export declare const DEFAULT_RECOGNITION_MODEL = "zipformer-de-kroko";
+export declare const RECOGNITION_MODELS: readonly RecognitionModelEntry[];
+export declare function findRecognitionModel(id?: string): RecognitionModelEntry | undefined;
+/** The first model that recognizes `lang` (a BCP 47 tag) at `quality` or better. */
+export declare function modelFor(lang: string, quality?: RecognitionQuality): RecognitionModelEntry | undefined;

package/lib/types/models.d.ts

@@ -0,0 +1,37 @@
+import { type FetchLike, type ModelAvailability } from '@gjsify/model-store';
+import { type RecognitionModelEntry, type RecognitionQuality } from './model-manifest.js';
+export type SpeechRecognitionAvailability = ModelAvailability;
+export interface SpeechRecognitionOptions {
+    langs: string[];
+    /** Spec default `false`. Plays no part here: every engine in this package is local. */
+    processLocally?: boolean;
+    /** Spec default `command`. A model that cannot honestly serve it is `unavailable`. */
+    quality?: RecognitionQuality;
+}
+export interface SpeechRecognitionInstallOptions {
+    langs: string[];
+    quality?: RecognitionQuality;
+    /** Called at least once, with `received === total` on success. */
+    onProgress?: (progress: {
+        modelId: string;
+        received: number;
+        total: number;
+    }) => void;
+    signal?: AbortSignal;
+    /** Override the global `fetch`. Tests only. */
+    fetchImpl?: FetchLike;
+}
+/** `<user cache>/gjsify/models/speech` — shared with `@gjsify/vad`. */
+export declare function modelCacheDir(): string;
+/** Absolute paths of a model's files, for the engine. Throws when it is not cached. */
+export declare function resolveRecognitionModel(entry: RecognitionModelEntry): Record<string, string>;
+/** Whether `entry` is fully cached. */
+export declare function isModelCached(entry: RecognitionModelEntry): boolean;
+/** Throws SyntaxError unless `tag` is a structurally valid BCP 47 language tag. */
+export declare function validateLanguageTag(tag: string): void;
+/** `SpeechRecognition.available()`. QUIET: never downloads, never loads a model. */
+export declare function available(options: SpeechRecognitionOptions): Promise<SpeechRecognitionAvailability>;
+/** `SpeechRecognition.install()`: fetch what `available()` would call `downloadable`. */
+export declare function install(options: SpeechRecognitionInstallOptions): Promise<boolean>;
+/** Delete the cached files for `id`. `false` when there was nothing to delete. */
+export declare function uninstall(id?: string): boolean;

package/lib/types/models.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/real-engine.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/recognition.d.ts

@@ -0,0 +1,58 @@
+import { type Event, EventTarget } from '@gjsify/dom-events';
+import { type PcmFormat, type VoiceActivityDetector } from '@gjsify/vad';
+import { type RecognizerEngine } from './backend.js';
+import { type RecognitionModelEntry } from './model-manifest.js';
+import { type SpeechRecognitionAvailability, type SpeechRecognitionInstallOptions, type SpeechRecognitionOptions } from './models.js';
+import { type SpeechRecognitionPhrase } from './results.js';
+/** As much of `@gjsify/media-capture`'s `PcmSource` as a session reads. */
+export interface PcmReader {
+    readonly sampleRate?: number;
+    readonly format?: PcmFormat;
+    start?(): void;
+    read(): Promise<Uint8Array | Int16Array | Float32Array | null>;
+    stop(): void;
+}
+/** Replace the parts of a session that touch hardware or a model. Tests, and apps with their own audio. */
+export interface SpeechRecognitionInit {
+    /** The engine for `model`. Default: sherpa-onnx on the cached files. */
+    engine?: (model: RecognitionModelEntry) => RecognizerEngine;
+    /** The detector, or `null` for none. Default: Silero when its model is cached. */
+    vad?: () => VoiceActivityDetector | null;
+    /** The audio. Default: the default microphone at 16 kHz mono through `@gjsify/media-capture`. */
+    source?: () => PcmReader;
+}
+export declare class SpeechRecognition extends EventTarget {
+    #private;
+    lang: string;
+    continuous: boolean;
+    interimResults: boolean;
+    maxAlternatives: number;
+    unspokenPunctuation: boolean;
+    phrases: SpeechRecognitionPhrase[];
+    constructor(init?: SpeechRecognitionInit);
+    get processLocally(): boolean;
+    set processLocally(value: boolean);
+    static available(options: SpeechRecognitionOptions): Promise<SpeechRecognitionAvailability>;
+    static install(options: SpeechRecognitionInstallOptions): Promise<boolean>;
+    start(track?: unknown): void;
+    /** Stop capturing; what was heard so far is still recognized and delivered. */
+    stop(): void;
+    /** Stop capturing and discard everything; only `end` follows. */
+    abort(): void;
+}
+type Handler = ((event: Event) => void) | null;
+/** The `on<event>` IDL attributes, installed on the prototype by {@link defineEventHandler}. */
+export interface SpeechRecognition {
+    onaudiostart: Handler;
+    onsoundstart: Handler;
+    onspeechstart: Handler;
+    onspeechend: Handler;
+    onsoundend: Handler;
+    onaudioend: Handler;
+    onresult: Handler;
+    onnomatch: Handler;
+    onerror: Handler;
+    onstart: Handler;
+    onend: Handler;
+}
+export {};

package/lib/types/recognition.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/register.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/results.d.ts

@@ -0,0 +1,41 @@
+export declare class SpeechRecognitionAlternative {
+    readonly transcript: string;
+    readonly confidence: number;
+    constructor(transcript: string, confidence?: number);
+    get [Symbol.toStringTag](): string;
+}
+export interface SpeechRecognitionResultInit {
+    alternatives: SpeechRecognitionAlternative[];
+    isFinal: boolean;
+    /** Seconds on the session's audio timeline, which starts at 0.0 at the first frame consumed. */
+    speechStartTime?: number;
+    speechEndTime?: number;
+}
+export declare class SpeechRecognitionResult {
+    readonly isFinal: boolean;
+    readonly speechStartTime: number;
+    readonly speechEndTime: number;
+    readonly length: number;
+    readonly [index: number]: SpeechRecognitionAlternative;
+    constructor(init: SpeechRecognitionResultInit);
+    item(index: number): SpeechRecognitionAlternative;
+    get [Symbol.toStringTag](): string;
+}
+export declare class SpeechRecognitionResultList {
+    readonly length: number;
+    readonly [index: number]: SpeechRecognitionResult;
+    constructor(results?: readonly SpeechRecognitionResult[]);
+    item(index: number): SpeechRecognitionResult;
+    [Symbol.iterator](): Iterator<SpeechRecognitionResult>;
+    get [Symbol.toStringTag](): string;
+}
+/** A contextual-biasing term. `boost` is advisory and must lie in [0, 10]. */
+export declare class SpeechRecognitionPhrase {
+    readonly phrase: string;
+    readonly boost: number;
+    constructor(phrase: string, boost?: number);
+    get [Symbol.toStringTag](): string;
+}
+/** A `SyntaxError` DOMException where the runtime has one, a named `Error` otherwise. */
+export declare function syntaxError(message: string): Error;
+export declare function namedError(message: string, name: string): Error;

package/lib/types/results.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/package.json

@@ -1,6 +1,94 @@
 {
-  "name": "@gjsify/speech-recognition",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@gjsify/speech-recognition",
+    "version": "0.64.33-next.323",
+    "description": "Web Speech recognition API (SpeechRecognition and its event and result classes) for GJS, running fully on the device: a streaming zipformer on sherpa-onnx, fed by @gjsify/media-capture and endpointed by @gjsify/vad. Models are fetched on first use, never bundled.",
+    "type": "module",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        },
+        "./register": {
+            "types": "./lib/types/register.d.ts",
+            "default": "./lib/esm/register.js"
+        },
+        "./globals": "./globals.mjs"
+    },
+    "files": [
+        "lib",
+        "globals.mjs"
+    ],
+    "sideEffects": [
+        "./lib/esm/register.js",
+        "./globals.mjs"
+    ],
+    "scripts": {
+        "clear": "gjsify clear lib tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo test.gjs.mjs",
+        "check": "gjsify tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test*.{mts,ts}'",
+        "build:types": "gjsify tsc",
+        "build:test": "gjsify run build:test:gjs",
+        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs"
+    },
+    "keywords": [
+        "gjs",
+        "speech",
+        "speechrecognition",
+        "stt",
+        "asr",
+        "sherpa-onnx",
+        "zipformer"
+    ],
+    "dependencies": {
+        "@gjsify/dom-events": "0.64.33-next.323",
+        "@gjsify/media-capture": "0.64.33-next.323",
+        "@gjsify/model-store": "0.64.33-next.323",
+        "@gjsify/node-globals": "0.64.33-next.323",
+        "@gjsify/sherpa-native": "0.64.33-next.323",
+        "@gjsify/utils": "0.64.33-next.323",
+        "@gjsify/vad": "0.64.33-next.323"
+    },
+    "devDependencies": {
+        "@girs/gjs": "5.4.0",
+        "@girs/glib-2.0": "5.4.0",
+        "@gjsify/cli": "0.64.33-next.323",
+        "@gjsify/unit": "0.64.33-next.323",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "gjsify": {
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "none",
+            "browser": "native",
+            "nativescript": "none"
+        },
+        "os": {
+            "linux": "partial",
+            "darwin": "none",
+            "win32": "none"
+        },
+        "osNotes": {
+            "linux": "Needs the @gjsify/sherpa-native prebuild (linux-x64 only today) and a cached German model. Without them SpeechRecognition.available() answers 'unavailable' and start() fires error service-not-allowed.",
+            "darwin": "@gjsify/sherpa-native is not built for macOS yet, so there is no engine. available() answers 'unavailable'.",
+            "win32": "@gjsify/sherpa-native is not built for Windows yet, so there is no engine. available() answers 'unavailable'."
+        },
+        "tier": 3
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/web/speech-recognition"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/web/speech-recognition#readme",
+    "gitHead": "603d30dc7b5600376fca2b715ecc154cc12b4b31"
+}