ngx-kit 7.3.2 → 7.4.0

package/types/ngx-kit-media-control.d.ts

@@ -0,0 +1,671 @@
+import * as ngx_kit_media_control from 'ngx-kit/media-control';
+import * as _angular_core from '@angular/core';
+import { Signal, ElementRef, InjectionToken, EnvironmentProviders, Type } from '@angular/core';
+
+/**
+ * A single playable media item.
+ *
+ * `src` intentionally accepts the shapes a consumer already has lying around:
+ * a remote/relative URL string, a `Blob`/`File` (turned into an object URL
+ * internally and revoked on teardown), or a live `MediaStream`.
+ */
+interface NgxMediaSource {
+    /** Playback source. */
+    src: string | Blob | File | MediaStream;
+    /** MIME type, e.g. `audio/mpeg`, `video/mp4`. Helps capability detection avoid guessing from the extension. */
+    type?: string;
+    /** Optional codec string per RFC 6381, e.g. `avc1.42E01E,mp4a.40.2`. */
+    codecs?: string;
+    /** Display metadata, also used for Media Session integration. */
+    title?: string;
+    artist?: string;
+    album?: string;
+    /** Poster image for video. */
+    poster?: string;
+    /**
+     * Separate download target. If omitted, falls back to `src` (only when
+     * `src` is a string — Blob/File/MediaStream have no meaningful download URL
+     * unless one is provided here).
+     */
+    downloadUrl?: string;
+    /** Suggested file name for the download action. */
+    downloadFileName?: string;
+    /** Headers to send when the engine has to fetch this source itself (e.g. duration probing, WASM decoding). */
+    requestHeaders?: HeadersInit;
+}
+/** A queue of sources plus the active index. Replaces the old bare `PlayList[]`. */
+interface NgxMediaPlaylist {
+    items: NgxMediaSource[];
+    currentIndex: number;
+}
+/**
+ * @deprecated Use {@link NgxMediaSource} instead. Kept so existing `PlayList[]`
+ * consumers keep compiling; `fileAddress`/`title` map 1:1 onto `src`/`title`.
+ */
+declare class PlayList {
+    title: string;
+    fileAddress: string;
+}
+declare function playListToMediaSource(item: PlayList): NgxMediaSource;
+/**
+ * Content equality for `NgxMediaSource`/playlist arrays, not reference
+ * equality. `src` strings compare by value; `Blob`/`File`/`MediaStream`
+ * compare by identity (they can't be compared by content cheaply/safely).
+ *
+ * Every field that can change *downstream behavior* is compared —
+ * `artist`/`album`/`poster` feed Media Session metadata, `downloadUrl`/
+ * `downloadFileName` change what the download button actually does, and
+ * `requestHeaders` changes what bytes a server returns for the same URL.
+ * Fields that are purely cosmetic and never drive a decision (there
+ * currently are none — if you add one, document why it's excluded here).
+ *
+ * This exists specifically so a consumer that re-creates an equivalent
+ * array/object literal on every change-detection cycle (`[sources]="[{...}]"`,
+ * or a `.map()` derived from an otherwise-stable list) doesn't cause the
+ * player to treat it as "a new playlist" and reload media on every tick —
+ * see `computed(..., { equal: mediaSourcesEqual })` in `NgxMediaControl` and
+ * the same guard in `NgxMediaFacade.setPlaylist`.
+ */
+declare function mediaSourcesEqual(a: readonly NgxMediaSource[], b: readonly NgxMediaSource[]): boolean;
+/**
+ * Derives a display file name from a source, tolerating everything a real
+ * URL can throw at `decodeURIComponent` (malformed `%` sequences, stray
+ * `#`/`?`) instead of letting the player crash just because it tried to
+ * make a pretty label. Never throws.
+ */
+declare function extractMediaFileName(source: Pick<NgxMediaSource, 'src' | 'title'>): string;
+
+/**
+ * Exhaustive playback state machine. Only one state is active at a time;
+ * transient conditions (buffering while playing, seeking while paused) are
+ * modeled as their own states rather than boolean flags layered on top of
+ * `playing`/`paused`, so `playing + destroyed` etc. cannot occur.
+ */
+type NgxMediaPlaybackState = 'idle' | 'loading' | 'ready' | 'playing' | 'paused' | 'buffering' | 'seeking' | 'ended' | 'error' | 'destroyed';
+interface NgxTimeRange {
+    start: number;
+    end: number;
+}
+/** Read-only snapshot of engine state, exposed to the UI as a signal. */
+interface NgxMediaState {
+    playback: NgxMediaPlaybackState;
+    currentTime: number;
+    duration: number;
+    buffered: readonly NgxTimeRange[];
+    volume: number;
+    muted: boolean;
+    playbackRate: number;
+    /** Only meaningful for video engines; undefined for audio-only. */
+    videoWidth?: number;
+    videoHeight?: number;
+}
+declare function initialMediaState(): NgxMediaState;
+/** Guards against illegal transitions (e.g. anything -> playing after destroyed). */
+declare function canTransition(from: NgxMediaPlaybackState, to: NgxMediaPlaybackState): boolean;
+
+type NgxMediaKind = 'audio' | 'video';
+/**
+ * Stable contract the UI/facade programs against. The UI never knows whether
+ * playback is happening through a native `<audio>`/`<video>` element, MSE, or
+ * a WASM decoder writing into an AudioBuffer — it only sees this interface.
+ */
+interface NgxMediaEngine {
+    readonly id: string;
+    readonly kind: NgxMediaKind;
+    /** Reactive, read-only state snapshot. Engines update this via an internal writable signal. */
+    readonly state: Signal<NgxMediaState>;
+    /**
+     * The element the UI should attach to the DOM (for video: for sizing/fullscreen/PiP;
+     * for audio: usually detached, kept alive only to drive playback).
+     * Null for engines that don't render through a media element (rare; e.g. a pure
+     * Web-Audio-buffer engine).
+     */
+    readonly mediaElement: HTMLMediaElement | null;
+    load(source: NgxMediaSource, signal?: AbortSignal): Promise<void>;
+    play(): Promise<void>;
+    pause(): void;
+    seek(time: number): Promise<void> | void;
+    setVolume(volume: number): void;
+    setMuted(muted: boolean): void;
+    setPlaybackRate(rate: number): void;
+    destroy(): void;
+}
+/** Given a source, can this engine play it without further help? Cheap, synchronous-preferred check. */
+interface NgxEngineCapability {
+    canPlay(source: NgxMediaSource): 'probably' | 'maybe' | '';
+}
+
+type NgxMediaErrorCategory = 'NETWORK' | 'UNSUPPORTED_FORMAT' | 'DECODER' | 'ABORTED' | 'AUTOPLAY_BLOCKED' | 'MEDIA' | 'PERMISSION' | 'BROWSER_UNSUPPORTED' | 'UNKNOWN';
+declare class NgxMediaError extends Error {
+    readonly category: NgxMediaErrorCategory;
+    /** Original DOM/browser error, if any — kept for `console.error`/telemetry, not surfaced to templates by default. */
+    readonly cause?: unknown | undefined;
+    constructor(category: NgxMediaErrorCategory, message: string, 
+    /** Original DOM/browser error, if any — kept for `console.error`/telemetry, not surfaced to templates by default. */
+    cause?: unknown | undefined);
+    static fromMediaElementError(el: HTMLMediaElement): NgxMediaError;
+    static autoplayBlocked(cause?: unknown): NgxMediaError;
+    static unsupported(message: string): NgxMediaError;
+    static noDecoder(source: string): NgxMediaError;
+}
+
+/**
+ * Optional processing graph: `<audio>/<video>` → MediaElementAudioSourceNode
+ * → gain → (optional analyser) → destination.
+ *
+ * Never constructed unless a consumer asks for gain/analyser/effects — plain
+ * playback never creates an `AudioContext`, respecting autoplay policy and
+ * avoiding the "one AudioContext per instance whether needed or not" issue
+ * in the original component.
+ *
+ * Autoplay note: this class never calls `resume()` on its own outside a
+ * user-triggered `play()`/`connect()` call — bypassing the suspended-state
+ * policy is explicitly out of scope.
+ */
+declare class NgxWebAudioGraph {
+    private readonly element;
+    private ctx;
+    private sourceNode;
+    private gainNode;
+    private analyserNode;
+    constructor(element: HTMLMediaElement);
+    /** Idempotent — safe to call multiple times; only the first call does any work. */
+    ensureConnected(): {
+        context: AudioContext;
+        gain: GainNode;
+    };
+    setGain(value: number): void;
+    getAnalyser(fftSize?: number): AnalyserNode;
+    resumeOnUserGesture(): Promise<void>;
+    destroy(): void;
+}
+
+/**
+ * Everything the UI component needs, expressed as signals it can bind to
+ * directly, plus imperative commands. This is the only class
+ * `NgxMediaControl` talks to — it never touches an engine, a decoder, or the
+ * DOM media element itself. Swapping native/MSE/WASM playback never touches
+ * the component.
+ */
+declare class NgxMediaFacade {
+    private readonly zone;
+    private readonly engineFactory;
+    private readonly decoderRegistry;
+    private readonly destroyRef;
+    private readonly mediaSession;
+    private webAudio;
+    private loadAbort;
+    private kind;
+    private preload;
+    /**
+     * Belt-and-suspenders alongside `AbortController`: not every operation a
+     * superseded load might be mid-way through is actually cancellable (a
+     * decoder's own internal work, a promise someone else is holding a
+     * reference to, ...). Every `loadCurrent()` call captures the generation
+     * counter at its start and checks it again before committing any result —
+     * a stale generation means "a newer load has already started", full stop,
+     * regardless of whether the stale one's `AbortSignal` was actually honored
+     * by everything downstream.
+     */
+    private loadGeneration;
+    private readonly _playlist;
+    private readonly _currentIndex;
+    /** Holds the live engine instance; swapped whenever a new source loads. */
+    private readonly _engine;
+    private get engine();
+    private readonly _error;
+    readonly playlist: _angular_core.Signal<NgxMediaSource[]>;
+    readonly currentIndex: _angular_core.Signal<number>;
+    /**
+     * Reads through to the current engine's own state signal, so every native
+     * media event (timeupdate, progress, ...) that the engine writes flows
+     * straight through here with no polling, no manual refresh, and no risk of
+     * going stale across an engine swap (native -> WASM fallback, etc.).
+     *
+     * When there is NO engine (playlist empty, or the engine was torn down
+     * after a load failure) but `error()` is set, this reports `playback:
+     * 'error'` rather than falling through to `idle` — otherwise `state()` and
+     * `error()` would be two sources of truth that can disagree, and anything
+     * built on `state().playback === 'error'` would silently miss real errors.
+     */
+    readonly state: _angular_core.Signal<NgxMediaState>;
+    readonly error: _angular_core.Signal<NgxMediaError | null>;
+    readonly currentSource: _angular_core.Signal<NgxMediaSource>;
+    readonly mediaElement: _angular_core.Signal<HTMLMediaElement | null>;
+    constructor();
+    /** Deterministic on a kind change: if a source is already active, immediately rebuilds the engine as the new kind (audio <-> video element) instead of leaving a stale-kind engine behind a UI that now expects the other one. */
+    configure(kind: NgxMediaKind): void;
+    /** Applies to loads started after this call — not retroactive to an element already created. */
+    setPreload(preload: 'none' | 'metadata' | 'auto'): void;
+    setPlaylist(sources: NgxMediaSource[], startIndex?: number, autoLoad?: boolean): void;
+    loadCurrent(playAfter?: boolean): Promise<void>;
+    /** Forces the current track to actually reload from scratch — e.g. a "retry after error" action — bypassing the engine's own idempotent-load skip (which is otherwise correct: selecting the same, already-loaded track should NOT re-fetch it). */
+    reloadCurrent(): Promise<void>;
+    /**
+     * Tries the native engine first (the normal fast path). Falls back to the
+     * decoder registry ONLY when the failure category indicates the format
+     * itself is the problem (`UNSUPPORTED_FORMAT`, `DECODER`) — never for
+     * `NETWORK` (404/500/CORS/interrupted), `ABORTED`, or `PERMISSION`, where
+     * retrying via a decoder would just repeat the same failing request
+     * (or a fresh one to the same broken URL) for no benefit. This matters
+     * because `canPlayType()`/extension/mime are only ever a hint and can be
+     * wrong (a mislabeled or fake extension), so the decision to fall back
+     * has to be made from the real failure, not guessed upfront.
+     */
+    private resolveEngine;
+    private shouldFallbackToDecoder;
+    play(): Promise<void>;
+    pause(): void;
+    togglePlayPause(): void;
+    seek(time: number): void;
+    skip(deltaSeconds: number): void;
+    setVolume(volume: number): void;
+    setMuted(muted: boolean): void;
+    setPlaybackRate(rate: number): void;
+    previous(): Promise<void>;
+    next(): Promise<void>;
+    selectIndex(index: number): Promise<void>;
+    /** Lazily creates the Web Audio graph — never touched unless a consumer asks for it. Always tied to the CURRENT engine's element; invalidated automatically on every engine swap (see `loadCurrent`). */
+    getWebAudioGraph(): NgxWebAudioGraph;
+    private bindMediaSession;
+    destroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxMediaFacade, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<NgxMediaFacade>;
+}
+
+type NgxMediaType = 'audio' | 'video' | 'both';
+declare class NgxMediaControl {
+    /**
+     * `'audio'` renders an audio-style control surface (no video frame).
+     * `'video'` renders a video frame with fullscreen/PiP controls.
+     * `'both'` renders the video frame but degrades gracefully to audio-only
+     * controls when the active source has no video track.
+     */
+    readonly type: _angular_core.InputSignal<NgxMediaType>;
+    /**
+     * Poster precedence: this input, when set, ALWAYS wins over a per-source
+     * `poster` (useful for a fixed placeholder while sources vary). Leave it
+     * unset to let each `NgxMediaSource.poster` take effect per track, and
+     * clearing either one correctly clears the poster actually applied (see
+     * the mount effect below) instead of leaving a stale image behind.
+     */
+    readonly poster: _angular_core.InputSignal<string | undefined>;
+    readonly showList: _angular_core.InputSignal<boolean>;
+    readonly download: _angular_core.InputSignal<boolean>;
+    readonly showFileName: _angular_core.InputSignal<boolean>;
+    readonly showSpeed: _angular_core.InputSignal<boolean>;
+    readonly showVolume: _angular_core.InputSignal<boolean>;
+    readonly linear: _angular_core.InputSignal<boolean>;
+    readonly preload: _angular_core.InputSignal<"none" | "metadata" | "auto">;
+    /**
+     * IMPORTANT, and different from earlier versions of this component: a
+     * native `<audio>`/`<video src>` fetch cannot carry arbitrary request
+     * headers — that's a browser platform limitation, not something this
+     * library can paper over without fetching the whole file into a `Blob`
+     * first (which defeats streaming/range-requests for anything but small
+     * clips, and was explicitly the wrong default per the library's
+     * performance goals). So `fetchHeaders` is applied as the DEFAULT
+     * `requestHeaders` for any resolved source that doesn't specify its own
+     * (see `resolvedSources` below) — it takes effect for sources that end
+     * up on a decoder/MSE backend (which do fetch through
+     * `NGX_MEDIA_REQUEST_HANDLER` and can carry headers), and has no effect
+     * on plain natively-playable sources, which never go through a fetch at
+     * all. Set headers per-source via `NgxMediaSource.requestHeaders`
+     * whenever different tracks need different auth.
+     */
+    readonly fetchHeaders: _angular_core.InputSignal<HeadersInit | undefined>;
+    /** Legacy simple form: bare URLs, one per playlist entry. Prefer `sources` for titles/artwork/per-track headers. */
+    readonly fileList: _angular_core.InputSignal<string[] | undefined>;
+    /** Preferred over `fileList`: full `NgxMediaSource` objects. */
+    readonly sources: _angular_core.InputSignal<NgxMediaSource[] | undefined>;
+    readonly trackChange: _angular_core.OutputEmitterRef<NgxMediaSource>;
+    readonly error: _angular_core.OutputEmitterRef<string>;
+    private readonly doc;
+    private readonly destroyRef;
+    protected readonly facade: NgxMediaFacade;
+    protected readonly containerRef: _angular_core.Signal<ElementRef<HTMLElement>>;
+    protected readonly videoHostRef: _angular_core.Signal<ElementRef<HTMLElement> | undefined>;
+    protected readonly downloading: _angular_core.WritableSignal<boolean>;
+    protected readonly togglePlayList: _angular_core.WritableSignal<boolean>;
+    protected readonly isFullscreen: _angular_core.WritableSignal<boolean>;
+    /** Local seek preview — see the seek-slider handlers below for why the slider never binds `state().currentTime` directly while the user is dragging it. */
+    protected readonly isSeeking: _angular_core.WritableSignal<boolean>;
+    protected readonly seekPreviewTime: _angular_core.WritableSignal<number>;
+    protected readonly state: _angular_core.Signal<ngx_kit_media_control.NgxMediaState>;
+    protected readonly playlist: _angular_core.Signal<NgxMediaSource[]>;
+    protected readonly currentIndex: _angular_core.Signal<number>;
+    protected readonly currentSource: _angular_core.Signal<NgxMediaSource>;
+    protected readonly playerError: _angular_core.Signal<ngx_kit_media_control.NgxMediaError | null>;
+    protected readonly effectiveKind: _angular_core.Signal<"audio" | "video">;
+    protected readonly displaySeekTime: _angular_core.Signal<number>;
+    protected readonly currentTimeDisplay: _angular_core.Signal<string>;
+    protected readonly totalTimeDisplay: _angular_core.Signal<string>;
+    protected readonly speedDisplay: _angular_core.Signal<string>;
+    protected readonly fileName: _angular_core.Signal<string>;
+    protected readonly isPlaying: _angular_core.Signal<boolean>;
+    protected readonly isBuffering: _angular_core.Signal<boolean>;
+    protected readonly hasLoadError: _angular_core.Signal<boolean>;
+    protected readonly errorMessage: _angular_core.Signal<string>;
+    protected readonly canFullscreen: _angular_core.Signal<boolean>;
+    protected readonly canPip: _angular_core.Signal<boolean>;
+    /**
+     * Derived from `sources()` OR `fileList()` (whichever the consumer used),
+     * memoized by CONTENT rather than reference (`equal: mediaSourcesEqual`).
+     * Angular's `input()` signal only compares by reference — a parent that
+     * binds an inline literal, e.g. `[sources]="[{...}]"`, or otherwise
+     * re-derives an equivalent array on every change-detection pass, produces
+     * a *new* array every tick. Without the custom `equal`, the effect below
+     * would see "a new value" on every tick and reload media in a loop. A
+     * content-equal `computed` keeps returning its previous, `===`-stable
+     * value whenever the new content is equivalent, so the effect below
+     * simply doesn't re-run.
+     */
+    protected readonly resolvedSources: _angular_core.Signal<NgxMediaSource[]>;
+    /** Tracks what's actually mounted in `videoHostRef`, so the mount effect only touches the DOM (and re-registers listeners) when the element itself changes, not on every unrelated signal read. */
+    private mountedElement;
+    private dblClickHandler;
+    private downloadResetTimeout;
+    constructor();
+    private detachMountedElement;
+    playPause(): void;
+    play(): void;
+    stop(): void;
+    muteUnmute(): void;
+    /**
+     * Seek strategy: dragging the slider only updates a local preview
+     * (`seekPreviewTime`) — no `facade.seek()` call, so no HTTP range
+     * request or media-pipeline seek happens per pixel of drag. The actual
+     * seek fires once, on `change` (`onSeekCommit`), which browsers fire
+     * both on pointer-release-after-drag AND after each discrete keyboard
+     * adjustment — so keyboard accessibility (arrow keys) still seeks
+     * immediately per keypress, it's only continuous dragging that's
+     * coalesced into a single request.
+     */
+    onSeekInput(ev: Event): void;
+    onSeekCommit(ev: Event): void;
+    skipTrack(seconds: number): void;
+    increaseSpeed(): void;
+    decreaseSpeed(): void;
+    changeVolume(ev: Event): void;
+    previous(): void;
+    next(): void;
+    onClickPlayList(index: number): void;
+    togglePlaylistPanel(): void;
+    /** Force-reload the current track from scratch (e.g. a "retry" affordance after an error) rather than relying on selecting the same playlist entry, which deliberately does NOT reload an already-loaded track. */
+    retryCurrent(): void;
+    downloadCurrentFile(): void;
+    toggleFullscreen(): Promise<void>;
+    togglePictureInPicture(): Promise<void>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxMediaControl, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgxMediaControl, "ngx-media-control", never, { "type": { "alias": "type"; "required": false; "isSignal": true; }; "poster": { "alias": "poster"; "required": false; "isSignal": true; }; "showList": { "alias": "showList"; "required": false; "isSignal": true; }; "download": { "alias": "download"; "required": false; "isSignal": true; }; "showFileName": { "alias": "showFileName"; "required": false; "isSignal": true; }; "showSpeed": { "alias": "showSpeed"; "required": false; "isSignal": true; }; "showVolume": { "alias": "showVolume"; "required": false; "isSignal": true; }; "linear": { "alias": "linear"; "required": false; "isSignal": true; }; "preload": { "alias": "preload"; "required": false; "isSignal": true; }; "fetchHeaders": { "alias": "fetchHeaders"; "required": false; "isSignal": true; }; "fileList": { "alias": "fileList"; "required": false; "isSignal": true; }; "sources": { "alias": "sources"; "required": false; "isSignal": true; }; }, { "trackChange": "trackChange"; "error": "error"; }, never, never, true, never>;
+}
+
+/**
+ * A decoder plugin doesn't decode into a static buffer and hand it back —
+ * real media needs streaming, seeking and duration discovery, so a decoder's
+ * job is to produce a fully-formed {@link NgxMediaEngine} that the facade can
+ * drive identically to the native engine. This keeps the abstraction usable
+ * for both "decode once into an AudioBuffer" (short clips) and "feed a
+ * MediaSource/SourceBuffer progressively" (long/streamed media) strategies,
+ * which a flat `decode() -> ArrayBuffer` contract cannot support.
+ */
+interface NgxMediaDecoder {
+    /** Unique id, used for logging/priority/debugging. */
+    readonly id: string;
+    /** Formats this decoder claims, informational (used by the registry for a fast pre-filter). */
+    readonly formats: readonly string[];
+    /**
+     * Higher runs first when multiple decoders claim the same source.
+     * Default treated as 0 by the registry.
+     */
+    readonly priority?: number;
+    /** Cheap capability check; may be async if it needs to sniff bytes. `signal` lets the registry cancel an in-flight probe (e.g. the user switched tracks before this decoder answered). */
+    canDecode(source: NgxMediaSource, signal?: AbortSignal): boolean | Promise<boolean>;
+    /**
+     * Build a ready-to-use engine for this source. `signal` allows the caller
+     * to cancel an in-flight WASM module load / stream open.
+     */
+    createEngine(source: NgxMediaSource, signal?: AbortSignal): Promise<NgxMediaEngine>;
+    /** Release any module-level resources (worker pools, cached WASM instances) held by this decoder itself. */
+    destroy(): void;
+}
+
+/**
+ * Base class for WASM-backed decoders. It does the two things every such
+ * decoder needs regardless of which codec module it wraps:
+ *
+ *  1. Lazily `import()`s the codec module on first real use, in a Web Worker
+ *     when a worker factory is supplied, so the (typically large) WASM binary
+ *     never enters the main bundle or the main thread's JS heap unless a
+ *     source actually needs it.
+ *  2. Provides a cancellable, disposable lifecycle (`AbortSignal`-aware load,
+ *     `destroy()` terminates the worker / frees the WASM instance) that is
+ *     safe under overlap: a `destroy()` that lands while `loadModule()` is
+ *     still pending must not let that pending load "resurrect" a module
+ *     reference for a decoder instance that's already gone, and must not
+ *     let a subsequent `createEngine()` call kick off a SECOND concurrent
+ *     module load while the first is still in flight.
+ *
+ * This class intentionally does NOT ship a real codec — bundling e.g.
+ * `@ffmpeg/ffmpeg` here would violate "no WASM in the default bundle" for
+ * every consumer, including ones who never touch this file. Concrete
+ * decoders (FLAC, WMA, a consumer's own 3GP decoder, ...) extend this and
+ * supply `loadModule` + `buildEngine`.
+ */
+declare abstract class NgxWasmDecoderBase implements NgxMediaDecoder {
+    abstract readonly id: string;
+    abstract readonly formats: readonly string[];
+    priority: number;
+    private worker;
+    private modulePromise;
+    /** Bumped by every `destroy()`; lets an in-flight `loadModule()`/`createEngine()` notice it's talking to a dead instance once it resolves. */
+    private generation;
+    /** Import path/factory for the codec's WASM glue module. Not evaluated until first `canDecode()`/`createEngine()` call. */
+    protected abstract loadModule(): Promise<unknown>;
+    /** Optional: return a `Worker` to run decoding off the main thread. Omit for short clips where worker overhead isn't worth it. */
+    protected createWorker?(): Worker;
+    abstract canDecode(source: NgxMediaSource, signal?: AbortSignal): boolean | Promise<boolean>;
+    /**
+     * Subclasses implement the actual decode-to-playable-engine step once the
+     * module (and optionally worker) are ready. Typical strategies:
+     *  - decode fully into an `AudioBuffer`, play via Web Audio (`AudioBufferSourceNode`)
+     *  - decode progressively, feed an MSE `SourceBuffer`
+     */
+    protected abstract buildEngine(source: NgxMediaSource, module: unknown, worker: Worker | null, signal?: AbortSignal): Promise<NgxMediaEngine>;
+    createEngine(source: NgxMediaSource, signal?: AbortSignal): Promise<NgxMediaEngine>;
+    private ensureModuleLoaded;
+    destroy(): void;
+}
+/**
+ * Minimal playable-engine wrapper around a fully-decoded `AudioBuffer`,
+ * useful for WASM decoders that decode short clips completely up front
+ * rather than streaming. Reuses the browser's own `AudioContext` playback
+ * graph instead of a native `<audio>` element, since there's no compressed
+ * file for the browser to play directly anymore.
+ *
+ * Playback-position bookkeeping: `offset` is the buffer-time position when
+ * the current `AudioBufferSourceNode` was (re)started, `startedAt` is the
+ * `AudioContext.currentTime` at that moment, and `rate` is the playback
+ * rate in effect since then — so at any instant, position =
+ * `offset + (ctx.currentTime - startedAt) * rate`. Every operation that
+ * stops or restarts the source (pause, seek, rate change while playing,
+ * replay after ended) re-baselines these three fields together so that
+ * formula stays correct instead of drifting.
+ */
+declare class DecodedBufferEngine implements NgxMediaEngine {
+    private readonly buffer;
+    readonly id: string;
+    readonly kind: NgxMediaKind;
+    readonly mediaElement: null;
+    private readonly _state;
+    readonly state: Signal<NgxMediaState>;
+    private ctx;
+    private source;
+    private gain;
+    private startedAt;
+    private offset;
+    private rate;
+    private volume;
+    private muted;
+    private rafId;
+    /** Bumped every time a NEW `AudioBufferSourceNode` is created, so a stale `onended` from a node that was `.stop()`-ed (rather than actually finishing) can recognize it's obsolete and not overwrite newer state. */
+    private playToken;
+    constructor(decoderId: string, ctx: AudioContext, buffer: AudioBuffer);
+    play(): Promise<void>;
+    pause(): void;
+    seek(time: number): void;
+    setVolume(volume: number): void;
+    setMuted(muted: boolean): void;
+    setPlaybackRate(rate: number): void;
+    load(): Promise<void>;
+    destroy(): void;
+    private currentPosition;
+    /** Drives `currentTime` for the UI while actually playing — never runs during pause/ended/destroyed, so there's no animation loop burning frames when nothing is moving. */
+    private startTimeTracking;
+    private stopTimeTracking;
+}
+
+/**
+ * Default fast-path engine: plays through a real `<audio>`/`<video>` element.
+ * Zero WASM, zero MediaSource — the browser's own decode pipeline does the work.
+ *
+ * Load semantics (the part that matters most for network behavior):
+ *  - `load()` is a real 3-state machine (idle/loading/ready) keyed on
+ *    {@link SourceIdentity}, not just a `readyState` snapshot:
+ *      same source + currently loading  -> returns the SAME in-flight promise
+ *      same source + already loaded     -> resolves immediately, no `el.load()` call
+ *      different source                 -> proceeds; the browser's own load
+ *                                           algorithm aborts whatever the
+ *                                           element was doing before
+ *  - Setting `el.src` already queues the browser's media load algorithm;
+ *    the immediate `el.load()` call right after does not cause a second
+ *    network request — its purpose is to make the abort-then-restart
+ *    synchronous (needed for older WebKit), not to "load twice". The state
+ *    machine above is what actually prevents redundant fetches across
+ *    repeated `load()` calls for the same source.
+ *
+ * Performance notes:
+ *  - `timeupdate`/`progress`/etc. fire far more often than the UI needs to
+ *    re-render; listeners run via `runOutsideAngular`, and `patch()` skips
+ *    the signal write entirely when nothing actually changed (including a
+ *    content-equal `buffered` array, which would otherwise allocate and
+ *    write on every `progress` tick even when the ranges didn't move).
+ */
+declare class NativeMediaEngine implements NgxMediaEngine {
+    /** Provided by the facade so listener callbacks never re-enter Angular's zone. */
+    private readonly runOutsideAngular;
+    readonly id = "native";
+    readonly kind: NgxMediaKind;
+    private readonly _state;
+    readonly state: Signal<NgxMediaState>;
+    private readonly el;
+    private objectUrl;
+    private destroyed;
+    private readonly cleanupFns;
+    private loadState;
+    private loadedIdentity;
+    private pendingLoad;
+    private activeLoadController;
+    constructor(kind: NgxMediaKind, 
+    /** Provided by the facade so listener callbacks never re-enter Angular's zone. */
+    runOutsideAngular?: <T>(fn: () => T) => T, existingElement?: HTMLMediaElement, preload?: 'none' | 'metadata' | 'auto');
+    get mediaElement(): HTMLMediaElement;
+    load(source: NgxMediaSource, abort?: AbortSignal): Promise<void>;
+    private performLoad;
+    play(): Promise<void>;
+    pause(): void;
+    seek(time: number): void;
+    setVolume(volume: number): void;
+    setMuted(muted: boolean): void;
+    setPlaybackRate(rate: number): void;
+    destroy(): void;
+    private resolveSrc;
+    private releaseObjectUrl;
+    /** Skips the signal write entirely when every field in `partial` is already equal to current state. */
+    private patch;
+    private bufferedRanges;
+    private attachListeners;
+    /**
+     * Some servers/streams report `duration === Infinity` until more data
+     * arrives. This forces the browser to resolve it immediately by seeking
+     * near the end and back — which works, but each call costs 1-2 extra
+     * HTTP range requests. No longer called automatically; opt-in for the
+     * rare case where you genuinely need duration *immediately* rather than
+     * letting `durationchange` update it naturally during normal playback.
+     */
+    probeUnseekableDuration(): Promise<void>;
+    private assertNotDestroyed;
+}
+
+/**
+ * Multi-provider token: every decoder a consumer registers via
+ * `provideNgxMediaDecoder()` is picked up automatically by the registry.
+ *
+ * IMPORTANT: this token intentionally has NO default factory. Angular does
+ * not allow mixing a token's own default provider with externally
+ * registered `multi: true` providers for the SAME token — doing so throws
+ * at DI-construction time the moment a consumer actually registers a
+ * decoder (a real, if latent, bug this fixes). The correct pattern for an
+ * "optionally empty" multi token is `@Optional()` injection at the
+ * consumption site (see `NgxMediaDecoderRegistry`), which yields `null`
+ * when nothing has registered and an array when one or more have.
+ */
+declare const NGX_MEDIA_DECODER: InjectionToken<NgxMediaDecoder>;
+/** Pluggable network layer so auth/signed URLs don't require coupling the core to HttpClient. */
+interface NgxMediaRequestHandler {
+    request(source: NgxMediaSource, signal?: AbortSignal): Promise<Response>;
+}
+declare const NGX_MEDIA_REQUEST_HANDLER: InjectionToken<NgxMediaRequestHandler>;
+interface NgxMediaConfig {
+    /** Default preload hint for native engines. */
+    preload: 'none' | 'metadata' | 'auto';
+    /** Ceiling for the number of decoder `canDecode` probes run in parallel. */
+    maxConcurrentDecoderProbes: number;
+}
+declare const NGX_MEDIA_CONFIG_DEFAULTS: NgxMediaConfig;
+declare const NGX_MEDIA_CONFIG: InjectionToken<NgxMediaConfig>;
+
+/**
+ * Root-level setup: `bootstrapApplication(App, { providers: [provideNgxMedia({...})] })`.
+ * The supplied config is merged over the library's own defaults, not
+ * replacing them outright — `provideNgxMedia({ preload: 'auto' })` must not
+ * silently drop `maxConcurrentDecoderProbes` and leave it `undefined`.
+ */
+declare function provideNgxMedia(config?: Partial<NgxMediaConfig>): EnvironmentProviders;
+/**
+ * Registers a decoder plugin into the `NGX_MEDIA_DECODER` multi-provider
+ * token. Accepts a class (instantiated via DI, so it can itself inject
+ * services) or a ready-made instance for simple cases.
+ *
+ *   bootstrapApplication(AppComponent, {
+ *     providers: [provideNgxMediaDecoder(My3gpDecoder)],
+ *   });
+ */
+declare function provideNgxMediaDecoder(decoder: Type<NgxMediaDecoder> | NgxMediaDecoder): EnvironmentProviders;
+/** Registers a custom network layer (auth headers, signed URLs, a non-fetch HTTP client, ...). */
+declare function provideNgxMediaRequestHandler(handler: NgxMediaRequestHandler): EnvironmentProviders;
+
+/**
+ * Format time in seconds as MM:SS
+ * @param seconds number
+ * @returns MM:SS
+ */
+declare function formatTime(seconds: number): string;
+
+/** True only in a real browser context — guards every browser API access for SSR. */
+declare function isBrowser(): boolean;
+declare function hasMediaSource(): boolean;
+declare function hasAudioContext(): boolean;
+declare function getAudioContextCtor(): typeof AudioContext | undefined;
+declare function hasMediaSession(): boolean;
+declare function hasPictureInPicture(): boolean;
+declare function hasFullscreen(): boolean;
+/**
+ * Best-effort container/codec detection using `canPlayType`. Never trusts the
+ * file extension alone: extension is only a last-resort hint when neither
+ * `type` nor `codecs` was supplied.
+ */
+declare function canPlayNatively(el: HTMLMediaElement, source: NgxMediaSource): 'probably' | 'maybe' | '';
+
+export { DecodedBufferEngine, NGX_MEDIA_CONFIG, NGX_MEDIA_CONFIG_DEFAULTS, NGX_MEDIA_DECODER, NGX_MEDIA_REQUEST_HANDLER, NativeMediaEngine, NgxMediaControl, NgxMediaError, NgxWasmDecoderBase, PlayList, canPlayNatively, canTransition, extractMediaFileName, formatTime, getAudioContextCtor, hasAudioContext, hasFullscreen, hasMediaSession, hasMediaSource, hasPictureInPicture, initialMediaState, isBrowser, mediaSourcesEqual, playListToMediaSource, provideNgxMedia, provideNgxMediaDecoder, provideNgxMediaRequestHandler };
+export type { NgxEngineCapability, NgxMediaConfig, NgxMediaDecoder, NgxMediaEngine, NgxMediaErrorCategory, NgxMediaKind, NgxMediaPlaybackState, NgxMediaPlaylist, NgxMediaRequestHandler, NgxMediaSource, NgxMediaState, NgxMediaType, NgxTimeRange };