@gjsify/vad 0.0.0-stage → 0.64.16

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @gjsify/vad
 
-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.
+Voice activity detection for GJS: [Silero VAD](https://github.com/snakers4/silero-vad) running on [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) through [`@gjsify/sherpa-native`](../sherpa-native#readme). It answers two questions about an audio stream — **when did speech start**, and **when did a stretch of speech end** — and nothing else. Linux x64 only today. Tier 3 (experimental, [ADR 0003](../../../docs/adr/0003-package-tiering.md)) until promoted. See [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/vad
+```
+
+## Usage
+
+The model is not bundled, so the first run fetches it (2.2 MiB from upstream's release page, verified by size and SHA-256 before it reaches disk):
+
+```typescript
+import { available, install, createVad } from '@gjsify/vad';
+import { openPcmSource } from '@gjsify/media-capture';
+
+if (available() === 'downloadable') await install();
+
+const vad = createVad();          // 16 kHz mono, 300 ms of silence ends a stretch
+const source = openPcmSource({ sampleRate: 16000, format: 'S16LE' });
+
+for await (const event of vad.run(source)) {
+    if (event.type === 'speech-start') showListeningIndicator();
+    else transcribe(event.samples); // Float32Array, mono, [-1, 1]
+}
+vad.close();
+```
+
+Feeding chunks by hand instead of handing over a source — any chunk length, the engine buffers the remainder:
+
+```typescript
+const vad = createVad({ model: 'silero-v5' });
+vad.open();
+for (const chunk of chunks) {
+    for (const event of vad.accept(chunk, 'S16LE')) handle(event);
+}
+for (const event of vad.flush()) handle(event); // not optional, see below
+vad.close();
+```
+
+`flush()` is not optional. The last utterance of a file or a stopped recording is followed by no silence, so nothing closes it and without a flush it is never reported at all.
+
+## The two events
+
+| | `speech-start` | `speech-end` |
+|---|---|---|
+| when | the detector *confirms* speech | a stretch has ended |
+| carries | `at` — stream position in seconds | `start`, `end`, `duration`, `startSample`, `samples` |
+
+`speech-start.at` is the **live edge** and it lags the acoustic onset: the detector has to hear `minSpeechMs` of speech before it commits. Measured on two 16 kHz recordings with the defaults, it confirmed at 0.67 s and 0.38 s for onsets that the matching `speech-end` later reported at 0.32 s and 0.03 s — about 0.35 s behind in both. That is the right behaviour for a "listening" indicator, which must not flicker on a cough; for *trimming* audio use `speech-end.start`, which is the onset itself.
+
+A burst too short to keep (< `minSpeechMs`) produces a `speech-start` with no `speech-end`. It stays that way: inventing a zero-length end would make a cough indistinguishable from a word.
+
+## What this package refuses to say
+
+Whether a pause means the speaker is **finished**. That is a question about a conversation — how long this speaker usually hesitates, whether the sentence sounds complete, whether the app may interrupt — and it belongs to a turn detector above this layer, with its own policy. A VAD measures acoustics, so there is deliberately no `turn-end` to reach for.
+
+`createFakeVadEngine()` is exported for exactly that consumer: a scripted engine that drives the event machine without a model or an inference run.
+
+## Defaults
+
+`createVad()` takes `minSilenceMs` **300** (ADR 0127 decision 10, not Silero's 550 — the whole wait is added to every reply), `minSpeechMs` 250, `maxSpeechMs` 20 000, `threshold` 0.5, `sampleRate` 16 000, `windowSize` 512, `numThreads` 1, `bufferSeconds` 30. A `maxSpeechMs` cut appears as a `speech-end` immediately followed by a fresh `speech-start`.
+
+## Models
+
+`available()` answers in the names the Web Speech on-device additions use: `available`, `downloading`, `downloadable`, `unavailable`. `unavailable` means there is **no native engine** on this host, not a missing file — fetching a model for an engine that is not installed is the one outcome a download prompt must never produce.
+
+```typescript
+import { listModels, install, uninstall, modelCacheDir } from '@gjsify/vad';
+
+listModels();      // every entry with its availability, for a settings panel
+await install('silero-v4', { onProgress: (p) => console.log(p.received, p.total) });
+uninstall('silero-v4');
+modelCacheDir();   // ~/.cache/gjsify/speech-models, shared with the other speech packages
+```
+
+`VadOptions.model` takes a manifest id (`silero-v5`, `silero-v4`) or a path — anything containing a path separator is used as given, which is how you point at a model this manifest does not know. An id must already be cached: resolving must not start a download behind a synchronous constructor.
+
+The models are MIT-licensed by their authors and are **not** part of this package's licence.
+
+## Without a native engine
+
+```typescript
+import { hasVadBackend, describeVadBackend } from '@gjsify/vad';
+
+if (!hasVadBackend()) console.log(describeVadBackend());
+```
+
+`hasVadBackend()` is the quiet check. `describeVadBackend()` names the engine and onnxruntime versions, or says why there is none and which `@gjsify/sherpa-native-<os>-<arch>` to install.
+
+## Audio input
+
+`run()` accepts `@gjsify/media-capture`'s `openPcmSource()` **structurally** — neither package depends on the other, because a VAD that drags GStreamer in would be unusable on a stream that came from a file or a socket. Any async iterable of chunks works; a source that reports a `sampleRate` different from the detector's is refused, because resampled audio read at the wrong rate does not fail, it just reads as silence.
+
+`Float32Array` and `Int16Array` chunks carry their own layout. A raw `Uint8Array` needs an explicit `'S16LE'` or `'F32LE'`: both are plausible for a byte buffer and guessing wrong produces audio that is silently wrong.
+
+## Notes
+
+- `gjsify run test` covers the event machine and the model cache with no engine, no model and no network. The real-engine suite skips unless a prebuild and a cached model are present, is file-only and never opens a microphone or plays sound; its speech leg additionally needs `GJSIFY_VAD_TEST_WAV` to name a 16 kHz mono PCM16 file, since no speech fixture is committed.
+- One detector, one stream. `reset()` reuses it across unrelated recordings; `close()` is final.

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";const i=`@gjsify/sherpa-native`,a=`[@gjsify/vad] No voice activity detection on this host — the GjsifySherpa-1.0 typelib is absent. Install ${i}-<os>-<arch> for this machine (linux-x64 only today). Gate on hasVadBackend().`,o=`[@gjsify/vad] The ${i} bridge failed to load — a fault on this host, NOT a missing prebuild. Voice activity detection is unavailable until it is fixed.`;let s=null,c=!1;function isNoGiError(e){return e instanceof Error&&e.message.includes(`GObject-Introspection`)}function _diagnoseVadLoadError(e){return isNoGiError(e)?{status:`absent`,diagnostic:null}:e instanceof Error&&e.name===`NativeLibraryLoadError`?{status:`failed`,diagnostic:o}:{status:`absent`,diagnostic:`${a} (${e instanceof Error?e.message:e})`}}function loadVadBackend(t={}){if(s!==null){if(t.load||t.loadError||t.hostOs)throw Error(`loadVadBackend(options) called after the probe already ran — the probe is cached per process, so the override would be ignored. Call _resetVadBackendCache() first (tests only).`);return s}let i=(t.hostOs??r)();if(i===`darwin`||i===`win32`)return s={status:`absent`,module:null,error:null,diagnostic:`[@gjsify/vad] No voice activity detection on this OS — the sherpa-onnx bridge is built for Linux only.`},s;let a=(t.load??n)();if(a===null){let n=(t.loadError??e)(),{status:r,diagnostic:i}=_diagnoseVadLoadError(n);return s={status:r,module:null,error:n,diagnostic:i},s}return s={status:`sherpa`,module:a,error:null,diagnostic:null},s}function hasVadBackend(){return s===null?t()&&loadVadBackend().status===`sherpa`:s.status===`sherpa`}function reportVadBackendOnce(e){c||e.diagnostic===null||(c=!0,e.status===`failed`?console.error(e.diagnostic,e.error):console.warn(e.diagnostic))}function describeVadBackend(){let e=loadVadBackend();if(e.status!==`sherpa`)return`none (${e.status}): ${e.diagnostic??`not available on this target`}`;let t=e.module;return`sherpa-onnx ${t.version()} on onnxruntime ${t.onnxruntime_version()} (${i})`}function _resetVadBackendCache(){s=null,c=!1}function createSherpaVadEngine(e){let t=loadVadBackend();if(t.status!==`sherpa`)throw reportVadBackendOnce(t),Error(t.diagnostic??`No native VAD engine on this host (${t.status})`);let n=new t.module.Vad({model:e.model,threshold:e.threshold,min_silence_duration:e.minSilenceSeconds,min_speech_duration:e.minSpeechSeconds,max_speech_duration:e.maxSpeechSeconds,sample_rate:e.sampleRate,window_size:e.windowSize,num_threads:e.numThreads,buffer_size_in_seconds:e.bufferSeconds,enable_debug:e.debug});return{open:()=>n.open(),accept:e=>n.accept(e),isSpeech:()=>n.is_speech(),hasSegment:()=>n.has_segment(),nextSegment:()=>{let[e,t,r]=n.next_segment();return e?{samples:t instanceof Float32Array?t:Float32Array.from(t),startSample:r}:null},flush:()=>n.flush(),reset:()=>n.reset(),close:()=>n.close()}}export{_diagnoseVadLoadError,_resetVadBackendCache,createSherpaVadEngine,describeVadBackend,hasVadBackend,loadVadBackend,reportVadBackendOnce};

package/lib/esm/fake-vad.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";function createFakeVadEngine(){let e=[],t=!1,n={accepted:0,chunks:0,opened:!1,flushed:0,resets:0,closed:!1};return{get accepted(){return n.accepted},get chunks(){return n.chunks},get opened(){return n.opened},get flushed(){return n.flushed},get resets(){return n.resets},get closed(){return n.closed},setSpeech(e){t=e},pushSegment(t,n){e.push({samples:new Float32Array(n).fill(.5),startSample:t})},open(){n.opened=!0},accept(e){if(!n.opened)throw Error(`fake VAD engine: accept() before open()`);n.accepted+=e.length,n.chunks++},isSpeech(){return t},hasSegment(){return e.length>0},nextSegment(){return e.shift()??null},flush(){n.flushed++},reset(){n.resets++,e.length=0,t=!1},close(){n.closed=!0}}}export{createFakeVadEngine};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import{_resetVadBackendCache as e,createSherpaVadEngine as t,describeVadBackend as n,hasVadBackend as r,loadVadBackend as i,reportVadBackendOnce as a}from"./backend.js";import{createFakeVadEngine as o}from"./fake-vad.js";import{DEFAULT_VAD_MODEL as s,VAD_MODELS as c,findVadModel as l,requireVadModel as u}from"./model-manifest.js";import{available as d,install as f,installedModels as p,listModels as m,modelCacheDir as h,modelPath as g,resolveModel as _,uninstall as v}from"./models.js";import{inferFormat as y,toFloatSamples as b}from"./pcm.js";import{VoiceActivityDetector as x,createVad as S}from"./vad.js";export{s as DEFAULT_VAD_MODEL,c as VAD_MODELS,x as VoiceActivityDetector,e as _resetVadBackendCache,d as available,o as createFakeVadEngine,t as createSherpaVadEngine,S as createVad,n as describeVadBackend,l as findVadModel,r as hasVadBackend,y as inferFormat,f as install,p as installedModels,m as listModels,i as loadVadBackend,h as modelCacheDir,g as modelPath,a as reportVadBackendOnce,u as requireVadModel,_ as resolveModel,b as toFloatSamples,v as uninstall};

package/lib/esm/model-manifest.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";const e=`silero-v5`,t=`https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models`,n=[{id:`silero-v5`,file:`silero_vad_v5.onnx`,url:`${t}/silero_vad_v5.onnx`,bytes:2313101,sha256:`6b99cbfd39246b6706f98ec13c7c50c6b299181f2474fa05cbc8046acc274396`,license:`MIT`,sampleRate:16e3,windowSize:512,description:`Silero VAD v5 (2.2 MiB) — the default. Takes input/state/sr; 16 kHz, 512-sample windows.`},{id:`silero-v4`,file:`silero_vad.onnx`,url:`${t}/silero_vad.onnx`,bytes:643854,sha256:`9e2449e1087496d8d4caba907f23e0bd3f78d91fa552479bb9c23ac09cbb1fd6`,license:`MIT`,sampleRate:16e3,windowSize:512,description:`Silero VAD v4 (0.6 MiB) — smaller and older. Only its 16 kHz branch is covered here.`}];function findVadModel(t=e){return n.find(e=>e.id===t)}function requireVadModel(t=e){let r=findVadModel(t);if(r===void 0)throw RangeError(`Unknown VAD model '${t}' — known ids: ${n.map(e=>e.id).join(`, `)}`);return r}export{e as DEFAULT_VAD_MODEL,n as VAD_MODELS,findVadModel,requireVadModel};

package/lib/esm/models.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{hasVadBackend as e}from"./backend.js";import{DEFAULT_VAD_MODEL as t,VAD_MODELS as n,requireVadModel as r}from"./model-manifest.js";import i from"gi://GLib?version=2.0";import a from"gi://Gio?version=2.0";import o from"@gjsify/fetch";function modelCacheDir(){return i.build_filenamev([i.get_user_cache_dir(),`gjsify`,`speech-models`])}function modelPath(e=t){return i.build_filenamev([modelCacheDir(),r(e).file])}const s=new Map;function sizeOf(e){try{return a.File.new_for_path(e).query_info(a.FILE_ATTRIBUTE_STANDARD_SIZE,a.FileQueryInfoFlags.NONE,null).get_size()}catch{return null}}function isCached(e){return sizeOf(i.build_filenamev([modelCacheDir(),e.file]))===e.bytes}function sha256(e){let t=i.Checksum.new(i.ChecksumType.SHA256);t.update(e);let n=t.get_string();if(n===null)throw Error(`GLib.Checksum returned no digest`);return n.toLowerCase()}function available(n=t){let i=r(n);return e()?isCached(i)?`available`:s.has(i.id)?`downloading`:`downloadable`:`unavailable`}function listModels(){return n.map(e=>({entry:e,availability:available(e.id)}))}function installedModels(){return n.filter(isCached).map(e=>e.id)}async function download(e,t){let n=modelCacheDir(),r=i.build_filenamev([n,e.file]),s=await(t.fetchImpl??o)(e.url,{signal:t.signal,redirect:`follow`});if(!s.ok)throw Error(`Downloading ${e.id} from ${e.url} failed: HTTP ${s.status}`);let c=s.headers.get(`content-length`);if(c!==null&&Number(c)!==e.bytes)throw Error(`Downloading ${e.id} refused: ${e.url} declares ${c} bytes, the manifest says ${e.bytes}`);let l=new Uint8Array(await s.arrayBuffer());if(l.length!==e.bytes)throw Error(`Downloading ${e.id} failed: got ${l.length} bytes, expected ${e.bytes}`);let u=sha256(l);if(u!==e.sha256)throw Error(`Downloading ${e.id} failed: sha256 ${u}, expected ${e.sha256}`);i.mkdir_with_parents(n,493);let d=`${r}.part-${i.uuid_string_random()}`,f=a.File.new_for_path(d);try{f.replace_contents(l,null,!1,a.FileCreateFlags.REPLACE_DESTINATION,null),f.move(a.File.new_for_path(r),a.FileCopyFlags.OVERWRITE,null,null)}catch(e){try{f.delete(null)}catch{}throw e}return t.onProgress?.({modelId:e.id,received:e.bytes,total:e.bytes}),r}function install(n=t,a={}){let o;try{o=r(n)}catch(e){return Promise.reject(e)}if(!e())return Promise.reject(Error(`install('${o.id}'): no native VAD engine on this host, so a model would be unusable — gate on available() and show describeVadBackend() instead.`));let c=i.build_filenamev([modelCacheDir(),o.file]);if(!a.force&&isCached(o))return a.onProgress?.({modelId:o.id,received:o.bytes,total:o.bytes}),Promise.resolve(c);let l=s.get(o.id);if(l!==void 0)return l;let u=download(o,a).finally(()=>s.delete(o.id));return s.set(o.id,u),u}function uninstall(e=t){let n=r(e);try{return a.File.new_for_path(i.build_filenamev([modelCacheDir(),n.file])).delete(null)}catch{return!1}}function resolveModel(e=t){if(e.includes(`/`)||e.includes(`\\`))return e;let n=r(e),a=i.build_filenamev([modelCacheDir(),n.file]);if(!isCached(n))throw Error(`VAD model '${n.id}' is not cached (${a}) — await install('${n.id}') first, or pass a path to a model file. ${n.bytes} bytes from ${n.url}.`);return a}export{available,install,installedModels,listModels,modelCacheDir,modelPath,resolveModel,uninstall};

package/lib/esm/pcm.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";function inferFormat(e){return e instanceof Float32Array?`F32LE`:e instanceof Int16Array?`S16LE`:null}const e=1/32768;function toFloatSamples(t,n){if(t instanceof Float32Array)return t;let r=n??inferFormat(t);if(r===null)throw TypeError(`A Uint8Array chunk carries no sample format — pass format: 'S16LE' or 'F32LE' (openPcmSource() reports its own as source.format), or hand over an Int16Array/Float32Array.`);if(t instanceof Int16Array){let n=new Float32Array(t.length);for(let r=0;r<t.length;r++)n[r]=t[r]*e;return n}let i=new DataView(t.buffer,t.byteOffset,t.byteLength);if(r===`F32LE`){let e=i.byteLength>>2,t=new Float32Array(e);for(let n=0;n<e;n++)t[n]=i.getFloat32(n*4,!0);return t}let a=i.byteLength>>1,o=new Float32Array(a);for(let t=0;t<a;t++)o[t]=i.getInt16(t*2,!0)*e;return o}export{inferFormat,toFloatSamples};

package/lib/esm/vad.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{createSherpaVadEngine as e,loadVadBackend as t,reportVadBackendOnce as n}from"./backend.js";import{resolveModel as r}from"./models.js";import{toFloatSamples as i}from"./pcm.js";const a={minSilenceMs:300,minSpeechMs:250,maxSpeechMs:2e4,threshold:.5,sampleRate:16e3,windowSize:512,numThreads:1,bufferSeconds:30,debug:!1};function positive(e,t){if(!Number.isFinite(t)||t<=0)throw RangeError(`VadOptions.${e} must be a positive number, got ${t}`);return t}var VoiceActivityDetector=class{sampleRate;minSilenceMs;minSpeechMs;maxSpeechMs;engine;accepted=0;inSpeech=!1;opened=!1;closed=!1;constructor(t={}){this.sampleRate=positive(`sampleRate`,t.sampleRate??a.sampleRate),this.minSilenceMs=positive(`minSilenceMs`,t.minSilenceMs??a.minSilenceMs),this.minSpeechMs=positive(`minSpeechMs`,t.minSpeechMs??a.minSpeechMs),this.maxSpeechMs=positive(`maxSpeechMs`,t.maxSpeechMs??a.maxSpeechMs),this.engine=t.engine??e({model:r(t.model),threshold:t.threshold??a.threshold,minSilenceSeconds:this.minSilenceMs/1e3,minSpeechSeconds:this.minSpeechMs/1e3,maxSpeechSeconds:this.maxSpeechMs/1e3,sampleRate:this.sampleRate,windowSize:positive(`windowSize`,t.windowSize??a.windowSize),numThreads:positive(`numThreads`,t.numThreads??a.numThreads),bufferSeconds:positive(`bufferSeconds`,t.bufferSeconds??a.bufferSeconds),debug:t.debug??a.debug})}open(){if(this.closed)throw Error(`This VoiceActivityDetector is closed — create another one.`);this.opened||=(this.engine.open(),!0)}get isOpen(){return this.opened&&!this.closed}get speaking(){return this.inSpeech}get position(){return this.accepted/this.sampleRate}get positionSamples(){return this.accepted}accept(e,t){this.open();let n=i(e,t);return this.engine.accept(n),this.accepted+=n.length,this.collect(!1)}flush(){return this.opened?(this.engine.flush(),this.collect(!0)):[]}reset(){this.opened&&(this.engine.reset(),this.accepted=0,this.inSpeech=!1)}close(){this.closed||(this.closed=!0,this.engine.close())}async*run(e){let t=e.sampleRate;if(t!==void 0&&t!==this.sampleRate)throw Error(`This detector was built for ${this.sampleRate} Hz and the source reports ${t} Hz. Resampled audio read at the wrong rate is not an error the detector can see — it just reads as silence. Pass sampleRate: ${t} to createVad(), or ask the source for ${this.sampleRate} Hz.`);let n=e.format;for await(let t of e)for(let e of this.accept(t,n))yield e;for(let e of this.flush())yield e}collect(e){let t=[];for(let e=this.engine.nextSegment();e!==null;e=this.engine.nextSegment())this.inSpeech||t.push({type:`speech-start`,at:e.startSample/this.sampleRate}),t.push(this.toSpeechEnd(e)),this.inSpeech=!1;let n=e?!1:this.engine.isSpeech();return n&&!this.inSpeech?(t.push({type:`speech-start`,at:this.position}),this.inSpeech=!0):!n&&this.inSpeech&&(this.inSpeech=!1),t}toSpeechEnd(e){let t=e.startSample/this.sampleRate,n=e.samples.length/this.sampleRate;return{type:`speech-end`,start:t,end:t+n,duration:n,startSample:e.startSample,samples:e.samples}}};function createVad(e={}){return e.engine===void 0&&n(t()),new VoiceActivityDetector(e)}export{VoiceActivityDetector,createVad};

package/lib/types/backend.d.ts

@@ -0,0 +1,103 @@
+import { type NativeSherpaModule } from '@gjsify/sherpa-native';
+import { type TargetOs } from '@gjsify/utils/core';
+export type VadBackendStatus = 'sherpa' | 'absent' | 'failed';
+export interface VadBackend {
+    status: VadBackendStatus;
+    /** The GjsifySherpa module, or `null` for `absent`/`failed`. */
+    module: NativeSherpaModule | null;
+    /** The original load error for `absent`/`failed`; `null` otherwise. */
+    error: unknown;
+    /** The one-time line the USE site prints; `null` = nothing to say. */
+    diagnostic: string | null;
+}
+export interface LoadVadBackendOptions {
+    /** Override `loadNativeSherpa()`. Tests only. */
+    load?: () => NativeSherpaModule | null;
+    /** Override the load error `load` failed with. Tests only. */
+    loadError?: () => Error | null;
+    /** Override the host OS the probe branches on. Tests only. */
+    hostOs?: () => TargetOs | undefined;
+}
+/** Classify a failed load. Exported (underscored) for the specs. */
+export declare function _diagnoseVadLoadError(error: unknown): {
+    status: 'absent' | 'failed';
+    diagnostic: string | null;
+};
+/**
+ * Resolve (once) what detector this host has. Emits NOTHING. Synchronous,
+ * because loading a typelib is — `install()` is the asynchronous part, and it
+ * is about the model rather than the engine.
+ *
+ * Passing options after the probe ran THROWS instead of being ignored; call
+ * {@link _resetVadBackendCache} first.
+ */
+export declare function loadVadBackend(options?: LoadVadBackendOptions): VadBackend;
+/**
+ * Whether this host has a native detector. Quiet; a QUERY, not a guarantee —
+ * a model still has to be cached, which is what `available()` answers.
+ */
+export declare function hasVadBackend(): boolean;
+/** Emit the backend's one-time diagnostic — called by `createVad()`, never by the queries. */
+export declare function reportVadBackendOnce(backend: VadBackend): void;
+/**
+ * The detector stack in words, and — when there is none — why and what to
+ * install. For a settings panel or a bug report; branch on
+ * {@link hasVadBackend} instead.
+ */
+export declare function describeVadBackend(): string;
+/** Reset the cached probe and its one-time diagnostic — tests only. */
+export declare function _resetVadBackendCache(): void;
+/** One completed stretch of speech, as the engine hands it over. */
+export interface EngineSegment {
+    /** The segment's audio, mono float in [-1, 1]. */
+    samples: Float32Array;
+    /** Offset of the first sample from the first sample ever accepted. */
+    startSample: number;
+}
+/**
+ * The detector seam: what `VoiceActivityDetector` needs and nothing else.
+ *
+ * `isSpeech()` is the LIVE edge and `nextSegment()` a COMPLETED segment, and
+ * the two are not the same measurement — see the class doc in `vad.ts` for how
+ * far apart they are in practice.
+ */
+export interface VadEngine {
+    /** Load the model. Idempotent. Throws when the model cannot be opened. */
+    open(): void;
+    /** Feed mono float samples in [-1, 1]. ANY length; the engine buffers the remainder. */
+    accept(samples: Float32Array): void;
+    /** Whether the engine is inside speech right now. */
+    isSpeech(): boolean;
+    /** Whether a completed segment is queued. */
+    hasSegment(): boolean;
+    /** Take the oldest completed segment, or `null`. */
+    nextSegment(): EngineSegment | null;
+    /** Close an in-progress segment and queue it — end of input. */
+    flush(): void;
+    /** Drop every queued segment AND the model state. */
+    reset(): void;
+    /** Release the model. Idempotent. */
+    close(): void;
+}
+/** What {@link createSherpaVadEngine} needs. Resolved values: a real path, seconds, samples. */
+export interface SherpaVadEngineConfig {
+    /** Absolute path to a Silero `.onnx` file. */
+    model: string;
+    threshold: number;
+    minSilenceSeconds: number;
+    minSpeechSeconds: number;
+    maxSpeechSeconds: number;
+    sampleRate: number;
+    windowSize: number;
+    numThreads: number;
+    bufferSeconds: number;
+    debug: boolean;
+}
+/**
+ * A {@link VadEngine} over `GjsifySherpa.Vad`.
+ *
+ * Construction does not load anything — the GObject's own knobs are construct
+ * properties and `open()` is a separate step, so this mirrors that rather than
+ * adding a second lifecycle on top.
+ */
+export declare function createSherpaVadEngine(config: SherpaVadEngineConfig): VadEngine;

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

@@ -0,0 +1,23 @@
+import type { VadEngine } from './backend.js';
+export interface FakeVadEngine extends VadEngine {
+    /** What `isSpeech()` answers from now on. */
+    setSpeech(live: boolean): void;
+    /** Queue a completed segment; the next `accept()` drains it. */
+    pushSegment(startSample: number, lengthSamples: number): void;
+    /** Samples handed to `accept()` so far. */
+    readonly accepted: number;
+    /** `accept()` calls so far. */
+    readonly chunks: number;
+    readonly opened: boolean;
+    readonly flushed: number;
+    readonly resets: number;
+    readonly closed: boolean;
+}
+/**
+ * An engine that answers exactly what the test told it to.
+ *
+ * It does NOT simulate Silero: `setSpeech()` and `pushSegment()` are the
+ * engine's two observable behaviours, and the point is to drive them into
+ * combinations rather than to reproduce how a model would reach them.
+ */
+export declare function createFakeVadEngine(): FakeVadEngine;

package/lib/types/index.d.ts

@@ -0,0 +1,12 @@
+export { createVad, VoiceActivityDetector } from './vad.js';
+export type { SpeechEndEvent, SpeechStartEvent, VadEvent, VadOptions } from './vad.js';
+export { available, install, installedModels, listModels, modelCacheDir, modelPath, resolveModel, uninstall, } from './models.js';
+export type { InstallOptions, InstallProgress, VadModelAvailability } from './models.js';
+export { DEFAULT_VAD_MODEL, findVadModel, requireVadModel, VAD_MODELS } from './model-manifest.js';
+export type { VadModelEntry } from './model-manifest.js';
+export { createSherpaVadEngine, describeVadBackend, hasVadBackend, loadVadBackend, reportVadBackendOnce, _resetVadBackendCache, } from './backend.js';
+export type { EngineSegment, LoadVadBackendOptions, VadBackend, VadBackendStatus, VadEngine } from './backend.js';
+export { inferFormat, toFloatSamples } from './pcm.js';
+export type { PcmChunk, PcmFormat, PcmSourceLike, VadInput } from './pcm.js';
+export { createFakeVadEngine } from './fake-vad.js';
+export type { FakeVadEngine } from './fake-vad.js';

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

@@ -0,0 +1,32 @@
+/** One fetchable Silero VAD model. */
+export interface VadModelEntry {
+    /** Stable id used by `available()`, `install()` and `VadOptions.model`. */
+    readonly id: string;
+    /** File name inside the cache directory. Upstream's own name, so a hand-placed file matches. */
+    readonly file: string;
+    /** Where it is fetched from. Upstream only — never a mirror of ours. */
+    readonly url: string;
+    /** Exact size in bytes. */
+    readonly bytes: number;
+    /** SHA-256 of the file, lowercase hex. */
+    readonly sha256: string;
+    /** SPDX id of the MODEL's licence, which is not this package's. */
+    readonly license: string;
+    /** Sample rate this entry has been measured at. */
+    readonly sampleRate: number;
+    /** Samples per inference window at {@link sampleRate}. */
+    readonly windowSize: number;
+    /** One line for a settings panel or a download prompt. */
+    readonly description: string;
+}
+/**
+ * The default model. v5 is what ADR 0127 decision 10 names, and it is four
+ * times the size of v4 — 2.2 MiB, which is small enough that the choice is
+ * about accuracy rather than bandwidth.
+ */
+export declare const DEFAULT_VAD_MODEL = "silero-v5";
+export declare const VAD_MODELS: readonly VadModelEntry[];
+/** The entry for `id`, or `undefined`. `id` may also be `undefined`, meaning {@link DEFAULT_VAD_MODEL}. */
+export declare function findVadModel(id?: string): VadModelEntry | undefined;
+/** The entry for `id`, or a `RangeError` naming the ids that do exist. */
+export declare function requireVadModel(id?: string): VadModelEntry;

package/lib/types/models.d.ts

@@ -0,0 +1,71 @@
+import fetch from '@gjsify/fetch';
+import { type VadModelEntry } from './model-manifest.js';
+/**
+ * What `available()` answers, as the Web Speech on-device additions spell it:
+ *
+ *   • `available`    — the file is cached and verified-by-size; use it now.
+ *   • `downloading`  — an `install()` for this id is in flight in this process.
+ *   • `downloadable` — the engine is here, the file is not; `install()` fetches it.
+ *   • `unavailable`  — no native engine on this host, so no model helps.
+ */
+export type VadModelAvailability = 'available' | 'downloading' | 'downloadable' | 'unavailable';
+export interface InstallProgress {
+    readonly modelId: string;
+    /** Bytes written so far. Jumps straight to `total` — see the header on buffering. */
+    readonly received: number;
+    /** The manifest's size for this model. */
+    readonly total: number;
+}
+export interface InstallOptions {
+    /** Called at least once, with `received === total` on success. */
+    onProgress?: (progress: InstallProgress) => void;
+    /** Abort the fetch. */
+    signal?: AbortSignal;
+    /** Override `fetch` from `@gjsify/fetch`. Tests only. */
+    fetchImpl?: typeof fetch;
+    /** Re-fetch and overwrite a cached file instead of returning it. */
+    force?: boolean;
+}
+/** `GLib.get_user_cache_dir()/gjsify/speech-models` — shared with the other ADR 0127 packages. */
+export declare function modelCacheDir(): string;
+/** Where `id` is cached, whether or not it exists yet. */
+export declare function modelPath(id?: string): string;
+/**
+ * Whether this host can run a VAD with `id`, and what it would take.
+ *
+ * QUIET and synchronous. Never downloads, never loads a model, and never
+ * throws for a host without an engine — only for an id the manifest does not
+ * have, which is a programming error rather than a host condition.
+ */
+export declare function available(id?: string): VadModelAvailability;
+/** Every manifest entry with what it would take, for a settings panel. */
+export declare function listModels(): {
+    entry: VadModelEntry;
+    availability: VadModelAvailability;
+}[];
+/** Cached model ids, in manifest order. */
+export declare function installedModels(): string[];
+/**
+ * Make `id` usable, fetching it if it is not cached. Resolves to its path.
+ *
+ * Idempotent and safe to call concurrently: a cached file returns immediately
+ * and two overlapping calls share one download. Rejects when the host has no
+ * native engine — `install()` is a commitment to a 2.2 MiB fetch, so it does
+ * not quietly succeed into a state where `createVad()` still cannot run.
+ *
+ * EVERY failure is a rejection, including an unknown id: a function that
+ * returns a promise and sometimes throws before it has to be awaited needs two
+ * error paths at every call site.
+ */
+export declare function install(id?: string, options?: InstallOptions): Promise<string>;
+/** Delete the cached file for `id`. `false` when there was nothing to delete. */
+export declare function uninstall(id?: string): boolean;
+/**
+ * Resolve `VadOptions.model` to a path on disk.
+ *
+ * A value containing a path separator is taken as a path and used as given —
+ * that is how a caller points at a model this manifest does not know. Anything
+ * else is a manifest id, and it must already be cached: resolving must not
+ * start a download behind a synchronous constructor.
+ */
+export declare function resolveModel(model?: string): string;

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

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

package/lib/types/pcm.d.ts

@@ -0,0 +1,34 @@
+/** The byte layouts `openPcmSource()` can be asked for. */
+export type PcmFormat = 'S16LE' | 'F32LE';
+/** A chunk of interleaved mono samples. `Uint8Array` is raw bytes in {@link PcmFormat}. */
+export type PcmChunk = Uint8Array | Int16Array | Float32Array;
+/**
+ * As much of `@gjsify/media-capture`'s `PcmSource` as this package reads.
+ *
+ * Both fields are optional so a bare `AsyncIterable` works too — then the
+ * sample rate falls back to the detector's own and the format has to be either
+ * inferable from the chunk type or given explicitly.
+ */
+export interface PcmSourceLike extends AsyncIterable<PcmChunk> {
+    readonly sampleRate?: number;
+    readonly format?: PcmFormat;
+}
+/** Any source `run()` accepts: a `PcmSource`-like object or a plain async iterable of chunks. */
+export type VadInput = PcmSourceLike | AsyncIterable<PcmChunk>;
+/**
+ * The format a chunk carries in its own type, or `null` for raw bytes.
+ *
+ * `Uint8Array` is deliberately NOT guessed at: `S16LE` and `F32LE` are both
+ * plausible for a byte buffer, and guessing wrong does not fail — it produces
+ * audio that is silently wrong, which a VAD then reports as silence.
+ */
+export declare function inferFormat(chunk: PcmChunk): PcmFormat | null;
+/**
+ * Convert `chunk` to mono float samples in [-1, 1].
+ *
+ * A `Float32Array` is returned as-is — the detector only reads it, and the
+ * caller owns the buffer either way. An odd trailing byte in an `S16LE` buffer
+ * is dropped rather than read past the end; GStreamer does not split a sample
+ * across buffers, so this is a guard for a hand-built chunk.
+ */
+export declare function toFloatSamples(chunk: PcmChunk, format?: PcmFormat): Float32Array;

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

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

package/lib/types/vad.d.ts

@@ -0,0 +1,173 @@
+import { type VadEngine } from './backend.js';
+import { type PcmChunk, type PcmFormat, type VadInput } from './pcm.js';
+/** Speech has begun and is still going. */
+export interface SpeechStartEvent {
+    type: 'speech-start';
+    /**
+     * Stream position where the detector CONFIRMED speech, in seconds.
+     *
+     * This is the live edge, and it lags the acoustic onset — the detector has
+     * to hear {@link VadOptions.minSpeechMs} of speech before it will commit.
+     * Measured on two 16 kHz recordings with the defaults: confirmed at 0.67 s
+     * and 0.38 s for onsets that the matching `speech-end` later reported at
+     * 0.32 s and 0.03 s, so about 0.35 s behind in both.
+     *
+     * That lag is the right behaviour for a "listening" indicator, which must
+     * not flicker on a cough. For trimming audio, use `speech-end.start`,
+     * which is the onset itself.
+     */
+    at: number;
+}
+/** A completed stretch of speech, with its audio. */
+export interface SpeechEndEvent {
+    type: 'speech-end';
+    /** Onset in seconds from the first sample accepted — back-dated by the detector, not the live edge. */
+    start: number;
+    /** End in seconds. */
+    end: number;
+    /** `end - start`. */
+    duration: number;
+    /** Onset in samples, for placing the audio without going through seconds. */
+    startSample: number;
+    /** The segment's audio: mono float in [-1, 1] at {@link VadOptions.sampleRate}. */
+    samples: Float32Array;
+}
+export type VadEvent = SpeechStartEvent | SpeechEndEvent;
+export interface VadOptions {
+    /**
+     * A model id from the manifest (`silero-v5`, `silero-v4`) or a path to an
+     * `.onnx` file. An id must already be cached — `await install(id)` first.
+     * Anything containing a path separator is used as given.
+     */
+    model?: string;
+    /**
+     * Silence that ends a stretch of speech, in ms. Default **300**.
+     *
+     * ADR 0127 decision 10's number, not Silero's 550: the whole wait is added
+     * to every reply, and 300 ms is short enough not to feel late while still
+     * sitting out the pause inside a sentence.
+     */
+    minSilenceMs?: number;
+    /** Speech shorter than this is discarded as a click or a cough. Default 250 ms. */
+    minSpeechMs?: number;
+    /** A stretch is cut at this length even without a pause. Default 20 000 ms. */
+    maxSpeechMs?: number;
+    /** Speech probability above which a window counts as speech. Default 0.5. */
+    threshold?: number;
+    /** Sample rate of the audio fed to {@link VoiceActivityDetector.accept}. Default 16 000. */
+    sampleRate?: number;
+    /** Samples per inference window. Default 512, which is Silero at 16 kHz. */
+    windowSize?: number;
+    /** onnxruntime threads. Default 1 — enough for Silero and the cheapest. */
+    numThreads?: number;
+    /** The engine's internal ring buffer, in seconds. Default 30; must exceed `maxSpeechMs`. */
+    bufferSeconds?: number;
+    /** Make sherpa-onnx print its configuration and decisions to stderr. */
+    debug?: boolean;
+    /** Replace the native engine. Tests use `createFakeVadEngine()`; nothing else should. */
+    engine?: VadEngine;
+}
+/**
+ * A voice activity detector over one audio stream.
+ *
+ * Feed it whatever chunks the capture source produced — any length, the engine
+ * buffers the remainder — and it answers with the events that fell due:
+ *
+ * ```ts
+ * const vad = createVad({ model: 'silero-v5' });
+ * vad.open();
+ * for await (const chunk of source) {
+ *     for (const event of vad.accept(chunk, source.format)) {
+ *         if (event.type === 'speech-start') showListening();
+ *         else transcribe(event.samples);
+ *     }
+ * }
+ * for (const event of vad.flush()) transcribe((event as SpeechEndEvent).samples);
+ * vad.close();
+ * ```
+ *
+ * `flush()` is not optional. The last utterance of a file or a stopped
+ * recording is closed by nothing — no silence follows it — so without a flush
+ * it is never reported at all.
+ */
+export declare class VoiceActivityDetector {
+    readonly sampleRate: number;
+    readonly minSilenceMs: number;
+    readonly minSpeechMs: number;
+    readonly maxSpeechMs: number;
+    private readonly engine;
+    private accepted;
+    private inSpeech;
+    private opened;
+    private closed;
+    constructor(options?: VadOptions);
+    /** Load the model. Idempotent. Throws when the model file cannot be opened. */
+    open(): void;
+    get isOpen(): boolean;
+    /** Whether the detector is inside speech right now — the live edge, for an indicator. */
+    get speaking(): boolean;
+    /** Seconds of audio accepted so far: the timeline the events are placed on. */
+    get position(): number;
+    /** Samples accepted so far. */
+    get positionSamples(): number;
+    /**
+     * Feed one chunk and collect the events it completed.
+     *
+     * `format` is only consulted for a raw `Uint8Array`; an `Int16Array` or
+     * `Float32Array` carries its own. Returns an empty array far more often
+     * than not — nothing falls due in most chunks.
+     */
+    accept(chunk: PcmChunk, format?: PcmFormat): VadEvent[];
+    /**
+     * Close an in-progress stretch of speech and collect what that completed —
+     * end of input.
+     *
+     * Idempotent and cheap on a detector that is not inside speech. Does not
+     * close the detector: after a flush it keeps taking audio, with the
+     * timeline running on.
+     */
+    flush(): VadEvent[];
+    /**
+     * Drop every queued segment and the model state, and forget the timeline.
+     *
+     * For reusing one detector across unrelated recordings. A `speech-start`
+     * already reported is not retracted — there is no event for that.
+     */
+    reset(): void;
+    /** Release the model. Idempotent. The detector is not reusable afterwards. */
+    close(): void;
+    /**
+     * Drive the detector from a capture source and yield its events.
+     *
+     * Takes `@gjsify/media-capture`'s `openPcmSource()` — structurally, so
+     * neither package depends on the other — or any async iterable of chunks.
+     * Flushes at the end of the stream, so the last utterance is reported; the
+     * detector is left open, because the caller owns its lifetime.
+     */
+    run(source: VadInput): AsyncGenerator<VadEvent, void, undefined>;
+    /**
+     * The state machine, and the reason it is one function.
+     *
+     * COMPLETED SEGMENTS ARE DRAINED FIRST, then the live edge is read. The
+     * order is what makes the three awkward cases come out right:
+     *
+     *   • Speech that began AND ended inside this one chunk never raised a live
+     *     edge, so the drain emits a synthetic `speech-start` before its
+     *     `speech-end`. A consumer never sees an end without a start.
+     *   • A `maxSpeechMs` cut arrives as a queued segment while the live edge
+     *     is still true, so it reads as `speech-end` immediately followed by a
+     *     fresh `speech-start` — the stretch continues, under a new start.
+     *   • A burst too short to keep (< `minSpeechMs`) leaves the live edge and
+     *     queues nothing. That is a `speech-start` with no `speech-end`, and it
+     *     stays that way: inventing a zero-length end would make a cough
+     *     indistinguishable from a word.
+     */
+    private collect;
+    private toSpeechEnd;
+}
+/**
+ * Build a detector. Throws when this host has no native engine, or when
+ * `options.model` is a manifest id that is not cached yet — gate on
+ * `hasVadBackend()` and `available()`.
+ */
+export declare function createVad(options?: VadOptions): VoiceActivityDetector;

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

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

package/package.json

@@ -1,6 +1,80 @@
 {
-  "name": "@gjsify/vad",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@gjsify/vad",
+    "version": "0.64.16",
+    "description": "Voice activity detection for GJS: Silero on sherpa-onnx, reporting when speech starts and when a stretch of speech has ended after 300 ms of silence. Takes PCM from @gjsify/media-capture or any async iterable of chunks, and downloads its model on first use instead of bundling one.",
+    "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"
+        }
+    },
+    "files": [
+        "lib"
+    ],
+    "sideEffects": false,
+    "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",
+        "vad",
+        "voice-activity-detection",
+        "silero",
+        "sherpa-onnx",
+        "speech"
+    ],
+    "dependencies": {
+        "@gjsify/fetch": "^0.64.16",
+        "@gjsify/sherpa-native": "^0.64.16",
+        "@gjsify/utils": "^0.64.16"
+    },
+    "devDependencies": {
+        "@girs/gio-2.0": "5.4.0",
+        "@girs/gjs": "5.4.0",
+        "@girs/glib-2.0": "5.4.0",
+        "@gjsify/cli": "^0.64.16",
+        "@gjsify/unit": "^0.64.16",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "gjsify": {
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "none",
+            "browser": "none",
+            "nativescript": "none"
+        },
+        "os": {
+            "linux": "partial",
+            "darwin": "none",
+            "win32": "none"
+        },
+        "osNotes": {
+            "linux": "Needs the @gjsify/sherpa-native prebuild, which exists for linux-x64 only today. Without it available() answers 'unavailable' and createVad() throws with the package to install; hasVadBackend() is the quiet check.",
+            "darwin": "@gjsify/sherpa-native is not built for macOS yet, so there is no detector to drive. available() answers 'unavailable'.",
+            "win32": "@gjsify/sherpa-native is not built for Windows yet, so there is no detector to drive. available() answers 'unavailable'."
+        },
+        "tier": 3
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/web/vad"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/web/vad#readme"
+}