@qvac/bci-whispercpp 0.0.0 → 0.1.1

package/lib/error.js

@@ -0,0 +1,112 @@
+'use strict'
+
+const { QvacErrorBase, addCodes } = require('@qvac/error')
+
+class QvacErrorAddonBCI extends QvacErrorBase { }
+
+const { name, version } = require('../package.json')
+
+// This library has error code range from 26001 to 27000.
+// Ranges used elsewhere in the @qvac/error registry:
+//   6001-6018  @qvac/transcription-whispercpp
+//   7001-7011  @qvac/tts-onnx
+//   8001-8008  @qvac/translation-nmtcpp
+//   24001+     @qvac/transcription-parakeet
+const ERR_CODES = Object.freeze({
+  FAILED_TO_LOAD_WEIGHTS: 26001,
+  FAILED_TO_CANCEL: 26002,
+  FAILED_TO_APPEND: 26003,
+  FAILED_TO_DESTROY: 26004,
+  FAILED_TO_ACTIVATE: 26005,
+  INVALID_NEURAL_INPUT: 26006,
+  JOB_ALREADY_RUNNING: 26007,
+  MODEL_NOT_LOADED: 26008,
+  MODEL_FILE_NOT_FOUND: 26009,
+  BUFFER_LIMIT_EXCEEDED: 26010,
+  FAILED_TO_START_JOB: 26011,
+  INVALID_CONFIG: 26012,
+  EMBEDDER_WEIGHTS_INVALID: 26013,
+  STREAM_ALREADY_ACTIVE: 26014,
+  INVALID_STREAM_INPUT: 26015,
+  INVALID_STREAM_HEADER: 26016,
+  WINDOW_TOO_LARGE: 26017
+})
+
+addCodes({
+  [ERR_CODES.FAILED_TO_LOAD_WEIGHTS]: {
+    name: 'FAILED_TO_LOAD_WEIGHTS',
+    message: (message) => `Failed to load weights, error: ${message}`
+  },
+  [ERR_CODES.FAILED_TO_CANCEL]: {
+    name: 'FAILED_TO_CANCEL',
+    message: (message) => `Failed to cancel inference, error: ${message}`
+  },
+  [ERR_CODES.FAILED_TO_APPEND]: {
+    name: 'FAILED_TO_APPEND',
+    message: (message) => `Failed to append data to processing queue, error: ${message}`
+  },
+  [ERR_CODES.FAILED_TO_DESTROY]: {
+    name: 'FAILED_TO_DESTROY',
+    message: (message) => `Failed to destroy instance, error: ${message}`
+  },
+  [ERR_CODES.FAILED_TO_ACTIVATE]: {
+    name: 'FAILED_TO_ACTIVATE',
+    message: (message) => `Failed to activate model, error: ${message}`
+  },
+  [ERR_CODES.INVALID_NEURAL_INPUT]: {
+    name: 'INVALID_NEURAL_INPUT',
+    message: (message) => `Invalid neural signal input: ${message}`
+  },
+  [ERR_CODES.JOB_ALREADY_RUNNING]: {
+    name: 'JOB_ALREADY_RUNNING',
+    message: () => 'Cannot set new job: a job is already set or being processed'
+  },
+  [ERR_CODES.MODEL_NOT_LOADED]: {
+    name: 'MODEL_NOT_LOADED',
+    message: () => 'Model is not loaded'
+  },
+  [ERR_CODES.MODEL_FILE_NOT_FOUND]: {
+    name: 'MODEL_FILE_NOT_FOUND',
+    message: (modelPath) => `Model file not found at: ${modelPath}`
+  },
+  [ERR_CODES.BUFFER_LIMIT_EXCEEDED]: {
+    name: 'BUFFER_LIMIT_EXCEEDED',
+    message: (limit) => `Neural signal buffer exceeded limit of ${limit}`
+  },
+  [ERR_CODES.FAILED_TO_START_JOB]: {
+    name: 'FAILED_TO_START_JOB',
+    message: (message) => `Failed to start inference job, error: ${message}`
+  },
+  [ERR_CODES.INVALID_CONFIG]: {
+    name: 'INVALID_CONFIG',
+    message: (message) => `Invalid BCI configuration: ${message}`
+  },
+  [ERR_CODES.EMBEDDER_WEIGHTS_INVALID]: {
+    name: 'EMBEDDER_WEIGHTS_INVALID',
+    message: (message) => `BCI embedder weights are invalid: ${message}`
+  },
+  [ERR_CODES.STREAM_ALREADY_ACTIVE]: {
+    name: 'STREAM_ALREADY_ACTIVE',
+    message: () => 'A streaming transcription is already in progress'
+  },
+  [ERR_CODES.INVALID_STREAM_INPUT]: {
+    name: 'INVALID_STREAM_INPUT',
+    message: (message) => `Invalid neural signal stream input: ${message}`
+  },
+  [ERR_CODES.INVALID_STREAM_HEADER]: {
+    name: 'INVALID_STREAM_HEADER',
+    message: (message) => `Invalid neural signal stream header: ${message}`
+  },
+  [ERR_CODES.WINDOW_TOO_LARGE]: {
+    name: 'WINDOW_TOO_LARGE',
+    message: (limit) => `Stream window size exceeds encoder capacity of ${limit} timesteps`
+  }
+}, {
+  name,
+  version
+})
+
+module.exports = {
+  ERR_CODES,
+  QvacErrorAddonBCI
+}

