Support per-stream hotwords in the JavaScript (node-addon) API for non-streaming ASR (#3723)

Author: cmurrayis

.github/scripts/test-nodejs-addon-npm.sh

@@ -170,6 +170,7 @@ tar xvf sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8.tar.bz2
 rm sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8.tar.bz2
 
 node ./test_asr_non_streaming_nemo_parakeet_tdt_v2.js
+node ./test_asr_non_streaming_nemo_parakeet_tdt_v2_hotwords.js
 rm -rf sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8
 
 echo "----------non-streaming ASR dolphin CTC----------"

harmony-os/SherpaOnnxHar/sherpa_onnx/src/main/cpp/non-streaming-asr.cc

@@ -649,9 +649,9 @@ Napi::Value CreateOfflineRecognizerAsyncWrapper(
 static Napi::External<SherpaOnnxOfflineStream> CreateOfflineStreamWrapper(
     const Napi::CallbackInfo &info) {
   Napi::Env env = info.Env();
-  if (info.Length() != 1) {
+  if (info.Length() != 1 && info.Length() != 2) {
     std::ostringstream os;
-    os << "Expect only 1 argument. Given: " << info.Length();
+    os << "Expect only 1 or 2 arguments. Given: " << info.Length();
 
     Napi::TypeError::New(env, os.str()).ThrowAsJavaScriptException();
 
@@ -661,7 +661,7 @@ static Napi::External<SherpaOnnxOfflineStream> CreateOfflineStreamWrapper(
   if (!info[0].IsExternal()) {
     Napi::TypeError::New(
         env,
-        "You should pass an offline recognizer pointer as the only argument")
+        "You should pass an offline recognizer pointer as the first argument")
         .ThrowAsJavaScriptException();
 
     return {};
@@ -670,8 +670,32 @@ static Napi::External<SherpaOnnxOfflineStream> CreateOfflineStreamWrapper(
   const SherpaOnnxOfflineRecognizer *recognizer =
       info[0].As<Napi::External<SherpaOnnxOfflineRecognizer>>().Data();
 
-  const SherpaOnnxOfflineStream *stream =
-      SherpaOnnxCreateOfflineStream(recognizer);
+  const SherpaOnnxOfflineStream *stream = nullptr;
+  if (info.Length() == 2) {
+    // Optional per-stream hotwords for contextual biasing. Note that only
+    // transducer models decoded with modified_beam_search support hotwords.
+    if (!info[1].IsString()) {
+      Napi::TypeError::New(env, "Argument 2 should be a string.")
+          .ThrowAsJavaScriptException();
+
+      return {};
+    }
+
+    std::string hotwords = info[1].As<Napi::String>().Utf8Value();
+    stream =
+        SherpaOnnxCreateOfflineStreamWithHotwords(recognizer, hotwords.c_str());
+  } else {
+    stream = SherpaOnnxCreateOfflineStream(recognizer);
+  }
+
+  if (!stream) {
+    Napi::TypeError::New(env,
+                         "Failed to create offline stream. Please check if "
+                         "your model and decoding method support hotwords.")
+        .ThrowAsJavaScriptException();
+
+    return {};
+  }
 
   return Napi::External<SherpaOnnxOfflineStream>::New(
       env, const_cast<SherpaOnnxOfflineStream *>(stream),

nodejs-addon-examples/README.md

@@ -146,6 +146,7 @@ The following tables list the examples in this folder.
 |[./test_asr_non_streaming_nemo_canary.js](./test_asr_non_streaming_nemo_canary.js)|Non-streaming speech recognition from a file using a [NeMo](https://github.com/NVIDIA/NeMo) [Canary](https://k2-fsa.github.io/sherpa/onnx/nemo/canary.html#sherpa-onnx-nemo-canary-180m-flash-en-es-de-fr-int8-english-spanish-german-french) model|
 |[./test_asr_non_streaming_zipformer_ctc.js](./test_asr_non_streaming_zipformer_ctc.js)|Non-streaming speech recognition from a file using a Zipformer CTC model with greedy search|
 |[./test_asr_non_streaming_nemo_parakeet_tdt_v2.js](./test_asr_non_streaming_nemo_parakeet_tdt_v2.js)|Non-streaming speech recognition from a file using a [NeMo](https://github.com/NVIDIA/NeMo) [parakeet-tdt-0.6b-v2](https://k2-fsa.github.io/sherpa/onnx/pretrained_models/offline-transducer/nemo-transducer-models.html#sherpa-onnx-nemo-parakeet-tdt-0-6b-v2-int8-english) model with greedy search|
+|[./test_asr_non_streaming_nemo_parakeet_tdt_v2_hotwords.js](./test_asr_non_streaming_nemo_parakeet_tdt_v2_hotwords.js)|Non-streaming speech recognition from a file using a [NeMo](https://github.com/NVIDIA/NeMo) [parakeet-tdt-0.6b-v2](https://k2-fsa.github.io/sherpa/onnx/pretrained_models/offline-transducer/nemo-transducer-models.html#sherpa-onnx-nemo-parakeet-tdt-0-6b-v2-int8-english) model with modified_beam_search and per-stream [hotwords](https://k2-fsa.github.io/sherpa/onnx/hotwords/index.html)|
 |[./test_asr_non_streaming_dolphin_ctc.js](./test_asr_non_streaming_dolphin_ctc.js)|Non-streaming speech recognition from a file using a [Dolphinhttps://github.com/DataoceanAI/Dolphin]) CTC model with greedy search|
 |[./test_asr_non_streaming_paraformer.js](./test_asr_non_streaming_paraformer.js)|Non-streaming speech recognition from a file using [Paraformer](https://github.com/alibaba-damo-academy/FunASR)|
 |[./test_asr_non_streaming_paraformer_itn.js](./test_asr_non_streaming_paraformer_itn.js)|Non-streaming speech recognition from a file using [Paraformer](https://github.com/alibaba-damo-academy/FunASR) with ITN|
@@ -443,6 +444,9 @@ tar xvf sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8.tar.bz2
 rm sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8.tar.bz2
 
 node ./test_asr_non_streaming_nemo_parakeet_tdt_v2.js
+
+# Per-stream hotwords (contextual biasing) with modified_beam_search
+node ./test_asr_non_streaming_nemo_parakeet_tdt_v2_hotwords.js
 ```
 
 ### Non-streaming speech recognition with Zipformer CTC models

nodejs-addon-examples/test_asr_non_streaming_nemo_parakeet_tdt_v2_hotwords.js

@@ -0,0 +1,75 @@
+// Copyright (c)  2026  Xiaomi Corporation
+const fs = require('fs');
+const sherpa_onnx = require('sherpa-onnx-node');
+
+// This example shows how to use per-stream hotwords (contextual biasing)
+// with a NeMo transducer model. Hotwords require
+// decodingMethod 'modified_beam_search'.
+//
+// The test wave contains the name "Phoebe", which the model transcribes
+// with the spelling "Phebe" by default. Passing the hotword "Phoebe" to
+// createStream() biases this stream towards the expected spelling.
+//
+// Please download test files from
+// https://github.com/k2-fsa/sherpa-onnx/releases/tag/asr-models
+
+const modelDir = './sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8';
+
+// To pass hotwords as normal words, the model config needs a bpe vocab.
+// This model's release does not ship bpe.vocab, but an equivalent one for
+// hotword encoding can be derived from tokens.txt (equal scores make the
+// encoder behave as longest-match).
+const bpeVocab = `${modelDir}/bpe.vocab`;
+if (!fs.existsSync(bpeVocab)) {
+  const tokens = fs.readFileSync(`${modelDir}/tokens.txt`, 'utf8');
+  const vocab = tokens.split('\n')
+                    .filter(line => line.trim() !== '')
+                    .map(line => `${line.split(' ')[0]}\t-1.0`)
+                    .join('\n');
+  fs.writeFileSync(bpeVocab, vocab + '\n');
+}
+
+const config = {
+  'featConfig': {
+    'sampleRate': 16000,
+    'featureDim': 80,
+  },
+  'modelConfig': {
+    'transducer': {
+      'encoder':
+          './sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8/encoder.int8.onnx',
+      'decoder':
+          './sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8/decoder.int8.onnx',
+      'joiner': './sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8/joiner.int8.onnx',
+    },
+    'tokens': './sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8/tokens.txt',
+    'numThreads': 2,
+    'provider': 'cpu',
+    'debug': 1,
+    'modelType': 'nemo_transducer',
+    'modelingUnit': 'bpe',
+    'bpeVocab': bpeVocab,
+  },
+  'decodingMethod': 'modified_beam_search',
+  'hotwordsScore': 2.0,
+};
+
+const waveFilename =
+    './sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8/test_wavs/0.wav';
+
+const recognizer = new sherpa_onnx.OfflineRecognizer(config);
+console.log('Started');
+const wave = sherpa_onnx.readWave(waveFilename);
+
+function decode(hotwords) {
+  const stream = recognizer.createStream(hotwords);
+  stream.acceptWaveform({sampleRate: wave.sampleRate, samples: wave.samples});
+  recognizer.decode(stream);
+  return recognizer.getResult(stream).text;
+}
+
+console.log('Without hotwords:', decode());
+
+// Multiple phrases are separated by '/'; a per-phrase boosting score can be
+// appended, e.g. 'PHOEBE :3.0/DON QUIXOTE'.
+console.log('With hotwords   :', decode('Phoebe'));

scripts/node-addon-api/lib/non-streaming-asr.js

@@ -92,10 +92,24 @@ class OfflineRecognizer {
 
   /**
    * Create a new OfflineStream bound to this recognizer.
+   *
+   * The optional hotwords argument enables contextual biasing for this
+   * stream only. Hotwords are supported only by transducer models decoded
+   * with decodingMethod 'modified_beam_search'. Separate multiple phrases
+   * with '/', and optionally append a per-phrase boosting score, e.g.
+   * 'PHOEBE :2.0/DON QUIXOTE'. When modelConfig.modelingUnit and
+   * modelConfig.bpeVocab are set, phrases are given as normal words;
+   * otherwise each phrase must be a sequence of tokens from tokens.txt
+   * separated by spaces. See also
+   * https://k2-fsa.github.io/sherpa/onnx/hotwords/index.html
+   *
+   * @param {string} [hotwords] Optional hotwords for this stream.
    * @returns {OfflineStream}
    */
-  createStream() {
-    const handle = addon.createOfflineStream(this.handle);
+  createStream(hotwords) {
+    const handle = hotwords === undefined ?
+        addon.createOfflineStream(this.handle) :
+        addon.createOfflineStream(this.handle, hotwords);
     return new OfflineStream(handle);
   }