markupr 2.1.8

package/src/main/audio/AudioCapture.ts

@@ -0,0 +1,978 @@
+/**
+ * AudioCapture.ts - Production Audio Capture Service for markupr
+ *
+ * Architecture:
+ * - Renderer process captures audio via getUserMedia (browser API)
+ * - Audio data streams to main process via IPC
+ * - Main process handles buffering, VAD, and recovery
+ *
+ * Why this approach:
+ * - getUserMedia is only available in renderer (browser context)
+ * - Main process provides reliability, buffering, and transcription coordination
+ * - IPC overhead is minimal for 100ms chunks at 16kHz mono
+ */
+
+import { ipcMain, systemPreferences, BrowserWindow } from 'electron';
+import { EventEmitter } from 'events';
+import { writeFile, unlink, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { app } from 'electron';
+import { errorHandler } from '../ErrorHandler';
+import { IPC_CHANNELS } from '../../shared/types';
+import { extensionFromMimeType, encodeFloat32Wav } from './audioUtils';
+
+// ============================================================================
+// Types and Interfaces
+// ============================================================================
+
+export interface AudioDevice {
+  id: string;
+  name: string;
+  isDefault: boolean;
+}
+
+export interface AudioChunk {
+  buffer: Buffer;
+  timestamp: number;
+  duration: number;
+  sampleRate: number;
+}
+
+export interface CapturedAudioAsset {
+  buffer: Buffer;
+  mimeType: string;
+  durationMs: number;
+}
+
+export interface AudioCaptureConfig {
+  sampleRate: number;
+  channels: number;
+  chunkDurationMs: number;
+  vadThreshold: number;
+  vadSilenceMs: number;
+  recoveryBufferMinutes: number;
+}
+
+export interface AudioCaptureService {
+  checkPermission(): Promise<boolean>;
+  requestPermission(): Promise<boolean>;
+  getDevices(): Promise<AudioDevice[]>;
+  setDevice(deviceId: string): void;
+  setPaused(paused: boolean): void;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  getAudioLevel(): number;
+  isCapturing(): boolean;
+  getCapturedAudioBuffer(): Buffer | null;
+  getCapturedAudioAsset(): CapturedAudioAsset | null;
+  exportCapturedAudio(
+    filePathBase: string
+  ): Promise<{ path: string; bytesWritten: number; durationMs: number; mimeType: string } | null>;
+  exportCapturedAudioWav(filePath: string): Promise<{ bytesWritten: number; durationMs: number } | null>;
+  clearCapturedAudio(): void;
+
+  // Event handlers
+  onAudioChunk: (callback: (chunk: AudioChunk) => void) => () => void;
+  onVoiceActivity: (callback: (active: boolean) => void) => () => void;
+  onError: (callback: (error: Error) => void) => () => void;
+  onAudioLevel: (callback: (level: number) => void) => () => void;
+}
+
+// ============================================================================
+// IPC Channel Constants
+// ============================================================================
+
+export const AUDIO_IPC_CHANNELS = {
+  // Main -> Renderer requests
+  REQUEST_DEVICES: IPC_CHANNELS.AUDIO_REQUEST_DEVICES,
+  START_CAPTURE: IPC_CHANNELS.AUDIO_START_CAPTURE,
+  STOP_CAPTURE: IPC_CHANNELS.AUDIO_STOP_CAPTURE,
+  SET_DEVICE: IPC_CHANNELS.AUDIO_SET_DEVICE,
+
+  // Renderer -> Main data
+  AUDIO_CHUNK: IPC_CHANNELS.AUDIO_CHUNK,
+  DEVICES_RESPONSE: IPC_CHANNELS.AUDIO_DEVICES_RESPONSE,
+  CAPTURE_ERROR: IPC_CHANNELS.AUDIO_CAPTURE_ERROR,
+  CAPTURE_STARTED: IPC_CHANNELS.AUDIO_CAPTURE_STARTED,
+  CAPTURE_STOPPED: IPC_CHANNELS.AUDIO_CAPTURE_STOPPED,
+} as const;
+
+// ============================================================================
+// Default Configuration
+// ============================================================================
+
+const DEFAULT_CONFIG: AudioCaptureConfig = {
+  sampleRate: 16000,
+  channels: 1, // Mono
+  chunkDurationMs: 250,
+  vadThreshold: 0.01, // RMS threshold for voice detection
+  vadSilenceMs: 600, // Consecutive silence before marking inactive
+  recoveryBufferMinutes: 5, // Rotate buffer files every 5 minutes
+};
+
+// ============================================================================
+// AudioCaptureService Implementation
+// ============================================================================
+
+class AudioCaptureServiceImpl extends EventEmitter implements AudioCaptureService {
+  private config: AudioCaptureConfig;
+  private capturing: boolean = false;
+  private stopRequested: boolean = false;
+  private stopFinalizeTimer: NodeJS.Timeout | null = null;
+  private stopPromise: Promise<void> | null = null;
+  private resolveStopPromise: (() => void) | null = null;
+  private currentDeviceId: string | null = null;
+  private currentAudioLevel: number = 0;
+  private voiceActive: boolean = false;
+  private paused: boolean = false;
+  private silenceStartTime: number = 0;
+  private mainWindow: BrowserWindow | null = null;
+
+  // Recovery buffer management
+  private recoveryBufferPath: string;
+  private currentBufferFile: string | null = null;
+  private bufferStartTime: number = 0;
+  private recoveryChunks: Buffer[] = [];
+  private recoveryInterval: NodeJS.Timeout | null = null;
+
+  // Full-session audio capture (used for post-session transcription + retry workflows)
+  private sessionAudioChunks: Buffer[] = [];
+  private sessionAudioBytes: number = 0;
+  private sessionAudioDurationMs: number = 0;
+  private sessionAudioMimeType: string = 'audio/wav';
+  private encodedAudioChunks: Buffer[] = [];
+  private encodedAudioBytes: number = 0;
+  private encodedAudioDurationMs: number = 0;
+  private encodedAudioMimeType: string | null = null;
+
+  constructor(config: Partial<AudioCaptureConfig> = {}) {
+    super();
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.recoveryBufferPath = join(app.getPath('temp'), 'markupr-audio');
+    this.setupIPCHandlers();
+  }
+
+  /**
+   * Set the main window reference for IPC communication
+   */
+  setMainWindow(window: BrowserWindow): void {
+    this.mainWindow = window;
+  }
+
+  // ==========================================================================
+  // Permission Management
+  // ==========================================================================
+
+  /**
+   * Check if microphone permission is granted (macOS only)
+   */
+  async checkPermission(): Promise<boolean> {
+    if (process.platform !== 'darwin') {
+      // Non-macOS platforms don't have system-level permission checks
+      return true;
+    }
+
+    const status = systemPreferences.getMediaAccessStatus('microphone');
+    const granted = status === 'granted';
+
+    if (!granted) {
+      errorHandler.log('info', 'Microphone permission not granted', {
+        component: 'AudioCapture',
+        operation: 'checkPermission',
+        data: { status },
+      });
+    }
+
+    return granted;
+  }
+
+  /**
+   * Request microphone permission (macOS only)
+   * Returns true if granted, false if denied
+   */
+  async requestPermission(): Promise<boolean> {
+    if (process.platform !== 'darwin') {
+      return true;
+    }
+
+    const status = systemPreferences.getMediaAccessStatus('microphone');
+
+    if (status === 'granted') {
+      return true;
+    }
+
+    if (status === 'denied') {
+      // User previously denied, they need to enable in System Preferences
+      return false;
+    }
+
+    // Status is 'not-determined' or 'restricted', request permission
+    try {
+      const granted = await systemPreferences.askForMediaAccess('microphone');
+
+      if (!granted) {
+        errorHandler.log('warn', 'Microphone permission denied by user', {
+          component: 'AudioCapture',
+          operation: 'requestPermission',
+        });
+      }
+
+      return granted;
+    } catch (error) {
+      errorHandler.log('error', 'Permission request failed', {
+        component: 'AudioCapture',
+        operation: 'requestPermission',
+        error: (error as Error).message,
+      });
+      return false;
+    }
+  }
+
+  // ==========================================================================
+  // Device Management
+  // ==========================================================================
+
+  /**
+   * Get list of available audio input devices
+   * This requests device list from renderer via IPC
+   */
+  async getDevices(): Promise<AudioDevice[]> {
+    return new Promise((resolve, reject) => {
+      if (!this.mainWindow) {
+        reject(new Error('Main window not set'));
+        return;
+      }
+
+      const timeout = setTimeout(() => {
+        reject(new Error('Device enumeration timeout'));
+      }, 5000);
+
+      const handler = (_event: Electron.IpcMainEvent, devices: AudioDevice[]) => {
+        clearTimeout(timeout);
+        ipcMain.removeListener(AUDIO_IPC_CHANNELS.DEVICES_RESPONSE, handler);
+        resolve(devices);
+      };
+
+      ipcMain.on(AUDIO_IPC_CHANNELS.DEVICES_RESPONSE, handler);
+      this.mainWindow.webContents.send(AUDIO_IPC_CHANNELS.REQUEST_DEVICES);
+    });
+  }
+
+  /**
+   * Set the audio input device to use
+   */
+  setDevice(deviceId: string): void {
+    this.currentDeviceId = deviceId;
+    if (this.capturing && this.mainWindow) {
+      // If already capturing, notify renderer to switch device
+      this.mainWindow.webContents.send(AUDIO_IPC_CHANNELS.SET_DEVICE, deviceId);
+    }
+  }
+
+  // ==========================================================================
+  // Capture Control
+  // ==========================================================================
+
+  /**
+   * Start audio capture
+   */
+  async start(): Promise<void> {
+    if (this.capturing) {
+      errorHandler.log('info', 'Audio capture already in progress', {
+        component: 'AudioCapture',
+        operation: 'start',
+      });
+      return;
+    }
+
+    // Check permission first
+    const hasPermission = await this.checkPermission();
+    if (!hasPermission) {
+      const granted = await this.requestPermission();
+      if (!granted) {
+        const permError = new Error('Microphone permission denied');
+        errorHandler.handleAudioError(permError, {
+          component: 'AudioCapture',
+          operation: 'start',
+        });
+        throw permError;
+      }
+    }
+
+    if (!this.mainWindow) {
+      const windowError = new Error('Main window not set');
+      errorHandler.log('error', 'Cannot start audio - no main window', {
+        component: 'AudioCapture',
+        operation: 'start',
+      });
+      throw windowError;
+    }
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('Audio capture start timeout'));
+      }, 10000);
+
+      const successHandler = () => {
+        clearTimeout(timeout);
+        ipcMain.removeListener(AUDIO_IPC_CHANNELS.CAPTURE_STARTED, successHandler);
+        ipcMain.removeListener(AUDIO_IPC_CHANNELS.CAPTURE_ERROR, errorHandler);
+
+        this.capturing = true;
+        this.stopRequested = false;
+        this.settleStopPromise();
+        if (this.stopFinalizeTimer) {
+          clearTimeout(this.stopFinalizeTimer);
+          this.stopFinalizeTimer = null;
+        }
+        this.paused = false;
+        this.sessionAudioChunks = [];
+        this.sessionAudioBytes = 0;
+        this.sessionAudioDurationMs = 0;
+        this.sessionAudioMimeType = 'audio/wav';
+        this.encodedAudioChunks = [];
+        this.encodedAudioBytes = 0;
+        this.encodedAudioDurationMs = 0;
+        this.encodedAudioMimeType = null;
+        this.startRecoveryBuffer();
+        console.log('[AudioCapture] Capture started');
+        resolve();
+      };
+
+      const errorHandler = (_event: Electron.IpcMainEvent, error: string) => {
+        clearTimeout(timeout);
+        ipcMain.removeListener(AUDIO_IPC_CHANNELS.CAPTURE_STARTED, successHandler);
+        ipcMain.removeListener(AUDIO_IPC_CHANNELS.CAPTURE_ERROR, errorHandler);
+        reject(new Error(error));
+      };
+
+      ipcMain.once(AUDIO_IPC_CHANNELS.CAPTURE_STARTED, successHandler);
+      ipcMain.once(AUDIO_IPC_CHANNELS.CAPTURE_ERROR, errorHandler);
+
+      // Send start command to renderer with config
+      this.mainWindow!.webContents.send(AUDIO_IPC_CHANNELS.START_CAPTURE, {
+        deviceId: this.currentDeviceId,
+        sampleRate: this.config.sampleRate,
+        channels: this.config.channels,
+        chunkDurationMs: this.config.chunkDurationMs,
+      });
+    });
+  }
+
+  /**
+   * Stop audio capture
+   */
+  async stop(): Promise<void> {
+    if (!this.capturing) {
+      this.stopRequested = false;
+      this.settleStopPromise();
+      return;
+    }
+
+    if (this.stopRequested && this.stopPromise) {
+      return this.stopPromise;
+    }
+
+    const stopPromise = this.ensureStopPromise();
+    this.stopRequested = true;
+    this.paused = false;
+
+    if (this.mainWindow) {
+      this.mainWindow.webContents.send(AUDIO_IPC_CHANNELS.STOP_CAPTURE);
+    } else {
+      this.finalizeCaptureStop('timeout');
+      return stopPromise;
+    }
+
+    if (this.stopFinalizeTimer) {
+      clearTimeout(this.stopFinalizeTimer);
+    }
+    this.stopFinalizeTimer = setTimeout(() => {
+      this.finalizeCaptureStop('timeout');
+    }, 1500);
+
+    console.log('[AudioCapture] Stop requested; awaiting renderer flush');
+    return stopPromise;
+  }
+
+  /**
+   * Check if currently capturing
+   */
+  isCapturing(): boolean {
+    return this.capturing;
+  }
+
+  setPaused(paused: boolean): void {
+    this.paused = paused;
+    if (paused) {
+      this.voiceActive = false;
+      this.currentAudioLevel = 0;
+      this.emit('audioLevel', 0);
+      this.emit('voiceActivity', false);
+    }
+  }
+
+  /**
+   * Get current audio level (0-1 normalized)
+   */
+  getAudioLevel(): number {
+    return this.currentAudioLevel;
+  }
+
+  /**
+   * Export captured audio with the most accurate available source format.
+   * Encoded MediaRecorder audio is preserved as-is; PCM falls back to WAV.
+   */
+  async exportCapturedAudio(
+    filePathBase: string
+  ): Promise<{ path: string; bytesWritten: number; durationMs: number; mimeType: string } | null> {
+    const encodedAsset = this.getCapturedEncodedAudioAsset();
+    if (encodedAsset) {
+      const extension = extensionFromMimeType(encodedAsset.mimeType);
+      const outputPath = `${filePathBase}${extension}`;
+      await mkdir(dirname(outputPath), { recursive: true });
+      await writeFile(outputPath, encodedAsset.buffer);
+      return {
+        path: outputPath,
+        bytesWritten: encodedAsset.buffer.byteLength,
+        durationMs: encodedAsset.durationMs,
+        mimeType: encodedAsset.mimeType,
+      };
+    }
+
+    const pcmAsset = this.getCapturedPcmAudioAsset();
+    if (!pcmAsset) {
+      return null;
+    }
+
+    const outputPath = `${filePathBase}.wav`;
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, pcmAsset.buffer);
+    return {
+      path: outputPath,
+      bytesWritten: pcmAsset.buffer.byteLength,
+      durationMs: pcmAsset.durationMs,
+      mimeType: 'audio/wav',
+    };
+  }
+
+  /**
+   * Backward-compatible WAV export wrapper.
+   */
+  async exportCapturedAudioWav(
+    filePath: string
+  ): Promise<{ bytesWritten: number; durationMs: number } | null> {
+    const rawAudio = this.getCapturedAudioBuffer();
+    if (!rawAudio) {
+      return null;
+    }
+
+    const wavBuffer = encodeFloat32Wav(rawAudio, this.config.sampleRate, this.config.channels);
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, wavBuffer);
+
+    const durationMs =
+      (rawAudio.byteLength / (this.config.channels * this.config.sampleRate * 4)) * 1000;
+    return {
+      bytesWritten: wavBuffer.byteLength,
+      durationMs,
+    };
+  }
+
+  /**
+   * Clear in-memory session audio data.
+   */
+  clearCapturedAudio(): void {
+    this.sessionAudioChunks = [];
+    this.sessionAudioBytes = 0;
+    this.sessionAudioDurationMs = 0;
+    this.sessionAudioMimeType = 'audio/wav';
+    this.encodedAudioChunks = [];
+    this.encodedAudioBytes = 0;
+    this.encodedAudioDurationMs = 0;
+    this.encodedAudioMimeType = null;
+  }
+
+  // ==========================================================================
+  // Event Subscription
+  // ==========================================================================
+
+  onAudioChunk(callback: (chunk: AudioChunk) => void): () => void {
+    this.on('audioChunk', callback);
+    return () => this.off('audioChunk', callback);
+  }
+
+  onVoiceActivity(callback: (active: boolean) => void): () => void {
+    this.on('voiceActivity', callback);
+    return () => this.off('voiceActivity', callback);
+  }
+
+  onError(callback: (error: Error) => void): () => void {
+    this.on('error', callback);
+    return () => this.off('error', callback);
+  }
+
+  onAudioLevel(callback: (level: number) => void): () => void {
+    this.on('audioLevel', callback);
+    return () => this.off('audioLevel', callback);
+  }
+
+  // ==========================================================================
+  // IPC Handlers
+  // ==========================================================================
+
+  private setupIPCHandlers(): void {
+    // Handle incoming audio chunks from renderer
+    ipcMain.on(AUDIO_IPC_CHANNELS.AUDIO_CHUNK, this.handleAudioChunk.bind(this));
+
+    // Handle capture errors from renderer
+    ipcMain.on(AUDIO_IPC_CHANNELS.CAPTURE_ERROR, (_event, error: string) => {
+      const captureError = new Error(error);
+      errorHandler.handleAudioError(captureError, {
+        component: 'AudioCapture',
+        operation: 'rendererCapture',
+      });
+      this.emit('error', captureError);
+    });
+
+    // Handle capture stopped (e.g., device disconnected)
+    ipcMain.on(AUDIO_IPC_CHANNELS.CAPTURE_STOPPED, () => {
+      if (this.stopRequested) {
+        this.finalizeCaptureStop('normal');
+        return;
+      }
+
+      if (this.capturing) {
+        this.capturing = false;
+        this.stopRecoveryBuffer();
+        const stopError = new Error('Audio capture stopped unexpectedly');
+        errorHandler.handleAudioError(stopError, {
+          component: 'AudioCapture',
+          operation: 'captureStop',
+          data: { unexpected: true },
+        });
+        this.emit('error', stopError);
+      }
+    });
+  }
+
+  private finalizeCaptureStop(reason: 'normal' | 'timeout'): void {
+    if (!this.capturing && !this.stopRequested) {
+      this.settleStopPromise();
+      return;
+    }
+
+    if (this.stopFinalizeTimer) {
+      clearTimeout(this.stopFinalizeTimer);
+      this.stopFinalizeTimer = null;
+    }
+
+    this.stopRequested = false;
+    this.capturing = false;
+    this.stopRecoveryBuffer();
+
+    this.voiceActive = false;
+    this.currentAudioLevel = 0;
+    this.emit('audioLevel', 0);
+    this.emit('voiceActivity', false);
+
+    console.log(`[AudioCapture] Capture stopped (${reason})`);
+    this.settleStopPromise();
+  }
+
+  private ensureStopPromise(): Promise<void> {
+    if (this.stopPromise) {
+      return this.stopPromise;
+    }
+
+    this.stopPromise = new Promise<void>((resolve) => {
+      this.resolveStopPromise = resolve;
+    });
+    return this.stopPromise;
+  }
+
+  private settleStopPromise(): void {
+    if (this.resolveStopPromise) {
+      this.resolveStopPromise();
+      this.resolveStopPromise = null;
+    }
+    this.stopPromise = null;
+  }
+
+  /**
+   * Process incoming audio chunk from renderer
+   */
+  private handleAudioChunk(
+    _event: Electron.IpcMainEvent,
+    data: {
+      samples?: number[];
+      encodedChunk?: Buffer | Uint8Array | ArrayBuffer;
+      mimeType?: string;
+      audioLevel?: number;
+      rms?: number;
+      timestamp: number;
+      duration: number;
+    }
+  ): void {
+    if (!this.capturing) return;
+
+    if (this.paused) {
+      return;
+    }
+
+    if (Array.isArray(data.samples) && data.samples.length > 0) {
+      const float32 = new Float32Array(data.samples);
+      const buffer = Buffer.from(float32.buffer);
+
+      // Calculate RMS for VAD and level visualization
+      const rms = this.calculateRMS(float32);
+      this.currentAudioLevel = Math.min(1, rms * 10);
+      this.emit('audioLevel', this.currentAudioLevel);
+
+      // Voice Activity Detection
+      this.updateVAD(rms, data.timestamp);
+
+      // Create chunk object
+      const chunk: AudioChunk = {
+        buffer,
+        timestamp: data.timestamp,
+        duration: data.duration,
+        sampleRate: this.config.sampleRate,
+      };
+
+      // Add to recovery/session buffers
+      this.recoveryChunks.push(buffer);
+      this.sessionAudioChunks.push(buffer);
+      this.sessionAudioBytes += buffer.byteLength;
+      this.sessionAudioDurationMs += Math.max(0, data.duration || this.config.chunkDurationMs);
+      this.sessionAudioMimeType = 'audio/wav';
+
+      this.emit('audioChunk', chunk);
+      return;
+    }
+
+    const encodedBuffer = this.toBuffer(data.encodedChunk);
+    if (!encodedBuffer || encodedBuffer.byteLength === 0) {
+      return;
+    }
+
+    this.encodedAudioChunks.push(encodedBuffer);
+    this.encodedAudioBytes += encodedBuffer.byteLength;
+    this.encodedAudioDurationMs += Math.max(0, data.duration || this.config.chunkDurationMs);
+    this.encodedAudioMimeType = data.mimeType || this.encodedAudioMimeType || 'audio/webm';
+    this.recoveryChunks.push(encodedBuffer);
+
+    // Prefer renderer-provided live RMS/level from real audio analysis.
+    const level =
+      Number.isFinite(data.audioLevel)
+        ? Math.max(0, Math.min(1, Number(data.audioLevel)))
+        : Math.max(0, Math.min(1, encodedBuffer.byteLength / 6000));
+    this.currentAudioLevel = level;
+    this.emit('audioLevel', level);
+
+    const rms =
+      Number.isFinite(data.rms)
+        ? Math.max(0, Math.min(1, Number(data.rms)))
+        : Math.max(0, (level - 0.08) * 0.06);
+    this.updateVAD(rms, data.timestamp);
+  }
+
+  // ==========================================================================
+  // Voice Activity Detection
+  // ==========================================================================
+
+  /**
+   * Calculate Root Mean Square of audio samples
+   */
+  private calculateRMS(samples: Float32Array): number {
+    let sum = 0;
+    for (let i = 0; i < samples.length; i++) {
+      sum += samples[i] * samples[i];
+    }
+    return Math.sqrt(sum / samples.length);
+  }
+
+  /**
+   * Update voice activity state based on RMS
+   */
+  private updateVAD(rms: number, timestamp: number): void {
+    const isVoice = rms > this.config.vadThreshold;
+
+    if (isVoice) {
+      // Voice detected
+      if (!this.voiceActive) {
+        this.voiceActive = true;
+        this.emit('voiceActivity', true);
+        console.log('[AudioCapture] Voice activity started');
+      }
+      this.silenceStartTime = 0;
+    } else {
+      // Silence detected
+      if (this.voiceActive) {
+        if (this.silenceStartTime === 0) {
+          this.silenceStartTime = timestamp;
+        } else if (timestamp - this.silenceStartTime > this.config.vadSilenceMs) {
+          // Enough silence, mark as inactive
+          this.voiceActive = false;
+          this.emit('voiceActivity', false);
+          this.silenceStartTime = 0;
+          console.log('[AudioCapture] Voice activity ended');
+        }
+      }
+    }
+  }
+
+  // ==========================================================================
+  // Recovery Buffer Management
+  // ==========================================================================
+
+  /**
+   * Start the recovery buffer system
+   * Writes audio to temp files for network failure recovery
+   */
+  private async startRecoveryBuffer(): Promise<void> {
+    // Ensure recovery directory exists
+    if (!existsSync(this.recoveryBufferPath)) {
+      await mkdir(this.recoveryBufferPath, { recursive: true });
+    }
+
+    this.bufferStartTime = Date.now();
+    this.recoveryChunks = [];
+    this.currentBufferFile = this.generateBufferFilename();
+
+    // Rotate buffer every recoveryBufferMinutes
+    this.recoveryInterval = setInterval(
+      () => this.rotateRecoveryBuffer(),
+      this.config.recoveryBufferMinutes * 60 * 1000
+    );
+
+    console.log('[AudioCapture] Recovery buffer started');
+  }
+
+  /**
+   * Stop the recovery buffer system
+   */
+  private stopRecoveryBuffer(): void {
+    if (this.recoveryInterval) {
+      clearInterval(this.recoveryInterval);
+      this.recoveryInterval = null;
+    }
+
+    // Write remaining chunks
+    if (this.recoveryChunks.length > 0) {
+      this.writeRecoveryBuffer().catch((err) => {
+        console.error('[AudioCapture] Failed to write final recovery buffer:', err);
+      });
+    }
+
+    this.recoveryChunks = [];
+    console.log('[AudioCapture] Recovery buffer stopped');
+  }
+
+  /**
+   * Rotate the recovery buffer - write current and start new
+   */
+  private async rotateRecoveryBuffer(): Promise<void> {
+    await this.writeRecoveryBuffer();
+
+    // Clean up old buffer files (keep last 2)
+    await this.cleanOldBuffers();
+
+    // Start new buffer
+    this.bufferStartTime = Date.now();
+    this.recoveryChunks = [];
+    this.currentBufferFile = this.generateBufferFilename();
+  }
+
+  /**
+   * Write current recovery buffer to disk
+   */
+  private async writeRecoveryBuffer(): Promise<void> {
+    if (this.recoveryChunks.length === 0 || !this.currentBufferFile) {
+      return;
+    }
+
+    try {
+      const combined = Buffer.concat(this.recoveryChunks);
+      await writeFile(this.currentBufferFile, combined);
+      console.log(
+        `[AudioCapture] Recovery buffer written: ${this.currentBufferFile} (${combined.length} bytes)`
+      );
+    } catch (error) {
+      console.error('[AudioCapture] Failed to write recovery buffer:', error);
+    }
+  }
+
+  /**
+   * Generate a unique buffer filename
+   */
+  private generateBufferFilename(): string {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return join(this.recoveryBufferPath, `audio-${timestamp}.raw`);
+  }
+
+  /**
+   * Clean up old recovery buffer files
+   */
+  private async cleanOldBuffers(): Promise<void> {
+    try {
+      const { readdir, stat } = await import('fs/promises');
+      const files = await readdir(this.recoveryBufferPath);
+
+      const bufferFiles = await Promise.all(
+        files
+          .filter((f) => f.startsWith('audio-') && f.endsWith('.raw'))
+          .map(async (f) => {
+            const path = join(this.recoveryBufferPath, f);
+            const stats = await stat(path);
+            return { path, mtime: stats.mtime.getTime() };
+          })
+      );
+
+      // Sort by modification time, newest first
+      bufferFiles.sort((a, b) => b.mtime - a.mtime);
+
+      // Delete all but the 2 most recent
+      for (let i = 2; i < bufferFiles.length; i++) {
+        await unlink(bufferFiles[i].path);
+        console.log(`[AudioCapture] Deleted old buffer: ${bufferFiles[i].path}`);
+      }
+    } catch (error) {
+      console.error('[AudioCapture] Failed to clean old buffers:', error);
+    }
+  }
+
+  /**
+   * Get recovery buffers for replay after network failure
+   * Returns buffers from the last N minutes
+   */
+  async getRecoveryBuffers(lastMinutes: number = 5): Promise<Buffer[]> {
+    const buffers: Buffer[] = [];
+    const cutoff = Date.now() - lastMinutes * 60 * 1000;
+
+    try {
+      const { readdir, stat, readFile } = await import('fs/promises');
+      const files = await readdir(this.recoveryBufferPath);
+
+      for (const file of files) {
+        if (!file.startsWith('audio-') || !file.endsWith('.raw')) continue;
+
+        const path = join(this.recoveryBufferPath, file);
+        const stats = await stat(path);
+
+        if (stats.mtime.getTime() > cutoff) {
+          const data = await readFile(path);
+          buffers.push(data);
+        }
+      }
+
+      // Include current in-memory chunks
+      if (this.recoveryChunks.length > 0) {
+        buffers.push(Buffer.concat(this.recoveryChunks));
+      }
+
+      console.log(`[AudioCapture] Retrieved ${buffers.length} recovery buffers`);
+    } catch (error) {
+      console.error('[AudioCapture] Failed to get recovery buffers:', error);
+    }
+
+    return buffers;
+  }
+
+  /**
+   * Clear all recovery buffers
+   */
+  async clearRecoveryBuffers(): Promise<void> {
+    try {
+      const { readdir } = await import('fs/promises');
+      const files = await readdir(this.recoveryBufferPath);
+
+      for (const file of files) {
+        if (file.startsWith('audio-') && file.endsWith('.raw')) {
+          await unlink(join(this.recoveryBufferPath, file));
+        }
+      }
+
+      this.recoveryChunks = [];
+      console.log('[AudioCapture] Recovery buffers cleared');
+    } catch (error) {
+      console.error('[AudioCapture] Failed to clear recovery buffers:', error);
+    }
+  }
+
+  /**
+   * Build a single buffer from all captured session chunks.
+   */
+  getCapturedAudioBuffer(): Buffer | null {
+    if (this.sessionAudioChunks.length === 0 || this.sessionAudioBytes === 0) {
+      return null;
+    }
+    return Buffer.concat(this.sessionAudioChunks, this.sessionAudioBytes);
+  }
+
+  getCapturedAudioAsset(): CapturedAudioAsset | null {
+    const encoded = this.getCapturedEncodedAudioAsset();
+    if (encoded) {
+      return encoded;
+    }
+
+    return this.getCapturedPcmAudioAsset();
+  }
+
+  private getCapturedPcmAudioAsset(): CapturedAudioAsset | null {
+    const rawAudio = this.getCapturedAudioBuffer();
+    if (!rawAudio) {
+      return null;
+    }
+
+    const wavBuffer = encodeFloat32Wav(rawAudio, this.config.sampleRate, this.config.channels);
+    const durationMs =
+      this.sessionAudioDurationMs > 0
+        ? this.sessionAudioDurationMs
+        : (rawAudio.byteLength / (this.config.channels * this.config.sampleRate * 4)) * 1000;
+
+    return {
+      buffer: wavBuffer,
+      mimeType: 'audio/wav',
+      durationMs,
+    };
+  }
+
+  private getCapturedEncodedAudioAsset(): CapturedAudioAsset | null {
+    if (this.encodedAudioChunks.length === 0 || this.encodedAudioBytes === 0) {
+      return null;
+    }
+
+    return {
+      buffer: Buffer.concat(this.encodedAudioChunks, this.encodedAudioBytes),
+      mimeType: this.encodedAudioMimeType || 'audio/webm',
+      durationMs: this.encodedAudioDurationMs,
+    };
+  }
+
+  private toBuffer(chunk: Buffer | Uint8Array | ArrayBuffer | undefined): Buffer | null {
+    if (!chunk) {
+      return null;
+    }
+    if (Buffer.isBuffer(chunk)) {
+      return chunk;
+    }
+    if (chunk instanceof ArrayBuffer) {
+      return Buffer.from(chunk);
+    }
+    if (ArrayBuffer.isView(chunk)) {
+      return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+    }
+    return null;
+  }
+
+}
+
+// ============================================================================
+// Singleton Export
+// ============================================================================
+
+export const audioCapture = new AudioCaptureServiceImpl();
+export { AudioCaptureServiceImpl };
+export default audioCapture;