/**
 * Speech Types
 *
 * Shared types for speech-to-text (STT) and text-to-speech (TTS) services.
 * Used by provider interfaces and the SpeechService.
 *
 * Issue #389
 */

// ==========================================
// Enums / Discriminators
// ==========================================

/**
 * Canonical array of TTS provider tiers.
 * Determines which TTS engine is used for synthesis.
 *
 * - default: Primary TTS engine (e.g., Kokoro)
 * - premium: Higher quality TTS engine (e.g., Chatterbox)
 * - fallback: Backup TTS engine (e.g., Piper/OpenedAI)
 */
export const SPEECH_TIERS = ["default", "premium", "fallback"] as const;
export type SpeechTier = (typeof SPEECH_TIERS)[number];

/**
 * Canonical array of audio output formats for TTS synthesis.
 */
export const AUDIO_FORMATS = ["mp3", "wav", "opus", "flac", "aac", "pcm"] as const;
export type AudioFormat = (typeof AUDIO_FORMATS)[number];

// ==========================================
// STT Types
// ==========================================

/**
 * Options for speech-to-text transcription.
 */
export interface TranscribeOptions {
  /** Language code (e.g., "en", "fr", "de") */
  language?: string;

  /** Model to use for transcription */
  model?: string;

  /** MIME type of the audio (e.g., "audio/mp3", "audio/wav") */
  mimeType?: string;

  /** Optional prompt to guide transcription */
  prompt?: string;

  /** Temperature for transcription (0.0 - 1.0) */
  temperature?: number;
}

/**
 * Result of a speech-to-text transcription.
 */
export interface TranscriptionResult {
  /** Transcribed text */
  text: string;

  /** Language detected or used */
  language: string;

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

  /** Confidence score (0.0 - 1.0, if available) */
  confidence?: number;

  /** Individual word or segment timings (if available) */
  segments?: TranscriptionSegment[];
}

/**
 * A segment within a transcription result.
 */
export interface TranscriptionSegment {
  /** Segment text */
  text: string;

  /** Start time in seconds */
  start: number;

  /** End time in seconds */
  end: number;

  /** Confidence for this segment */
  confidence?: number;
}

// ==========================================
// TTS Types
// ==========================================

/**
 * Options for text-to-speech synthesis.
 */
export interface SynthesizeOptions {
  /** Voice ID to use */
  voice?: string;

  /** Desired audio format */
  format?: AudioFormat;

  /** Speech speed multiplier (0.5 - 2.0) */
  speed?: number;

  /** Preferred TTS tier */
  tier?: SpeechTier;
}

/**
 * Result of a text-to-speech synthesis.
 */
export interface SynthesisResult {
  /** Synthesized audio data */
  audio: Buffer;

  /** Audio format of the result */
  format: AudioFormat;

  /** Voice used for synthesis */
  voice: string;

  /** Tier that produced the synthesis */
  tier: SpeechTier;

  /** Duration of the generated audio in seconds (if available) */
  durationSeconds?: number;
}

/**
 * Extended options for Chatterbox TTS synthesis.
 *
 * Chatterbox supports voice cloning via a reference audio buffer and
 * emotion exaggeration control. These are passed as extra body parameters
 * to the OpenAI-compatible API.
 *
 * Issue #394
 */
export interface ChatterboxSynthesizeOptions extends SynthesizeOptions {
  /**
   * Reference audio buffer for voice cloning.
   * When provided, Chatterbox will clone the voice from this audio sample.
   * Should be a WAV or MP3 file of 5-30 seconds for best results.
   */
  referenceAudio?: Buffer;

  /**
   * Emotion exaggeration factor (0.0 to 1.0).
   * Controls how much emotional expression is applied to the synthesized speech.
   * - 0.0: Neutral, minimal emotion
   * - 0.5: Moderate emotion (default when not specified)
   * - 1.0: Maximum emotion exaggeration
   */
  emotionExaggeration?: number;
}

/**
 * Information about an available TTS voice.
 */
export interface VoiceInfo {
  /** Voice identifier */
  id: string;

  /** Human-readable voice name */
  name: string;

  /** Language code */
  language?: string;

  /** Tier this voice belongs to */
  tier: SpeechTier;

  /** Whether this is the default voice for its tier */
  isDefault?: boolean;
}
