4.5 KiB

Raw Blame History

whisper.cpp Node.js addon

This is an addon demo that can perform whisper model reasoning in node and electron environments, based on cmake-js. It can be used as a reference for using the whisper.cpp project in other node projects.

This addon now supports Voice Activity Detection (VAD) for improved transcription performance.

Install

npm install

Compile

Make sure it is in the project root directory and compiled with make-js.

npx cmake-js compile -T addon.node -B Release

For Electron addon and cmake-js options, you can see cmake-js and make very few configuration changes.

Such as appointing special cmake path:
npx cmake-js compile -c 'xxx/cmake' -T addon.node -B Release

Run

Basic Usage

cd examples/addon.node

node index.js --language='language' --model='model-path' --fname_inp='file-path'

VAD (Voice Activity Detection) Usage

Run the VAD example with performance comparison:

node vad-example.js

Cancellation Usage

Run the cancellation example (cancels an in-flight transcription via AbortSignal):

node cancel-example.js

Cancelling a transcription

An in-flight transcription can be cancelled by passing an AbortSignal as the signal parameter:

const ac = new AbortController();

const promise = whisperAsync({
  // ... other params ...
  signal: ac.signal,
});

// cancel at any time
ac.abort();

const result = await promise;
// result.cancelled === true
// result.transcription contains the segments transcribed before cancellation

Cancellation is checked before each encoder run and before each ggml graph computation, so it usually takes effect within a fraction of a second. The promise resolves normally (it does not reject): result.cancelled is true and result.transcription contains the segments completed before the abort.

Voice Activity Detection (VAD) Support

VAD can significantly improve transcription performance by only processing speech segments, which is especially beneficial for audio files with long periods of silence.

VAD Model Setup

Before using VAD, download a VAD model:

# From the whisper.cpp root directory
./models/download-vad-model.sh silero-v6.2.0

VAD Parameters

All VAD parameters are optional and have sensible defaults:

vad: Enable VAD (default: false)
vad_model: Path to VAD model file (required when VAD enabled)
vad_threshold: Speech detection threshold 0.0-1.0 (default: 0.5)
vad_min_speech_duration_ms: Min speech duration in ms (default: 250)
vad_min_silence_duration_ms: Min silence duration in ms (default: 100)
vad_max_speech_duration_s: Max speech duration in seconds (default: FLT_MAX)
vad_speech_pad_ms: Speech padding in ms (default: 30)
vad_samples_overlap: Sample overlap 0.0-1.0 (default: 0.1)

JavaScript API Example

const path = require("path");
const { whisper } = require(path.join(__dirname, "../../build/Release/addon.node"));
const { promisify } = require("util");

const whisperAsync = promisify(whisper);

// With VAD enabled
const vadParams = {
  language: "en",
  model: path.join(__dirname, "../../models/ggml-base.en.bin"),
  fname_inp: path.join(__dirname, "../../samples/jfk.wav"),
  vad: true,
  vad_model: path.join(__dirname, "../../models/ggml-silero-v6.2.0.bin"),
  vad_threshold: 0.5,
  progress_callback: (progress) => console.log(`Progress: ${progress}%`)
};

whisperAsync(vadParams).then(result => console.log(result));

Supported Parameters

Both traditional whisper.cpp parameters and new VAD parameters are supported:

language: Language code (e.g., "en", "es", "fr")
model: Path to whisper model file
fname_inp: Path to input audio file
use_gpu: Enable GPU acceleration (default: true)
flash_attn: Enable flash attention (default: false)
no_prints: Disable console output (default: false)
no_timestamps: Disable timestamps (default: false)
detect_language: Auto-detect language (default: false)
audio_ctx: Audio context size (default: 0)
max_len: Maximum segment length (default: 0)
max_context: Maximum context size (default: -1)
prompt: Initial prompt for decoder
comma_in_time: Use comma in timestamps (default: true)
print_progress: Print progress info (default: false)
progress_callback: Progress callback function
signal: AbortSignal used to cancel the transcription (see above section)
VAD parameters (see above section)

4.5 KiB Raw Blame History