@runtypelabs/persona 1.46.1 → 1.48.0

package/src/voice/voice-activity-detector.ts

@@ -0,0 +1,90 @@
+/**
+ * Voice Activity Detector (VAD)
+ *
+ * Reusable RMS-based voice activity detection that monitors a mic stream
+ * and fires a callback when a condition is sustained for a given duration.
+ *
+ * - mode 'silence': fires when volume stays below threshold (user stopped talking)
+ * - mode 'speech':  fires when volume stays above threshold (user started talking)
+ *
+ * Fires callback exactly once per start() call, then stops checking.
+ * Calling start() again implicitly calls stop() first.
+ */
+export class VoiceActivityDetector {
+  private sourceNode: MediaStreamAudioSourceNode | null = null;
+  private analyserNode: AnalyserNode | null = null;
+  private interval: ReturnType<typeof setInterval> | null = null;
+  private conditionStart: number | null = null;
+  private fired = false;
+
+  /**
+   * Begin monitoring the given stream for voice activity.
+   *
+   * @param audioContext  Active AudioContext
+   * @param stream       MediaStream from getUserMedia
+   * @param mode         'silence' fires when quiet for duration, 'speech' fires when loud for duration
+   * @param config       threshold (RMS level) and duration (ms)
+   * @param callback     Fires exactly once when the condition is met
+   */
+  start(
+    audioContext: AudioContext,
+    stream: MediaStream,
+    mode: "silence" | "speech",
+    config: { threshold: number; duration: number },
+    callback: () => void,
+  ): void {
+    this.stop();
+
+    this.fired = false;
+    this.conditionStart = null;
+
+    this.sourceNode = audioContext.createMediaStreamSource(stream);
+    this.analyserNode = audioContext.createAnalyser();
+    this.analyserNode.fftSize = 2048;
+    this.sourceNode.connect(this.analyserNode);
+
+    const dataArray = new Float32Array(this.analyserNode.fftSize);
+
+    this.interval = setInterval(() => {
+      if (!this.analyserNode || this.fired) return;
+      this.analyserNode.getFloatTimeDomainData(dataArray);
+
+      // Compute RMS volume
+      let sum = 0;
+      for (let i = 0; i < dataArray.length; i++) {
+        sum += dataArray[i] * dataArray[i];
+      }
+      const rms = Math.sqrt(sum / dataArray.length);
+
+      const conditionMet =
+        mode === "silence"
+          ? rms < config.threshold
+          : rms >= config.threshold;
+
+      if (conditionMet) {
+        if (this.conditionStart === null) {
+          this.conditionStart = Date.now();
+        } else if (Date.now() - this.conditionStart >= config.duration) {
+          this.fired = true;
+          callback();
+        }
+      } else {
+        this.conditionStart = null;
+      }
+    }, 100);
+  }
+
+  stop(): void {
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = null;
+    }
+    if (this.sourceNode) {
+      this.sourceNode.disconnect();
+      this.sourceNode = null;
+    }
+    this.analyserNode = null;
+    this.conditionStart = null;
+    this.fired = false;
+  }
+}

package/src/voice/voice-factory.ts

