/**
* Плагин, который можно вставить в цепочку обработки аудио.
* Каждый плагин владеет своими внутренними AudioNodes и предоставляет
* пару вход/выход, к которым подключается цепочка.
*/
export interface IAudioGraphPlugin {
	/** Уникальный идентификатор внутри цепочки — используется для удаления. */
	readonly id: string;
	/** Узел, к которому подключается предыдущий элемент цепочки. */
	readonly inputNode: AudioNode;
	/** Узел, который подключается к следующему элементу цепочки. */
	readonly outputNode: AudioNode;
}
/**
* Высокоуровневая абстракция аудиографа.
*
* Управляет singleton AudioContext, цепочками плагинов для каждого
* источника и общим master gain node. Источники — это HTMLMediaElements,
* привязанные через createMediaElementSource — необратимая операция,
* обрабатываемая прозрачно.
*/
export interface IAudioGraph {
	/** Базовый AudioContext (создаётся лениво при первом использовании). */
	readonly context: AudioContext;
	/** Текущее состояние AudioContext. */
	readonly contextState: AudioContextState;
	/**
	* Возобновляет AudioContext — аудио проходит через граф.
	*
	* Может бросить исключение, если AudioContext был закрыт извне.
	*/
	enableContext(): Promise<void>;
	/** Приостанавливает AudioContext — обработка аудио останавливается. */
	disableContext(): Promise<void>;
	/**
	* Привязывает медиаэлемент к графу.
	* При первом вызове для элемента вызывает createMediaElementSource
	* (необратимо). Последующие вызовы для неподключённого элемента
	* просто переподключают его.
	*
	* Может бросить исключение, если AudioContext был закрыт извне.
	* В этом случае нужно вызвать dispose() и пересоздать AudioGraph.
	*/
	connectSource(element: HTMLMediaElement): Promise<void>;
	/** Отключает медиаэлемент от цепочки плагинов (аудио продолжает играть напрямую, без обработки). */
	disconnectSource(element: HTMLMediaElement): void;
	/** Подключён ли элемент в данный момент и привязан ли он. */
	isSourceConnected(element: HTMLMediaElement): boolean;
	/** Добавляет плагин в цепочку обработки источника. */
	addPlugin(element: HTMLMediaElement, plugin: IAudioGraphPlugin): void;
	/** Удаляет плагин из цепочки источника по id. */
	removePlugin(element: HTMLMediaElement, pluginId: string): void;
	/** Все плагины в текущей цепочке источника. */
	getPlugins(element: HTMLMediaElement): readonly IAudioGraphPlugin[];
	/**
	* Создаёт AnalyserNode, подключённый к выходному сигналу источника.
	* Возвращает null, если источник не подключён.
	* Анализатор сохраняется при добавлении/удалении плагинов
	* (переподключается при пересборке цепочки).
	*/
	createAnalyser(element: HTMLMediaElement): AnalyserNode | null;
	/** Устанавливает общую выходную громкость (0 = тишина, 1 = единица). */
	setMasterVolume(volume: number): void;
	/** Текущая общая громкость. */
	getMasterVolume(): number;
	/** Закрывает AudioContext и освобождает все ресурсы. */
	dispose(): void;
}
/**
* Аудио-фейдер — управляет плавными нарастаниями/затуханиями громкости
* (fade in/out).
*
* Фейдер использует отдельный GainNode, выход которого умножается с
* master volume GainNode на стороне Web Audio API, что позволяет
* независимо управлять фейдом и общей громкостью.
*/
export interface IAudioFader {
	/** Активен ли в данный момент фейд-рамп (включая паузу). */
	readonly faded: boolean;
	/** Принудительно устанавливает gain фейда в 0, затем нарастает до 1. */
	appear(): void;
	/** Принудительно устанавливает gain фейда в 1, затем затухает до 0. */
	disappear(): void;
	/** Замораживает активный фейд-рамп в текущей позиции. */
	pause(): void;
	/** Возобновляет ранее приостановленный фейд-рамп с замороженной позиции. */
	resume(): void;
	/** Отменяет активный фейд и устанавливает gain в целевое значение текущего рампа. */
	cancel(): void;
}
/**
* Параметры нормализации аудио для медиапотока.
*
*   - `lufs` — интегрированная громкость (LUFS), используется для расчёта
*     смещения усиления, необходимого для приведения потока к общему
*     целевому уровню.
*   - `peak` — истинный пик (дБ), используется для настройки порога лимитера.
*   - `targetLufs` — целевая громкость для нормализации (по умолчанию: -14 LUFS,
*     де-факто стандарт для музыкального стриминга — Spotify, YouTube, Apple Music).
*/
export interface IAudioNormalizationConfig {
	readonly lufs: number;
	readonly peak: number;
	readonly targetLufs?: number;
}
/**
* Конфигурация эквалайзера — отображение частота (Гц) → усиление (дБ).
* Передаётся при создании для определения доступных частотных полос.
*
*   const config: IAudioEqualizerConfig = { 60: 0, 250: 0, 1000: 0, 8000: 0 };
*/
export interface IAudioEqualizerConfig {
	readonly [frequency: number]: number;
}
/**
* Отдельная частотная полоса в эквалайзере.
* `value` отражает текущее усиление в дБ; `set` обновляет его,
* `reset` возвращает к значению по умолчанию.
*/
export interface IAudioEqualizerFilter {
	readonly frequency: number;
	readonly value: number;
	set(value: number): void;
	reset(): void;
}
/**
* Эквалайзер — набор частотных полос, индексированных по центральной
* частоте в Гц.
*/
export interface IAudioEqualizer {
	readonly [frequency: number]: IAudioEqualizerFilter;
}