whisper-node

To use whisper-node in your project, install the package via npm.

Windows Requirement: You must install the make command (e.g., from GNUWin32) to ensure successful compilation/operation.

Optional: Download Models You can pre-download a Whisper model using the provided CLI command:

npx whisper-node download

npm install whisper-node

The primary way to use the library is by calling the whisper function with a file path. By default, it returns an array of objects containing timestamps and the transcribed text.

Input Requirements:

• Files must be in .wav format.
• Audio must be sampled at 16Hz (16000Hz).

If you have an .mp3, you can convert it using FFmpeg:

ffmpeg -i input.mp3 -ar 16000 output.wav

import whisper from 'whisper-node';

const transcript = await whisper("example/sample.wav");

console.log(transcript); // output: [ {start,end,speech} ]

When calling whisper(), you can provide an IOptions object to customize the transcription process.

Available keys:

• modelName (string, optional): The name of the model stored within the package's internal directory (node_modules/whisper-node/lib/whisper.cpp/models).
• modelPath (string, optional): A custom filesystem path to a specific model file.
• whisperOptions (IFlagTypes, optional): A set of flags passed directly to the underlying whisper.cpp command.
• shellOptions (IShellOptions, optional): Configuration for the shell execution environment.

interface IOptions {
  modelName?: string,
  modelPath?: string,
  whisperOptions?: IFlagTypes,
  shellOptions?: IShellOptions
}

The whisper function returns a Promise that resolves to an array of objects. Each object represents a segment of speech with the following structure:

• start: A string representing the start timestamp (e.g., "00:00:14.310").
• end: A string representing the end timestamp (e.g., "00:00:16.480").
• speech: The transcribed text string.

[
  {
    "start":  "00:00:14.310",
    "end":    "00:00:16.480",
    "speech": "howdy"
  }
]

The createCppCommand function generates a shell command string compatible with whisper.cpp. It requires a filePath (the audio file to transcribe) and allows you to specify a model via modelName or modelPath, along with various transcription options.

Constraints:

• You must provide either modelName or modelPath. Providing both will throw an error.
• If no model is provided, the library attempts to use the DEFAULT_MODEL.
• If using a modelName, the model must be present in the ./models/ directory (otherwise, you must run npx whisper-node download).

const command = createCppCommand({
  filePath: './audio.wav',
  modelName: 'base',
  options: {
    language: 'en',
    gen_file_txt: true
  }
});
// Resulting string example: `./main -l en -otxt -m ./models/ggml-base.bin -f ./audio.wav`

The whisper function is the primary entrypoint for transcribing audio files using the whisper.cpp engine. It accepts a file path to the audio and an optional configuration object. The function returns a Promise that resolves to an array of ITranscriptLine objects, where each object contains the start time, end time, and the transcribed speech text.

Returns: Promise<ITranscriptLine[]> where ITranscriptLine is {start, end, speech}.

import { whisper } from 'whisper-node';

const transcript = await whisper('path/to/audio.mp3', {
  modelName: 'base',
  whisperOptions: {
    // ... whisper.cpp flags
  }
});

console.log(transcript); // [{ start: 0, end: 2, speech: 'Hello world' }, ...]

The parseTranscript function converts a VTT-formatted transcript string into an array of ITranscriptLine objects. It expects lines in the format [start_timestamp --> end_timestamp] speech_content.

Note that the parser relies on a specific delimiter: a timestamp enclosed in brackets followed by exactly two spaces (] ) before the speech content. It also strips newlines and leading spaces from the speech text.

import parseTranscript from './src/tsToArray';

const vttContent = "[00:00:01.000 --> 00:00:04.000]  Hello world\n";
const transcript = parseTranscript(vttContent);
// Result: [{ start: '00:00:01.000', end: '00:00:04.000', speech: 'Hello world' }]

The ITranscriptLine type defines the shape of an individual segment in a parsed transcript. Each object contains the timing information and the transcribed text.

type ITranscriptLine = {
  start: string;
  end: string;
  speech: string;
}