@qvac/bci-whispercpp 0.0.0 → 0.1.0

package/bci.js

@@ -0,0 +1,370 @@
+'use strict'
+
+const { QvacErrorAddonBCI, ERR_CODES } = require('./lib/error')
+const { checkConfig } = require('./configChecker')
+
+const state = Object.freeze({
+  LOADING: 'loading',
+  LISTENING: 'listening',
+  PROCESSING: 'processing',
+  IDLE: 'idle'
+})
+
+const END_OF_INPUT = 'end of job'
+
+// Upper bound on buffered neural-signal bytes between append() calls.
+// Neural data is ~1 MB/s at 512ch * 50 Hz * 4 B, so 500 MB ~= 8 minutes of
+// signal. The bound matches qvac-lib-infer-whispercpp and protects against
+// runaway producers.
+const MAX_BUFFERED_BYTES = 500 * 1024 * 1024
+
+function nextSafeId (current) {
+  return current >= Number.MAX_SAFE_INTEGER ? 1 : current + 1
+}
+
+/**
+ * Low-level interface between the Bare C++ BCI addon and the JS runtime.
+ * Accepts neural signal data (Uint8Array) instead of audio.
+ */
+class BCIInterface {
+  /**
+   * @param {Object} binding - the native binding object
+   * @param {Object} configurationParams - configuration for the BCI model
+   * @param {Function} outputCb - callback for inference events (Output, JobEnded, Error)
+   * @param {Function} [transitionCb] - callback for state changes
+   */
+  constructor (binding, configurationParams, outputCb, transitionCb = null) {
+    this._binding = binding
+    this._outputCb = outputCb
+    this._transitionCb = transitionCb
+    this._nextJobId = 1
+    this._activeJobId = null
+    this._bufferedSignal = []
+    this._bufferedBytes = 0
+    this._state = state.LOADING
+
+    checkConfig(configurationParams)
+    this._handle = this._binding.createInstance(
+      this,
+      configurationParams,
+      this._addonOutputCallback.bind(this),
+      transitionCb
+    )
+  }
+
+  _setState (newState) {
+    this._state = newState
+    if (this._transitionCb) {
+      this._transitionCb(this, newState)
+    }
+  }
+
+  _addonOutputCallback (addon, event, data, error) {
+    const isError = typeof error === 'string' && error.length > 0
+    const isStats = data && typeof data === 'object' && (
+      'totalTime' in data ||
+      'tokensPerSecond' in data ||
+      'totalWallMs' in data
+    )
+    const isTranscriptOutput = (
+      (Array.isArray(data) && data.length > 0) ||
+      (data && typeof data === 'object' && typeof data.text === 'string')
+    )
+
+    let mappedEvent = event
+    if (event === 'Error' || isError || String(event).includes('Error')) {
+      mappedEvent = 'Error'
+    } else if (event === 'JobEnded' || isStats || String(event).includes('RuntimeStats')) {
+      mappedEvent = 'JobEnded'
+    } else if (event === 'Output' || isTranscriptOutput) {
+      mappedEvent = 'Output'
+    } else if (Array.isArray(data) && data.length === 0) {
+      return
+    }
+
+    const jobId = this._activeJobId
+    if (jobId === null || jobId === undefined) {
+      return
+    }
+
+    if (mappedEvent === 'Output') {
+      this._setState(state.PROCESSING)
+
+      if (this._outputCb != null) {
+        const isTranscriptArray = Array.isArray(data) && data.length > 0 &&
+          typeof data[0]?.text === 'string'
+        const isSingleTranscript = !Array.isArray(data) &&
+          data && typeof data === 'object' && typeof data.text === 'string'
+        if (isTranscriptArray) {
+          for (const segment of data) {
+            this._outputCb(addon, 'Output', jobId, [segment], null)
+          }
+        } else if (isSingleTranscript) {
+          this._outputCb(addon, 'Output', jobId, [data], null)
+        } else {
+          this._outputCb(addon, 'Output', jobId, data, null)
+        }
+      }
+      return
+    }
+
+    if (this._outputCb != null) {
+      this._outputCb(addon, mappedEvent, jobId, data, isError ? error : null)
+    }
+
+    if (mappedEvent === 'Error' || mappedEvent === 'JobEnded') {
+      this._activeJobId = null
+      this._setState(state.LISTENING)
+    }
+  }
+
+  async unload () {
+    await this.destroyInstance()
+  }
+
+  async load (configurationParams) {
+    checkConfig(configurationParams)
+    await this.destroyInstance()
+    this._handle = this._binding.createInstance(
+      this,
+      configurationParams,
+      this._addonOutputCallback.bind(this),
+      this._transitionCb
+    )
+    this._setState(state.LOADING)
+  }
+
+  async reload (configurationParams) {
+    checkConfig(configurationParams)
+    await this.cancel()
+
+    if (typeof this._binding.reload === 'function') {
+      await this._binding.reload(this._handle, configurationParams)
+      this._setState(state.LOADING)
+      return
+    }
+
+    await this.load(configurationParams)
+  }
+
+  async loadWeights (weightsData) {
+    try {
+      this._binding.loadWeights(this._handle, weightsData)
+    } catch (err) {
+      throw new QvacErrorAddonBCI({
+        code: ERR_CODES.FAILED_TO_LOAD_WEIGHTS,
+        adds: err.message,
+        cause: err
+      })
+    }
+  }
+
+  async unloadWeights () {
+    return true
+  }
+
+  async activate () {
+    try {
+      this._binding.activate(this._handle)
+      this._setState(state.LISTENING)
+    } catch (err) {
+      throw new QvacErrorAddonBCI({
+        code: ERR_CODES.FAILED_TO_ACTIVATE,
+        adds: err.message,
+        cause: err
+      })
+    }
+  }
+
+  async cancel (jobId) {
+    try {
+      await this._binding.cancel(this._handle, jobId)
+      this._bufferedSignal = []
+      this._bufferedBytes = 0
+      this._activeJobId = null
+      this._setState(state.LISTENING)
+    } catch (err) {
+      throw new QvacErrorAddonBCI({
+        code: ERR_CODES.FAILED_TO_CANCEL,
+        adds: err.message,
+        cause: err
+      })
+    }
+  }
+
+  /**
+   * Appends neural signal data to the processing buffer.
+   * Send { type: 'end of job' } to trigger processing.
+   * @param {Object} data
+   * @param {string} data.type - 'neural' or 'end of job'
+   * @param {Uint8Array} [data.input] - binary neural signal data
+   * @returns {number} job ID
+   */
+  async append (data) {
+    try {
+      if (data?.type === END_OF_INPUT) {
+        if (this._bufferedSignal.length === 0) {
+          throw new QvacErrorAddonBCI({
+            code: ERR_CODES.INVALID_NEURAL_INPUT,
+            adds: 'no neural signal data was appended before end-of-job'
+          })
+        }
+        const currentJobId = this._nextJobId
+        const input = this._concatBufferedSignal()
+        const previousState = this._state
+        const previousJobId = this._activeJobId
+
+        let accepted = false
+        try {
+          accepted = this._binding.runJob(this._handle, {
+            type: 'neural',
+            input
+          })
+        } catch (err) {
+          this._activeJobId = previousJobId
+          this._setState(previousState)
+          throw err
+        }
+        if (!accepted) {
+          this._activeJobId = previousJobId
+          this._setState(previousState)
+          throw new QvacErrorAddonBCI({ code: ERR_CODES.JOB_ALREADY_RUNNING })
+        }
+
+        this._activeJobId = currentJobId
+        this._nextJobId = nextSafeId(this._nextJobId)
+        this._bufferedSignal = []
+        this._bufferedBytes = 0
+        this._setState(state.PROCESSING)
+        return currentJobId
+      }
+
+      if (data?.type === 'neural') {
+        if (!(data.input instanceof Uint8Array)) {
+          throw new QvacErrorAddonBCI({
+            code: ERR_CODES.INVALID_NEURAL_INPUT,
+            adds: 'input must be Uint8Array'
+          })
+        }
+        if (this._bufferedBytes + data.input.byteLength > MAX_BUFFERED_BYTES) {
+          throw new QvacErrorAddonBCI({
+            code: ERR_CODES.BUFFER_LIMIT_EXCEEDED,
+            adds: MAX_BUFFERED_BYTES + ' bytes'
+          })
+        }
+        this._bufferedSignal.push(data.input)
+        this._bufferedBytes += data.input.byteLength
+        return this._nextJobId
+      }
+
+      throw new Error(`Unknown append input type: ${data?.type}`)
+    } catch (err) {
+      if (err instanceof QvacErrorAddonBCI) throw err
+      throw new QvacErrorAddonBCI({
+        code: ERR_CODES.FAILED_TO_APPEND,
+        adds: err.message,
+        cause: err
+      })
+    }
+  }
+
+  /**
+   * Run a single batch job directly with neural signal data.
+   * @param {Object} data
+   * @param {Uint8Array} data.input - binary neural signal data
+   */
+  async runJob (data) {
+    if (!data || !(data.input instanceof Uint8Array)) {
+      throw new QvacErrorAddonBCI({
+        code: ERR_CODES.INVALID_NEURAL_INPUT,
+        adds: 'runJob input must be a Uint8Array'
+      })
+    }
+    if (data.input.byteLength === 0) {
+      throw new QvacErrorAddonBCI({
+        code: ERR_CODES.INVALID_NEURAL_INPUT,
+        adds: 'runJob input must not be empty'
+      })
+    }
+
+    const candidateJobId = this._nextJobId
+    const previousState = this._state
+    const previousJobId = this._activeJobId
+    let accepted = false
+    try {
+      accepted = this._binding.runJob(this._handle, {
+        type: 'neural',
+        input: data.input
+      })
+    } catch (err) {
+      this._activeJobId = previousJobId
+      this._setState(previousState)
+      throw new QvacErrorAddonBCI({
+        code: ERR_CODES.FAILED_TO_START_JOB,
+        adds: err.message,
+        cause: err
+      })
+    }
+
+    if (!accepted) {
+      this._activeJobId = previousJobId
+      this._setState(previousState)
+      return false
+    }
+
+    this._activeJobId = candidateJobId
+    this._nextJobId = nextSafeId(this._nextJobId)
+    this._setState(state.PROCESSING)
+    return accepted
+  }
+
+  async status () {
+    return this._state
+  }
+
+  async destroyInstance () {
+    if (this._handle === null) {
+      return
+    }
+    try {
+      try {
+        await this._binding.cancel(this._handle)
+      } catch {}
+      this._binding.destroyInstance(this._handle)
+      this._handle = null
+      this._bufferedSignal = []
+      this._bufferedBytes = 0
+      this._activeJobId = null
+      this._setState(state.IDLE)
+    } catch (err) {
+      throw new QvacErrorAddonBCI({
+        code: ERR_CODES.FAILED_TO_DESTROY,
+        adds: err.message,
+        cause: err
+      })
+    }
+  }
+
+  _concatBufferedSignal () {
+    if (this._bufferedSignal.length === 0) {
+      return new Uint8Array()
+    }
+    if (this._bufferedSignal.length === 1) {
+      return this._bufferedSignal[0]
+    }
+    const totalLength = this._bufferedSignal.reduce(
+      (sum, chunk) => sum + chunk.byteLength, 0
+    )
+    const merged = new Uint8Array(totalLength)
+    let offset = 0
+    for (const chunk of this._bufferedSignal) {
+      merged.set(chunk, offset)
+      offset += chunk.byteLength
+    }
+    return merged
+  }
+}
+
+BCIInterface.END_OF_INPUT = END_OF_INPUT
+
+module.exports = { BCIInterface, END_OF_INPUT, MAX_BUFFERED_BYTES, nextSafeId }

