@qvac/bci-whispercpp - npm Package Compare versions

Comparing version 0.3.0 to 0.3.1

CHANGELOG.md

@@ -8,2 +8,22 @@ # Changelog
 
+## [0.3.1]
+
+### Added
+
+- `files.embedder` — optional path to the embedder weights file. The
+  embedder location can now be supplied explicitly from JS instead of
+  always being derived from a hardcoded `bci-embedder.bin` filename next to
+  the GGML model. The path flows from JS (`files.embedder` →
+  `configurationParams.embedderPath`) down to
+  `BCIModel::loadEmbedderIfNeeded()`. Fully backward compatible: when
+  `files.embedder` is omitted, the native side falls back to resolving
+  `bci-embedder.bin` next to `files.model` (previous behaviour).
+
+  ```js
+  // default (unchanged) — embedder resolved next to the model
+  new BCIWhispercpp({ files: { model } }, config)
+  // explicit embedder location
+  new BCIWhispercpp({ files: { model, embedder } }, config)
+  ```
+
 ## [0.3.0]
@@ -10,0 +30,0 @@

index.d.ts

@@ -41,2 +41,7 @@ import QvacResponse from '@qvac/infer-base/src/QvacResponse'
   model: string
+  /**
+   * Optional path to the embedder weights file. When omitted the native
+   * addon resolves `bci-embedder.bin` from the same directory as `model`.
+   */
+  embedder?: string
 }
@@ -43,0 +48,0 @@

index.js

@@ -60,2 +60,5 @@ 'use strict'
    * @param {string} args.files.model - path to the BCI GGML model file
+   * @param {string} [args.files.embedder] - optional path to the embedder
+   *   weights file. When omitted, the native addon falls back to resolving
+   *   `bci-embedder.bin` next to `files.model`.
    * @param {Object} [args.logger] - optional logger instance
@@ -77,3 +80,14 @@ * @param {Object} [args.opts] - optional options (e.g. { stats: true })
 
+    if (files.embedder !== undefined &&
+        (typeof files.embedder !== 'string' || files.embedder.length === 0)) {
+      throw new QvacErrorAddonBCI({
+        code: ERR_CODES.MODEL_FILE_NOT_FOUND,
+        adds: 'files.embedder must be a non-empty string when provided'
+      })
+    }
+
     this._files = { model: files.model }
+    if (typeof files.embedder === 'string' && files.embedder.length > 0) {
+      this._files.embedder = files.embedder
+    }
     this._config = config
@@ -154,2 +168,9 @@ this.opts = opts
 
