@vkontakte/videoplayer-shared 1.0.99 → 1.0.100-dev.065b3da4a.0

package/types/audio/AudioGraph.d.ts

@@ -0,0 +1,37 @@
+import type { IAudioGraph, IAudioGraphPlugin } from "./types";
+/**
+* Конкретная реализация IAudioGraph.
+*
+* Архитектура:
+*
+*   source₁ → [Chain₁] ─┐
+*   source₂ → [Chain₂] ─┼→ [masterGain] → ctx.destination
+*
+* Каждый источник получает собственную цепочку плагинов.
+* Общий master GainNode управляет общей выходной громкостью.
+*/
+export declare class AudioGraph implements IAudioGraph {
+	private _ctx;
+	private _masterGain;
+	private readonly _connections;
+	private _contextEnabled;
+	private readonly _boundBeforeDisable;
+	/** Доступна ли Web Audio API в текущем окружении. */
+	static isSupported(): boolean;
+	get context(): AudioContext;
+	get contextState(): AudioContextState;
+	enableContext(): Promise<void>;
+	disableContext(): Promise<void>;
+	connectSource(element: HTMLMediaElement): Promise<void>;
+	disconnectSource(element: HTMLMediaElement): void;
+	isSourceConnected(element: HTMLMediaElement): boolean;
+	addPlugin(element: HTMLMediaElement, plugin: IAudioGraphPlugin): void;
+	removePlugin(element: HTMLMediaElement, pluginId: string): void;
+	getPlugins(element: HTMLMediaElement): readonly IAudioGraphPlugin[];
+	createAnalyser(element: HTMLMediaElement): AnalyserNode | null;
+	setMasterVolume(volume: number): void;
+	getMasterVolume(): number;
+	dispose(): void;
+	/** Лениво создаёт AudioContext и master gain. */
+	private ensureContext;
+}

package/types/audio/AudioPluginChain.d.ts

@@ -0,0 +1,41 @@
+import type { IAudioGraphPlugin } from "./types";
+/**
+* Упорядоченная цепочка аудиоплагинов между источником и назначением.
+*
+* Цепочка имеет фиксированные input и output GainNodes. Плагины
+* вставляются между ними. При добавлении или удалении плагинов
+* пересобирается только внутреннее соединение
+* input → плагины → output — источники, подключённые ко входу,
+* не затрагиваются.
+*
+*   source → [input] → plugin₁ → plugin₂ → … → [output] → destination
+*/
+export declare class AudioPluginChain {
+	private readonly _inputNode;
+	private readonly _outputNode;
+	private _plugins;
+	private _destination;
+	private readonly _taps;
+	constructor(ctx: AudioContext);
+	/** Узел, к которому подключаются источники. */
+	get input(): AudioNode;
+	/** Текущие плагины в порядке цепочки. */
+	get plugins(): readonly IAudioGraphPlugin[];
+	/** Подключает выход цепочки к узлу назначения. */
+	connectTo(destination: AudioNode): void;
+	/** Паразитное подключение к выходу цепочки (например, для AnalyserNode). Сохраняется при пересборке. */
+	addTap(node: AudioNode): void;
+	hasPlugin(id: string): boolean;
+	addPlugin(plugin: IAudioGraphPlugin): void;
+	removePlugin(id: string): void;
+	/**
+	* Разрушает и пересобирает внутреннее соединение:
+	* input → plugin₁ → … → pluginₙ → output → destination
+	*
+	* Отключает только outputNode каждого плагина (не inputNode), чтобы
+	* сохранить внутренние соединения внутри плагинов, имеющих несколько
+	* внутренних узлов (например, последовательность BiquadFilterNodes
+	* в EqualizerPlugin).
+	*/
+	private rebuild;
+}

package/types/audio/AudioSourceConnection.d.ts

@@ -0,0 +1,36 @@
+import type { IAudioGraphPlugin } from "./types";
+/**
+* Управляет привязкой отдельного HTMLMediaElement к AudioContext.
+*
+* createMediaElementSource(element) необратим — после вызова аудио
+* элемента навсегда направляется через Web Audio. Этот класс отслеживает
+* это состояние: первый bind() создаёт узел-источник; unbind() лишь
+* отключает его; последующий bind() переподключает без создания нового
+* узла-источника.
+*
+* Каждое подключение имеет собственную AudioPluginChain, что позволяет
+* применять эффекты индивидуально для каждого источника. Выход цепочки
+* подаётся на общий destination (обычно master gain node).
+*/
+export declare class AudioSourceConnection {
+	private readonly _pluginChain;
+	private readonly _element;
+	private readonly _ctx;
+	private _sourceNode;
+	private _isBound;
+	constructor(element: HTMLMediaElement, ctx: AudioContext, destination: AudioNode);
+	get isBound(): boolean;
+	get plugins(): readonly IAudioGraphPlugin[];
+	/** Привязывает элемент к аудиографу. Создаёт MediaElementSource при первом вызове. */
+	bind(): void;
+	/**
+	* Отвязывает элемент от аудиографа: источник подключается напрямую к ctx.destination,
+	* минуя все плагины (включая мастер-громкость). Это намеренное поведение — unbind
+	* полностью отключает элемент от любой обработки.
+	*/
+	unbind(): void;
+	addPlugin(plugin: IAudioGraphPlugin): void;
+	removePlugin(id: string): void;
+	/** Снимает сигнал с выхода источника параллельно (для визуализации). */
+	addAnalyser(analyser: AnalyserNode): void;
+}

package/types/audio/global.d.d.ts

@@ -0,0 +1,3 @@
+interface Window {
+	webkitAudioContext: typeof AudioContext;
+}