package/binding.js

@@ -0,0 +1 @@
+module.exports = require.addon()

package/configChecker.js

@@ -0,0 +1,91 @@
+'use strict'
+
+/**
+ * Validates BCI addon configuration.
+ * @param {Object} configObject
+ * @returns {void} or throws if invalid
+ */
+function checkConfig (configObject) {
+  const requiredSections = ['whisperConfig', 'contextParams', 'miscConfig']
+
+  for (const section of requiredSections) {
+    if (!configObject[section]) {
+      throw new Error(`${section} object is required`)
+    }
+  }
+
+  const validWhisperParams = [
+    'n_threads',
+    'duration_ms',
+    'translate',
+    'no_timestamps',
+    'single_segment',
+    'print_special',
+    'print_progress',
+    'print_realtime',
+    'print_timestamps',
+    'language',
+    'detect_language',
+    'suppress_blank',
+    'suppress_nst',
+    'temperature',
+    'greedy_best_of',
+    'beam_search_beam_size'
+  ]
+
+  const validContextParams = [
+    'model',
+    'use_gpu',
+    'flash_attn',
+    'gpu_device'
+  ]
+
+  const validMiscParams = [
+    'caption_enabled'
+  ]
+
+  const validBCIParams = [
+    'day_idx'
+  ]
+
+  for (const userParam of Object.keys(configObject.whisperConfig)) {
+    if (!validWhisperParams.includes(userParam)) {
+      throw new Error(`${userParam} is not a valid parameter for whisperConfig`)
+    }
+  }
+
+  for (const userParam of Object.keys(configObject.contextParams)) {
+    if (!validContextParams.includes(userParam)) {
+      throw new Error(`${userParam} is not a valid parameter for contextParams`)
+    }
+  }
+
+  for (const userParam of Object.keys(configObject.miscConfig)) {
+    if (!validMiscParams.includes(userParam)) {
+      throw new Error(`${userParam} is not a valid parameter for miscConfig`)
+    }
+  }
+  if (configObject.miscConfig.caption_enabled !== undefined &&
+      typeof configObject.miscConfig.caption_enabled !== 'boolean') {
+    throw new Error('miscConfig.caption_enabled must be a boolean')
+  }
+
+  if (configObject.bciConfig) {
+    for (const userParam of Object.keys(configObject.bciConfig)) {
+      if (!validBCIParams.includes(userParam)) {
+        throw new Error(`${userParam} is not a valid parameter for bciConfig`)
+      }
+    }
+    const dayIdx = configObject.bciConfig.day_idx
+    if (dayIdx !== undefined) {
+      if (typeof dayIdx !== 'number' || !Number.isFinite(dayIdx) || !Number.isInteger(dayIdx)) {
+        throw new Error('bciConfig.day_idx must be a finite integer')
+      }
+      if (dayIdx < -1) {
+        throw new Error('bciConfig.day_idx must be >= -1 (use -1 to enable mel-passthrough mode)')
+      }
+    }
+  }
+}
+
+module.exports = { checkConfig }