@@ -0,0 +1,56 @@
+// Voice Provider Factory
+// Creates appropriate voice provider based on configuration
+
+import type { VoiceProvider, VoiceConfig } from '../types';
+import { RuntypeVoiceProvider } from './runtype-voice-provider';
+import { BrowserVoiceProvider } from './browser-voice-provider';
+
+export function createVoiceProvider(config: VoiceConfig): VoiceProvider {
+  switch (config.type) {
+    case 'runtype':
+      if (!config.runtype) {
+        throw new Error('Runtype voice provider requires configuration');
+      }
+      return new RuntypeVoiceProvider(config.runtype);
+    
+    case 'browser':
+      if (!BrowserVoiceProvider.isSupported()) {
+        throw new Error('Browser speech recognition not supported');
+      }
+      return new BrowserVoiceProvider(config.browser || {});
+    
+    case 'custom':
+      throw new Error('Custom voice providers not yet implemented');
+    
+    default:
+      throw new Error(`Unknown voice provider type: ${config.type}`);
+  }
+}
+
+// Auto-select the best available provider
+export function createBestAvailableVoiceProvider(config?: Partial<VoiceConfig>): VoiceProvider {
+  // Prefer Runtype if configured
+  if (config?.type === 'runtype' && config.runtype) {
+    return createVoiceProvider({ type: 'runtype', runtype: config.runtype });
+  }
+  
+  // Fall back to browser if supported
+  if (BrowserVoiceProvider.isSupported()) {
+    return createVoiceProvider({ 
+      type: 'browser', 
+      browser: config?.browser || { language: 'en-US' }
+    });
+  }
+  
+  throw new Error('No supported voice providers available');
+}
+
+// Check if any voice provider is available
+export function isVoiceSupported(config?: Partial<VoiceConfig>): boolean {
+  try {
+    createBestAvailableVoiceProvider(config);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}

package/src/voice/voice.test.ts

@@ -0,0 +1,220 @@
+// Voice SDK Tests
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import type { VoiceConfig } from '../types';
+import { RuntypeVoiceProvider } from './runtype-voice-provider';
+import { BrowserVoiceProvider } from './browser-voice-provider';
+import { createVoiceProvider, createBestAvailableVoiceProvider, isVoiceSupported } from './voice-factory';
+
+// Mock window object for browser tests
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const mockWindow: any = {
+  SpeechRecognition: undefined,
+  webkitSpeechRecognition: undefined
+};
+
+beforeAll(() => {
+  // @ts-ignore
+  global.window = mockWindow;
+});
+
+afterAll(() => {
+  // @ts-ignore
+  delete global.window;
+});
+
+function mockBrowserSupport(supported: boolean) {
+  if (supported) {
+    mockWindow.SpeechRecognition = class {};
+    mockWindow.webkitSpeechRecognition = class {};
+  } else {
+    delete mockWindow.SpeechRecognition;
+    delete mockWindow.webkitSpeechRecognition;
+  }
+}
+
+// Note: TypeScript interfaces don't exist at runtime, so we can't test them directly
+// We test the concrete implementations instead
+
+describe('RuntypeVoiceProvider', () => {
+  it('should create instance with valid config', () => {
+    const config = {
+      agentId: 'test-agent',
+      clientToken: 'test-token',
+      host: 'localhost:8787',
+      voiceId: 'rachel'
+    };
+    
+    const provider = new RuntypeVoiceProvider(config);
+    expect(provider).toBeInstanceOf(RuntypeVoiceProvider);
+    expect(provider.type).toBe('runtype');
+  });
+  
+  it('should have correct methods', () => {
+    const config = {
+      agentId: 'test-agent',
+      clientToken: 'test-token'
+    };
+    
+    const provider = new RuntypeVoiceProvider(config);
+    expect(typeof provider.connect).toBe('function');
+    expect(typeof provider.disconnect).toBe('function');
+    expect(typeof provider.startListening).toBe('function');
+    expect(typeof provider.stopListening).toBe('function');
+    expect(typeof provider.onResult).toBe('function');
+    expect(typeof provider.onError).toBe('function');
+    expect(typeof provider.onStatusChange).toBe('function');
+  });
+});
+
+describe('BrowserVoiceProvider', () => {
+  it('should create instance with default config', () => {
+    const provider = new BrowserVoiceProvider();
+    expect(provider).toBeInstanceOf(BrowserVoiceProvider);
+    expect(provider.type).toBe('browser');
+  });
+  
+  it('should have correct methods', () => {
+    const provider = new BrowserVoiceProvider();
+    expect(typeof provider.connect).toBe('function');
+    expect(typeof provider.disconnect).toBe('function');
+    expect(typeof provider.startListening).toBe('function');
+    expect(typeof provider.stopListening).toBe('function');
+    expect(typeof provider.onResult).toBe('function');
+    expect(typeof provider.onError).toBe('function');
+    expect(typeof provider.onStatusChange).toBe('function');
+  });
+  
+  it('should check browser support', () => {
+    // Test supported
+    mockBrowserSupport(true);
+    expect(BrowserVoiceProvider.isSupported()).toBe(true);
+    
+    // Test unsupported
+    mockBrowserSupport(false);
+    expect(BrowserVoiceProvider.isSupported()).toBe(false);
+  });
+});
+
+describe('Voice Factory', () => {
+  it('should create Runtype provider', () => {
+    const config: VoiceConfig = {
+      type: 'runtype',
+      runtype: {
+        agentId: 'test-agent',
+        clientToken: 'test-token'
+      }
+    };
+    
+    const provider = createVoiceProvider(config);
+    expect(provider).toBeInstanceOf(RuntypeVoiceProvider);
+    expect(provider.type).toBe('runtype');
+  });
+  
+  it('should create Browser provider when supported', () => {
+    // Mock browser support
+    mockBrowserSupport(true);
+    
+    const config: VoiceConfig = {
+      type: 'browser',
+      browser: {
+        language: 'en-US'
+      }
+    };
+    
+    const provider = createVoiceProvider(config);
+    expect(provider).toBeInstanceOf(BrowserVoiceProvider);
+    expect(provider.type).toBe('browser');
+  });
+  
+  it('should throw error for unsupported browser provider', () => {
+    // Mock no browser support
+    mockBrowserSupport(false);
+    
+    const config: VoiceConfig = {
+      type: 'browser'
+    };
+    
+    expect(() => createVoiceProvider(config)).toThrow('Browser speech recognition not supported');
+  });
+  
+  it('should throw error for custom provider', () => {
+    const config: VoiceConfig = {
+      type: 'custom',
+      custom: {}
+    };
+    
+    expect(() => createVoiceProvider(config)).toThrow('Custom voice providers not yet implemented');
+  });
+  
+  it('should throw error for unknown provider type', () => {
+    const config = {
+      type: 'unknown' as any
+    };
+    
+    expect(() => createVoiceProvider(config)).toThrow('Unknown voice provider type: unknown');
+  });
+});
+
+describe('Best Available Voice Provider', () => {
+  it('should prefer Runtype when configured', () => {
+    // Mock no browser support
+    mockBrowserSupport(false);
+    
+    const config = {
+      type: 'runtype' as const,
+      runtype: {
+        agentId: 'test-agent',
+        clientToken: 'test-token'
+      }
+    };
+    
+    const provider = createBestAvailableVoiceProvider(config);
+    expect(provider).toBeInstanceOf(RuntypeVoiceProvider);
+  });
+  
+  it('should fall back to browser when Runtype not configured', () => {
+    // Mock browser support
+    mockBrowserSupport(true);
+    
+    const provider = createBestAvailableVoiceProvider();
+    expect(provider).toBeInstanceOf(BrowserVoiceProvider);
+  });
+  
+  it('should throw error when no providers available', () => {
+    // Mock no browser support
+    mockBrowserSupport(false);
+    
+    expect(() => createBestAvailableVoiceProvider()).toThrow('No supported voice providers available');
+  });
+});
+
+describe('Voice Support Check', () => {
+  it('should return true when voice is supported', () => {
+    // Mock browser support
+    mockBrowserSupport(true);
+    
+    expect(isVoiceSupported()).toBe(true);
+  });
+  
+  it('should return true when Runtype is configured', () => {
+    // Mock no browser support
+    mockBrowserSupport(false);
+    
+    const config = {
+      type: 'runtype' as const,
+      runtype: {
+        agentId: 'test-agent',
+        clientToken: 'test-token'
+      }
+    };
+    
+    expect(isVoiceSupported(config)).toBe(true);
+  });
+  
+  it('should return false when no voice support available', () => {
+    // Mock no browser support
+    mockBrowserSupport(false);
+    
+    expect(isVoiceSupported()).toBe(false);
+  });
+});