avbridge 2.3.0 → 2.6.0

package/dist/player.d.ts

@@ -1,123 +1,3 @@
-/**
- * `<avbridge-player>` — YouTube-style controls element.
- *
- * Wraps `<avbridge-video>` with a full player UI: play/pause, seek bar,
- * volume, settings menu (speed, subtitles, audio tracks), fullscreen,
- * keyboard shortcuts, touch gestures, and auto-hiding controls.
- *
- * All properties, methods, and events from `<avbridge-video>` are proxied
- * through. Consumers interact with `<avbridge-player>` exclusively.
- */
-declare class AvbridgePlayerElement extends HTMLElement {
-    static readonly observedAttributes: ("src" | "muted" | "autoplay" | "loop" | "preload" | "poster" | "playsinline" | "crossorigin" | "disableremoteplayback" | "preferstrategy")[];
-    private _video;
-    private _playBtn;
-    private _overlayBtn;
-    private _seekInput;
-    private _seekProgress;
-    private _seekBuffered;
-    private _seekThumb;
-    private _seekTooltip;
-    private _timeDisplay;
-    private _volumeBtn;
-    private _volumeInput;
-    private _settingsBtn;
-    private _settingsMenu;
-    private _fullscreenBtn;
-    private _speedIndicator;
-    private _rippleLeft;
-    private _rippleRight;
-    private _state;
-    private _controlsTimer;
-    private _settingsOpen;
-    private _userSeeking;
-    private _holdTimer;
-    private _holdSpeedActive;
-    private _savedPlaybackRate;
-    private _lastTapTime;
-    private _tapTimer;
-    private _statsOpen;
-    private _statsEl;
-    private _statsInterval;
-    private _eventCleanup;
-    constructor();
-    private _template;
-    private _bindEvents;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
-    private _setState;
-    private _togglePlay;
-    private _onSeekInput;
-    private _onSeekCommit;
-    /** Linear click-to-time mapping across the full track width (no edge clamping). */
-    private _timeFromSeekPointer;
-    private _onSeekPointerDown;
-    private _onSeekHover;
-    private _updateSeekVisuals;
-    private _updateTime;
-    private _toggleMute;
-    private _updateVolume;
-    private _toggleSettings;
-    private _closeSettings;
-    private _buildSettingsMenu;
-    private _toggleStats;
-    private _updateStats;
-    private _toggleFullscreen;
-    private _updateFullscreenIcon;
-    private _showControls;
-    private _scheduleHide;
-    /** Track whether the last interaction was touch so click handler can skip. */
-    private _lastPointerTypeWasTouch;
-    private _onContainerClick;
-    private _onContainerDblClick;
-    private _onPointerDown;
-    private _onPointerUp;
-    private _cancelHold;
-    private _doDoubleTap;
-    private _onKeydown;
-    private _clearTimers;
-    get src(): string;
-    set src(v: string);
-    get source(): unknown;
-    set source(v: unknown);
-    get currentTime(): number;
-    set currentTime(v: number);
-    get duration(): number;
-    get paused(): boolean;
-    get ended(): boolean;
-    get readyState(): number;
-    get volume(): number;
-    set volume(v: number);
-    get muted(): boolean;
-    set muted(v: boolean);
-    get playbackRate(): number;
-    set playbackRate(v: number);
-    get autoplay(): boolean;
-    set autoplay(v: boolean);
-    get loop(): boolean;
-    set loop(v: boolean);
-    get videoWidth(): number;
-    get videoHeight(): number;
-    get buffered(): TimeRanges;
-    get played(): TimeRanges;
-    get seekable(): TimeRanges;
-    get strategy(): string | undefined;
-    get strategyClass(): string | undefined;
-    get audioTracks(): unknown[];
-    get subtitleTracks(): unknown[];
-    get player(): unknown;
-    get videoElement(): HTMLVideoElement;
-    play(): Promise<void>;
-    pause(): void;
-    load(): Promise<void>;
-    destroy(): Promise<void>;
-    setAudioTrack(id: number): Promise<void>;
-    setSubtitleTrack(id: number | null): Promise<void>;
-    getDiagnostics(): unknown;
-    canPlayType(mime: string): string;
-}
-
 /**
  * Core types shared across avbridge modules.
  *
@@ -364,6 +244,185 @@ interface PlayerEventMap {
 type PlayerEventName = keyof PlayerEventMap;
 /** Generic listener type re-exported for player.on overloads. */
 type Listener<T> = (payload: T) => void;
