nwhisper
Version:
Native Node.js bindings for OpenAI's Whisper using whisper.cpp. High-performance local speech-to-text with custom model support.
312 lines (241 loc) • 8.11 kB
Markdown
# nwhisper
Native Node.js bindings for OpenAI's Whisper using whisper.cpp. High-performance local speech-to-text with custom model path support.
[](https://choosealicense.com/licenses/mit/)
## Features
- **Custom Model Path Support**: Use your own trained models by providing a custom model file path
- Automatically convert the audio to WAV format with a 16000 Hz frequency to support the whisper model.
- Output transcripts to (.txt .srt .vtt .json .wts .lrc)
- Optimized for CPU (Including Apple Silicon ARM)
- Timestamp precision to single word
- Split on word rather than on token (Optional)
- Translate from source language to english (Optional)
- Convert audio format to wav to support whisper model
- Backward compatible with nodejs-whisper
## Installation
1. Install make tools
```bash
sudo apt update
sudo apt install build-essential
```
2. Install nwhisper with npm
```bash
npm i nwhisper
```
3. Download whisper model (for standard models)
```bash
npx nwhisper download
```
- NOTE: user may need to install make tool
### Windows Installation
1. Install MinGW-w64 or MSYS2 (which includes make tools)
- Option 1: Install MSYS2 from https://www.msys2.org/
- Option 2: Install MinGW-w64 from https://www.mingw-w64.org/
2. Install nwhisper with npm
```bash
npm i nwhisper
```
3. Download whisper model (for standard models)
```bash
npx nwhisper download
```
- Note: Make sure mingw32-make or make is available in your system PATH.
## Usage/Examples
See `example/basic.ts` (can be run with `$ npm run example`)
```javascript
import path from 'path'
import { transcribe } from 'nwhisper'
// Need to provide exact path to your audio file.
const filePath = path.resolve(__dirname, 'YourAudioFileName')
// Using standard model
await transcribe(filePath, {
modelName: 'base.en', //Downloaded models name
autoDownloadModelName: 'base.en', // (optional) auto download a model if model is not present
removeWavFileAfterTranscription: false, // (optional) remove wav file once transcribed
withCuda: false, // (optional) use cuda for faster processing
logger: console, // (optional) Logging instance, defaults to console
whisperOptions: {
outputInCsv: false, // get output result in csv file
outputInJson: false, // get output result in json file
outputInJsonFull: false, // get output result in json file including more information
outputInLrc: false, // get output result in lrc file
outputInSrt: true, // get output result in srt file
outputInText: false, // get output result in txt file
outputInVtt: false, // get output result in vtt file
outputInWords: false, // get output result in wts file for karaoke
translateToEnglish: false, // translate from source language to english
wordTimestamps: false, // word-level timestamps
timestamps_length: 20, // amount of dialogue per timestamp pair
splitOnWord: true, // split on word rather than on token
},
})
// Using custom models (NEW FEATURES)
// Method 1: Specify model directory
const modelDir = path.join(process.cwd(), '.models')
await transcribe(filePath, {
modelName: 'tiny.en',
modelDir: modelDir,
whisperOptions: {
outputInSrt: true,
},
})
// Method 2: Direct file path
const modelPath = path.join(__dirname, 'models', 'my-custom-model.bin')
await transcribe(filePath, {
modelPath: modelPath,
whisperOptions: {
outputInSrt: true,
language: 'en',
},
})
// Method 3: Download to and use custom directory
await transcribe(filePath, {
modelName: 'tiny.en',
autoDownloadModelName: 'tiny.en',
modelDir: path.join(__dirname, 'models'), // Download to and use this directory
whisperOptions: {
outputInSrt: true,
},
})
// Model list
const MODELS_LIST = [
'tiny',
'tiny.en',
'base',
'base.en',
'small',
'small.en',
'medium',
'medium.en',
'large-v1',
'large',
'large-v3-turbo',
]
```
## Types
```
interface IOptions {
modelName?: string // Model name (works with directories)
modelPath?: string // NEW: Direct path to model file
modelDir?: string // NEW: Directory for models (download & use)
autoDownloadModelName?: string // Model to auto-download
removeWavFileAfterTranscription?: boolean
withCuda?: boolean
whisperOptions?: WhisperOptions
logger?: Console
}
interface WhisperOptions {
outputInCsv?: boolean
outputInJson?: boolean
outputInJsonFull?: boolean
outputInLrc?: boolean
outputInSrt?: boolean
outputInText?: boolean
outputInVtt?: boolean
outputInWords?: boolean
translateToEnglish?: boolean
timestamps_length?: number
wordTimestamps?: boolean
splitOnWord?: boolean
}
```
## Custom Model Path Usage
The main feature of nwhisper is the ability to use custom model files. This is useful when you have:
- Fine-tuned models for specific domains
- Custom trained models
- Models in different locations than the default
### Example with Custom Model
```javascript
import { transcribe } from 'nwhisper'
import path from 'path'
// Method 1: Specify model directory
const modelDir = path.join(process.cwd(), '.models')
const result = await transcribe('audio.wav', {
modelName: 'tiny.en',
modelDir: modelDir,
whisperOptions: {
outputInSrt: true,
language: 'en'
}
})
// Method 2: Direct file path
const modelPath = path.join(__dirname, 'models', 'my-custom-model.bin')
const result2 = await transcribe('audio.wav', {
modelPath: modelPath,
whisperOptions: {
outputInSrt: true,
language: 'auto'
}
})
// Method 3: Download to and use custom directory
const result3 = await transcribe('audio.wav', {
modelName: 'tiny.en',
autoDownloadModelName: 'tiny.en',
modelDir: modelDir, // Download to and use this directory
whisperOptions: {
outputInSrt: true,
language: 'auto'
}
})
```
### Model Priority
1. **modelPath** - Direct file path (highest priority)
2. **modelDir + modelName** - Model directory with model name
3. **Standard directory** - Default whisper.cpp models (fallback)
### Important Notes
- `modelDir` serves dual purpose: download location and model location
- When `modelDir` is specified, models are downloaded to and used from that directory
- Model files should follow whisper.cpp naming (e.g., `ggml-tiny.en.bin`)
- Models must be compatible with whisper.cpp format
## Migration from nodejs-whisper
nwhisper is fully backward compatible with nodejs-whisper. Simply replace the package:
```bash
# Remove old package
npm uninstall nodejs-whisper
# Install nwhisper
npm install nwhisper
```
### Function Names
- **Recommended**: Use `transcribe` function for new code
- **Legacy**: `nodewhisper` function is still available but deprecated
```javascript
// New (recommended)
import { transcribe } from 'nwhisper'
await transcribe('audio.wav', { modelName: 'tiny.en' })
// Legacy (deprecated but still works)
import { nodewhisper } from 'nwhisper'
await nodewhisper('audio.wav', { modelName: 'tiny.en' })
```
No code changes required for existing functionality!
## Run locally
Clone the project
```bash
git clone https://github.com/teomyth/nwhisper
```
Go to the project directory
```bash
cd nwhisper
```
Install dependencies
```bash
npm install
```
Start the server
```bash
npm run dev
```
Build project
```bash
npm run build
```
## Made with
- [Whisper OpenAI (using C++ port by: ggerganov)](https://github.com/ggerganov/whisper.cpp)
## Feedback
If you have any feedback, please reach out to us at teomyth.com
## Authors
- [](https://www.github.com/teomyth) - Current maintainer
## Acknowledgments
This project is a fork of [nodejs-whisper](https://github.com/ChetanXpro/nodejs-whisper) by [@chetanXpro](https://www.github.com/chetanXpro). We extend our gratitude to the original author for creating the foundation that made nwhisper possible.
### Original Project
- **Original Author**: [](https://www.github.com/chetanXpro)
- **Original Repository**: [nodejs-whisper](https://github.com/ChetanXpro/nodejs-whisper)
- **License**: MIT