+    if (this._files.embedder && !fs.existsSync(this._files.embedder)) {
+      throw new QvacErrorAddonBCI({
+        code: ERR_CODES.MODEL_FILE_NOT_FOUND,
+        adds: this._files.embedder
+      })
+    }
+
     const whisperConfig = {
@@ -186,2 +207,9 @@ language: 'en',
 
+    // Optional override. When provided, the native side loads the embedder
+    // weights from this exact path instead of resolving `bci-embedder.bin`
+    // next to the GGML model file. Mirrors the `backendsDir` override.
+    if (this._files.embedder) {
+      configurationParams.embedderPath = this._files.embedder
+    }
+
     if (this.state.destroyed) {
@@ -188,0 +216,0 @@ throw new QvacErrorAddonBCI({

package.json

 {
   "name": "@qvac/bci-whispercpp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Brain-Computer Interface (BCI) neural signal transcription addon for qvac, powered by whisper.cpp",
@@ -26,3 +26,4 @@ "addon": true,
     "test:dts": "tsc -p tsconfig.dts.json",
-    "test:mobile:generate": "node scripts/generate-mobile-tests.js"
+    "test:mobile:generate": "npm install && node scripts/generate-mobile-tests.js",
+    "download-models": "node scripts/download-models.js"
   },
@@ -63,2 +64,3 @@ "files": [
   "devDependencies": {
+    "@qvac/registry-client": "^0.6.0",
     "@types/node": "^22.15.3",
@@ -65,0 +67,0 @@ "bare-buffer": "^3.4.2",

README.md

@@ -13,2 +13,3 @@ # @qvac/bci-whispercpp
 - [Installation](#installation)
+- [Quickstart](#quickstart)
 - [Model Conversion](#model-conversion)
@@ -90,2 +91,34 @@ - [Usage](#usage)
 
+## Quickstart
+
+To run an example you need the BCI model files and (for batch mode) the test fixtures. The download script fetches the **model files from the QVAC model registry** (no GitHub CLI, no auth) and the **neural-signal fixtures from the public release tarball** (the fixtures aren't in the registry yet).
+
+```bash
+cd packages/bci-whispercpp
+npm install   # installs @qvac/registry-client (devDependency)
+
+# Download model files (ggml-bci-windowed.bin + bci-embedder.bin) + test fixtures
+npm run download-models
+# node scripts/download-models.js --models    # models only (from the registry)
+# node scripts/download-models.js --fixtures  # fixtures only
+# node scripts/download-models.js --force     # re-download even if present
+```
+
+The models land in `models/` and the neural-signal fixtures in `test/fixtures/`. Then run an example:
+
+```bash
+# Transcribe all bundled fixture samples and print WER
+bare examples/transcribe-neural.js --batch
+
+# Transcribe a single neural signal file
+bare examples/transcribe-neural.js test/fixtures/neural_sample_0.bin
+
+# Streaming transcription over a sliding window
+bare examples/transcribe-stream-neural.js test/fixtures/neural_sample_0.bin
+```
+
+By default the examples look for `models/ggml-bci-windowed.bin` (with `bci-embedder.bin` alongside it). Override with `WHISPER_MODEL_PATH=/path/to/ggml-bci-windowed.bin` or by passing the model path as the final argument.
+
+> The model files come from the [`qvac` model registry](https://github.com/tetherto/qvac/tree/main/packages/registry-server) (engine `@qvac/bci-whispercpp`, S3 source `qvac_models_compiled/bci-whispercpp/...`). If you already have them locally, skip the download step and point `WHISPER_MODEL_PATH` at your copy. The fixtures URL can be overridden with `BCI_FIXTURES_URL`.
+
 ### Model Conversion Prerequisites
@@ -120,3 +153,3 @@
 
-**Important:** Both files must be in the same directory at runtime. The C++ addon looks for `bci-embedder.bin` next to the GGML model file and will fail if it is missing.
+**Important:** By default both files must be in the same directory at runtime — the addon resolves `bci-embedder.bin` next to the GGML model file and will fail if it is missing. To store the embedder elsewhere, pass an explicit path via `files.embedder` (see [Usage](#usage)).
 
@@ -144,3 +177,12 @@ ## Usage
 
-> The companion `bci-embedder.bin` must sit next to `files.model`. The native addon resolves it by path and will fail to load otherwise.
+> By default the companion `bci-embedder.bin` must sit next to `files.model` — the native addon resolves it relative to the model path and will fail to load otherwise. To keep the embedder in a different location, pass its path explicitly via `files.embedder`:
+>
+> ```js
+> const bci = new BCIWhispercpp({
+>   files: {
+>     model: './models/ggml-bci-windowed.bin',
+>     embedder: './weights/bci-embedder.bin' // optional override
+>   }
+> })
+> ```
 
@@ -259,3 +301,3 @@ ### 2. Load the model
 
-Integration tests require both `ggml-bci-windowed.bin` and `bci-embedder.bin` to be present in the same directory. See [Model Conversion](#model-conversion).
+Integration tests require both `ggml-bci-windowed.bin` and `bci-embedder.bin` to be present in the same directory, plus the neural-signal fixtures. The quickest way to get them is `npm run download-models` (see [Quickstart](#quickstart)); alternatively produce the models yourself via [Model Conversion](#model-conversion).
 
@@ -274,3 +316,4 @@ ## Configuration
 |-------|------|-------------|
-| `files.model` | string | **Required.** Path to BCI GGML model file (`bci-embedder.bin` must sit alongside it). |
+| `files.model` | string | **Required.** Path to BCI GGML model file. By default `bci-embedder.bin` must sit alongside it. |
+| `files.embedder` | string | Optional explicit path to the embedder weights file. Overrides the default lookup of `bci-embedder.bin` next to `files.model`. |
 | `logger` | object | Optional logger; wrapped in `@qvac/logging`. Defaults to a noop logger. |
@@ -354,3 +397,3 @@ | `opts.stats` | boolean | When `true`, runtime stats are surfaced on `response.stats` for batch jobs. Default `false`. |
 | `26008` | `MODEL_NOT_LOADED` | Inference called before `load()` or after `destroy()` |
-| `26009` | `MODEL_FILE_NOT_FOUND` | `files.model` missing or unreadable |
+| `26009` | `MODEL_FILE_NOT_FOUND` | `files.model` missing/unreadable, or `files.embedder` provided but missing/invalid |
 | `26010` | `BUFFER_LIMIT_EXCEEDED` | Neural signal buffer exceeded the addon limit |
@@ -357,0 +400,0 @@ | `26011` | `FAILED_TO_START_JOB` | Addon refused to start the job |

No alert changes

Improved metrics

Total package byte prevSize

282669478

0.12%

Lines of code

1557

1.96%

Number of lines in readme file

422

11.35%

Worsened metrics

Dev dependency count

8

14.29%

No dependency changes