// Platform-agnostic audio decoding contract.
//
// The job of a decoder is to take some encoded audio (a browser-decodable blob
// on web, a file URI on native) and return `PcmAudio`: 16 kHz mono Float32
// samples in [-1, 1], exactly what Whisper expects.
//
// This file holds ONLY the types/interface. The actual implementations live in
// platform-specific siblings (`decode.web.ts` / `decode.native.ts`) which Metro
// resolves by platform. Consumers should import the resolved `decoder` via
// `index.ts` (`getDecoder()`), never the platform files directly.

import type { PcmAudio } from '../types';

/**
 * Input to a decoder. Which field is required depends on the platform:
 *
 * - Web reads from in-memory `data` (an `ArrayBuffer`, e.g. from a `<input
 *   type="file">` / drag-and-drop `File.arrayBuffer()`). Nothing is uploaded.
 * - Native reads from a `file://` (or content) `uri` on disk.
 *
 * `name` is an optional original filename, used only for diagnostics / to sniff
 * the container extension; decoders must not depend on it being present.
 */
export interface AudioFileInput {
  /** Encoded bytes held in memory. Required on web. */
  data?: ArrayBuffer;
  /** On-disk location of the encoded file. Required on native. */
  uri?: string;
  /** Original filename, if known (used for extension sniffing / errors). */
  name?: string;
}

/**
 * Decodes encoded audio into Whisper-ready PCM (16 kHz, mono, [-1, 1]).
 * Implementations are platform-specific; see `decode.web.ts` /
 * `decode.native.ts`.
 */
export interface AudioDecoder {
  decode(input: AudioFileInput): Promise<PcmAudio>;
}
