Skip to main content
Hotwords (also known as contextual biasing) allow you to boost recognition accuracy for specific words or phrases. This is useful for domain-specific vocabulary, proper nouns, or technical terms.
Model Type RequirementHotwords are only supported by Transducer and NeMo Transducer models (transducer, nemo_transducer). All other model types (Whisper, Paraformer, Sense Voice, etc.) do not support hotwords.

​
Checking Hotword Support

Use sttSupportsHotwords(modelType) to check if a model type supports hotwords: 
import { sttSupportsHotwords } from 'react-native-sherpa-onnx/stt';

if (sttSupportsHotwords('transducer')) {
  // Show hotword options in UI
}
The function returns true only for 'transducer' and 'nemo_transducer'.

​
Error Codes

CodeWhen
HOTWORDS_NOT_SUPPORTEDcreateSTT is called with a non-empty hotwordsFile and the model type is not transducer or nemo_transducer
INVALID_HOTWORDS_FILEHotwords file is missing, not readable, invalid UTF-8, contains null bytes, has no valid lines, or has invalid score format

​
Automatic Decoding Method Switch

When you provide a non-empty hotwords file, the SDK automatically sets the decoding method to modified_beam_search (and ensures maxActivePaths is at least 4), because sherpa-onnx only applies hotwords with that method.
You do not need to set decodingMethod manually. The init result includes decodingMethod so you can confirm which method was applied.

​
Hotword File Format

For transducer and nemo_transducer models:
  • One word or phrase per line
  • UTF-8 text; no null bytes
  • Optional score per line: word_or_phrase :1.5 (space, colon, then a single number)
  • Each non-empty line must contain at least one letter character (lines with only digits, punctuation, or symbols are rejected)

​
Example Hotword File

SHERPA ONNX :2.0
REACT NATIVE :1.8
TURBOMODULE :1.5
qualcomm
apple neural engine
The SDK validates the file when you pass a path: it must exist, be readable, and satisfy the rules above. Invalid files cause rejection with INVALID_HOTWORDS_FILE.

​
Modeling Unit and BPE Vocab

Only relevant when using hotwords. Pass modelingUnit (and if needed bpeVocab) so hotwords are tokenized correctly.
​
modelingUnit
string
Set when using hotwords: 'cjkchar' | 'bpe' | 'cjkchar+bpe'Must match the model’s training unit. See the table below.
​
bpeVocab
string
Only needed when modelingUnit is 'bpe' or 'cjkchar+bpe'Path to the BPE vocabulary file (sentencepiece bpe.vocab). For 'cjkchar' you do not need bpeVocab.
If the model directory contains bpe.vocab, it is detected automatically and used when bpeVocab is not provided (for bpe / cjkchar+bpe).

​
When to Use Which Modeling Unit

The value depends on how the model was trained, not on the app. You find it in the model’s documentation (e.g. k2-fsa releases, Hugging Face card).

BPE

Use for: English (or similar) transducer modelsExamples: “zipformer-en”, “icefall … en”, LibriSpeech modelsFiles: Model often has bpe.model or bpe.vocab in the folderHotwords file: One word/phrase per line (e.g. SPEECH RECOGNITION)

CJKChar

Use for: Chinese character-based transducer modelsExamples: “conformer-zh”, “wenetspeech”, “multi-dataset zh” modelsFiles: No BPE; tokens are charactersHotwords file: Chinese words per line (e.g. 语音识别)

CJKChar+BPE

Use for: Bilingual Chinese + English transducer modelsExamples: “bilingual-zh-en”, “streaming zipformer bilingual”Files: Model often has bpe.vocabHotwords file: Can mix Chinese and English (e.g. 礼拜二, FOREVER)
If you’re unsure: check the model’s repo or README for “modeling unit”, “tokenizer”, or “BPE”. If the folder contains bpe.vocab (or bpe.model), the model is usually bpe or cjkchar+bpe.

​
Usage Example

import { createSTT } from 'react-native-sherpa-onnx/stt';
import { DocumentDirectoryPath } from '@dr.pogodin/react-native-fs';

// Create hotwords file
const hotwordsPath = `${DocumentDirectoryPath}/hotwords.txt`;
await RNFS.writeFile(
  hotwordsPath,
  'SHERPA ONNX :2.0\nREACT NATIVE :1.8\nTURBOMODULE :1.5',
  'utf8'
);

// Initialize STT with hotwords
const stt = await createSTT({
  modelPath: { type: 'asset', path: 'models/zipformer-en' },
  modelType: 'transducer',
  hotwordsFile: hotwordsPath,
  hotwordsScore: 1.5, // Optional: default boost score
  modelingUnit: 'bpe',
  // bpeVocab will be auto-detected if bpe.vocab exists in model folder
});

// The decoding method is automatically set to 'modified_beam_search'
console.log(stt.config.decodingMethod); // 'modified_beam_search'

// Transcribe with hotword boosting
const result = await stt.transcribeFile('/path/to/audio.wav');
console.log(result.text);

// Clean up
await stt.destroy();

​
Validation Rules

The SDK validates the hotwords file when you initialize STT:
The path must point to an existing file that the app can read.
The file must be valid UTF-8 text without null bytes.
The file must contain at least one non-empty line with letter characters.
If a line includes a score (e.g. word :1.5), the part after : must be a valid number.
Each line must contain at least one letter character (lines with only digits, punctuation, or SRT timestamps are rejected).

​
See Also

STT API

Complete Speech-to-Text API reference

Supported Models

View all supported model types

Model Setup

Learn how to set up and manage models

Streaming STT

Real-time speech recognition

Build docs developers (and LLMs) love

Get started for freeTalk to us