npm package: @lumiastream/wakeword
Description: A wake word detection library using Vosk and SoX for real-time voice recognition.
Latest version: 1.2.1

# LumiaWakeWord

A wake word detection library using Vosk and SoX for real-time voice recognition.

## Features
- Real-time wake word detection
- Multi-platform support (Windows, macOS, Linux)
- Audio device selection (especially useful for Windows)
- Confidence threshold filtering
- Dynamic grammar updates

## Installation

```bash
npm install @lumiastream/wakeword
```

## Quick Start

```javascript
import { startWakeWord, listAudioDevices } from "@lumiastream/wakeword";

// List available audio devices
const devices = await listAudioDevices();
console.log("Available devices:", devices);

// Start wake word detection
const wakeWord = startWakeWord({
  grammar: ["hello", "lumia", "computer"],
  confidence: 0.7,
  device: "0" // Optional: specify audio device
});

// Handle detections
wakeWord.stdout.on("data", (data) => {
  const lines = data.toString().split("\n");
  for (const line of lines) {
    if (line.startsWith("voice|")) {
      const word = line.split("|")[1];
      console.log(`Wake word detected: ${word}`);
    }
  }
});
```

## Audio Device Selection

### Windows Users
Windows users often need to select the correct audio input device. Use these commands to find and test devices:

```bash
# List all available audio devices
npm run list-devices

# Interactive device testing
npm run test-devices

# Use a specific device
AUDIO_DEVICE=1 npm start
```

### Setting the Audio Device

**Method 1: Environment Variable**
```bash
set AUDIO_DEVICE=1
npm start
```

**Method 2: Programmatically**
```javascript
startWakeWord({
  device: "1",
  grammar: ["hello", "lumia"]
});
```

See [AUDIO_DEVICES.md](AUDIO_DEVICES.md) for detailed device configuration guide.

## API Reference

### `listAudioDevices()`
Returns a Promise that resolves to an array of available audio devices.

```javascript
const devices = await listAudioDevices();
// Returns: [{ id: "0", name: "Microphone (Realtek)" }, ...]
```

### `startWakeWord(options)`
Starts the wake word detection process.

**Options:**
- `device` (string): Audio device ID to use
- `soxPath` (string): Path to SoX binary (optional)
- `sampleRate` (number): Sample rate, default 16000
- `grammar` (string[]): Array of wake words to detect
- `confidence` (number): Confidence threshold (0-1), default 0.7
- `modelPath` (string): Full path to a Vosk model directory (optional)

**Returns:** ChildProcess instance

## Scripts

```bash
npm run list-devices    # List available audio devices
npm run test-devices    # Interactive device testing
npm start              # Start wake word detection
```

## Example

Run the included example:
```bash
node example.js
```

## Dependencies

- [Vosk](https://alphacephei.com/vosk/) - Speech recognition toolkit
- [SoX](http://sox.sourceforge.net/) - Sound processing tool
- Vosk model included: vosk-model-small-en-us-0.15

## Platform Notes

### Windows
- Default uses device "0" if not specified
- Use `npm run test-devices` to find the correct device
- USB microphones may appear as separate devices

### macOS/Linux
- Uses system default audio input automatically
- Device selection usually not needed

## Troubleshooting

1. **No audio detected on Windows:**
   - Run `npm run test-devices` to find the correct device
   - Set `AUDIO_DEVICE` environment variable

2. **Poor recognition quality:**
   - Adjust confidence threshold (lower = more sensitive)
   - Try different audio devices
   - Ensure microphone is not muted

3. **Device not found:**
   - Ensure microphone is connected before starting
   - Check system audio settings

## SoX Binaries

Pre-compiled SoX binaries are included for all platforms.
Source: https://github.com/zackees/static-sox/tree/main/bin

## License

See LICENSE file for details.