@lumiastream/wakeword 1.0.1 → 1.1.0

package/Readme.md

@@ -1,3 +1,156 @@
-Get Sox Binaries:
+# LumiaWakeWord
 
-// https://github.com/zackees/static-sox/tree/main/bin sox static binary
+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
+
+**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.

package/lib/index.js

@@ -0,0 +1,75 @@
+import { listAudioDevices } from "./list-devices.js";
+import { spawn } from "child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * List available audio input devices
+ * @returns {Promise<Array<{id: string, name: string}>>} Array of available devices
+ */
+export { listAudioDevices };
+
+/**
+ * Start the wake word detection with optional device selection
+ * @param {Object} options - Configuration options
+ * @param {string} [options.device] - Audio device ID to use
+ * @param {string} [options.soxPath] - Path to SoX binary
+ * @param {number} [options.sampleRate] - Sample rate (default: 16000)
+ * @param {Array<string>} [options.grammar] - Wake words to detect
+ * @param {number} [options.confidence] - Confidence threshold (0-1)
+ * @returns {ChildProcess} The spawned voice detection process
+ */
+export function startWakeWord(options = {}) {
+	const {
+		device = null,
+		soxPath = null,
+		sampleRate = 16000,
+		grammar = [],
+		confidence = 0.7,
+	} = options;
+
+	const voiceScript = join(here, "voice.js");
+	const args = [voiceScript];
+
+	if (soxPath) {
+		args.push(soxPath);
+	} else {
+		args.push(""); // placeholder for default sox path
+	}
+
+	if (device) {
+		args.push(device);
+	}
+
+	const env = { ...process.env };
+	if (sampleRate) {
+		env.SAMPLE_RATE = sampleRate.toString();
+	}
+	if (device && !args[2]) {
+		env.AUDIO_DEVICE = device;
+	}
+
+	const proc = spawn("node", args, {
+		env,
+		stdio: ["pipe", "pipe", "inherit"],
+	});
+
+	// Send initial grammar if provided
+	if (grammar.length > 0) {
+		proc.stdin.write(`update,${grammar.join(",")}\n`);
+	}
+
+	// Send confidence threshold if provided
+	if (confidence !== 0.7) {
+		proc.stdin.write(`confidence,${confidence}\n`);
+	}
+
+	return proc;
+}
+
+export default {
+	listAudioDevices,
+	startWakeWord,
+};

package/lib/list-devices.js

