@codenkay/video-nsgplayer-core 0.1.5 → 2.0.0

package/dist/index.d.cts

@@ -1,10 +1,26 @@
-import Hls, { LoaderContext, LoaderConfiguration, LoaderCallbacks } from 'hls.js';
+import Hls, { LoaderStats, LoaderContext, LoaderConfiguration, LoaderCallbacks } from 'hls.js';
 
 /** Player lifecycle states. */
 type PlayerState = "idle" | "loading" | "ready" | "playing" | "paused" | "buffering" | "renewing" | "ended" | "error" | "destroyed";
 type HlsSupportMode = "hls.js" | "native" | "unsupported";
 type QualitySelection = "auto" | number;
 type PlaybackRate = 0.5 | 0.75 | 1 | 1.25 | 1.5 | 2;
+type PlayerTextTrack = {
+    index: number;
+    id: string;
+    label: string;
+    language?: string;
+    uri?: string;
+};
+type PlayerAudioTrack = {
+    index: number;
+    id: string;
+    label: string;
+    language?: string;
+    uri?: string;
+};
+/** Runtime caption selection: off or a concrete subtitle track index. */
+type TextTrackSelection = "off" | number;
 type HlsQualityLevel = {
     index: number;
     height: number;
@@ -222,6 +238,14 @@ type PlayerEventMap = {
         selection: QualitySelection;
         label?: string;
     };
+    texttrackchange: {
+        tracks: PlayerTextTrack[];
+        selection: TextTrackSelection;
+    };
+    audiotrackchange: {
+        tracks: PlayerAudioTrack[];
+        selection: number;
+    };
     volumechange: {
         volume: number;
         muted: boolean;
@@ -255,7 +279,7 @@ type PlayerEventMap = {
 };
 
 declare const PLAYBACK_RATES: readonly [0.5, 0.75, 1, 1.25, 1.5, 2];
-declare const PACKAGE_VERSION = "0.1.5";
+declare const PACKAGE_VERSION = "0.1.8";
 declare const DEFAULT_PLAYER_BEHAVIOR: Required<PlayerBehaviorConfig>;
 declare const DEFAULT_CONTROLS: Required<ControlsConfig>;
 declare const DEFAULT_THEME: Required<ThemeConfig>;
@@ -390,6 +414,10 @@ type HlsEngineCallbacks = {
     onAuthRecoveryNeeded?: (reason: string) => void;
     onQualitiesChange?: (levels: HlsQualityLevel[]) => void;
     onQualitySelectionChange?: (selection: QualitySelection) => void;
+    onTextTracksChange?: (tracks: PlayerTextTrack[]) => void;
+    onTextTrackSelectionChange?: (selection: TextTrackSelection) => void;
+    onAudioTracksChange?: (tracks: PlayerAudioTrack[]) => void;
+    onAudioTrackSelectionChange?: (selection: number) => void;
     onEnded?: () => void;
 };
 type HlsEngineOptions = {
@@ -415,9 +443,12 @@ type HlsEngineOptions = {
 /**
  * Dual-path HLS engine: hls.js when supported, otherwise native Safari HLS.
  *
- * Signed CDN playback requires auth query params on every HLS request.
- * Encrypted VOD also requires a same-origin `enc.key` proxy (Bearer + query)
- * via `streaming.keyProxyUrlBuilder` — browser CORS cannot fetch Video API keys.
+ * Signed CDN playback requires auth query params on every HLS request
+ * (playlists, segments, and AES `enc.key` on CDN hosts).
+ *
+ * Optional `streaming.keyProxyUrlBuilder` (same-origin BFF) or
+ * `streaming.getKeyAccessToken` (browser Bearer) for Video API–origin keys
+ * when query-signed CDN access is insufficient.
  */
 declare class HlsEngine {
     private readonly options;
@@ -428,6 +459,11 @@ declare class HlsEngine {
     private mediaRecoveryCount;
     private qualities;
     private qualitySelection;
+    private textTracks;
+    private textTrackSelection;
+    private audioTracks;
+    private audioTrackSelection;
+    private nativeTextTrackCleanup;
     constructor(options: HlsEngineOptions);
     start(): Promise<void>;
     private startWithHlsJs;
@@ -439,7 +475,16 @@ declare class HlsEngine {
     setQuality(selection: QualitySelection): void;
     getQuality(): QualitySelection;
     getQualities(): HlsQualityLevel[];
+    getTextTracks(): PlayerTextTrack[];
+    getTextTrackSelection(): TextTrackSelection;
+    setTextTrack(selection: TextTrackSelection): void;
+    getAudioTracks(): PlayerAudioTrack[];
+    getAudioTrackSelection(): number;
+    setAudioTrack(index: number): void;
     getSupportMode(): HlsSupportMode;
+    private syncHlsSubtitleTracks;
+    private syncHlsAudioTracks;
+    private bindNativeTextTracks;
     destroy(): void;
 }
 
@@ -465,9 +510,17 @@ type VideoPlayer = {
     getQuality: () => QualitySelection;
     setQuality: (selection: QualitySelection | string) => void;
     getAvailableQualities: () => ReturnType<HlsEngine["getQualities"]>;
+    getTextTracks: () => PlayerTextTrack[];
+    getSelectedTextTrack: () => TextTrackSelection;
+    setTextTrack: (selection: TextTrackSelection) => void;
+    getAudioTracks: () => PlayerAudioTrack[];
+    getSelectedAudioTrack: () => number;
+    setAudioTrack: (index: number) => void;
     enterFullscreen: () => Promise<void>;
     exitFullscreen: () => Promise<void>;
     isFullscreen: () => boolean;
+    /** Attach fullscreen target container (host UI chrome). Zoom stays UI-only. */
+    setFullscreenElement: (el: HTMLElement | null) => void;
     reload: () => Promise<void>;
     destroy: () => void;
     getDiagnostics: () => PlayerDiagnostics;
@@ -591,32 +644,52 @@ declare class RefreshManager {
     private renew;
 }
 
-type HlsLoader = new (config: object) => {
+type HlsLoaderInstance = {
+    stats: LoaderStats;
     load(context: LoaderContext, config: LoaderConfiguration, callbacks: LoaderCallbacks<LoaderContext>): void;
     destroy(): void;
+    abort?: () => void;
 };
+type HlsLoader = new (config: object) => HlsLoaderInstance;
 type AuthParamsLoaderOptions = {
     videoId?: string;
     keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
     getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
 };
+declare function isEncryptionKeyUrl(rawUrl: string, baseOrigin?: string): boolean;
+/**
+ * Always resolve a builtin hls.js loader (XhrLoader).
+ *
+ * Never trust `Hls.DefaultConfig.loader` alone — if it was reassigned to a
+ * custom wrapper, `extends` / nested `inner.load()` chains blow Firefox's
+ * stack (`InternalError: too much recursion`).
+ */
+declare function resolveBuiltinHlsLoader(HlsClass: typeof Hls): HlsLoader;
 /**
  * Rewrites an HLS request URL so signed auth query params are present.
- * Master playlists are signed on loadSource; child playlists / segments / keys
- * are relative and would otherwise be fetched unsigned → CDN 403.
  *
- * AES `enc.key` handling (pick one):
- * 1. `keyProxyUrlBuilder` — same-origin BFF (needs Cloudflare-allowlisted server IP)
- * 2. `getKeyAccessToken` — browser-direct CDN fetch with API Bearer header
+ * AES `enc.key` handling (enterprise priority order):
+ * 1. `keyProxyUrlBuilder` — same-origin BFF (production; server IP must pass CDN/WAF)
+ * 2. Otherwise keep CDN/API URL and apply signed `token`/`expires` (and related) query
+ *    params — same auth model as segments on Appextech CDN hosts
+ * 3. Optional `getKeyAccessToken` is applied at load-time (Bearer), not in this rewrite
  */
 declare function rewriteHlsRequestUrl(rawUrl: string, store: AuthParamsStore, options?: AuthParamsLoaderOptions, baseOrigin?: string): string;
 /**
- * hls.js loader that re-applies live AuthParamsStore credentials on every
- * manifest / level / fragment / key request.
+ * hls.js loader that:
+ * - Re-applies signed auth query params on every media request
+ * - Loads AES `enc.key` via BFF / optional Bearer fetch / signed-query XHR
+ *
+ * Uses composition (not `extends DefaultConfig.loader`) so repeated mounts,
+ * HMR, or a polluted DefaultConfig cannot nest `super.load()` into recursion.
  */
 declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoader;
 
 declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>, depth?: number): unknown;
+/**
+ * Redacts sensitive fields. Cycle-safe and depth-capped.
+ * Only walks plain objects/arrays — never DOM / host graphs.
+ */
 declare function redactObject(obj: Record<string, unknown>, seen?: WeakSet<object>, depth?: number): Record<string, unknown>;
 
-export { type AccessibilityConfig, type AnalyticsConfig, type AuthConfig, AuthManager, AuthParamsStore, type AuthToken, type AuthTokenProviderContext, type BufferedRange, type ControlsConfig, type CreateVideoPlayerOptions, DEFAULT_CONTROLS, DEFAULT_LIVE_EDGE_TOLERANCE_SECONDS, DEFAULT_PLAYER_BEHAVIOR, DEFAULT_PLAYER_CONFIG, DEFAULT_THEME, DEFAULT_WATERMARK, type DebugConfig, EventEmitter, type HlsQualityLevel, type HlsSupportMode, type LiveMediaSnapshot, type LoggingConfig, PACKAGE_VERSION, PLAYBACK_RATES, type PlayIconPreset, type PlaybackCredentialConfig, type PlaybackRate, type PlaybackSource, type PlaybackSourceContext, PlaybackSourceManager, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };
+export { type AccessibilityConfig, type AnalyticsConfig, type AuthConfig, AuthManager, AuthParamsStore, type AuthToken, type AuthTokenProviderContext, type BufferedRange, type ControlsConfig, type CreateVideoPlayerOptions, DEFAULT_CONTROLS, DEFAULT_LIVE_EDGE_TOLERANCE_SECONDS, DEFAULT_PLAYER_BEHAVIOR, DEFAULT_PLAYER_CONFIG, DEFAULT_THEME, DEFAULT_WATERMARK, type DebugConfig, EventEmitter, type HlsQualityLevel, type HlsSupportMode, type LiveMediaSnapshot, type LoggingConfig, PACKAGE_VERSION, PLAYBACK_RATES, type PlayIconPreset, type PlaybackCredentialConfig, type PlaybackRate, type PlaybackSource, type PlaybackSourceContext, PlaybackSourceManager, type PlayerAudioTrack, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerTextTrack, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type TextTrackSelection, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isEncryptionKeyUrl, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, resolveBuiltinHlsLoader, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };

package/dist/index.d.ts

@@ -1,10 +1,26 @@
-import Hls, { LoaderContext, LoaderConfiguration, LoaderCallbacks } from 'hls.js';
+import Hls, { LoaderStats, LoaderContext, LoaderConfiguration, LoaderCallbacks } from 'hls.js';
 
 /** Player lifecycle states. */
 type PlayerState = "idle" | "loading" | "ready" | "playing" | "paused" | "buffering" | "renewing" | "ended" | "error" | "destroyed";
 type HlsSupportMode = "hls.js" | "native" | "unsupported";
 type QualitySelection = "auto" | number;
 type PlaybackRate = 0.5 | 0.75 | 1 | 1.25 | 1.5 | 2;
+type PlayerTextTrack = {
+    index: number;
+    id: string;
+    label: string;
+    language?: string;
+    uri?: string;
+};
+type PlayerAudioTrack = {
+    index: number;
+    id: string;
+    label: string;
+    language?: string;
+    uri?: string;
+};
+/** Runtime caption selection: off or a concrete subtitle track index. */
+type TextTrackSelection = "off" | number;
 type HlsQualityLevel = {
     index: number;
     height: number;
@@ -222,6 +238,14 @@ type PlayerEventMap = {
         selection: QualitySelection;
         label?: string;
     };
+    texttrackchange: {
+        tracks: PlayerTextTrack[];
+        selection: TextTrackSelection;
+    };
+    audiotrackchange: {
+        tracks: PlayerAudioTrack[];
+        selection: number;
+    };
     volumechange: {
         volume: number;
         muted: boolean;
@@ -255,7 +279,7 @@ type PlayerEventMap = {
 };
 
 declare const PLAYBACK_RATES: readonly [0.5, 0.75, 1, 1.25, 1.5, 2];
-declare const PACKAGE_VERSION = "0.1.5";
+declare const PACKAGE_VERSION = "0.1.8";
 declare const DEFAULT_PLAYER_BEHAVIOR: Required<PlayerBehaviorConfig>;
 declare const DEFAULT_CONTROLS: Required<ControlsConfig>;
 declare const DEFAULT_THEME: Required<ThemeConfig>;
@@ -390,6 +414,10 @@ type HlsEngineCallbacks = {
     onAuthRecoveryNeeded?: (reason: string) => void;
     onQualitiesChange?: (levels: HlsQualityLevel[]) => void;
     onQualitySelectionChange?: (selection: QualitySelection) => void;
+    onTextTracksChange?: (tracks: PlayerTextTrack[]) => void;
+    onTextTrackSelectionChange?: (selection: TextTrackSelection) => void;
+    onAudioTracksChange?: (tracks: PlayerAudioTrack[]) => void;
+    onAudioTrackSelectionChange?: (selection: number) => void;
     onEnded?: () => void;
 };
 type HlsEngineOptions = {
@@ -415,9 +443,12 @@ type HlsEngineOptions = {
 /**
  * Dual-path HLS engine: hls.js when supported, otherwise native Safari HLS.
  *
- * Signed CDN playback requires auth query params on every HLS request.
- * Encrypted VOD also requires a same-origin `enc.key` proxy (Bearer + query)
- * via `streaming.keyProxyUrlBuilder` — browser CORS cannot fetch Video API keys.
+ * Signed CDN playback requires auth query params on every HLS request
+ * (playlists, segments, and AES `enc.key` on CDN hosts).
+ *
+ * Optional `streaming.keyProxyUrlBuilder` (same-origin BFF) or
+ * `streaming.getKeyAccessToken` (browser Bearer) for Video API–origin keys
+ * when query-signed CDN access is insufficient.
  */
 declare class HlsEngine {
     private readonly options;
@@ -428,6 +459,11 @@ declare class HlsEngine {
     private mediaRecoveryCount;
     private qualities;
     private qualitySelection;
+    private textTracks;
+    private textTrackSelection;
+    private audioTracks;
+    private audioTrackSelection;
+    private nativeTextTrackCleanup;
     constructor(options: HlsEngineOptions);
     start(): Promise<void>;
     private startWithHlsJs;
@@ -439,7 +475,16 @@ declare class HlsEngine {
     setQuality(selection: QualitySelection): void;
     getQuality(): QualitySelection;
     getQualities(): HlsQualityLevel[];
+    getTextTracks(): PlayerTextTrack[];
+    getTextTrackSelection(): TextTrackSelection;
+    setTextTrack(selection: TextTrackSelection): void;
+    getAudioTracks(): PlayerAudioTrack[];
+    getAudioTrackSelection(): number;
+    setAudioTrack(index: number): void;
     getSupportMode(): HlsSupportMode;
+    private syncHlsSubtitleTracks;
+    private syncHlsAudioTracks;
+    private bindNativeTextTracks;
     destroy(): void;
 }
 
@@ -465,9 +510,17 @@ type VideoPlayer = {
     getQuality: () => QualitySelection;
     setQuality: (selection: QualitySelection | string) => void;
     getAvailableQualities: () => ReturnType<HlsEngine["getQualities"]>;
+    getTextTracks: () => PlayerTextTrack[];
+    getSelectedTextTrack: () => TextTrackSelection;
+    setTextTrack: (selection: TextTrackSelection) => void;
+    getAudioTracks: () => PlayerAudioTrack[];
+    getSelectedAudioTrack: () => number;
+    setAudioTrack: (index: number) => void;
     enterFullscreen: () => Promise<void>;
     exitFullscreen: () => Promise<void>;
     isFullscreen: () => boolean;
+    /** Attach fullscreen target container (host UI chrome). Zoom stays UI-only. */
+    setFullscreenElement: (el: HTMLElement | null) => void;
     reload: () => Promise<void>;
     destroy: () => void;
     getDiagnostics: () => PlayerDiagnostics;
@@ -591,32 +644,52 @@ declare class RefreshManager {
     private renew;
 }
 
-type HlsLoader = new (config: object) => {
+type HlsLoaderInstance = {
+    stats: LoaderStats;
     load(context: LoaderContext, config: LoaderConfiguration, callbacks: LoaderCallbacks<LoaderContext>): void;
     destroy(): void;
+    abort?: () => void;
 };
+type HlsLoader = new (config: object) => HlsLoaderInstance;
 type AuthParamsLoaderOptions = {
     videoId?: string;
     keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
     getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
 };
+declare function isEncryptionKeyUrl(rawUrl: string, baseOrigin?: string): boolean;
+/**
+ * Always resolve a builtin hls.js loader (XhrLoader).
+ *
+ * Never trust `Hls.DefaultConfig.loader` alone — if it was reassigned to a
+ * custom wrapper, `extends` / nested `inner.load()` chains blow Firefox's
+ * stack (`InternalError: too much recursion`).
+ */
+declare function resolveBuiltinHlsLoader(HlsClass: typeof Hls): HlsLoader;
 /**
  * Rewrites an HLS request URL so signed auth query params are present.
- * Master playlists are signed on loadSource; child playlists / segments / keys
- * are relative and would otherwise be fetched unsigned → CDN 403.
  *
- * AES `enc.key` handling (pick one):
- * 1. `keyProxyUrlBuilder` — same-origin BFF (needs Cloudflare-allowlisted server IP)
- * 2. `getKeyAccessToken` — browser-direct CDN fetch with API Bearer header
+ * AES `enc.key` handling (enterprise priority order):
+ * 1. `keyProxyUrlBuilder` — same-origin BFF (production; server IP must pass CDN/WAF)
+ * 2. Otherwise keep CDN/API URL and apply signed `token`/`expires` (and related) query
+ *    params — same auth model as segments on Appextech CDN hosts
+ * 3. Optional `getKeyAccessToken` is applied at load-time (Bearer), not in this rewrite
  */
 declare function rewriteHlsRequestUrl(rawUrl: string, store: AuthParamsStore, options?: AuthParamsLoaderOptions, baseOrigin?: string): string;
 /**
- * hls.js loader that re-applies live AuthParamsStore credentials on every
- * manifest / level / fragment / key request.
+ * hls.js loader that:
+ * - Re-applies signed auth query params on every media request
+ * - Loads AES `enc.key` via BFF / optional Bearer fetch / signed-query XHR
+ *
+ * Uses composition (not `extends DefaultConfig.loader`) so repeated mounts,
+ * HMR, or a polluted DefaultConfig cannot nest `super.load()` into recursion.
  */
 declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoader;
 
 declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>, depth?: number): unknown;
+/**
+ * Redacts sensitive fields. Cycle-safe and depth-capped.
+ * Only walks plain objects/arrays — never DOM / host graphs.
+ */
 declare function redactObject(obj: Record<string, unknown>, seen?: WeakSet<object>, depth?: number): Record<string, unknown>;
 
-export { type AccessibilityConfig, type AnalyticsConfig, type AuthConfig, AuthManager, AuthParamsStore, type AuthToken, type AuthTokenProviderContext, type BufferedRange, type ControlsConfig, type CreateVideoPlayerOptions, DEFAULT_CONTROLS, DEFAULT_LIVE_EDGE_TOLERANCE_SECONDS, DEFAULT_PLAYER_BEHAVIOR, DEFAULT_PLAYER_CONFIG, DEFAULT_THEME, DEFAULT_WATERMARK, type DebugConfig, EventEmitter, type HlsQualityLevel, type HlsSupportMode, type LiveMediaSnapshot, type LoggingConfig, PACKAGE_VERSION, PLAYBACK_RATES, type PlayIconPreset, type PlaybackCredentialConfig, type PlaybackRate, type PlaybackSource, type PlaybackSourceContext, PlaybackSourceManager, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };
+export { type AccessibilityConfig, type AnalyticsConfig, type AuthConfig, AuthManager, AuthParamsStore, type AuthToken, type AuthTokenProviderContext, type BufferedRange, type ControlsConfig, type CreateVideoPlayerOptions, DEFAULT_CONTROLS, DEFAULT_LIVE_EDGE_TOLERANCE_SECONDS, DEFAULT_PLAYER_BEHAVIOR, DEFAULT_PLAYER_CONFIG, DEFAULT_THEME, DEFAULT_WATERMARK, type DebugConfig, EventEmitter, type HlsQualityLevel, type HlsSupportMode, type LiveMediaSnapshot, type LoggingConfig, PACKAGE_VERSION, PLAYBACK_RATES, type PlayIconPreset, type PlaybackCredentialConfig, type PlaybackRate, type PlaybackSource, type PlaybackSourceContext, PlaybackSourceManager, type PlayerAudioTrack, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerTextTrack, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type TextTrackSelection, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isEncryptionKeyUrl, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, resolveBuiltinHlsLoader, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };