@holoscript/core 1.0.0-alpha.1 → 2.0.0

package/src/traits/VoiceInputTrait.test.ts

@@ -0,0 +1,252 @@
+/**
+ * VoiceInputTrait Tests
+ *
+ * Comprehensive tests for voice recognition and command matching
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { VoiceInputTrait, type VoiceInputConfig, type VoiceCommand } from '../traits/VoiceInputTrait';
+
+describe('VoiceInputTrait', () => {
+  let trait: VoiceInputTrait;
+  let config: VoiceInputConfig;
+
+  beforeEach(() => {
+    config = {
+      mode: 'continuous',
+      confidenceThreshold: 0.7,
+      commands: [
+        {
+          phrase: 'turn on',
+          aliases: ['activate', 'power up'],
+          action: 'activate',
+        },
+        {
+          phrase: 'move forward',
+          aliases: ['go forward', 'advance'],
+          action: 'move',
+          params: { direction: 'forward' },
+        },
+        {
+          phrase: 'stop',
+          aliases: ['halt', 'pause'],
+          action: 'stop',
+        },
+      ],
+    };
+    trait = new VoiceInputTrait(config);
+  });
+
+  describe('Initialization', () => {
+    it('should initialize with config', () => {
+      expect(trait).toBeDefined();
+    });
+
+    it('should not be listening initially', () => {
+      expect(trait.isActive()).toBe(false);
+    });
+
+    it('should accept custom confidence threshold', () => {
+      const customTrait = new VoiceInputTrait({
+        mode: 'push-to-talk',
+        confidenceThreshold: 0.85,
+      });
+      expect(customTrait).toBeDefined();
+    });
+  });
+
+  describe('Listening Control', () => {
+    it('should start listening', () => {
+      trait.startListening();
+      // Note: Web Speech API not available in test env, so this just tests the method exists
+      expect(trait).toBeDefined();
+    });
+
+    it('should stop listening', () => {
+      trait.stopListening();
+      expect(trait.isActive()).toBe(false);
+    });
+
+    it('should toggle listening state', () => {
+      const initialState = trait.isActive();
+      trait.toggleListening();
+      // Can't easily test state change without Web Speech API
+      expect(trait).toBeDefined();
+    });
+  });
+
+  describe('Event Listeners', () => {
+    it('should register event listener', () => {
+      const listener = vi.fn();
+      trait.on(listener);
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('should unregister event listener', () => {
+      const listener = vi.fn();
+      trait.on(listener);
+      trait.off(listener);
+      expect(trait).toBeDefined();
+    });
+
+    it('should allow multiple listeners', () => {
+      const listener1 = vi.fn();
+      const listener2 = vi.fn();
+      trait.on(listener1);
+      trait.on(listener2);
+      expect(trait).toBeDefined();
+    });
+  });
+
+  describe('Configuration', () => {
+    it('should support continuous mode', () => {
+      const continuousTrait = new VoiceInputTrait({
+        mode: 'continuous',
+        confidenceThreshold: 0.7,
+      });
+      expect(continuousTrait).toBeDefined();
+    });
+
+    it('should support push-to-talk mode', () => {
+      const pushTrait = new VoiceInputTrait({
+        mode: 'push-to-talk',
+        confidenceThreshold: 0.7,
+      });
+      expect(pushTrait).toBeDefined();
+    });
+
+    it('should support always-listening mode', () => {
+      const alwaysTrait = new VoiceInputTrait({
+        mode: 'always-listening',
+        confidenceThreshold: 0.5,
+      });
+      expect(alwaysTrait).toBeDefined();
+    });
+
+    it('should accept multiple languages', () => {
+      const multiLangTrait = new VoiceInputTrait({
+        mode: 'continuous',
+        confidenceThreshold: 0.7,
+        languages: ['en-US', 'es-ES', 'fr-FR'],
+      });
+      expect(multiLangTrait).toBeDefined();
+    });
+
+    it('should support audio feedback toggle', () => {
+      const feedbackTrait = new VoiceInputTrait({
+        mode: 'continuous',
+        confidenceThreshold: 0.7,
+        audioFeedback: true,
+      });
+      expect(feedbackTrait).toBeDefined();
+    });
+
+    it('should support transcript display', () => {
+      const transcriptTrait = new VoiceInputTrait({
+        mode: 'continuous',
+        confidenceThreshold: 0.7,
+        showTranscript: true,
+      });
+      expect(transcriptTrait).toBeDefined();
+    });
+  });
+
+  describe('Command Configuration', () => {
+    it('should support command phrases', () => {
+      const commands: VoiceCommand[] = [
+        { phrase: 'hello', action: 'greet' },
+      ];
+      const cmdTrait = new VoiceInputTrait({
+        mode: 'continuous',
+        confidenceThreshold: 0.7,
+        commands,
+      });
+      expect(cmdTrait).toBeDefined();
+    });
+
+    it('should support command aliases', () => {
+      const commands: VoiceCommand[] = [
+        {
+          phrase: 'turn on',
+          aliases: ['activate', 'power up', 'enable'],
+          action: 'activate',
+        },
+      ];
+      const cmdTrait = new VoiceInputTrait({
+        mode: 'continuous',
+        confidenceThreshold: 0.7,
+        commands,
+      });
+      expect(cmdTrait).toBeDefined();
+    });
+
+    it('should support per-command confidence', () => {
+      const commands: VoiceCommand[] = [
+        {
+          phrase: 'critical action',
+          action: 'critical',
+          confidence: 0.95,
+        },
+        {
+          phrase: 'normal action',
+          action: 'normal',
+          confidence: 0.7,
+        },
+      ];
+      const cmdTrait = new VoiceInputTrait({
+        mode: 'continuous',
+        confidenceThreshold: 0.7,
+        commands,
+      });
+      expect(cmdTrait).toBeDefined();
+    });
+
+    it('should support command parameters', () => {
+      const commands: VoiceCommand[] = [
+        {
+          phrase: 'go to location',
+          action: 'navigate',
+          params: { target: 'location' },
+        },
+      ];
+      const cmdTrait = new VoiceInputTrait({
+        mode: 'continuous',
+        confidenceThreshold: 0.7,
+        commands,
+      });
+      expect(cmdTrait).toBeDefined();
+    });
+  });
+
+  describe('Timeout Configuration', () => {
+    it('should support custom timeout', () => {
+      const timeoutTrait = new VoiceInputTrait({
+        mode: 'continuous',
+        confidenceThreshold: 0.7,
+        timeout: 5000,
+      });
+      expect(timeoutTrait).toBeDefined();
+    });
+
+    it('should use default timeout if not specified', () => {
+      const defaultTrait = new VoiceInputTrait({
+        mode: 'continuous',
+        confidenceThreshold: 0.7,
+      });
+      expect(defaultTrait).toBeDefined();
+    });
+  });
+
+  describe('Cleanup', () => {
+    it('should dispose resources', () => {
+      trait.dispose();
+      expect(trait).toBeDefined();
+    });
+
+    it('should stop listening on dispose', () => {
+      trait.startListening();
+      trait.dispose();
+      expect(trait.isActive()).toBe(false);
+    });
+  });
+});

package/src/traits/VoiceInputTrait.ts

@@ -0,0 +1,401 @@
+/**
+ * @holoscript/core VoiceInput Trait
+ *
+ * Enables voice-driven interactions for HoloScript+ objects
+ * Integrates speech recognition with confidence-based command parsing
+ */
+
+export type VoiceInputMode = 'continuous' | 'push-to-talk' | 'always-listening';
+export type ConfidenceThreshold = number; // 0.0 to 1.0
+
+/**
+ * Voice input configuration for HoloScript+ objects
+ */
+export interface VoiceInputConfig {
+  /** Speech recognition mode */
+  mode: VoiceInputMode;
+  
+  /** Minimum confidence level (0-1) to trigger command */
+  confidenceThreshold: ConfidenceThreshold;
+  
+  /** Languages supported (BCP 47 codes) */
+  languages?: string[];
+  
+  /** Commands this object responds to */
+  commands?: VoiceCommand[];
+  
+  /** Enable speech-to-text display */
+  showTranscript?: boolean;
+  
+  /** Audio feedback (beep on recognition) */
+  audioFeedback?: boolean;
+  
+  /** Max command processing time (ms) */
+  timeout?: number;
+}
+
+/**
+ * Voice command definition
+ */
+export interface VoiceCommand {
+  /** Primary trigger phrase */
+  phrase: string;
+  
+  /** Alternative phrases (fuzzy matching) */
+  aliases?: string[];
+  
+  /** Confidence threshold for this specific command */
+  confidence?: number;
+  
+  /** Action to execute */
+  action: string;
+  
+  /** Parameters extracted from command */
+  params?: Record<string, string>;
+}
+
+/**
+ * Voice recognition result
+ */
+export interface VoiceRecognitionResult {
+  /** Transcribed text */
+  transcript: string;
+  
+  /** Confidence (0-1) */
+  confidence: number;
+  
+  /** Is final result or interim? */
+  isFinal: boolean;
+  
+  /** Language detected */
+  language: string;
+  
+  /** Matched command if any */
+  matchedCommand?: VoiceCommand;
+  
+  /** Timestamp */
+  timestamp: number;
+}
+
+/**
+ * Voice input event
+ */
+export interface VoiceInputEvent {
+  type: 'start' | 'interim' | 'final' | 'error' | 'timeout';
+  result: VoiceRecognitionResult;
+  hologramId: string;
+}
+
+/**
+ * VoiceInputTrait - Enables speech recognition on HoloScript+ objects
+ */
+export class VoiceInputTrait {
+  private config: VoiceInputConfig;
+  private recognition: any = null;
+  private isListening: boolean = false;
+  private listeners: Set<(event: VoiceInputEvent) => void> = new Set();
+  private interimTranscript: string = '';
+  private commandCache: Map<string, VoiceCommand> = new Map();
+
+  constructor(config: VoiceInputConfig) {
+    this.config = {
+      showTranscript: false,
+      audioFeedback: true,
+      timeout: 10000,
+      ...config,
+    };
+
+    this.initializeRecognition();
+    this.buildCommandCache();
+  }
+
+  /**
+   * Initialize Web Speech API
+   */
+  private initializeRecognition(): void {
+    // Use native Web Speech API or polyfill
+    const SpeechRecognition = (globalThis as any).SpeechRecognition ||
+      (globalThis as any).webkitSpeechRecognition;
+
+    if (!SpeechRecognition) {
+      console.error('Web Speech API not supported');
+      return;
+    }
+
+    this.recognition = new SpeechRecognition();
+    this.setupRecognitionHandlers();
+  }
+
+  /**
+   * Setup Web Speech API event handlers
+   */
+  private setupRecognitionHandlers(): void {
+    if (!this.recognition) return;
+
+    this.recognition.continuous = this.config.mode === 'continuous';
+    this.recognition.interimResults = true;
+    this.recognition.lang = this.config.languages?.[0] || 'en-US';
+
+    this.recognition.onstart = () => {
+      this.isListening = true;
+      this.interimTranscript = '';
+      if (this.config.audioFeedback) {
+        this.playBeep('start');
+      }
+    };
+
+    this.recognition.onresult = (event: any) => {
+      this.interimTranscript = '';
+
+      for (let i = event.resultIndex; i < event.results.length; i++) {
+        const transcript = event.results[i][0].transcript;
+        const confidence = event.results[i][0].confidence;
+        const isFinal = event.results[i].isFinal;
+
+        if (isFinal) {
+          this.processVoiceCommand(transcript, confidence);
+        } else {
+          this.interimTranscript += transcript;
+        }
+      }
+
+      if (this.config.showTranscript) {
+        this.emitEvent({
+          type: 'interim',
+          result: {
+            transcript: this.interimTranscript,
+            confidence: 0,
+            isFinal: false,
+            language: this.recognition.lang,
+            timestamp: Date.now(),
+          },
+          hologramId: '',
+        });
+      }
+    };
+
+    this.recognition.onerror = (_event: any) => {
+      this.emitEvent({
+        type: 'error',
+        result: {
+          transcript: '',
+          confidence: 0,
+          isFinal: false,
+          language: this.recognition.lang,
+          timestamp: Date.now(),
+        },
+        hologramId: '',
+      });
+    };
+
+    this.recognition.onend = () => {
+      this.isListening = false;
+      if (this.config.audioFeedback) {
+        this.playBeep('end');
+      }
+    };
+  }
+
+  /**
+   * Process voice command with fuzzy matching
+   */
+  private processVoiceCommand(
+    transcript: string,
+    confidence: number
+  ): void {
+    if (confidence < this.config.confidenceThreshold) {
+      return;
+    }
+
+    const normalized = transcript.toLowerCase().trim();
+    let bestMatch: VoiceCommand | null = null;
+    let bestScore: number = 0;
+
+    // Try to find matching command
+    for (const command of this.config.commands || []) {
+      const cmdConfidence = command.confidence || this.config.confidenceThreshold;
+
+      // Exact match
+      if (normalized === command.phrase.toLowerCase()) {
+        if (confidence >= cmdConfidence) {
+          bestMatch = command;
+          bestScore = 1.0;
+          break;
+        }
+      }
+
+      // Fuzzy match with aliases
+      const allPhrases = [command.phrase, ...(command.aliases || [])];
+      for (const phrase of allPhrases) {
+        const score = this.fuzzyMatch(normalized, phrase.toLowerCase());
+        if (score > bestScore && score >= 0.7) {
+          bestScore = score;
+          bestMatch = command;
+        }
+      }
+    }
+
+    // Emit recognition result
+    this.emitEvent({
+      type: 'final',
+      result: {
+        transcript: normalized,
+        confidence,
+        isFinal: true,
+        language: this.recognition.lang,
+        matchedCommand: bestMatch || undefined,
+        timestamp: Date.now(),
+      },
+      hologramId: '',
+    });
+
+    if (bestMatch) {
+      if (this.config.audioFeedback) {
+        this.playBeep('success');
+      }
+    }
+  }
+
+  /**
+   * Fuzzy string matching (simple Levenshtein-like approach)
+   */
+  private fuzzyMatch(input: string, target: string): number {
+    if (input === target) return 1.0;
+    if (input.length === 0 || target.length === 0) return 0;
+
+    // Check if input is substring of target
+    if (target.includes(input)) {
+      return Math.min(1.0, input.length / target.length);
+    }
+
+    // Simple edit distance estimation
+    const distance = Math.abs(input.length - target.length);
+    const maxLen = Math.max(input.length, target.length);
+    return Math.max(0, 1.0 - distance / maxLen);
+  }
+
+  /**
+   * Build command index for faster lookup
+   */
+  private buildCommandCache(): void {
+    for (const command of this.config.commands || []) {
+      this.commandCache.set(command.phrase.toLowerCase(), command);
+      for (const alias of command.aliases || []) {
+        this.commandCache.set(alias.toLowerCase(), command);
+      }
+    }
+  }
+
+  /**
+   * Start listening for voice input
+   */
+  public startListening(): void {
+    if (!this.recognition || this.isListening) return;
+
+    try {
+      this.recognition.start();
+    } catch (error) {
+      console.error('Failed to start speech recognition:', error);
+    }
+  }
+
+  /**
+   * Stop listening for voice input
+   */
+  public stopListening(): void {
+    if (!this.recognition || !this.isListening) return;
+
+    try {
+      this.recognition.stop();
+    } catch (error) {
+      console.error('Failed to stop speech recognition:', error);
+    }
+  }
+
+  /**
+   * Toggle listening state
+   */
+  public toggleListening(): void {
+    if (this.isListening) {
+      this.stopListening();
+    } else {
+      this.startListening();
+    }
+  }
+
+  /**
+   * Add command listener
+   */
+  public on(listener: (event: VoiceInputEvent) => void): void {
+    this.listeners.add(listener);
+  }
+
+  /**
+   * Remove command listener
+   */
+  public off(listener: (event: VoiceInputEvent) => void): void {
+    this.listeners.delete(listener);
+  }
+
+  /**
+   * Emit voice event to all listeners
+   */
+  private emitEvent(event: VoiceInputEvent): void {
+    for (const listener of this.listeners) {
+      listener(event);
+    }
+  }
+
+  /**
+   * Play audio feedback beep
+   */
+  private playBeep(type: 'start' | 'end' | 'success'): void {
+    // AudioContext beep generation
+    try {
+      const audioContext = new (globalThis as any).AudioContext();
+      const oscillator = audioContext.createOscillator();
+      const gainNode = audioContext.createGain();
+
+      oscillator.connect(gainNode);
+      gainNode.connect(audioContext.destination);
+
+      const now = audioContext.currentTime;
+      const duration = 0.1;
+
+      // Vary beep frequency by type
+      oscillator.frequency.value = type === 'start' ? 800 : type === 'success' ? 1000 : 600;
+      gainNode.gain.setValueAtTime(0.3, now);
+      gainNode.gain.exponentialRampToValueAtTime(0.01, now + duration);
+
+      oscillator.start(now);
+      oscillator.stop(now + duration);
+    } catch (error) {
+      // Silently fail if audio not available
+    }
+  }
+
+  /**
+   * Get current listening state
+   */
+  public isActive(): boolean {
+    return this.isListening;
+  }
+
+  /**
+   * Dispose and cleanup
+   */
+  public dispose(): void {
+    if (this.recognition) {
+      this.recognition.abort();
+    }
+    this.listeners.clear();
+    this.commandCache.clear();
+  }
+}
+
+/**
+ * HoloScript+ @voice_input trait factory
+ */
+export function createVoiceInputTrait(config: VoiceInputConfig): VoiceInputTrait {
+  return new VoiceInputTrait(config);
+}