package/index.d.ts

@@ -0,0 +1,134 @@
+import QvacResponse from '@qvac/infer-base/src/QvacResponse'
+import type { LoggerInterface } from '@qvac/logging'
+
+declare interface BCIConfig {
+  /**
+   * Session day index used to select day-specific projection matrices in
+   * bci-embedder.bin.
+   *
+   *   - `day_idx >= 0` (default `0`): apply the day projection; values beyond
+   *     the available range are clamped at the native layer.
+   *   - `day_idx === -1`: mel passthrough — skip preprocessing and treat
+   *     the input buffer as pre-computed 512-bin mel features in
+   *     frame-major layout. Intended for parity testing against the Python
+   *     reference, not production use.
+   */
+  day_idx?: number
+}
+
+declare interface WhisperConfig {
+  language?: string
+  n_threads?: number
+  temperature?: number
+  suppress_nst?: boolean
+  suppress_blank?: boolean
+  duration_ms?: number
+  translate?: boolean
+  no_timestamps?: boolean
+  single_segment?: boolean
+  print_special?: boolean
+  print_progress?: boolean
+  print_realtime?: boolean
+  print_timestamps?: boolean
+  detect_language?: boolean
+  greedy_best_of?: number
+  beam_search_beam_size?: number
+}
+
+declare interface BCIWhispercppFiles {
+  /** Absolute path to the BCI GGML model file. */
+  model: string
+}
+
+declare interface BCIWhispercppArgs {
+  files: BCIWhispercppFiles
+  logger?: LoggerInterface
+  opts?: {
+    stats?: boolean
+  }
+}
+
+declare interface BCIWhispercppConfig {
+  whisperConfig?: WhisperConfig
+  bciConfig?: BCIConfig
+  contextParams?: {
+    model?: string
+    use_gpu?: boolean
+    flash_attn?: boolean
+    gpu_device?: number
+  }
+  miscConfig?: {
+    caption_enabled?: boolean
+  }
+}
+
+declare interface TranscriptSegment {
+  text: string
+  toAppend: boolean
+  start: number
+  end: number
+  id: number
+}
+
+declare interface BCIWhispercppState {
+  configLoaded: boolean
+  destroyed: boolean
+}
+
+/**
+ * BCI neural signal transcription client powered by whisper.cpp.
+ *
+ * Uses `createJobHandler` + `exclusiveRunQueue` from `@qvac/infer-base` and
+ * follows the same lifecycle contract as `TranscriptionWhispercpp` /
+ * `LlmLlamacpp`: construct with local file paths, call `load()`, issue
+ * `transcribe()` / `transcribeFile()` calls, then `destroy()`.
+ */
+declare class BCIWhispercpp {
+  constructor(args: BCIWhispercppArgs, config?: BCIWhispercppConfig)
+
+  /** Load and activate the model. Must be awaited before `transcribe()`. */
+  load(): Promise<void>
+
+  /** Transcribe a neural signal binary file (convenience wrapper). */
+  transcribeFile(filePath: string): Promise<QvacResponse>
+
+  /** Transcribe a neural signal buffer (batch mode). */
+  transcribe(neuralData: Uint8Array): Promise<QvacResponse>
+
+  /** Cancel the in-flight inference, if any. */
+  cancel(): Promise<void>
+
+  /** Unload the model and release native resources. Instance is reusable. */
+  unload(): Promise<void>
+
+  /**
+   * Destroy the instance, unload, and mark as permanently destroyed.
+   * Subsequent `load()` calls will throw `MODEL_NOT_LOADED`.
+   */
+  destroy(): Promise<void>
+
+  /** Current lifecycle state. */
+  getState(): BCIWhispercppState
+}
+
+declare namespace BCIWhispercpp {
+  /**
+   * Compute Word Error Rate between hypothesis and reference strings.
+   * @returns WER as a ratio (0.0 = perfect).
+   */
+  function computeWER(hypothesis: string, reference: string): number
+
+  export {
+    BCIWhispercpp as default,
+    BCIWhispercpp,
+    BCIConfig,
+    WhisperConfig,
+    BCIWhispercppFiles,
+    BCIWhispercppArgs,
+    BCIWhispercppConfig,
+    BCIWhispercppState,
+    TranscriptSegment
+  }
+}
+
+export = BCIWhispercpp