vibefast-cli 0.2.4 → 0.3.1

package/recipes/wake-word/apps/native/assets/vosk-model/README.md

@@ -0,0 +1,103 @@
+# Vosk Model for Wake Word Detection
+
+This directory contains the Vosk speech recognition model for on-device wake word detection.
+
+## Required Model
+
+You need to download and place a Vosk model here.
+
+### Recommended Model
+
+**vosk-model-small-en-us-0.15** (~40 MB)
+
+- Optimized for mobile devices
+- Good accuracy for wake word detection
+- Low memory footprint
+
+## How to Download
+
+### Automated (Recommended)
+
+Run this command from the project root:
+
+```bash
+pnpm setup:vosk
+```
+
+This will automatically download, extract, and configure the model.
+
+### Manual Setup
+
+1. Go to [Vosk Models Page](https://alphacephei.com/vosk/models)
+2. Download `vosk-model-small-en-us-0.15.zip`
+3. Extract the ZIP file
+4. Rename the extracted folder to `model-en-us`
+5. Place the entire folder in this directory
+
+## Directory Structure
+
+After setup, you should have:
+
+```
+assets/vosk-model/
+└── vosk-model-small-en-us-0.15/
+    ├── am/
+    ├── conf/
+    ├── graph/
+    ├── ivector/
+    └── README
+```
+
+## Important Notes
+
+- **Do NOT commit the model** to git (it's in .gitignore)
+- Each developer needs to download their own model
+- The model is ~40 MB uncompressed
+- Model works offline (no internet required)
+- Model is free and open source
+
+## Alternative Models
+
+If you need a different language or size:
+
+- **Smaller** (~10 MB): `vosk-model-small-en-us-0.15` (less accurate)
+- **Larger** (~1.8 GB): `vosk-model-en-us-0.22` (more accurate, not recommended for mobile)
+- **Other languages**: See [Vosk Models](https://alphacephei.com/vosk/models)
+
+## Configuration
+
+The model path is configured in `app.config.ts`:
+
+```typescript
+[
+  'react-native-vosk',
+  {
+    models: ['assets/vosk-model'],
+    iOSMicrophonePermission:
+      'We use the mic for on-device wake-phrase detection.',
+  },
+];
+```
+
+## No API Key Required
+
+Unlike Picovoice, Vosk is completely free and open source. No API key or account needed!
+
+## Troubleshooting
+
+### Model not found error
+
+- Verify the model folder exists in `assets/vosk-model/`
+- Check the folder name matches what's in `app.config.ts`
+- Run `pnpm prebuild` after adding the model
+
+### Build size too large
+
+- Use the "small" model variant
+- Ensure you're not including multiple models
+
+### Recognition not working
+
+- Verify model is for English (if using English wake words)
+- Check microphone permissions are granted
+- Test with clear speech at normal volume

package/recipes/wake-word/apps/native/src/app/(root)/(protected)/test-wake-word.tsx

@@ -0,0 +1,216 @@
+import { useEffect } from 'react';
+import { Alert, Button, ScrollView, Text, View } from 'react-native';
+
+import { useWakeWord, WakeWordIndicator } from '@/features/wake-word';
+
+export default function TestWakeWord() {
+  const wakeWord = useWakeWord({
+    config: {
+      cooldownMs: 1500,
+    },
+    onTrigger: (event) => {
+      console.log('🎤 WAKE WORD DETECTED!', {
+        keyword: event.keyword,
+        timestamp: new Date(event.timestamp).toLocaleTimeString(),
+      });
+
+      // Show alert
+      Alert.alert(
+        '🎤 Wake Word Detected!',
+        `Keyword: ${event.keyword}\nTime: ${new Date(event.timestamp).toLocaleTimeString()}`,
+        [{ text: 'OK' }],
+      );
+    },
+  });
+
+  // Log state changes
+  useEffect(() => {
+    console.log('Wake Word State:', {
+      status: wakeWord.state.status,
+      isListening: wakeWord.state.isListening,
+      error: wakeWord.state.error,
+    });
+  }, [wakeWord.state]);
+
+  return (
+    <ScrollView className="flex-1 bg-white pt-24 dark:bg-gray-900">
+      <View className="p-6">
+        {/* Status Indicator */}
+        <View className="mb-6 rounded-lg bg-gray-100 p-4 dark:bg-gray-800">
+          <Text className="mb-3 text-lg font-semibold text-gray-900 dark:text-white">
+            Status
+          </Text>
+
+          <WakeWordIndicator state={wakeWord.state} className="mb-3" />
+
+          <View className="gap-2">
+            <View className="flex-row items-center">
+              <View
+                className={`mr-2 size-3 rounded-full ${
+                  wakeWord.state.isListening ? 'bg-green-500' : 'bg-gray-400'
+                }`}
+              />
+              <Text className="text-gray-700 dark:text-gray-300">
+                Status: {wakeWord.state.status}
+              </Text>
+            </View>
+
+            <Text className="text-gray-700 dark:text-gray-300">
+              Listening: {wakeWord.state.isListening ? '✅ Yes' : '❌ No'}
+            </Text>
+
+            {wakeWord.state.error && (
+              <Text className="text-red-600 dark:text-red-400">
+                ⚠️ Error: {wakeWord.state.error}
+              </Text>
+            )}
+
+            {wakeWord.state.lastTrigger && (
+              <View className="mt-2 rounded bg-green-100 p-2 dark:bg-green-900">
+                <Text className="font-semibold text-green-800 dark:text-green-200">
+                  Last Trigger:
+                </Text>
+                <Text className="text-green-700 dark:text-green-300">
+                  {wakeWord.state.lastTrigger.keyword} at{' '}
+                  {new Date(
+                    wakeWord.state.lastTrigger.timestamp,
+                  ).toLocaleTimeString()}
+                </Text>
+              </View>
+            )}
+          </View>
+        </View>
+
+        {/* Instructions */}
+        <View className="mb-6 rounded-lg bg-blue-50 p-4 dark:bg-blue-900/20">
+          <Text className="mb-3 text-lg font-semibold text-blue-900 dark:text-blue-100">
+            📋 Test Instructions
+          </Text>
+
+          <View className="gap-2">
+            <Text className="text-blue-800 dark:text-blue-200">
+              1. ✅ Grant microphone permission when prompted
+            </Text>
+            <Text className="text-blue-800 dark:text-blue-200">
+              2. 🎤 Say {`"Hello World"`} clearly at normal volume
+            </Text>
+            <Text className="text-blue-800 dark:text-blue-200">
+              3. 📱 Watch for alert popup
+            </Text>
+            <Text className="text-blue-800 dark:text-blue-200">
+              4. 📊 Check console logs for details
+            </Text>
+          </View>
+        </View>
+
+        {/* Controls */}
+        <View className="mb-6 gap-3">
+          <Button
+            title={
+              wakeWord.state.isListening
+                ? '⏸️ Stop Listening'
+                : '▶️ Start Listening'
+            }
+            onPress={
+              wakeWord.state.isListening
+                ? wakeWord.actions.stop
+                : wakeWord.actions.start
+            }
+            color={wakeWord.state.isListening ? '#ef4444' : '#10b981'}
+          />
+
+          <Button
+            title="🔄 Restart"
+            onPress={wakeWord.actions.restart}
+            disabled={!wakeWord.state.isListening}
+            color="#3b82f6"
+          />
+        </View>
+
+
+
+        {/* Wake Phrases */}
+        <View className="mb-6 rounded-lg bg-purple-50 p-4 dark:bg-purple-900/20">
+          <Text className="mb-3 text-lg font-semibold text-purple-900 dark:text-purple-100">
+            🗣️ Wake Phrases to Try
+          </Text>
+
+          <View className="gap-2">
+            <Text className="text-purple-800 dark:text-purple-200">
+              • {`"Hello World"`} (primary)
+            </Text>
+            {/* <Text className="text-purple-800 dark:text-purple-200">
+              • "Hello Vibefast" (variant)
+            </Text> */}
+          </View>
+        </View>
+
+        {/* Tips */}
+        <View className="mb-6 rounded-lg bg-yellow-50 p-4 dark:bg-yellow-900/20">
+          <Text className="mb-3 text-lg font-semibold text-yellow-900 dark:text-yellow-100">
+            💡 Tips for Best Results
+          </Text>
+
+          <View className="gap-2">
+            <Text className="text-yellow-800 dark:text-yellow-200">
+              • Speak at 1-1.5m distance from device
+            </Text>
+            <Text className="text-yellow-800 dark:text-yellow-200">
+              • Use normal speaking volume
+            </Text>
+            <Text className="text-yellow-800 dark:text-yellow-200">
+              • Reduce background noise
+            </Text>
+            <Text className="text-yellow-800 dark:text-yellow-200">
+              • Speak clearly and naturally
+            </Text>
+            <Text className="text-yellow-800 dark:text-yellow-200">
+              • Wait 1.5s between triggers (cooldown)
+            </Text>
+          </View>
+        </View>
+
+        {/* Expected Console Output */}
+        <View className="rounded-lg bg-gray-50 p-4 dark:bg-gray-800">
+          <Text className="mb-3 text-lg font-semibold text-gray-900 dark:text-white">
+            📊 Expected Console Output
+          </Text>
+
+          <View className="gap-1">
+            <Text className="font-mono text-xs text-green-600 dark:text-green-400">
+              ✅ Microphone prepared
+            </Text>
+            <Text className="font-mono text-xs text-green-600 dark:text-green-400">
+              ✅ Vosk model loaded
+            </Text>
+            <Text className="font-mono text-xs text-green-600 dark:text-green-400">
+              ✅ Wake word detection started
+            </Text>
+            <Text className="font-mono text-xs text-blue-600 dark:text-blue-400">
+              🎤 Wake word detected: {`"vibefast"`}
+            </Text>
+          </View>
+        </View>
+
+        {/* Debug Info */}
+        <View className="mt-6 rounded-lg border border-gray-300 p-4 dark:border-gray-700">
+          <Text className="mb-2 text-sm font-semibold text-gray-900 dark:text-white">
+            🔍 Debug Info
+          </Text>
+          <Text className="font-mono text-xs text-gray-600 dark:text-gray-400">
+            Status: {wakeWord.state.status}
+          </Text>
+          <Text className="font-mono text-xs text-gray-600 dark:text-gray-400">
+            Listening: {String(wakeWord.state.isListening)}
+          </Text>
+          <Text className="font-mono text-xs text-gray-600 dark:text-gray-400">
+            Error: {wakeWord.state.error || 'none'}
+          </Text>
+          <Text className="font-mono text-xs text-gray-600 dark:text-gray-400">
+            Last Trigger: {wakeWord.state.lastTrigger?.keyword || 'none'}
+          </Text>
+        </View>
+      </View>
+    </ScrollView>
+  );
+}

package/recipes/wake-word/apps/native/src/features/wake-word/components/index.ts

@@ -0,0 +1 @@
+export { WakeWordIndicator } from './wake-word-indicator';

package/recipes/wake-word/apps/native/src/features/wake-word/components/wake-word-indicator.tsx

@@ -0,0 +1,61 @@
+import { useEffect } from 'react';
+import { Text, View } from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  useSharedValue,
+  withRepeat,
+  withSequence,
+  withTiming,
+} from 'react-native-reanimated';
+
+import type { WakeWordState } from '../types';
+
+interface WakeWordIndicatorProps {
+  state: WakeWordState;
+  className?: string;
+}
+
+/**
+ * Simple visual indicator for wake word status
+ */
+export function WakeWordIndicator({
+  state,
+  className,
+}: WakeWordIndicatorProps) {
+  const opacity = useSharedValue(1);
+
+  useEffect(() => {
+    if (state.isListening) {
+      opacity.value = withRepeat(
+        withSequence(
+          withTiming(0.3, { duration: 1000 }),
+          withTiming(1, { duration: 1000 }),
+        ),
+        -1,
+        true,
+      );
+    } else {
+      opacity.value = withTiming(1);
+    }
+  }, [state.isListening, opacity]);
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    opacity: opacity.value,
+  }));
+
+  if (!state.isListening) {
+    return null;
+  }
+
+  return (
+    <Animated.View
+      style={animatedStyle}
+      className={`flex-row items-center gap-2 ${className || ''}`}
+    >
+      <View className="size-2 rounded-full bg-green-500" />
+      <Text className="text-xs text-gray-600 dark:text-gray-400">
+        Listening for {`"Hello World"`}
+      </Text>
+    </Animated.View>
+  );
+}

