voice-cmd

A robust, offline voice command utility for Node.js using Vosk.

Features

• 🔋 Offline: Fully offline speech recognition.
• 🚀 Zero Config: Auto-downloads default model on first run.
• 🎙️ Flexible: Select specific microphone devices.
• 🛠️ Type-Safe: Strict typescript support for models and commands.

Installation

npm install voice-cmd
# or
bun install voice-cmd

Usage

CLI

The CLI is the easiest way to use voice commands. It runs on Node.js automatically, even if installed with Bun.

# Listen using default model
npx voice-cmd listen
# or
bunx voice-cmd listen

Programmatic Usage

Basic (Zero Config)

The default behavior downloads a lightweight English model (small-en) if not present.

import { Voice } from 'voice-cmd';

const voice = new Voice();

// Register commands
voice.on("open *site", ({ site }) => {
    console.log(`Opening ${site}...`);
});

// Start listening (keeps process alive automatically)
await voice.start();

Note: If you are using Bun, please run your scripts using node or tsx (e.g., npx tsx myscript.ts) because the underlying speech engine (vosk) requires Node.js environment.

Select Microphone

// List valid devices
const devices = Voice.getDevices();
console.log(devices);

// Select using index
const voice = new Voice({
    deviceId: 2 // e.g. "Microphone (USB)"
});

Custom Models

You can choose a specific model size or provide a custom path.

Type-Safe Selection:

const voice = new Voice({
    modelName: 'big-en' // Downloads larger, more accurate model
});

Custom Path (Offline / Air-gapped):

const voice = new Voice({
    modelPath: '/path/to/my/model-directory'
});

Environment Variable: Setting VOICE_CMD_MODEL_PATH overrides all other configuration.

Development

If you are cloning this repo to contribute:

1. Install dependencies: npm install or bun install
2. Run example: npm run example
3. Build: npm run build