@@ -0,0 +1,128 @@
+import { spawn } from "child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+function unpacked(p) {
+	return p.includes("app.asar")
+		? p.replace("app.asar", "app.asar.unpacked")
+		: p;
+}
+
+const exeName = { win32: "sox.exe", darwin: "soxmac", linux: "soxlinux" }[
+	process.platform
+];
+
+let soxPath = process.argv[2] || join(here, "..", "binaries", exeName);
+soxPath = unpacked(soxPath);
+
+if (!existsSync(soxPath)) {
+	console.error(`SoX not found: ${soxPath}`);
+	process.exit(1);
+}
+
+export function listAudioDevices() {
+	return new Promise((resolve, reject) => {
+		if (process.platform !== "win32") {
+			// On macOS and Linux, SoX uses default device
+			resolve([{ id: "default", name: "Default Audio Input" }]);
+			return;
+		}
+
+		// Windows: Parse available devices from SoX help output
+		const proc = spawn(soxPath, ["-t", "waveaudio", "-h"], {
+			encoding: "utf8",
+			windowsHide: true,
+		});
+
+		let output = "";
+		let errorOutput = "";
+
+		proc.stdout?.on("data", (data) => {
+			output += data.toString();
+		});
+
+		proc.stderr?.on("data", (data) => {
+			errorOutput += data.toString();
+		});
+
+		proc.on("close", (code) => {
+			const devices = [];
+			
+			// Parse output for device list
+			const lines = (output + errorOutput).split("\n");
+			let inDeviceList = false;
+			
+			for (const line of lines) {
+				// Look for input device section
+				if (line.includes("Input:") || line.includes("input")) {
+					inDeviceList = true;
+					continue;
+				}
+				
+				// Stop at output section
+				if (line.includes("Output:") || line.includes("output")) {
+					inDeviceList = false;
+				}
+				
+				// Parse device entries (typically in format "0: Device Name")
+				if (inDeviceList) {
+					const match = line.match(/^\s*(\d+):\s*(.+)$/);
+					if (match) {
+						devices.push({
+							id: match[1],
+							name: match[2].trim(),
+						});
+					}
+				}
+			}
+
+			if (devices.length === 0) {
+				// Fallback: try to extract any numbered devices
+				const allMatches = (output + errorOutput).matchAll(/(\d+):\s*([^\n]+)/g);
+				for (const match of allMatches) {
+					const name = match[2].trim();
+					// Filter out obvious non-device entries
+					if (!name.includes("SoX") && !name.includes("Usage") && name.length > 0) {
+						devices.push({
+							id: match[1],
+							name: name,
+						});
+					}
+				}
+			}
+
+			// If still no devices found, provide default options
+			if (devices.length === 0) {
+				devices.push(
+					{ id: "0", name: "Device 0 (Default)" },
+					{ id: "1", name: "Device 1" },
+					{ id: "2", name: "Device 2" }
+				);
+			}
+
+			resolve(devices);
+		});
+
+		proc.on("error", (err) => {
+			reject(err);
+		});
+	});
+}
+
+// If run directly, list devices
+if (import.meta.url === `file://${process.argv[1]}`) {
+	listAudioDevices()
+		.then((devices) => {
+			console.log("Available audio input devices:");
+			devices.forEach((device) => {
+				console.log(`  ${device.id}: ${device.name}`);
+			});
+		})
+		.catch((err) => {
+			console.error("Error listing devices:", err);
+			process.exit(1);
+		});
+}

package/lib/test-devices.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+import { listAudioDevices } from "./list-devices.js";
+import { spawn } from "child_process";
+import readline from "node:readline";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+async function testDevice(deviceId) {
+	console.log(`\nTesting device ${deviceId}...`);
+	console.log("Speak into your microphone. Press Ctrl+C to stop.\n");
+
+	const voiceScript = join(here, "voice.js");
+	const proc = spawn("node", [voiceScript, undefined, deviceId], {
+		stdio: ["pipe", "inherit", "inherit"],
+	});
+
+	// Send test grammar
+	proc.stdin.write("update,hello,test,lumia\n");
+
+	return new Promise((resolve) => {
+		proc.on("close", () => {
+			resolve();
+		});
+
+		// Allow user to stop with Ctrl+C
+		process.on("SIGINT", () => {
+			proc.kill();
+			resolve();
+		});
+	});
+}
+
+async function main() {
+	console.log("LumiaWakeWord Audio Device Tester");
+	console.log("==================================\n");
+
+	try {
+		const devices = await listAudioDevices();
+
+		if (process.platform !== "win32") {
+			console.log("Note: On macOS/Linux, the default audio input is used automatically.");
+			console.log("Device selection is primarily for Windows users.\n");
+		}
+
+		console.log("Available audio input devices:");
+		devices.forEach((device) => {
+			console.log(`  ${device.id}: ${device.name}`);
+		});
+
+		if (process.platform === "win32") {
+			const rl = readline.createInterface({
+				input: process.stdin,
+				output: process.stdout,
+			});
+
+			const deviceId = await new Promise((resolve) => {
+				rl.question(
+					"\nEnter device ID to test (or press Enter for default): ",
+					(answer) => {
+						rl.close();
+						resolve(answer.trim() || "0");
+					}
+				);
+			});
+
+			await testDevice(deviceId);
+
+			console.log("\n\nTo use this device permanently, you can:");
+			console.log(`1. Set environment variable: AUDIO_DEVICE=${deviceId}`);
+			console.log(`2. Pass as 3rd argument when running voice.js`);
+			console.log(`3. Update your application to pass the device ID\n`);
+		} else {
+			console.log("\nTesting default audio input...");
+			await testDevice(null);
+		}
+	} catch (err) {
+		console.error("Error:", err);
+		process.exit(1);
+	}
+}
+
+main();