package/recipes/wake-word/apps/native/src/features/wake-word/constants.ts

@@ -0,0 +1,10 @@
+// Keyword names matching the .ppn files
+export const KEYWORD_NAMES = ['vibefast'] as const;
+
+export type KeywordName = (typeof KEYWORD_NAMES)[number];
+
+// Default cooldown to prevent rapid re-triggers
+export const DEFAULT_COOLDOWN_MS = 1500;
+
+// Default sensitivity (0.0 - 1.0, higher = more sensitive but more false positives)
+export const DEFAULT_SENSITIVITY = 0.5;

package/recipes/wake-word/apps/native/src/features/wake-word/hooks/use-wake-word.ts

@@ -0,0 +1,181 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { prepareMicrophone, resetAudioMode } from '../services/audio-session';
+import { wakeWordBus } from '../services/event-bus';
+import { wakeWordManager } from '../services/wake-word-manager';
+import type { WakeWordConfig, WakeWordEvent, WakeWordState } from '../types';
+
+interface UseWakeWordOptions {
+  config: WakeWordConfig;
+  onTrigger?: (event: WakeWordEvent) => void;
+  autoStart?: boolean;
+}
+
+/**
+ * Hook for managing wake word detection lifecycle
+ */
+export function useWakeWord({
+  config,
+  onTrigger,
+  autoStart = false,
+}: UseWakeWordOptions) {
+  const [state, setState] = useState<WakeWordState>({
+    status: 'idle',
+    isListening: false,
+  });
+
+  const configRef = useRef(config);
+  const onTriggerRef = useRef(onTrigger);
+  const isMountedRef = useRef(true);
+
+  // Keep refs fresh
+  useEffect(() => {
+    configRef.current = config;
+    onTriggerRef.current = onTrigger;
+  }, [config, onTrigger]);
+
+  useEffect(() => {
+    return () => {
+      isMountedRef.current = false;
+      if (wakeWordManager.isRunning()) {
+        void wakeWordManager.stop();
+      }
+      void resetAudioMode();
+    };
+  }, []);
+
+  const start = useCallback(async () => {
+    if (wakeWordManager.isRunning()) {
+      console.warn('⚠️ Wake word already listening');
+      if (!isMountedRef.current) {
+        return;
+      }
+      setState((prev) => ({
+        ...prev,
+        status: 'listening',
+        isListening: true,
+      }));
+      return;
+    }
+
+    if (!isMountedRef.current) {
+      return;
+    }
+    setState((prev) => ({ ...prev, status: 'starting' }));
+
+    try {
+      // Request mic permissions
+      const hasPermission = await prepareMicrophone();
+      if (!hasPermission) {
+        throw new Error('Microphone permission denied');
+      }
+
+      // Start wake word detection (Vosk doesn't need access key)
+      await wakeWordManager.start(configRef.current);
+
+      if (!isMountedRef.current) {
+        return;
+      }
+      setState((prev) => ({
+        ...prev,
+        status: 'listening',
+        isListening: true,
+        error: undefined,
+      }));
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : 'Unknown error';
+      console.error('❌ Failed to start wake word:', errorMessage);
+      try {
+        await resetAudioMode();
+      } catch (audioError) {
+        console.error(
+          '❌ Failed to reset audio mode after start error:',
+          audioError,
+        );
+      }
+      if (!isMountedRef.current) {
+        return;
+      }
+      setState((prev) => ({
+        ...prev,
+        status: 'error',
+        isListening: false,
+        error: errorMessage,
+      }));
+    }
+  }, []);
+
+  const stop = useCallback(async () => {
+    const wasRunning = wakeWordManager.isRunning();
+
+    try {
+      if (wasRunning) {
+        await wakeWordManager.stop();
+      }
+    } catch (error) {
+      console.error('❌ Failed to stop wake word:', error);
+    }
+
+    try {
+      await resetAudioMode();
+    } catch (audioError) {
+      console.error('❌ Failed to reset audio mode:', audioError);
+    }
+
+    if (!isMountedRef.current) {
+      return;
+    }
+    setState((prev) => ({
+      ...prev,
+      status: 'idle',
+      isListening: false,
+      error: undefined,
+    }));
+  }, []);
+
+  const restart = useCallback(async () => {
+    await stop();
+    await start();
+  }, [start, stop]);
+
+  // Handle wake word triggers
+  useEffect(() => {
+    const handleTrigger = (event: WakeWordEvent) => {
+      setState((prev) => ({
+        ...prev,
+        lastTrigger: event,
+      }));
+
+      onTriggerRef.current?.(event);
+    };
+
+    wakeWordBus.on('trigger', handleTrigger);
+
+    return () => {
+      wakeWordBus.off('trigger', handleTrigger);
+    };
+  }, []);
+
+  // Auto-start if enabled
+  useEffect(() => {
+    if (autoStart && config.enabled !== false) {
+      void start();
+    }
+
+    return () => {
+      if (autoStart) {
+        void stop();
+      }
+    };
+  }, [autoStart, config.enabled, start, stop]);
+
+  return {
+    state,
+    actions: {
+      start,
+      stop,
+      restart,
+    },
+  };
+}