package/lib/stream.js

@@ -0,0 +1,207 @@
+'use strict'
+
+const { QvacErrorAddonBCI, ERR_CODES } = require('./error')
+
+/**
+ * Streaming helpers for the sliding-window transcription driver in index.js.
+ *
+ * These are pure functions kept separate from the class so they can be
+ * unit-tested in isolation (see test/unit/stitch.test.js) and so index.js
+ * stays focused on lifecycle orchestration.
+ */
+
+/**
+ * Coerce a stream chunk into a Uint8Array without copying when possible.
+ * Throws INVALID_STREAM_INPUT if the chunk isn't a recognised binary form.
+ */
+function toUint8 (chunk) {
+  if (chunk instanceof Uint8Array) return chunk
+  if (ArrayBuffer.isView(chunk)) {
+    return new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength)
+  }
+  if (chunk instanceof ArrayBuffer) return new Uint8Array(chunk)
+  if (Array.isArray(chunk)) return Uint8Array.from(chunk)
+  throw new QvacErrorAddonBCI({
+    code: ERR_CODES.INVALID_STREAM_INPUT,
+    adds: 'stream yielded non-binary chunk'
+  })
+}
+
+/**
+ * Copy out the byte range [startTs, endTs) from a list of body chunks
+ * (each element a Uint8Array) into a single contiguous Uint8Array.
+ * The caller owns timestep→byte translation via bytesPerTimestep.
+ */
+function sliceBody (bodyChunks, bytesPerTimestep, startTs, endTs, totalBytes) {
+  const startByte = startTs * bytesPerTimestep
+  const endByte = Math.min(endTs * bytesPerTimestep, totalBytes)
+  const out = new Uint8Array(Math.max(0, endByte - startByte))
+  if (out.byteLength === 0) return out
+  let offset = 0
+  let cursor = 0
+  for (const chunk of bodyChunks) {
+    const chunkStart = cursor
+    const chunkEnd = cursor + chunk.byteLength
+    cursor = chunkEnd
+    if (chunkEnd <= startByte) continue
+    if (chunkStart >= endByte) break
+    const from = Math.max(0, startByte - chunkStart)
+    const to = Math.min(chunk.byteLength, endByte - chunkStart)
+    out.set(chunk.subarray(from, to), offset)
+    offset += (to - from)
+  }
+  return out
+}
+
+/**
+ * Build an [T, C] header-prefixed buffer the addon can consume as a single
+ * batch input, reusing the per-window body bytes.
+ */
+function buildWindowBuffer (windowBody, channels, windowTimesteps) {
+  const out = new Uint8Array(8 + windowBody.byteLength)
+  const view = new DataView(out.buffer, out.byteOffset, out.byteLength)
+  view.setUint32(0, windowTimesteps, true)
+  view.setUint32(4, channels, true)
+  out.set(windowBody, 8)
+  return out
+}
+
+function normalizeWord (w) {
+  return w.toLowerCase().replace(/[^a-z0-9']/g, '')
+}
+
+/**
+ * Text-only word-level stitch: find the longest normalised-word suffix of
+ * `prevText` that also appears as a prefix of `newText`, and treat only
+ * the remainder of `newText` as fresh content.
+ *
+ * The streaming driver in index.js uses `stitchSegments` (below) because
+ * it needs to preserve per-segment timestamp metadata. `stitchMerge` is
+ * retained as a public text-only helper for callers that only have raw
+ * transcript strings to merge (e.g. post-hoc analysis, unit testing the
+ * overlap algorithm without constructing segment objects) and as the
+ * reference implementation of the underlying word-overlap logic.
+ *
+ * Returns { delta, merged, bestK }:
+ *  - delta:  the newly-discovered tail
+ *  - merged: prevText extended by delta
+ *  - bestK:  number of words absorbed as overlap (for inspection/tests)
+ *
+ * maxWords caps the search depth so pathological inputs stay O(maxWords^2).
+ * Known limitation: legitimate immediate word repetitions at a window
+ * boundary (e.g. "the the") will collapse; acceptable for v1 sliding
+ * window until a segmentation model replaces this.
+ */
+function stitchMerge (prevText, newText, maxWords) {
+  const prevWords = prevText.trim().split(/\s+/).filter(Boolean)
+  const newWords = newText.trim().split(/\s+/).filter(Boolean)
+
+  if (prevWords.length === 0) {
+    return { delta: newWords.join(' '), merged: newWords.join(' '), bestK: 0 }
+  }
+  if (newWords.length === 0) {
+    return { delta: '', merged: prevWords.join(' '), bestK: 0 }
+  }
+
+  const bestK = _computeBestK(prevWords, newWords, maxWords)
+  const deltaWords = newWords.slice(bestK)
+  const delta = deltaWords.join(' ')
+  const merged = [...prevWords, ...deltaWords].join(' ')
+  return { delta, merged, bestK }
+}
+
+/**
+ * Segment-aware variant of stitchMerge: preserves the per-segment
+ * timestamp/metadata fields emitted by the native decoder.
+ *
+ * `segments` is the array returned by a per-window decode (each entry is
+ * a whisper-style `{ text, t0, t1, ... }`). We run the same word-level
+ * overlap detection but trim the leading `bestK` words from the incoming
+ * segments rather than flattening to a single string.
+ *
+ * `windowStartTimestep` is attached to every emitted segment so
+ * consumers can correlate a window-local `t0`/`t1` back to the absolute
+ * position in the input stream.
+ *
+ * Returns:
+ *   - deltaSegments: trimmed segments the driver should emit as an update
+ *       (segments fully absorbed by the overlap are dropped; a segment
+ *       partially overlapped gets its `text` rewritten to the surviving
+ *       tail words).
+ *   - merged: running transcript text (identical to stitchMerge.merged)
+ *   - bestK: for inspection / tests
+ */
+function stitchSegments (prevText, segments, maxWords, windowStartTimestep = 0) {
+  const prevWords = prevText.trim().split(/\s+/).filter(Boolean)
+
+  const perSegment = []
+  const newWords = []
+  for (const seg of segments) {
+    const text = (seg && typeof seg.text === 'string') ? seg.text : ''
+    const words = text.trim().split(/\s+/).filter(Boolean)
+    perSegment.push({ seg, words })
+    for (const w of words) newWords.push(w)
+  }
+
+  if (newWords.length === 0) {
+    return { deltaSegments: [], merged: prevWords.join(' '), bestK: 0 }
+  }
+  if (prevWords.length === 0) {
+    const deltaSegments = perSegment
+      .filter(({ words }) => words.length > 0)
+      .map(({ seg }) => ({ ...seg, windowStartTimestep }))
+    return { deltaSegments, merged: newWords.join(' '), bestK: 0 }
+  }
+
+  const bestK = _computeBestK(prevWords, newWords, maxWords)
+
+  let toSkip = bestK
+  const deltaSegments = []
+  for (const { seg, words } of perSegment) {
+    if (words.length === 0) continue
+    if (toSkip >= words.length) { toSkip -= words.length; continue }
+    if (toSkip === 0) {
+      deltaSegments.push({ ...seg, windowStartTimestep })
+    } else {
+      const remainingWords = words.slice(toSkip)
+      const hasT0 = typeof seg.t0 === 'number'
+      const hasT1 = typeof seg.t1 === 'number'
+      const approxT0 = (hasT0 && hasT1)
+        ? seg.t0 + Math.round((seg.t1 - seg.t0) * (toSkip / words.length))
+        : seg.t0
+      deltaSegments.push({
+        ...seg,
+        text: remainingWords.join(' '),
+        t0: approxT0,
+        windowStartTimestep
+      })
+      toSkip = 0
+    }
+  }
+
+  const merged = [...prevWords, ...newWords.slice(bestK)].join(' ')
+  return { deltaSegments, merged, bestK }
+}
+
+function _computeBestK (prevWords, newWords, maxWords) {
+  const maxK = Math.min(prevWords.length, newWords.length, maxWords)
+  for (let k = maxK; k >= 1; k--) {
+    let match = true
+    for (let i = 0; i < k; i++) {
+      const a = normalizeWord(prevWords[prevWords.length - k + i])
+      const b = normalizeWord(newWords[i])
+      if (a.length === 0 || b.length === 0 || a !== b) { match = false; break }
+    }
+    if (match) return k
+  }
+  return 0
+}
+
+module.exports = {
+  toUint8,
+  sliceBody,
+  buildWindowBuffer,
+  normalizeWord,
+  stitchMerge,
+  stitchSegments
+}

package/lib/util.js

@@ -0,0 +1,15 @@
+'use strict'
+
+function flattenSegments (output) {
+  const segments = []
+  for (const entry of output) {
+    if (Array.isArray(entry)) {
+      segments.push(...entry)
+    } else if (entry && typeof entry.text === 'string') {
+      segments.push(entry)
+    }
+  }
+  return segments
+}
+
+module.exports = { flattenSegments }

package/lib/wer.js

@@ -0,0 +1,40 @@
+'use strict'
+
+/**
+ * Compute Word Error Rate between hypothesis and reference.
+ * Uses Levenshtein distance on word sequences.
+ * @param {string} hypothesis
+ * @param {string} reference
+ * @returns {number} WER as a ratio (0.0 = perfect, 1.0 = 100% errors)
+ */
+function computeWER (hypothesis, reference) {
+  const hyp = hypothesis.toLowerCase().trim().split(/\s+/).filter(Boolean)
+  const ref = reference.toLowerCase().trim().split(/\s+/).filter(Boolean)
+
+  if (ref.length === 0) return hyp.length === 0 ? 0 : 1
+
+  const n = ref.length
+  const m = hyp.length
+  const dp = Array.from({ length: n + 1 }, () => Array(m + 1).fill(0))
+
+  for (let i = 0; i <= n; i++) dp[i][0] = i
+  for (let j = 0; j <= m; j++) dp[0][j] = j
+
+  for (let i = 1; i <= n; i++) {
+    for (let j = 1; j <= m; j++) {
+      if (ref[i - 1] === hyp[j - 1]) {
+        dp[i][j] = dp[i - 1][j - 1]
+      } else {
+        dp[i][j] = 1 + Math.min(
+          dp[i - 1][j],
+          dp[i][j - 1],
+          dp[i - 1][j - 1]
+        )
+      }
+    }
+  }
+
+  return dp[n][m] / n
+}
+
+module.exports = { computeWER }

package/package.json

@@ -1 +1,96 @@
-{"name":"@qvac/bci-whispercpp","version":"0.0.0"}
+{
+  "name": "@qvac/bci-whispercpp",
+  "version": "0.1.1",
+  "description": "Brain-Computer Interface (BCI) neural signal transcription addon for qvac, powered by whisper.cpp",
+  "addon": true,
+  "engines": {
+    "bare": ">=1.24.0"
+  },
+  "scripts": {
+    "lint": "standard \"examples/**/*.js\" \"test/**/*.js\" \"*.js\" \"lib/**/*.js\"",
+    "lint:fix": "standard --fix \"examples/**/*.js\" \"test/**/*.js\" \"*.js\" \"lib/**/*.js\"",
+    "lint-cpp": "clang-tidy -p build addon/src/js-interface/JSAdapter.cpp addon/src/js-interface/binding.cpp addon/src/model-interface/bci/BCIConfig.cpp addon/src/model-interface/bci/BCIModel.cpp addon/src/model-interface/bci/NeuralProcessor.cpp addon/src/addon/AddonJs.hpp addon/src/js-interface/JSAdapter.hpp addon/src/addon/BCIErrors.hpp addon/src/model-interface/BCITypes.hpp addon/src/model-interface/bci/BCIConfig.hpp addon/src/model-interface/bci/BCIModel.hpp addon/src/model-interface/bci/NeuralProcessor.hpp",
+    "build": "bare-make generate && bare-make build && bare-make install",
+    "build:pack": "mkdir -p dist && npm pack --pack-destination dist",
+    "test": "npm run test:unit && npm run test:integration",
+    "test:unit": "brittle-bare test/unit/*.test.js",
+    "test:integration": "brittle-bare test/integration/addon.test.js",
+    "test:cpp:build": "bare-make generate -D BUILD_TESTING=ON && bare-make build --target test-bci-core && bare-make install",
+    "test:cpp:run": "cd build/addon/tests/ && LLVM_PROFILE_FILE=default.profraw ./test-bci-core --gtest_output=xml:cpp-test-results.xml",
+    "test:cpp": "npm run test:cpp:build && npm run test:cpp:run",
+    "coverage:cpp:build": "bare-make generate -D BUILD_TESTING=ON -D ENABLE_COVERAGE=ON && bare-make build --target test-bci-core",
+    "coverage:cpp:summary": "cd build/addon/tests && llvm-cov-19 report ./test-bci-core --instr-profile=coverage.profdata -ignore-filename-regex='(tests|build|node_modules|gtest|gmock|\\.vcpkg|/usr)/' > coverage-summary.txt",
+    "coverage:cpp:report": "cd build/addon/tests/ && ls -lha && llvm-profdata-19 merge -sparse default.profraw -o coverage.profdata && llvm-cov-19 show ./test-bci-core -instr-profile=coverage.profdata -format=html -output-dir=coverage-html -ignore-filename-regex='(tests|build|node_modules|gtest|gmock|\\.vcpkg|/usr)/' && llvm-cov-19 export ./test-bci-core -instr-profile=coverage.profdata -format=lcov -ignore-filename-regex='(tests|build|node_modules|gtest|gmock|\\.vcpkg|/usr)/' > lcov.info && npm run coverage:cpp:summary",
+    "coverage:cpp": "npm run coverage:cpp:build && npm run test:cpp:run && npm run coverage:cpp:report",
+    "test:dts": "tsc -p tsconfig.dts.json",
+    "test:mobile:generate": "node scripts/generate-mobile-tests.js"
+  },
+  "files": [
+    "addonLogging.js",
+    "addonLogging.d.ts",
+    "binding.js",
+    "bci.js",
+    "configChecker.js",
+    "index.js",
+    "index.d.ts",
+    "prebuilds",
+    "lib",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tetherto/qvac.git",
+    "directory": "packages/bci-whispercpp"
+  },
+  "author": "Tether",
+  "keywords": [
+    "tether",
+    "addon",
+    "whisper",
+    "bci",
+    "brain-computer-interface",
+    "neural",
+    "qvac"
+  ],
+  "license": "Apache-2.0",
+  "bugs": "https://github.com/tetherto/qvac/issues",
+  "homepage": "https://github.com/tetherto/qvac/tree/main/packages/bci-whispercpp#readme",
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "bare-buffer": "^3.4.2",
+    "brittle": "^3.17.0",
+    "cmake-bare": "^1.7.5",
+    "cmake-vcpkg": "^1.1.0",
+    "standard": "^17.1.2",
+    "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "@qvac/error": "^0.1.0",
+    "@qvac/infer-base": "^0.4.0",
+    "@qvac/logging": "^0.1.0",
+    "bare-fs": "^4.5.1",
+    "bare-path": "^3.0.0"
+  },
+  "exports": {
+    "./package": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./addonLogging": {
+      "types": "./addonLogging.d.ts",
+      "default": "./addonLogging.js"
+    },
+    "./addonLogging.js": "./addonLogging.js",
+    "./bci": "./bci.js",
+    "./bci.js": "./bci.js",
+    "./binding": "./binding.js",
+    "./binding.js": "./binding.js",
+    "./util": "./lib/util.js",
+    "./wer": "./lib/wer.js"
+  },
+  "types": "index.d.ts"
+}