# STP Plugin: Vosk Offline Speech

The Sketch-thru-Plan (STP) recognizer can employ transcribed speech generated by potentially different recognizers. To promote code reuse and make it possible to more easily swap recognizers, the functionality should be packaged as a plugin that conforms to a well-known interface.

This plugin is implemented based on [Vosk](https://alphacephei.com/vosk/) WebAssembly, providing offline speech recognition that runs entirely in the browser. No cloud service, API keys, or network connection is required — a domain-adapted Kaldi model optimized for military planning vocabulary is included with the plugin and deployed alongside the application.

## Prerequisites

This plugin requires a Vosk speech model to be served as static files alongside your application. A domain-adapted model is included at `model/vosk-model-la-domain.zip` (~28 MB). The model must be deployed as **unpacked files** in a directory accessible to the web server — the plugin fetches each model file individually at runtime and cannot load a zip or archive directly.

### Setting up the model

Extract the model into your application's static directory:

```bash
# PowerShell (Windows)
Expand-Archive -Path plugins/speech/voskspeech-plugin/model/vosk-model-la-domain.zip -DestinationPath your-app/model

# bash / macOS / Linux
unzip plugins/speech/voskspeech-plugin/model/vosk-model-la-domain.zip -d your-app/model
```

The resulting `model/` directory (~50 MB on disk) must contain the unpacked `am/`, `conf/`, `graph/`, and `ivector/` subdirectories — the acoustic model, decoding graph, and configuration files required by the Vosk WASM runtime.

> **Note:** The page must be served over **HTTPS** for microphone access. Modern browsers also require **AudioWorklet** (Chrome 66+, Firefox 76+, Safari 14.1+, Edge 79+) and **WebAssembly** support.

### Where the model comes from

`model/vosk-model-la-domain.zip` is **not authored in this repository** and must
never be edited here. It is a deterministic repackaging of
`Clients/MultiSpeech/Models/vosk-model-la-domain/` in the STP engine repo, and
`samples/basic/vosk-model-la-domain.zip` is a byte copy of it. Refresh both, plus
the `model-artifacts.sha256` stamp beside the zip, with a single engine command:

```bash
cd <STP>/Clients/MultiSpeech/vosk-model-builder
python -m build.model_artifacts --deploy --js-sdk-root <this repo>
```

`npm run verify:speech-model` checks both copies against that stamp and runs in
CI. It reads the Git LFS pointers rather than the blobs, so it costs no LFS
bandwidth: a pointer records `oid sha256:<hash>`, which is the content hash.

This is enforced because it went wrong (Jira STP-683). The two copies here were
built from the 2026-05-14 engine model, had missed two rebuilds, and were not
even identical to each other - same files, same content, 32 bytes of embedded
zip timestamps apart, because each was zipped in its own run. Nothing compared
them.

## Accessing the plugin functionality

The plugin requires two separate scripts: the Vosk WASM runtime and the plugin bundle itself. The Vosk runtime (`vosk-browser`) is **not** bundled into the plugin — it is loaded separately so the browser can cache the large WASM module independently.

Copy `vosk.js` from `node_modules/vosk-browser/dist/vosk.js` into your app directory, then reference both scripts:

```html
<!-- Vosk WASM runtime (exposes global `Vosk`) — must be loaded first -->
<script type="application/javascript" src="vosk.js"></script>
<!-- Vosk speech plugin (exposes global `StpVS`) -->
<script type="application/javascript" src="stpvoskspeech-bundle-min.js"></script>
```

The `vosk-processor.js` AudioWorklet file must also be accessible from your application — it is loaded at runtime by the plugin. By default it is expected in the same directory as the page; use the `workletPath` constructor parameter to specify an alternate location.

## Referencing the plugin

The plugin is built as a `UMD` library, and is therefore compatible with plain vanilla (IIFE), AMD and CommonJS. Also included is an ESM bundle (`stpvoskspeech-bundle.esm.js`).

When used in vanilla javascript, an `StpVS` exported global can be used to access the plugin types:

```javascript
const speechreco = new StpVS.VoskSpeechRecognizer();
```

If the model is served from a non-default location, or the AudioWorklet file is in a different directory, pass the paths to the constructor:

```javascript
// VoskSpeechRecognizer(modelPath?, sampleRate?, workletPath?)
const speechreco = new StpVS.VoskSpeechRecognizer('./my-models/vosk-model-la-domain', 16000, './lib/vosk-processor.js');
```

Model loading begins eagerly in the background as soon as the recognizer is created.

## Examples

* The [basic sample](../../../samples/basic/README.md) supports selection of Vosk alongside Azure and AWS speech plugins at runtime via a dropdown control

## Building the project

The repository includes a pre-built `dist` folder that can be used directly for testing. If changes are made to the plugin and there is a need to rebuild, run:

```
npm install
npm run build
```

## Documentation

See the [speech plugins overview](../README.md) for details on the `ISpeechRecognizer` interface, recognition strategies, and event handling.