package/recipes/wake-word/apps/native/src/features/wake-word/index.ts

@@ -0,0 +1,22 @@
+// Hooks
+
+// Components
+export { WakeWordIndicator } from './components';
+// Constants
+export {
+  DEFAULT_COOLDOWN_MS,
+  DEFAULT_SENSITIVITY,
+  KEYWORD_NAMES,
+} from './constants';
+export { useWakeWord } from './hooks/use-wake-word';
+// Services
+export { prepareMicrophone, resetAudioMode } from './services/audio-session';
+export { wakeWordBus } from './services/event-bus';
+export { wakeWordManager } from './services/wake-word-manager';
+// Types
+export type {
+  WakeWordConfig,
+  WakeWordEvent,
+  WakeWordState,
+  WakeWordStatus,
+} from './types';

package/recipes/wake-word/apps/native/src/features/wake-word/services/audio-session.ts

@@ -0,0 +1,40 @@
+import { AudioModule, setAudioModeAsync } from 'expo-audio';
+
+/**
+ * Prepare microphone permissions and audio mode for wake word detection
+ */
+export async function prepareMicrophone(): Promise<boolean> {
+  try {
+    const status = await AudioModule.requestRecordingPermissionsAsync();
+
+    if (!status.granted) {
+      console.warn('❌ Microphone permission denied');
+      return false;
+    }
+
+    await setAudioModeAsync({
+      playsInSilentMode: true,
+      allowsRecording: true,
+    });
+
+    console.log('✅ Microphone prepared for wake word detection');
+    return true;
+  } catch (error) {
+    console.error('❌ Failed to prepare microphone:', error);
+    return false;
+  }
+}
+
+/**
+ * Reset audio mode (call when stopping wake word detection)
+ */
+export async function resetAudioMode(): Promise<void> {
+  try {
+    await setAudioModeAsync({
+      playsInSilentMode: false,
+      allowsRecording: false,
+    });
+  } catch (error) {
+    console.error('❌ Failed to reset audio mode:', error);
+  }
+}

package/recipes/wake-word/apps/native/src/features/wake-word/services/event-bus.ts

@@ -0,0 +1,31 @@
+import { EventEmitter } from 'events';
+
+import type { WakeWordEvent } from '../types';
+
+/**
+ * Event bus for wake word triggers
+ * Allows decoupling wake word detection from action handlers
+ */
+class WakeWordEventBus extends EventEmitter {
+  emit(event: 'trigger', data: WakeWordEvent): boolean;
+  emit(event: string | symbol, ...args: any[]): boolean {
+    return super.emit(event, ...args);
+  }
+
+  on(event: 'trigger', listener: (data: WakeWordEvent) => void): this;
+  on(event: string | symbol, listener: (...args: any[]) => void): this {
+    return super.on(event, listener);
+  }
+
+  once(event: 'trigger', listener: (data: WakeWordEvent) => void): this;
+  once(event: string | symbol, listener: (...args: any[]) => void): this {
+    return super.once(event, listener);
+  }
+
+  off(event: 'trigger', listener: (data: WakeWordEvent) => void): this;
+  off(event: string | symbol, listener: (...args: any[]) => void): this {
+    return super.off(event, listener);
+  }
+}
+
+export const wakeWordBus = new WakeWordEventBus();