/**
 * Общие типы и константы аудио-подсистемы (шины, хендлы, опции).
 * Реализации — в AudioManager (фасад), Voices (полифония sfx), Loops (лупы).
 */

export interface AudioBuses {
    master: GainNode;
    music: GainNode;
    sfx: GainNode;
    ambience: GainNode;
}

export type BusName = 'master' | 'music' | 'sfx' | 'ambience';

export interface MusicHandle {
    stop(fadeSeconds?: number): void;
    /** Задать громкость сразу (для медленных тик-фейдов поверх — локальные слои). */
    setVolume(volume: number): void;
}

/** Хендл играющего разового sfx: параметры в полёте + остановка. */
export interface SfxHandle {
    stop(fadeSeconds?: number): void;
    setVolume(volume: number): void;
    setPan(pan: number): void;
    setRate(rate: number): void;
}

/** Опции разового sfx. */
export interface PlayOptions {
    /** Относительная громкость в шине (см. bus), 0..1+. */
    volume?: number;
    /** Скорость воспроизведения 0.5..2 (джиттер шагов, вариации тона). */
    rate?: number;
    /** Панорама -1..1; |pan| < 0.01 — узел StereoPanner не создаётся. */
    pan?: number;
    /** Заглушить прежние играющие экземпляры этого же ключа (короткий фейд). */
    restart?: boolean;
    /** Шина голоса (по умолчанию sfx) — например UI-звук в master. */
    bus?: BusName;
}

export interface LoopOptions {
    loop?: boolean;
    fade?: number;
    volume?: number;
    bus?: BusName;
}

export const DEFAULT_FADE = 1;
export const MIN_FADE_VOLUME = 0.0001;

export const clamp = (v: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, v));