@ngxsp/core 0.0.1-next.0

package/index.d.ts

@@ -0,0 +1,853 @@
+import { Observable } from 'rxjs';
+
+interface MetadataHint {
+    contentId?: string;
+    title?: string;
+    year?: number;
+    imdbId?: string;
+    tmdbId?: string;
+}
+interface VideoMetadata {
+    title?: string;
+    description?: string;
+    year?: number;
+    genres?: string[];
+    cast?: string[];
+    posterUrl?: string;
+    backdropUrl?: string;
+    extras?: Record<string, unknown>;
+}
+interface MetadataMatch {
+    id: string;
+    label: string;
+    score?: number;
+    extra?: unknown;
+}
+interface MetadataProvider {
+    id: string;
+    match(hint: MetadataHint): Promise<MetadataMatch[]>;
+    fetch(id: string): Promise<VideoMetadata>;
+}
+
+interface CapabilityReport {
+    timestamp: number;
+    userAgent?: string;
+    source?: {
+        type?: string;
+        live?: boolean;
+        drm?: boolean;
+        url?: string;
+        contentId?: string;
+    };
+    platform: {
+        isSecureContext: boolean;
+    };
+    features: {
+        mse: boolean;
+        eme: boolean;
+        mediaCapabilities: boolean;
+    };
+    canPlay: Record<string, boolean>;
+    /**
+     * Optional, best-effort decoding probes via the MediaCapabilities API.
+     *
+     * Keys are stable labels (e.g. "h264_1080p").
+     */
+    mediaDecoding?: Record<string, {
+        supported: boolean;
+        smooth?: boolean;
+        powerEfficient?: boolean;
+    }>;
+    notes: string[];
+}
+/** Best-effort decoding probes used for diagnostics and ABR tuning hints. */
+declare function createMediaDecodingReport(): Promise<CapabilityReport['mediaDecoding']>;
+declare function createCapabilityReport(videoEl?: HTMLVideoElement, cfg?: PlayerConfig, mediaDecoding?: CapabilityReport['mediaDecoding']): CapabilityReport;
+
+type SourceType = 'local-file' | 'url' | 'hls' | 'dash';
+/**
+ * High-level playback profiles (v2.0).
+ *
+ * Used to apply sensible defaults (ABR / buffering) with minimal configuration.
+ */
+type EngineProfileId = 'default' | 'tv' | 'mobile' | 'low-latency';
+type AspectRatioMode = 'contain' | 'cover' | '1:1' | '4:3' | '16:9' | '21:9';
+type ProgressMode = 'local' | 'server' | 'hybrid';
+type AdsMode = 'csai' | 'ssai' | 'mixed';
+interface DrmConfig {
+    /**
+     * Key system configuration, usually driven by your backend.
+     * Examples: 'com.widevine.alpha', 'com.microsoft.playready'
+     */
+    keySystems: Record<string, {
+        licenseServerUrl: string;
+        /**
+         * Additional request headers sent to the license server.
+         */
+        headers?: Record<string, string>;
+        /** Optional robustness constraints (e.g. 'SW_SECURE_DECODE', 'HW_SECURE_ALL'). */
+        videoRobustness?: string;
+        audioRobustness?: string;
+    }>;
+    /**
+     * Whether offline/persistent licenses are intended for this content.
+     * Actual capability depends on device + license policy.
+     */
+    persistentLicense?: boolean;
+    /**
+     * License request retry policy.
+     *
+     * If unset, engines should apply conservative defaults (3 attempts, exponential backoff).
+     */
+    licenseRetry?: {
+        maxAttempts?: number;
+        baseDelayMs?: number;
+        backoffFactor?: number;
+        fuzzFactor?: number;
+        timeoutMs?: number;
+    };
+}
+interface PlayerSource {
+    type: SourceType;
+    url?: string;
+    file?: File;
+    live?: boolean;
+    drm?: DrmConfig;
+    /** Optional engine profile for default tuning (can be set at `PlayerConfig.profile`). */
+    profile?: EngineProfileId;
+    /**
+     * Optional ABR hints for adaptive engines (e.g. Shaka).
+     *
+     * These are *hints* only: engines may ignore them if unsupported.
+     */
+    abr?: {
+        /** Hard cap for rendition height (e.g. 720). */
+        maxHeight?: number;
+        /** Hard cap for bitrate (bits/s). */
+        maxBandwidth?: number;
+    };
+    /** Internal engine hints (best-effort). */
+    _shakaStreaming?: {
+        lowLatencyMode?: boolean;
+        bufferingGoalSec?: number;
+        rebufferingGoalSec?: number;
+    };
+    /**
+     * Whether this source is allowed to be downloaded/offlined.
+     */
+    offlineEligible?: boolean;
+    /**
+     * Optional identifier for progress/metadata/subtitles lookup.
+     */
+    contentId?: string;
+    /**
+     * Optional sidecar URL for local metadata (json/txt) or subtitles.
+     */
+    sidecar?: {
+        metadataUrl?: string;
+        subtitles?: Array<{
+            lang: string;
+            url: string;
+            format?: string;
+        }>;
+        chaptersUrl?: string;
+        thumbnailVttUrl?: string;
+    };
+}
+interface ProgressConfig {
+    mode: ProgressMode;
+    endpoint?: string;
+    intervalSec: number;
+}
+interface SkipSegment {
+    kind: 'intro' | 'recap';
+    startSec: number;
+    endSec: number;
+}
+interface NextEpisodeHint {
+    label: string;
+    onNext: () => void | Promise<void>;
+}
+interface UiConfig {
+    /** Optional UI skin preset (default: classic) */
+    skin?: 'classic' | 'netflix';
+    /** Optional display title used by some skins */
+    title?: string;
+    ratios: AspectRatioMode[];
+    defaultRatio: AspectRatioMode;
+    keyboardShortcuts: boolean;
+    skipSegments?: SkipSegment[];
+    nextEpisode?: NextEpisodeHint;
+    chaptersVttUrl?: string;
+    thumbnailsVttUrl?: string;
+    /** Preview strategy for timeline hover (default: thumbnails) */
+    previewMode?: 'thumbnails' | 'frame' | 'off';
+}
+interface ResilienceConfig {
+    retries: number;
+    backoffMs: {
+        min: number;
+        max: number;
+    };
+    healthEndpoint?: string;
+}
+interface SubtitleHint {
+    contentId?: string;
+    title?: string;
+    season?: number;
+    episode?: number;
+    language?: string;
+    /** Année (films) */
+    year?: number;
+    /** Identifiants externes (optionnels) */
+    imdbId?: string;
+    tmdbId?: number;
+    /** Pour rester extensible sans casser le typage */
+    extra?: Record<string, unknown>;
+}
+interface SubtitlesConfig {
+    enabled: boolean;
+    providers: string[];
+    preferredLang?: string;
+    /** Optional hint for internet providers */
+    hint?: SubtitleHint;
+}
+interface MetadataConfig {
+    enabled: boolean;
+    providers: string[];
+    localSidecar: boolean;
+    /** Optional hint for internet providers */
+    hint?: MetadataHint;
+}
+interface AdsConfig {
+    enabled: boolean;
+    mode: AdsMode;
+    providerConfig?: unknown;
+}
+interface EpisodeItem {
+    /** Unique id for progress/offline/metadata/subtitles. */
+    contentId: string;
+    season?: number;
+    episode?: number;
+    title?: string;
+    source: PlayerSource;
+    /** Optional per-episode UI overrides (skip segments, thumbnails, etc.) */
+    ui?: Partial<UiConfig>;
+    /** Optional metadata hint for internet providers. */
+    metadataHint?: {
+        title?: string;
+        year?: number;
+        imdbId?: string;
+        tmdbId?: string;
+    };
+}
+interface SeriesConfig {
+    title?: string;
+    /** 0-based index of current episode in episodes[] */
+    currentIndex: number;
+    episodes: EpisodeItem[];
+    /** Auto-play next episode when ended. Default true. */
+    autoNext?: boolean;
+    /** Warm-up next episode manifest when within N seconds of end. Default 30. */
+    preloadNextSeconds?: number;
+}
+interface PlayerConfig {
+    source: PlayerSource;
+    /** High-level playback profile (v2.0). */
+    profile?: EngineProfileId;
+    /** Optional DRM config. When set, it overrides/augments source.drm. */
+    drm?: DrmConfig;
+    /** Optional series mode */
+    series?: SeriesConfig;
+    /** Optional playlist mode (overrides source at runtime) */
+    playlist?: PlayerSource[];
+    /** Starting index in playlist (default 0) */
+    playlistStartIndex?: number;
+    /** Auto-play next item on ended (default true when playlist provided) */
+    autoNext?: boolean;
+    progress: ProgressConfig;
+    ui: UiConfig;
+    resilience: ResilienceConfig;
+    subtitles: SubtitlesConfig;
+    metadata: MetadataConfig;
+    ads: AdsConfig;
+    /** Optional: enable offline materialization via @ngxsp/plugin-offline. */
+    offline?: {
+        enabled?: boolean;
+        /** Storage key override; default = `offline:${contentId || url}` */
+        key?: string;
+    };
+    /**
+     * Remote control-plane: fetch JSON overrides at runtime (optionally cached), then merge into this config.
+     * Designed to keep the engine decoupled from Angular and allow feature flags / tuning without rebuild.
+     */
+    remoteConfig?: RemoteConfigConfig;
+}
+interface RemoteConfigConfig {
+    enabled: boolean;
+    /** Absolute URL returning a JSON payload (object). */
+    url: string;
+    /** Cache TTL (seconds). Default: 300s. */
+    ttlSec?: number;
+    /** Merge mode. Default: 'deep'. */
+    mode?: 'shallow' | 'deep';
+    /** Allow-list of top-level keys that can be overridden remotely. */
+    allow?: string[];
+}
+type RemoteConfigPayload = Record<string, unknown>;
+type PlayerState = {
+    kind: 'idle';
+} | {
+    kind: 'loading';
+} | {
+    kind: 'buffering';
+} | {
+    kind: 'playing';
+} | {
+    kind: 'paused';
+} | {
+    kind: 'ended';
+} | {
+    kind: 'error';
+    error: PlayerError;
+};
+/**
+ * Minimal time model exposed by the public API.
+ * Kept as a stable alias for wrappers (Angular/Electron) and adapters.
+ */
+interface PlayerTime {
+    currentTime: number;
+    duration: number;
+    /** Best-effort buffered end (seconds) for native playback. */
+    bufferedEnd?: number;
+}
+
+interface DiagnosticsEngineInfo {
+    /** Selected engine id (ex: 'native', 'shaka') */
+    id: string;
+    /** How the engine was selected */
+    selectedBy: 'supports' | 'caps' | 'fallback' | 'explicit' | 'none';
+    /** Optional selection reasons (debuggable, non-normative) */
+    reasons: string[];
+}
+interface DiagnosticsSnapshot {
+    /** Epoch milliseconds when the snapshot was produced. */
+    ts: number;
+    engine: DiagnosticsEngineInfo;
+    capabilities: CapabilityReport;
+    source?: PlayerSource;
+    state: PlayerState;
+    time: PlayerTime;
+    lastNonFatal: PlayerError | null;
+    /** @deprecated use `engine.id` */
+    selectedEngineId?: string;
+    /** @deprecated use `state` + `time` */
+    snapshot?: {
+        currentTime: number;
+        duration: number;
+        state: PlayerState;
+        bufferedAheadSec: number;
+    };
+}
+type PlayerErrorCode = 'AUTOPLAY_BLOCKED' | 'SRC_NOT_SUPPORTED' | 'NETWORK_TIMEOUT' | 'NETWORK_HTTP' | 'DECODE_ERROR' | 'ENGINE_MISSING' | 'ENGINE_CRASH' | 'DRM_ERROR' | 'UNKNOWN';
+interface PlayerError {
+    code: PlayerErrorCode | string;
+    message: string;
+    fatal?: boolean;
+    details?: unknown;
+}
+interface MediaTrack {
+    id: string;
+    kind: 'audio' | 'text' | 'video';
+    language?: string;
+    label?: string;
+    active: boolean;
+    width?: number;
+    height?: number;
+    bandwidth?: number;
+}
+type PlayerEvent = {
+    type: 'play';
+} | {
+    type: 'pause';
+} | {
+    type: 'timeupdate';
+    currentTime: number;
+    duration: number;
+} | {
+    type: 'ended';
+} | {
+    type: 'error';
+    code: PlayerErrorCode | string;
+    message: string;
+    detail?: unknown;
+} | {
+    type: 'adbreak-start';
+    id?: string;
+} | {
+    type: 'adbreak-end';
+    id?: string;
+} | {
+    type: 'ad-start';
+    id?: string;
+} | {
+    type: 'ad-end';
+    id?: string;
+};
+
+type EngineEvent = {
+    type: 'timeupdate';
+    currentTime: number;
+    duration: number;
+} | {
+    type: 'bufferupdate';
+    bufferedAheadSec: number;
+} | {
+    type: 'state';
+    state: 'loading' | 'buffering' | 'playing' | 'paused' | 'ended';
+} | {
+    type: 'tracks';
+    tracks: MediaTrack[];
+} | {
+    type: 'error';
+    error: {
+        code: string;
+        message: string;
+        fatal?: boolean;
+        details?: unknown;
+    };
+};
+interface LoadOptions {
+    startTimeSec?: number;
+    /** Optional playlist index override for PlayerFacade */
+    playlistIndex?: number;
+}
+interface PlaybackEngine {
+    readonly id: string;
+    attach(videoEl: HTMLVideoElement): Promise<void>;
+    load(source: PlayerSource, opts?: LoadOptions): Promise<void>;
+    destroy(): Promise<void>;
+    play(): Promise<void>;
+    pause(): Promise<void>;
+    seekTo(timeSec: number): Promise<void>;
+    setPlaybackRate(rate: number): Promise<void>;
+    setVolume(volume: number): Promise<void>;
+    setTextTrack(trackId: string | null): Promise<void>;
+    setAudioTrack(trackId: string | null): Promise<void>;
+    setVideoTrack(trackId: string | null): Promise<void>;
+    getTracks(): Promise<MediaTrack[]>;
+    onEvent(cb: (ev: EngineEvent) => void): () => void;
+}
+
+interface PlaybackCapabilities {
+    /** Browser has MediaSource (MSE). */
+    mse: boolean;
+    /** Browser has Encrypted Media Extensions (EME) API. */
+    eme: boolean;
+    /** True if navigator.mediaCapabilities is available. */
+    mediaCapabilities: boolean;
+    /** Whether basic HLS playback is possible via MSE/native. */
+    hls: boolean;
+    /** Whether basic DASH playback is possible via MSE. */
+    dash: boolean;
+    /** Progressive mp4/webm playback via <video src>. */
+    progressive: boolean;
+    /** Heuristic: support for at least one of common video codecs. */
+    codecs: {
+        mp4_h264: boolean;
+        mp4_hevc: boolean;
+        webm_vp9: boolean;
+        webm_av1: boolean;
+    };
+    /** Known DRM key systems availability (best-effort). */
+    drm: {
+        widevine: boolean;
+        playready: boolean;
+        fairplay: boolean;
+    };
+}
+declare function createDefaultCapabilities(): PlaybackCapabilities;
+declare function detectPlaybackCapabilities(videoEl?: HTMLVideoElement): Promise<PlaybackCapabilities>;
+
+interface EngineFactory {
+    /** Unique id (ex: 'native', 'shaka') */
+    id: string;
+    /** Higher priority wins when multiple support the same source. Default 0. */
+    priority?: number;
+    /** Whether this engine supports this config/source. */
+    supports(config: PlayerConfig): boolean;
+    /**
+     * Optional, capability-aware selector.
+     * If present, it is preferred over supports().
+     */
+    supportsWithCaps?: (config: PlayerConfig, caps: PlaybackCapabilities) => boolean;
+    /** Create a new engine instance. */
+    create(): PlaybackEngine;
+}
+declare function selectEngine(config: PlayerConfig, factories: EngineFactory[], caps?: PlaybackCapabilities): EngineFactory | null;
+
+interface HttpPort {
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+
+interface StoragePort {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove?(key: string): Promise<void>;
+}
+declare class MemoryStoragePort implements StoragePort {
+    private map;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+
+interface TelemetryPort {
+    add(sample: Record<string, unknown>): void;
+    export?(): unknown;
+}
+declare class NoopTelemetryPort implements TelemetryPort {
+    add(_sample: Record<string, unknown>): void;
+}
+
+interface LogPort {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+declare class ConsoleLogPort implements LogPort {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+
+interface PlayerPorts {
+    http: HttpPort;
+    storage: StoragePort;
+    telemetry: TelemetryPort;
+    log: LogPort;
+}
+declare function createDefaultPorts(): PlayerPorts;
+
+interface PlayerSnapshot {
+    currentTime: number;
+    duration: number;
+    state: PlayerState;
+    bufferedAheadSec: number;
+}
+/**
+ * Public diagnostics payload.
+ *
+ * NOTE: This is intentionally an alias of `DiagnosticsSnapshot` to keep one
+ * canonical shape exported by `@ngxsp/core`.
+ */
+type PlayerDiagnostics = DiagnosticsSnapshot;
+declare class PlayerFacade {
+    private chooseEngine;
+    private ports;
+    private engineFactories;
+    private engineId;
+    private lastNonFatal;
+    private mediaDecodingSub;
+    private video?;
+    private engine?;
+    private plugins;
+    private ctx?;
+    private stateSub;
+    private timeSub;
+    private bufferSub;
+    private tracksSub;
+    private errorSub;
+    private metadataSub;
+    private capsSub;
+    readonly capabilities$: Observable<PlaybackCapabilities | null>;
+    readonly state$: Observable<PlayerState>;
+    readonly time$: Observable<{
+        currentTime: number;
+        duration: number;
+    }>;
+    readonly bufferAheadSec$: Observable<number>;
+    readonly tracks$: Observable<MediaTrack[]>;
+    readonly error$: Observable<PlayerError>;
+    readonly metadata$: Observable<VideoMetadata | null>;
+    private seriesIndexSub;
+    readonly seriesIndex$: Observable<number | null>;
+    private playlistIndexSub;
+    readonly playlistIndex$: Observable<number | null>;
+    private playlist;
+    private playlistKey;
+    private externalVttUrl?;
+    constructor(chooseEngine?: (cfg: PlayerConfig) => PlaybackEngine, ports?: PlayerPorts);
+    attach(videoEl: HTMLVideoElement, plugins: PlayerPlugin[] | undefined, config: PlayerConfig, ports?: Partial<PlayerPorts>, engines?: EngineFactory[]): void;
+    load(config: PlayerConfig, opts?: LoadOptions): Promise<void>;
+    reload(opts?: LoadOptions): Promise<void>;
+    next(): Promise<void>;
+    previous(): Promise<void>;
+    destroy(): Promise<void>;
+    /** Emit a non-fatal error (does not transition to fatal error state). */
+    emitNonFatal(err: unknown, code?: PlayerErrorCode | string): void;
+    /** Emit a fatal error (transitions to error state). */
+    private emitFatal;
+    private tryAutoNext;
+    private installed;
+    private qoe;
+    private installVideoEventListeners;
+    private emitTelemetry;
+    private toPlayerError;
+    play(): Promise<void>;
+    pause(): Promise<void>;
+    seekTo(timeSec: number): Promise<void>;
+    setRate(rate: number): Promise<void>;
+    setVolume(volume: number): Promise<void>;
+    setTextTrack(trackId: string | null): Promise<void>;
+    setAudioTrack(trackId: string | null): Promise<void>;
+    setVideoTrack(trackId: string | null): Promise<void>;
+    setAspectRatio(_mode: AspectRatioMode): void;
+    snapshot(): PlayerSnapshot;
+    /**
+     * Diagnostics helper for UI / support logs.
+     * Safe to call anytime after attach().
+     */
+    diagnostics(): PlayerDiagnostics;
+    setExternalVttTrack(lang: string, vtt: string): Promise<void>;
+    setMetadata(meta: VideoMetadata): void;
+    private ensureExternalTrack;
+    private handleEngineEvent;
+    private tryRestoreStartTime;
+}
+
+interface PlayerContext {
+    config: PlayerConfig;
+    facade: PlayerFacade;
+    ports: PlayerPorts;
+    /**
+     * Stable content identifier if available (used for progress/subtitle/metadata lookups).
+     */
+    contentId?: string;
+}
+interface PlayerPlugin {
+    id: string;
+    onInit?(ctx: PlayerContext): void | Promise<void>;
+    onLoadStart?(ctx: PlayerContext): void | Promise<void>;
+    onLoaded?(ctx: PlayerContext): void | Promise<void>;
+    onError?(ctx: PlayerContext, err: PlayerError): void | Promise<void>;
+    onDestroy?(ctx: PlayerContext): void | Promise<void>;
+}
+
+declare class NativeEngine implements PlaybackEngine {
+    readonly id = "native";
+    private video?;
+    private listeners;
+    attach(videoEl: HTMLVideoElement): Promise<void>;
+    load(source: PlayerSource, opts?: {
+        startTimeSec?: number;
+    }): Promise<void>;
+    destroy(): Promise<void>;
+    play(): Promise<void>;
+    pause(): Promise<void>;
+    seekTo(timeSec: number): Promise<void>;
+    setPlaybackRate(rate: number): Promise<void>;
+    setVolume(volume: number): Promise<void>;
+    setTextTrack(_trackId: string | null): Promise<void>;
+    setAudioTrack(_trackId: string | null): Promise<void>;
+    setVideoTrack(_trackId: string | null): Promise<void>;
+    getTracks(): Promise<MediaTrack[]>;
+    onEvent(cb: (ev: EngineEvent) => void): () => void;
+}
+
+/**
+ * Local provider: loads sidecar metadata from a URL (json or txt).
+ * - JSON: parsed into `VideoMetadata` where possible
+ * - TXT: stored as description
+ */
+declare class LocalMetadataProvider implements MetadataProvider {
+    id: string;
+    match(_hint: MetadataHint): Promise<MetadataMatch[]>;
+    fetch(id: string): Promise<VideoMetadata>;
+}
+
+interface SubtitleQuery {
+    contentId?: string;
+    title?: string;
+    season?: number;
+    episode?: number;
+    language?: string;
+}
+interface SubtitleCandidate {
+    id: string;
+    providerId: string;
+    lang: string;
+    label?: string;
+    format?: string;
+    score?: number;
+    url?: string;
+    extra?: unknown;
+}
+interface SubtitleProvider {
+    id: string;
+    search(query: SubtitleQuery): Promise<SubtitleCandidate[]>;
+    fetch(candidate: SubtitleCandidate): Promise<string | ArrayBuffer>;
+}
+
+/**
+ * Local provider: uses `config.source.sidecar.subtitles` entries as candidates.
+ */
+declare class LocalSubtitleProvider implements SubtitleProvider {
+    id: string;
+    search(query: SubtitleQuery): Promise<SubtitleCandidate[]>;
+    fetch(candidate: SubtitleCandidate): Promise<string | ArrayBuffer>;
+}
+
+interface CacheStore {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttlMs: number): Promise<void>;
+    del(key: string): Promise<void>;
+}
+declare class DefaultCacheStore implements CacheStore {
+    private dbp;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttlMs: number): Promise<void>;
+    del(key: string): Promise<void>;
+    private db;
+}
+
+type PlayerCommand = {
+    type: 'play';
+} | {
+    type: 'pause';
+} | {
+    type: 'toggle';
+} | {
+    type: 'seek';
+    to: number;
+} | {
+    type: 'setPlaybackRate';
+    rate: number;
+} | {
+    type: 'setVolume';
+    volume: number;
+} | {
+    type: 'setMuted';
+    muted: boolean;
+} | {
+    type: 'selectTextTrack';
+    id: string;
+} | {
+    type: 'disableTextTrack';
+} | {
+    type: 'selectAudioTrack';
+    id: string;
+} | {
+    type: 'requestPiP';
+} | {
+    type: 'exitPiP';
+} | {
+    type: 'requestFullscreen';
+} | {
+    type: 'exitFullscreen';
+} | {
+    type: 'requestCast';
+} | {
+    type: 'stopCast';
+};
+declare function isCategorizedEventType(type: string): boolean;
+
+type Unsubscribe = () => void;
+interface PlayerEventBus {
+    emit(event: PlayerEvent): void;
+    on<T extends PlayerEvent['type']>(type: T, handler: (e: Extract<PlayerEvent, {
+        type: T;
+    }>) => void): Unsubscribe;
+}
+declare class SimpleEventBus implements PlayerEventBus {
+    private handlers;
+    emit(event: PlayerEvent): void;
+    on<T extends PlayerEvent['type']>(type: T, handler: (e: Extract<PlayerEvent, {
+        type: T;
+    }>) => void): Unsubscribe;
+}
+
+declare class ProgressPlugin implements PlayerPlugin {
+    readonly id = "progress";
+    private timer;
+    onLoadStart(ctx: PlayerContext): Promise<void>;
+    onLoaded(ctx: PlayerContext): Promise<void>;
+    onDestroy(ctx: PlayerContext): Promise<void>;
+    private stop;
+    private save;
+}
+
+declare class ResiliencePlugin implements PlayerPlugin {
+    readonly id = "resilience";
+    private attempts;
+    private recovering;
+    onLoadStart(ctx: PlayerContext): Promise<void>;
+    onError(ctx: PlayerContext, err: PlayerError): Promise<void>;
+    private health;
+}
+
+/**
+ * SSAI helper (v1.11)
+ *
+ * Keeps the core decoupled from vendor SDKs.
+ * This plugin rewrites the manifest URL before the engine loads it.
+ */
+interface SsaiManifestRewriteConfig {
+    /** If provided, used as the final playback URL (highest priority). */
+    stitchedUrl?: string;
+    /** Append query parameters to the source URL (e.g. session, device). */
+    appendQuery?: Record<string, string | number | boolean | null | undefined>;
+}
+declare function createSsaiManifestRewritePlugin(): PlayerPlugin;
+
+type TelemetryLevel = 'debug' | 'info' | 'warn' | 'error';
+type TelemetryEvent = 'player:init' | 'player:attach' | 'player:source_set' | 'player:engine_selected' | 'player:load_start' | 'player:load_ok' | 'player:load_fail' | 'player:play_request' | 'player:play_ok' | 'player:play_fail' | 'player:pause' | 'player:timeupdate' | 'player:ended' | 'player:error_nonfatal' | 'player:error_fatal' | 'player:playing' | 'qoe:first_frame' | 'qoe:rebuffer_start' | 'qoe:rebuffer_end' | 'qoe:summary' | 'player:auto_next' | 'player:playlist_index' | 'ads:break_start' | 'ads:break_end' | 'ads:ad_start' | 'ads:ad_end' | 'ssai:manifest_rewrite';
+interface TelemetrySample {
+    ts: number;
+    level: TelemetryLevel;
+    event: TelemetryEvent;
+    contentId?: string;
+    engineId?: string;
+    message?: string;
+    data?: Record<string, unknown>;
+}
+
+/**
+ * High-level playback profiles.
+ *
+ * Goal: provide good defaults with *minimal configuration*.
+ * Users can still override per-source hints via `source.abr`.
+ */
+interface EngineProfileHints {
+    /** Defaults applied only when the user did not specify `source.abr.*` */
+    abr?: {
+        maxHeight?: number;
+        maxBandwidth?: number;
+    };
+    /** Shaka-specific streaming knobs (best-effort, ignored by non-shaka engines). */
+    shakaStreaming?: {
+        lowLatencyMode?: boolean;
+        bufferingGoalSec?: number;
+        rebufferingGoalSec?: number;
+    };
+}
+declare function getEngineProfileHints(profile?: EngineProfileId): EngineProfileHints;
+/**
+ * Apply profile defaults to a `PlayerSource` without overriding user-provided hints.
+ *
+ * This function is intentionally conservative: it only fills missing fields.
+ */
+declare function applyEngineProfileToSource(source: PlayerSource, profile?: EngineProfileId): PlayerSource;
+
+declare function createNativeEngineFactory(): EngineFactory;
+
+declare function applyRemoteConfig(cfg: PlayerConfig, ports: Partial<PlayerPorts>): Promise<{
+    config: PlayerConfig;
+    applied: boolean;
+    payload?: RemoteConfigPayload;
+    source: 'cache' | 'network' | 'none';
+}>;
+
+export { type AdsConfig, type AdsMode, type AspectRatioMode, type CacheStore, type CapabilityReport, ConsoleLogPort, DefaultCacheStore, type DiagnosticsEngineInfo, type DiagnosticsSnapshot, type DrmConfig, type EngineEvent, type EngineFactory, type EngineProfileHints, type EngineProfileId, type EpisodeItem, type HttpPort, type LoadOptions, LocalMetadataProvider, LocalSubtitleProvider, type LogPort, type MediaTrack, MemoryStoragePort, type MetadataConfig, type MetadataHint, type MetadataMatch, type MetadataProvider, NativeEngine, type NextEpisodeHint, NoopTelemetryPort, type PlaybackCapabilities, type PlaybackEngine, type PlayerCommand, type PlayerConfig, type PlayerContext, type PlayerDiagnostics, type PlayerError, type PlayerErrorCode, type PlayerEvent, type PlayerEventBus, PlayerFacade, type PlayerPlugin, type PlayerPorts, type PlayerSnapshot, type PlayerSource, type PlayerState, type PlayerTime, type ProgressConfig, type ProgressMode, ProgressPlugin, type RemoteConfigConfig, type RemoteConfigPayload, type ResilienceConfig, ResiliencePlugin, type SeriesConfig, SimpleEventBus, type SkipSegment, type SourceType, type SsaiManifestRewriteConfig, type StoragePort, type SubtitleCandidate, type SubtitleHint, type SubtitleProvider, type SubtitleQuery, type SubtitlesConfig, type TelemetryEvent, type TelemetryLevel, type TelemetryPort, type TelemetrySample, type UiConfig, type Unsubscribe, type VideoMetadata, applyEngineProfileToSource, applyRemoteConfig, createCapabilityReport, createDefaultCapabilities, createDefaultPorts, createMediaDecodingReport, createNativeEngineFactory, createSsaiManifestRewritePlugin, detectPlaybackCapabilities, getEngineProfileHints, isCategorizedEventType, selectEngine };