/**
 * Cloud-agnostic speech-to-text abstraction.
 *
 * Providers implement SpeechTranscriber to wrap platform-specific SDKs
 * (Azure Speech, Google Cloud Speech, Deepgram, local Whisper, etc.)
 * behind a unified push-audio + callback interface.
 */

/** Callback for partial (interim) transcription results. */
export type PartialCallback = (text: string) => void;

/** Callback for final (committed) transcription results. */
export type FinalCallback = (text: string, confidence: number) => void;

/** Callback for transcription errors. */
export type ErrorCallback = (error: Error) => void;

/**
 * Cloud-agnostic streaming speech-to-text interface.
 *
 * Audio is pushed in chunks (PCM 16-bit, 16kHz, mono by convention).
 * Results are delivered asynchronously via callbacks.
 */
export interface SpeechTranscriber {
  /** Start continuous recognition for the given language. */
  start(language?: string): Promise<void> | void;

  /** Stop recognition and finalize any pending results. */
  stop(): Promise<string> | string;

  /** Push raw audio data (PCM 16-bit, 16kHz, mono). */
  pushAudio(data: ArrayBuffer | Uint8Array): void;

  /** Register callback for partial (interim) results. */
  onPartial(callback: PartialCallback): void;

  /** Register callback for final (committed) results. */
  onFinal(callback: FinalCallback): void;

  /** Register callback for errors. */
  onError(callback: ErrorCallback): void;

  /** Set custom vocabulary / phrase hints for better accuracy. */
  setVocabulary?(phrases: string[]): void;

  /** Whether the transcriber is currently active. */
  readonly isActive: boolean;
}

/** Configuration for creating a speech transcriber. */
export interface SpeechConfig {
  /** Provider type. */
  provider: 'azure' | 'whisper' | 'google' | 'deepgram' | 'mock';

  /** Azure-specific: speech service key. */
  speechKey?: string;

  /** Azure-specific: speech service region. */
  speechRegion?: string;

  /** Whisper-specific: model size (tiny, base, small, medium, large). */
  whisperModelSize?: string;

  /** Default language (BCP-47 code, e.g. 'en-US'). */
  language?: string;

  /** Custom vocabulary phrases for better accuracy. */
  vocabulary?: string[];
}

/** Result of a completed transcription session. */
export interface TranscriptionResult {
  /** Full transcribed text. */
  text: string;

  /** Confidence score (0-1), if available. */
  confidence?: number;

  /** Duration of audio in seconds. */
  durationSeconds?: number;

  /** Which provider produced this result. */
  provider: string;
}
