import { AudioMedia } from "@langchain/langgraph-sdk/stream";

//#region src/use-audio-player.d.ts
/**
 * Lifecycle state of an audio or video player returned by
 * {@link useAudioPlayer} and {@link useVideoPlayer}.
 *
 * Single-enum design (vs. multiple booleans) eliminates impossible
 * states and gives callers a clean `switch` target.
 */
type PlayerStatus = "idle" | "buffering" | "playing" | "paused" | "finished" | "error";
/**
 * Options for {@link useAudioPlayer}.
 *
 * All fields optional; defaults cover OpenAI `gpt-4o-audio-preview`
 * pcm16 streams (`sampleRate: 24000`, `channels: 1`) and any WAV
 * stream the upstream model emits.
 */
interface UseAudioPlayerOptions {
  /**
   * Begin playback as soon as the first byte arrives (PCM strategy)
   * or the blob settles (`element` strategy). Subject to browser
   * autoplay policies — on sites without prior user gesture, the
   * underlying `play()` may be rejected and the hook transitions to
   * `"error"` with a descriptive message.
   */
  autoPlay?: boolean;
  /**
   * Overrides for the PCM strategy. Ignored by the `element` strategy
   * and by WAV streams (the RIFF `fmt ` chunk is authoritative there).
   */
  pcm?: {
    /** Sample rate in Hz. Defaults to `24000`. */sampleRate?: number; /** Channel count. Defaults to `1` (mono). */
    channels?: number;
  };
  /**
   * Additional mime prefixes that should be treated as raw PCM16
   * (in addition to `audio/pcm` / `audio/L16`). Use when upstream
   * reports a custom mime like `audio/pcm16`.
   */
  pcmMimePrefixes?: readonly string[];
  /**
   * Force a specific playback strategy. Default `"auto"` picks `"pcm"`
   * for PCM / L16 / WAV mime types and `"element"` for everything else.
   */
  strategy?: "auto" | "pcm" | "element";
}
/**
 * Player controls + live state returned by {@link useAudioPlayer}.
 *
 * Shape is shared with {@link useVideoPlayer} where possible — learn
 * one surface, use it for both.
 */
interface AudioPlayerHandle {
  /** Current lifecycle state. See {@link PlayerStatus}. */
  status: PlayerStatus;
  /**
   * Which implementation is active. `"pcm"` scheduling through
   * `AudioContext` starts within one chunk of the first byte; `"element"`
   * waits for `message-finish` before a hidden `HTMLAudioElement` takes
   * over.
   */
  strategy: "pcm" | "element";
  /** Start (or resume) playback. No-op while `status === "error"`. */
  play(): void;
  /** Pause without discarding buffered samples / element position. */
  pause(): void;
  /**
   * Hard stop: tears down the `AudioContext` (PCM) or detaches the
   * element (`element`) and drops any scheduled work.
   */
  stop(): void;
  /** Sugar for `status === "playing" ? pause() : play()`. */
  toggle(): void;
  /**
   * Reset back to `"idle"` and drop any transient error. The next
   * `play()` starts fresh from the current position.
   */
  reset(): void;
  /**
   * Resolve on the next terminal transition (`finished` | `paused` |
   * `idle`). Reject on transitions to `"error"`. Calling `stop()` or
   * `reset()` resolves the pending promise immediately. Calling
   * `playToEnd` also triggers `play()` if currently paused/idle.
   */
  playToEnd(): Promise<void>;
  /**
   * Seconds of audio consumed since the current `play()` call. Resets
   * on `reset()` and on media changes.
   */
  currentTime: number;
  /**
   * Total duration in seconds, when knowable. The `element` strategy
   * exposes this once `loadedmetadata` fires; the `pcm` strategy leaves
   * it `undefined` (PCM duration isn't known until `message-finish`).
   */
  duration?: number;
  /**
   * Seek to an absolute timestamp in seconds. Only defined on the
   * `element` strategy; `undefined` on `pcm` (random-access seeking of
   * a live scheduled buffer is not supported).
   */
  seek?(seconds: number): void;
  /**
   * RMS level of the last analysed frame, normalised to `[0, 1]`.
   * Drop-in for a VU meter. `0` when no analyser frame has been read
   * yet, when paused, or before `play()`.
   */
  level: number;
  /**
   * Current 256-bin frequency-domain snapshot from the internal
   * {@link AnalyserNode}. Returns `undefined` before the graph is
   * connected or on environments without Web Audio. Safe to poll
   * inside `requestAnimationFrame`.
   */
  getFrequencyData(): Uint8Array | undefined;
  /**
   * Current 256-sample waveform snapshot (byte time-domain) from the
   * internal {@link AnalyserNode}. Returns `undefined` before the graph
   * is connected or on environments without Web Audio.
   */
  getTimeDomainData(): Uint8Array | undefined;
  /** Last error raised by the stream reader, decoder, or element. */
  error: Error | undefined;
}
/**
 * Progressive audio playback for {@link AudioMedia} handles with a
 * uniform surface across PCM (streamed) and container (`HTMLAudioElement`)
 * strategies.
 *
 * ### Behaviour
 *
 * - Strategy selection is derived from `media.mimeType` and may be
 *   overridden via `options.strategy`. PCM / L16 / WAV all flow through
 *   the progressive Web Audio path; every other mime uses a hidden
 *   `HTMLAudioElement`.
 *
 * - **PCM strategy.** Chunks are decoded in real time and scheduled on
 *   a single `AudioContext`; playback begins within one chunk of the
 *   first byte. `seek` / `duration` are `undefined` because random
 *   access on a live scheduled buffer is not supported.
 *
 * - **Element strategy.** `status` stays in `"buffering"` until
 *   `message-finish` materialises a blob URL; the element then owns
 *   playback. `seek` / `duration` are available.
 *
 * - Both strategies expose `level`, `getFrequencyData()`, and
 *   `getTimeDomainData()` by tapping an {@link AnalyserNode} in the
 *   audio graph.
 *
 * - React StrictMode's simulated unmount/remount is safe: the shared
 *   reader and replay buffer mean a second attach sees the same bytes
 *   that the first one did.
 *
 * @param media - Audio handle from `useAudio` etc.
 * @param options - Strategy overrides and PCM format hints.
 */
declare function useAudioPlayer(media: AudioMedia | undefined, options?: UseAudioPlayerOptions): AudioPlayerHandle;
//#endregion
export { AudioPlayerHandle, PlayerStatus, UseAudioPlayerOptions, useAudioPlayer };
//# sourceMappingURL=use-audio-player.d.ts.map