package/types/audio/index.d.ts

@@ -0,0 +1,5 @@
+export type { IAudioGraphPlugin, IAudioEqualizerConfig, IAudioNormalizationConfig } from "./types";
+export { AudioGraph } from "./AudioGraph";
+export { VolumeFaderPlugin } from "./plugins/VolumeFaderPlugin";
+export { EqualizerPlugin } from "./plugins/EqualizerPlugin";
+export { NormalizerPlugin } from "./plugins/NormalizerPlugin";

package/types/audio/plugins/EqualizerPlugin.d.ts

@@ -0,0 +1,31 @@
+import type { IAudioGraphPlugin, IAudioEqualizer, IAudioEqualizerConfig } from "../types";
+/**
+* Многополосный эквалайзер-плагин.
+*
+* Каждая частотная полоса из конфигурации получает собственный
+* BiquadFilterNode (peaking). Полосы соединены последовательно между
+* входом и выходом плагина:
+*
+*   input → filter₁ → filter₂ → … → filterₙ → output
+*
+* Все экземпляры в рамках одного AudioContext имеют общие настройки
+* усиления: ConstantSourceNodes (по одному на полосу) хранятся в WeakMap
+* по ключу AudioContext и переиспользуются между экземплярами. Изменение
+* усиления на любом экземпляре обновляет их все.
+*/
+export declare class EqualizerPlugin implements IAudioGraphPlugin {
+	readonly id = "equalizer";
+	private static _sources;
+	private readonly _inputNode;
+	private readonly _outputNode;
+	private readonly _filterMap;
+	readonly equalizer: IAudioEqualizer;
+	constructor(ctx: AudioContext, config: IAudioEqualizerConfig);
+	get inputNode(): AudioNode;
+	get outputNode(): AudioNode;
+	/** Сбросить все полосы к усилениям по умолчанию (влияет на все экземпляры). */
+	resetAll(): void;
+	/** Отключить все фильтры от общих ConstantSourceNodes. */
+	dispose(): void;
+	private rebuild;
+}

package/types/audio/plugins/NormalizerPlugin.d.ts

@@ -0,0 +1,23 @@
+import type { IAudioGraphPlugin, IAudioNormalizationConfig } from "../types";
+/**
+* Плагин нормализации — нормализует громкость между медиапотоками.
+*
+* Поток сигнала: компрессор (лимитер) → gain
+*
+* GainNode компенсирует разницу между `lufs` потока и общим целевым
+* уровнем. DynamicsCompressorNode работает как лимитер, порог которого
+* задаётся значением `peak` потока.
+*/
+export declare class NormalizerPlugin implements IAudioGraphPlugin {
+	readonly id = "normalizer";
+	private readonly _compressor;
+	private readonly _gainNode;
+	constructor(ctx: AudioContext, config: IAudioNormalizationConfig);
+	get inputNode(): AudioNode;
+	get outputNode(): AudioNode;
+	/**
+	* Применяет конфигурацию нормализации: устанавливает порог лимитера
+	* из `peak` и вычисляет смещение усиления из `lufs`.
+	*/
+	applyConfig(config: IAudioNormalizationConfig): void;
+}

package/types/audio/plugins/VolumeFaderPlugin.d.ts

@@ -0,0 +1,39 @@
+import type { Milliseconds } from "../../utils/semanticTypes";
+import type { IAudioGraphPlugin, IAudioFader } from "../types";
+interface VolumeFaderConfig {
+	/** Длительность фейда в миллисекундах. */
+	readonly duration: Milliseconds;
+	/** Пользовательская кривая, передаваемая напрямую в setValueCurveAtTime. Если не указана, используется косинусное сглаживание. */
+	readonly curve?: Float32Array;
+}
+/**
+* Плагин фейдера громкости — обёртка над GainNode, реализующая IAudioFader.
+*
+* Использует косинусную кривую сглаживания через setValueCurveAtTime
+* для плавных фейдов. GainNode фейда независим от master volume GainNode —
+* их значения перемножаются на стороне Web Audio API.
+*
+* По умолчанию: gain = 1 (единица — без ослабления).
+*/
+export declare class VolumeFaderPlugin implements IAudioGraphPlugin, IAudioFader {
+	readonly id = "volume-fader";
+	private readonly _gainNode;
+	private readonly _duration;
+	private readonly _curve;
+	private _fade;
+	constructor(ctx: AudioContext, config: VolumeFaderConfig);
+	get inputNode(): AudioNode;
+	get outputNode(): AudioNode;
+	get faded(): boolean;
+	appear(): void;
+	disappear(): void;
+	pause(): void;
+	resume(): void;
+	cancel(): void;
+	private _finishFade;
+	private _startFade;
+	private _buildEasingCurve;
+	private _scheduleCurve;
+	private _sampleIndex;
+}
+export {};

package/types/audio/types.d.ts

@@ -0,0 +1,132 @@
+/**
+* Плагин, который можно вставить в цепочку обработки аудио.
+* Каждый плагин владеет своими внутренними 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;
+}

package/types/index.d.ts

@@ -10,5 +10,6 @@ export * as devNull from "./devNull";
 export type { DevNullEntry } from "./devNull";
 export * from "./AppTracer";
 export * from "./di";
+export * from "./audio";
 
 export * from './__polyfills/index.es2015';

package/types/utils/clearVideoElement.d.ts

@@ -1 +1 @@
-export declare const clearVideoElement: (video: HTMLMediaElement, clearVideoElementInnerHTML?: boolean) => void;
+export declare const clearVideoElement: (video: HTMLMediaElement) => void;