+/**
+ * CustomEvents dispatched by `<avbridge-video>` and `<avbridge-player>`.
+ * Map each event name to the full `CustomEvent<Detail>` so addEventListener
+ * overloads can type the listener parameter correctly.
+ *
+ * Standard HTMLMediaElement events (play, pause, seeking, volumechange,
+ * etc.) are forwarded from the inner `<video>` as plain `Event`s and remain
+ * typed via the built-in `HTMLElementEventMap`. They are NOT in this map —
+ * TypeScript will pick up their native types automatically.
+ */
+interface AvbridgeVideoElementEventMap {
+    strategychange: CustomEvent<{
+        strategy: StrategyName;
+        strategyClass: string | null;
+        reason: string;
+        from?: StrategyName;
+        currentTime?: number;
+        diagnostics: DiagnosticsSnapshot;
+    }>;
+    trackschange: CustomEvent<{
+        audioTracks: AudioTrackInfo[];
+        subtitleTracks: SubtitleTrackInfo[];
+    }>;
+    timeupdate: CustomEvent<{
+        currentTime: number;
+    }>;
+    ended: CustomEvent<Record<string, never>>;
+    ready: CustomEvent<{
+        diagnostics: DiagnosticsSnapshot;
+    }>;
+    destroy: CustomEvent<Record<string, never>>;
+    error: CustomEvent<{
+        error: Error;
+        diagnostics: DiagnosticsSnapshot | null;
+    }>;
+    progress: CustomEvent<{
+        buffered: TimeRanges;
+    }>;
+    loadstart: CustomEvent<Record<string, never>>;
+}
+
+/**
+ * `<avbridge-player>` — YouTube-style controls element.
+ *
+ * Wraps `<avbridge-video>` with a full player UI: play/pause, seek bar,
+ * volume, settings menu (speed, subtitles, audio tracks), fullscreen,
+ * keyboard shortcuts, touch gestures, and auto-hiding controls.
+ *
+ * All properties, methods, and events from `<avbridge-video>` are proxied
+ * through. Consumers interact with `<avbridge-player>` exclusively.
+ */
+
+declare class AvbridgePlayerElement extends HTMLElement {
+    static readonly observedAttributes: ("src" | "muted" | "autoplay" | "loop" | "preload" | "poster" | "playsinline" | "crossorigin" | "disableremoteplayback" | "preferstrategy")[];
+    private _video;
+    private _playBtn;
+    private _overlayBtn;
+    private _seekInput;
+    private _seekProgress;
+    private _seekBuffered;
+    private _seekThumb;
+    private _seekTooltip;
+    private _timeDisplay;
+    private _volumeBtn;
+    private _volumeInput;
+    private _settingsBtn;
+    private _settingsMenu;
+    private _fullscreenBtn;
+    private _speedIndicator;
+    private _rippleLeft;
+    private _rippleRight;
+    private _state;
+    private _controlsTimer;
+    private _settingsOpen;
+    private _userSeeking;
+    private _holdTimer;
+    private _holdSpeedActive;
+    private _savedPlaybackRate;
+    private _lastTapTime;
+    private _tapTimer;
+    private _statsOpen;
+    private _statsEl;
+    private _statsInterval;
+    private _eventCleanup;
+    constructor();
+    private _template;
+    private _bindEvents;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    private _setState;
+    private _togglePlay;
+    private _onSeekInput;
+    private _onSeekCommit;
+    /** Linear click-to-time mapping across the full track width (no edge clamping). */
+    private _timeFromSeekPointer;
+    private _onSeekPointerDown;
+    private _onSeekHover;
+    private _updateSeekVisuals;
+    private _updateTime;
+    private _toggleMute;
+    private _updateVolume;
+    private _toggleSettings;
+    private _closeSettings;
+    private _buildSettingsMenu;
+    private _toggleStats;
+    private _updateStats;
+    private _toggleFullscreen;
+    private _updateFullscreenIcon;
+    private _showControls;
+    private _scheduleHide;
+    /** Track whether the last interaction was touch so click handler can skip. */
+    private _lastPointerTypeWasTouch;
+    private _onContainerClick;
+    private _onContainerDblClick;
+    private _onPointerDown;
+    private _onPointerUp;
+    private _cancelHold;
+    private _doDoubleTap;
+    private _onKeydown;
+    private _clearTimers;
+    get src(): string;
+    set src(v: string);
+    get source(): unknown;
+    set source(v: unknown);
+    get currentTime(): number;
+    set currentTime(v: number);
+    get duration(): number;
+    get paused(): boolean;
+    get ended(): boolean;
+    get readyState(): number;
+    get volume(): number;
+    set volume(v: number);
+    get muted(): boolean;
+    set muted(v: boolean);
+    get playbackRate(): number;
+    set playbackRate(v: number);
+    get autoplay(): boolean;
+    set autoplay(v: boolean);
+    get loop(): boolean;
+    set loop(v: boolean);
+    get videoWidth(): number;
+    get videoHeight(): number;
+    get buffered(): TimeRanges;
+    get played(): TimeRanges;
+    get seekable(): TimeRanges;
+    get strategy(): string | undefined;
+    get strategyClass(): string | undefined;
+    get audioTracks(): unknown[];
+    get subtitleTracks(): unknown[];
+    /**
+     * External subtitle files to attach when the source loads. Forwarded
+     * to the inner <avbridge-video>. Takes effect on next bootstrap.
+     */
+    get subtitles(): unknown;
+    set subtitles(value: unknown);
+    /** Attach a subtitle track to the current playback without a reload. */
+    addSubtitle(subtitle: {
+        url: string;
+        language?: string;
+        format?: "vtt" | "srt";
+    }): Promise<void>;
+    get player(): unknown;
+    get videoElement(): HTMLVideoElement;
+    play(): Promise<void>;
+    pause(): void;
+    load(): Promise<void>;
+    destroy(): Promise<void>;
+    setAudioTrack(id: number): Promise<void>;
+    setSubtitleTrack(id: number | null): Promise<void>;
+    getDiagnostics(): unknown;
+    canPlayType(mime: string): string;
+    addEventListener<K extends keyof AvbridgeVideoElementEventMap>(type: K, listener: (this: AvbridgePlayerElement, ev: AvbridgeVideoElementEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
+    addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: AvbridgePlayerElement, ev: HTMLElementEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof AvbridgeVideoElementEventMap>(type: K, listener: (this: AvbridgePlayerElement, ev: AvbridgeVideoElementEventMap[K]) => unknown, options?: boolean | EventListenerOptions): void;
+    removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: AvbridgePlayerElement, ev: HTMLElementEventMap[K]) => unknown, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+}
 
 declare class UnifiedPlayer {
     private readonly options;
@@ -504,7 +563,20 @@ declare class AvbridgeVideoElement extends HTMLElementCtor {
     private _strategy;
     private _strategyClass;
     private _audioTracks;
+    /** Subtitle tracks reported by the active UnifiedPlayer (options.subtitles
+     *  + embedded container tracks + programmatic addSubtitle calls). */
     private _subtitleTracks;
+    /** Subtitle tracks derived from light-DOM `<track>` children. Maintained
+     *  by _syncTextTracks on every mutation. Merged into the public
+     *  `subtitleTracks` getter so the player's settings menu sees them. */
+    private _htmlTrackInfo;
+    /**
+     * External subtitle list forwarded to `createPlayer()` on the next
+     * bootstrap. Setting this after bootstrap queues it for the next
+     * source change; consumers that need to swap subtitles mid-playback
+     * should set `source` to reload.
+     */
+    private _subtitles;
     /**
      * Initial strategy preference. `"auto"` means "let the classifier decide";
      * any other value is passed to `createPlayer({ initialStrategy })` and
@@ -621,6 +693,37 @@ declare class AvbridgeVideoElement extends HTMLElementCtor {
     get player(): UnifiedPlayer | null;
     get audioTracks(): AudioTrackInfo[];
     get subtitleTracks(): SubtitleTrackInfo[];
+    /**
+     * External subtitle files to attach when the source loads. Takes effect
+     * on the next bootstrap — set before assigning `source`, or reload via
+     * `load()` after changing. For dynamic post-bootstrap addition, use
+     * `addSubtitle()` instead.
+     *
+     * @example
+     * el.subtitles = [{ url: "/en.srt", format: "srt", language: "en" }];
+     * el.src = "/movie.mp4";
+     */
+    get subtitles(): Array<{
+        url: string;
+        language?: string;
+        format?: "vtt" | "srt";
+    }> | null;
+    set subtitles(value: Array<{
+        url: string;
+        language?: string;
+        format?: "vtt" | "srt";
+    }> | null);
+    /**
+     * Attach a subtitle track to the current playback without rebuilding
+     * the player. Works while the element is playing — converts SRT to
+     * VTT if needed, adds a `<track>` to the inner `<video>`. Canvas
+     * strategies pick up the new track via their textTracks watcher.
+     */
+    addSubtitle(subtitle: {
+        url: string;
+        language?: string;
+        format?: "vtt" | "srt";
+    }): Promise<void>;
     /** Force a (re-)bootstrap if a source is currently set. */
     load(): Promise<void>;
     /**
@@ -637,6 +740,12 @@ declare class AvbridgeVideoElement extends HTMLElementCtor {
     setAudioTrack(id: number): Promise<void>;
     setSubtitleTrack(id: number | null): Promise<void>;
     getDiagnostics(): DiagnosticsSnapshot | null;
+    addEventListener<K extends keyof AvbridgeVideoElementEventMap>(type: K, listener: (this: AvbridgeVideoElement, ev: AvbridgeVideoElementEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
+    addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: AvbridgeVideoElement, ev: HTMLElementEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof AvbridgeVideoElementEventMap>(type: K, listener: (this: AvbridgeVideoElement, ev: AvbridgeVideoElementEventMap[K]) => unknown, options?: boolean | EventListenerOptions): void;
+    removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: AvbridgeVideoElement, ev: HTMLElementEventMap[K]) => unknown, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
     private _dispatch;
     private _dispatchError;
 }