package/lib/voice.js

@@ -1,4 +1,3 @@
-// voice.js  (ESM)
 import { Model, Recognizer, setLogLevel } from "vosk-koffi";
 import record from "./record.js";
 import { dirname, join } from "node:path";
@@ -18,16 +17,20 @@ function unpacked(p) {
 }
 
 /* ------------------------------------------------------------------ */
-/* 1. Resolve SoX binary                                              */
+/* 1. Resolve SoX binary and audio device                            */
 /* ------------------------------------------------------------------ */
 const exeName = { win32: "sox.exe", darwin: "soxmac", linux: "soxlinux" }[
 	process.platform
 ];
 
-/* Priority: argv[2]  → fallback to sibling binaries/<exe> */
+/* Priority for sox path: argv[2] → fallback to sibling binaries/<exe> */
+/* Priority for device: argv[3] → env var → default */
 let soxPath = process.argv[2] || join(here, "..", "binaries", exeName);
 soxPath = unpacked(soxPath);
 
+// Parse device from argv[3] or environment variable
+let audioDevice = process.argv[3] || process.env.AUDIO_DEVICE || null;
+
 if (!existsSync(soxPath)) throw new Error(`SoX not found: ${soxPath}`);
 try {
 	chmodSync(soxPath, 0o755);
@@ -60,8 +63,17 @@ rec.setWords(true);
 /* 4. Start the microphone                                            */
 /* ------------------------------------------------------------------ */
 const recArgs = { sampleRate: SAMPLE_RATE, threshold: 0, binPath: soxPath };
-if (process.platform === "win32") {
+
+// Set device based on platform and configuration
+if (audioDevice !== null) {
+	// User specified a device explicitly
+	recArgs.device = audioDevice;
+	console.error(`Using audio device: ${audioDevice}`);
+} else if (process.platform === "win32") {
+	// Windows: default to device 0 if not specified
 	recArgs.device = "0";
+	console.error("Using default Windows audio device: 0");
+	console.error("To specify a different device, use: AUDIO_DEVICE=<device_id> or pass as 3rd argument");
 }
 
 const mic = record.record(recArgs).stream();
@@ -123,7 +135,7 @@ const rl = readline.createInterface({ input: process.stdin, terminal: false });
 
 rl.on("line", (line) => {
 	const trimmed = line.trim();
-	if (!trimmed.startsWith("update,") || !trimmed.startsWith("confidence,"))
+	if (!trimmed.startsWith("update,") && !trimmed.startsWith("confidence,"))
 		return;
 
 	if (trimmed.startsWith("confidence,")) {

package/package.json

@@ -1,15 +1,18 @@
 {
 	"name": "@lumiastream/wakeword",
-	"version": "1.0.1",
+	"version": "1.1.0",
 	"type": "module",
-	"main": "lib/voice.js",
+	"main": "lib/index.js",
 	"files": [
 		"lib/",
 		"models/",
 		"binaries/"
 	],
 	"scripts": {
-		"postinstall": "chmod +x binaries/soxmac binaries/soxlinux binaries/sox.exe || true"
+		"postinstall": "chmod +x binaries/soxmac binaries/soxlinux binaries/sox.exe || true",
+		"list-devices": "node lib/list-devices.js",
+		"test-devices": "node lib/test-devices.js",
+		"start": "node lib/voice.js"
 	},
 	"dependencies": {
 		"vosk-koffi": "^1.1.1"