@lumiastream/wakeword 1.0.2 → 1.1.1

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,120 @@
+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: Use PowerShell to get audio devices
+		const psCommand = `Get-WmiObject Win32_SoundDevice | Select-Object -Property Name, DeviceID | ConvertTo-Json`;
+		const proc = spawn("powershell", ["-Command", psCommand], {
+			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 = [];
+			
+			try {
+				// Try to parse PowerShell JSON output
+				if (output.trim()) {
+					const psDevices = JSON.parse(output);
+					const deviceArray = Array.isArray(psDevices) ? psDevices : [psDevices];
+					
+					deviceArray.forEach((device, index) => {
+						if (device && device.Name) {
+							devices.push({
+								id: index.toString(),
+								name: device.Name,
+							});
+						}
+					});
+				}
+			} catch (e) {
+				// PowerShell failed, try alternative method
+			}
+
+			// If PowerShell didn't work, try using Get-AudioDevice module if available
+			if (devices.length === 0) {
+				// Provide numbered device options for manual selection
+				// SoX on Windows typically uses device numbers 0-9
+				for (let i = 0; i <= 5; i++) {
+					devices.push({
+						id: i.toString(),
+						name: `Audio Input Device ${i}${i === 0 ? ' (Default)' : ''}`,
+					});
+				}
+				
+				console.log("\nNote: Unable to query actual device names.");
+				console.log("Showing generic device numbers (0-5).");
+				console.log("You may need to test each to find your microphone.\n");
+			}
+
+			resolve(devices);
+		});
+
+		proc.on("error", (err) => {
+			// If PowerShell is not available, provide default options
+			const devices = [];
+			for (let i = 0; i <= 5; i++) {
+				devices.push({
+					id: i.toString(),
+					name: `Audio Input Device ${i}${i === 0 ? ' (Default)' : ''}`,
+				});
+			}
+			resolve(devices);
+		});
+	});
+}
+
+// If run directly, list devices
+if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, '/'))) {
+	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,87 @@
+#!/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");
+	// Pass empty string for soxPath (will use default), then deviceId
+	const args = deviceId ? [voiceScript, "", deviceId] : [voiceScript];
+	const proc = spawn("node", args, {
+		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

@@ -17,16 +17,23 @@ 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> */
-let soxPath = process.argv[2] || join(here, "..", "binaries", exeName);
+/* Priority for sox path: argv[2] → fallback to sibling binaries/<exe> */
+/* Priority for device: argv[3] → env var → default */
+let soxPath = process.argv[2];
+if (!soxPath || soxPath === "") {
+	soxPath = 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);
@@ -59,8 +66,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();

package/package.json

@@ -1,15 +1,18 @@
 {
 	"name": "@lumiastream/wakeword",
-	"version": "1.0.2",
+	"version": "1.1.1",
 	"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"