@codenkay/video-nsgplayer-core 3.0.2 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 4.0.0
+
+### Major Changes
+
+- Fix minor issues
+
+## 3.0.4
+
+### Patch Changes
+
+- Preserve "use client" in React/UI builds, forward analytics, intermittent watermark, Angular Ivy packaging, and packaging metadata.
+
+## 3.0.3
+
+- Browser-direct AES keys: after signed-query CORS/network failure, retry once
+  with `getKeyAccessToken` Bearer before XHR (needed when AUTH_MODE=browser and
+  Appextech enables CORS + Authorization on `enc.key`).
+- Clearer KEY_LOAD_ERROR message distinguishing BFF vs browser-direct CORS.
+
 ## 3.0.2
 
 - Fix pack/build regression on AES `enc.key`: do **not** statically import

package/README.md

@@ -40,3 +40,15 @@ await player.play();
 ```
 
 See repository `docs/` for configuration, authentication, and security.
+
+## Samples
+
+Framework adapters wrap this engine. Clone a ready playground:
+
+| Lab | Repo |
+|-----|------|
+| React (Vite, no BFF) | [nsgplayer-sample-react](https://github.com/codenannu/nsgplayer-sample-react) |
+| Next.js + thin BFF | [nsgplayer-sample-nextjs](https://github.com/codenannu/nsgplayer-sample-nextjs) |
+| Angular (headless) | [nsgplayer-sample-angular](https://github.com/codenannu/nsgplayer-sample-angular) |
+
+Full matrix: [docs/samples.md](../../docs/samples.md).

package/dist/index.cjs

@@ -213,7 +213,7 @@ var AuthManager = class {
 
 // src/config/defaults.ts
 var PLAYBACK_RATES = [0.5, 0.75, 1, 1.25, 1.5, 2];
-var PACKAGE_VERSION = "3.0.2";
+var PACKAGE_VERSION = "3.0.3";
 var DEFAULT_PLAYER_BEHAVIOR = {
   autoplay: true,
   startMuted: true,
@@ -237,7 +237,8 @@ var DEFAULT_CONTROLS = {
   showSkip: true,
   showLive: true,
   seekCueDurationMs: 720,
-  keyboardShortcuts: true
+  keyboardShortcuts: true,
+  persistQualityPreference: false
 };
 var DEFAULT_THEME = {
   playIconPreset: "triangle",
@@ -282,7 +283,8 @@ var DEFAULT_PLAYER_CONFIG = {
     engine: "hls",
     hls: {
       enableWorker: true,
-      lowLatencyMode: true,
+      // VOD + AES-128: LL mode causes ABR thrash → bufferAppendError on MSE.
+      lowLatencyMode: false,
       backBufferLength: 90,
       fatalRecoveryLimit: 3
     }
@@ -859,7 +861,8 @@ function rememberBuiltin(HlsClass, loader) {
 function getStashedBuiltinLoader(loader) {
   return loader[BUILTIN_LOADER_REF];
 }
-function resolveBuiltinHlsLoader(HlsClass) {
+function resolveBuiltinHlsLoader(HlsModule) {
+  const HlsClass = HlsModule;
   const cached = builtinLoaderByHls.get(HlsClass);
   if (cached) return cached;
   const start = HlsClass.DefaultConfig.loader;
@@ -987,29 +990,52 @@ async function fetchEncryptionKeyBytes(url, accessToken, signal) {
     };
   }
 }
+var AES_128_KEY_BYTES = 16;
+function normalizeAes128Key(data) {
+  if (data.byteLength === AES_128_KEY_BYTES) {
+    return data.slice(0);
+  }
+  return null;
+}
 function reportKeySuccess(context, callbacks, result) {
+  const key = normalizeAes128Key(result.data);
+  if (!key) {
+    const stats2 = createLoaderStats();
+    callbacks.onError(
+      {
+        code: 422,
+        text: `enc.key must be ${AES_128_KEY_BYTES} bytes (got ${result.data.byteLength})`
+      },
+      context,
+      result.response,
+      stats2
+    );
+    return false;
+  }
   const stats = createLoaderStats();
   const end = performance.now();
   stats.loading.first = stats.loading.start;
   stats.loading.end = end;
-  stats.loaded = result.data.byteLength;
-  stats.total = result.data.byteLength;
+  stats.loaded = key.byteLength;
+  stats.total = key.byteLength;
   callbacks.onSuccess(
     {
       url: result.url,
-      data: result.data,
+      data: key,
       code: result.response.status
     },
     stats,
     context,
     result.response
   );
+  return true;
 }
-async function loadEncryptionKeyEnterprise(context, callbacks, plan, signal, state) {
+async function loadEncryptionKeyEnterprise(context, callbacks, plan, signal, state, lifecycle) {
   const stats = createLoaderStats();
+  const stillCurrent = () => lifecycle.isCurrent() && !signal.aborted;
   const canTryProxy = Boolean(plan.proxyUrl) && !state.circuitOpen && state.proxyFailures < plan.maxProxyFailures;
   if (canTryProxy && plan.proxyUrl) {
-    while (!state.circuitOpen && state.proxyFailures < plan.maxProxyFailures && !signal.aborted) {
+    while (!state.circuitOpen && state.proxyFailures < plan.maxProxyFailures && stillCurrent()) {
       state.proxyFailures += 1;
       try {
         const response = await fetch(plan.proxyUrl, {
@@ -1019,18 +1045,33 @@ async function loadEncryptionKeyEnterprise(context, callbacks, plan, signal, sta
           cache: "no-store",
           signal
         });
+        if (!lifecycle.isCurrent()) return "aborted";
         const contentType = response.headers.get("content-type");
         const data = await response.arrayBuffer();
+        if (!lifecycle.isCurrent()) return "aborted";
         const head = new TextDecoder().decode(data.slice(0, 64));
         if (response.ok && !isProxyUpstreamBlocked(response.status, contentType, head)) {
+          const key = normalizeAes128Key(data);
+          if (!key) {
+            callbacks.onError(
+              {
+                code: 422,
+                text: `enc.key proxy returned ${data.byteLength} bytes (need ${AES_128_KEY_BYTES})`
+              },
+              { ...context, url: plan.proxyUrl },
+              response,
+              stats
+            );
+            return "ok";
+          }
           const end = performance.now();
           stats.loading.end = end;
-          stats.loaded = data.byteLength;
-          stats.total = data.byteLength;
+          stats.loaded = key.byteLength;
+          stats.total = key.byteLength;
           callbacks.onSuccess(
             {
               url: response.url || plan.proxyUrl,
-              data,
+              data: key,
               code: response.status
             },
             stats,
@@ -1063,25 +1104,22 @@ async function loadEncryptionKeyEnterprise(context, callbacks, plan, signal, sta
         return "ok";
       } catch (error) {
         if (error instanceof DOMException && error.name === "AbortError") {
-          callbacks.onError(
-            { code: 0, text: "enc.key proxy aborted/timeout" },
-            context,
-            null,
-            stats
-          );
-          return "ok";
+          return "aborted";
         }
         state.circuitOpen = true;
         break;
       }
     }
+    if (!lifecycle.isCurrent()) return "aborted";
     state.circuitOpen = true;
   }
+  if (!lifecycle.isCurrent()) return "aborted";
   const queryResult = await fetchEncryptionKeyBytes(
     plan.signedKeyUrl,
     null,
     signal
   );
+  if (!lifecycle.isCurrent()) return "aborted";
   if (queryResult.ok) {
     reportKeySuccess(
       { ...context, url: plan.signedKeyUrl },
@@ -1090,13 +1128,19 @@ async function loadEncryptionKeyEnterprise(context, callbacks, plan, signal, sta
     );
     return "ok";
   }
-  const needsBearer = Boolean(plan.accessToken) && (queryResult.status === 401 || queryResult.status === 403);
+  if (queryResult.status === 0 && signal.aborted) {
+    return "aborted";
+  }
+  const needsBearer = Boolean(plan.accessToken) && (queryResult.status === 401 || queryResult.status === 403 || // Browser-direct: opaque CORS/network on unsigned GET — try Bearer once
+  // Appextech allows ACAO + Authorization (AUTH_MODE=browser, no BFF).
+  queryResult.cors || queryResult.status === 0);
   if (needsBearer && plan.accessToken) {
     const bearerResult = await fetchEncryptionKeyBytes(
       plan.signedKeyUrl,
       plan.accessToken,
       signal
     );
+    if (!lifecycle.isCurrent()) return "aborted";
     if (bearerResult.ok) {
       reportKeySuccess(
         { ...context, url: plan.signedKeyUrl },
@@ -1105,7 +1149,10 @@ async function loadEncryptionKeyEnterprise(context, callbacks, plan, signal, sta
       );
       return "ok";
     }
-    if (bearerResult.cors) {
+    if (bearerResult.status === 0 && signal.aborted) {
+      return "aborted";
+    }
+    if (bearerResult.cors || bearerResult.status === 0) {
       return "try_xhr";
     }
     callbacks.onError(
@@ -1133,7 +1180,8 @@ async function loadEncryptionKeyEnterprise(context, callbacks, plan, signal, sta
   );
   return "ok";
 }
-function createAuthParamsLoader(HlsClass, store, options = {}) {
+function createAuthParamsLoader(HlsModule, store, options = {}) {
+  const HlsClass = HlsModule;
   const BaseLoader = resolveBuiltinHlsLoader(HlsClass);
   rememberBuiltin(HlsClass, BaseLoader);
   const maxProxyFailures = typeof options.keyProxyMaxFailures === "number" && options.keyProxyMaxFailures >= 0 ? options.keyProxyMaxFailures : KEY_PROXY_MAX_FAILURES;
@@ -1142,17 +1190,34 @@ function createAuthParamsLoader(HlsClass, store, options = {}) {
     constructor(config) {
       this.context = null;
       this.keyAbort = null;
+      /** Bumps on each key load so superseded aborts never call onError. */
+      this.keyLoadGeneration = 0;
+      this.pendingKeyCallbacks = null;
       this.inner = new BaseLoader(config);
       this.stats = this.inner.stats;
     }
-    abort() {
+    finishKeyAbort() {
+      const cbs = this.pendingKeyCallbacks;
+      this.pendingKeyCallbacks = null;
       this.keyAbort?.abort();
       this.keyAbort = null;
+      if (cbs?.onAbort && this.context) {
+        const stats = createLoaderStats();
+        stats.aborted = true;
+        try {
+          cbs.onAbort(stats, this.context, null);
+        } catch {
+        }
+      }
+    }
+    abort() {
+      this.keyLoadGeneration += 1;
+      this.finishKeyAbort();
       this.inner.abort();
     }
     destroy() {
-      this.keyAbort?.abort();
-      this.keyAbort = null;
+      this.keyLoadGeneration += 1;
+      this.finishKeyAbort();
       this.context = null;
       this.inner.destroy();
     }
@@ -1184,10 +1249,19 @@ function createAuthParamsLoader(HlsClass, store, options = {}) {
         );
         const proxyUrl = proxyConfigured && !keyProxyState.circuitOpen ? rewriteHlsRequestUrl(originalUrl, store, options) : null;
         const accessToken = options.getKeyAccessToken?.() ?? null;
-        this.keyAbort?.abort();
+        if (this.keyAbort || this.pendingKeyCallbacks) {
+          this.keyLoadGeneration += 1;
+          this.finishKeyAbort();
+        }
+        const generation = ++this.keyLoadGeneration;
         this.keyAbort = new AbortController();
+        this.pendingKeyCallbacks = callbacks;
+        context.responseType = "arraybuffer";
         const timeoutMs = typeof config?.timeout === "number" && config.timeout > 0 ? config.timeout : 2e4;
         const timer = setTimeout(() => this.keyAbort?.abort(), timeoutMs);
+        const lifecycle = {
+          isCurrent: () => generation === this.keyLoadGeneration
+        };
         void loadEncryptionKeyEnterprise(
           context,
           callbacks,
@@ -1198,13 +1272,22 @@ function createAuthParamsLoader(HlsClass, store, options = {}) {
             maxProxyFailures
           },
           this.keyAbort.signal,
-          keyProxyState
+          keyProxyState,
+          lifecycle
         ).then((result) => {
+          if (!lifecycle.isCurrent()) return;
+          if (result === "aborted") {
+            this.finishKeyAbort();
+            return;
+          }
+          this.pendingKeyCallbacks = null;
           if (result === "try_xhr") {
             context.url = signedKeyUrl;
             this.inner.load(context, config, callbacks);
           }
         }).catch((error) => {
+          if (!lifecycle.isCurrent()) return;
+          this.pendingKeyCallbacks = null;
           callbacks.onError(
             {
               code: 0,
@@ -1235,6 +1318,10 @@ function createAuthParamsLoader(HlsClass, store, options = {}) {
 function isAuthHttpStatus(code) {
   return code === 401 || code === 403;
 }
+function isGeckoBrowser() {
+  if (typeof navigator === "undefined") return false;
+  return /firefox|gecko\//i.test(navigator.userAgent);
+}
 var HlsEngine = class {
   constructor(options) {
     this.options = options;
@@ -1250,6 +1337,8 @@ var HlsEngine = class {
     this.audioTracks = [];
     this.audioTrackSelection = 0;
     this.nativeTextTrackCleanup = null;
+    this.startPositionApplied = false;
+    this.autoplayApplied = false;
   }
   async start() {
     const { videoEl, playbackUrl, startMuted, volume } = this.options;
@@ -1296,10 +1385,27 @@ var HlsEngine = class {
       getKeyAccessToken,
       keyProxyMaxFailures: this.options.keyProxyMaxFailures
     });
+    const enableWorker = hlsConfig.enableWorker && !isGeckoBrowser();
+    if (hlsConfig.enableWorker && !enableWorker) {
+      this.options.logger.warn(
+        "Disabling hls.js worker on Firefox to avoid MSE bufferAppendError"
+      );
+    }
     this.hls = new Hls({
-      enableWorker: hlsConfig.enableWorker,
+      enableWorker,
+      // LL mode on short encrypted VOD drives aggressive ABR thrash → MSE errors.
       lowLatencyMode: hlsConfig.lowLatencyMode,
       backBufferLength: hlsConfig.backBufferLength,
+      // Stabilize ABR: avoid first-frag-only bandwidth test that immediately
+      // hops levels on single-segment Appextech VODs (HAR showed truncated
+      // 720p body vs Content-Length during level switches).
+      testBandwidth: false,
+      abrEwmaDefaultEstimate: 5e5,
+      abrBandWidthFactor: 0.8,
+      abrBandWidthUpFactor: 0.5,
+      maxStarvationDelay: 4,
+      capLevelToPlayerSize: true,
+      startLevel: -1,
       loader
     });
     this.hls.attachMedia(videoEl);
@@ -1317,7 +1423,11 @@ var HlsEngine = class {
       this.syncHlsSubtitleTracks();
       this.syncHlsAudioTracks();
       callbacks.onStateChange?.("ready");
-      void this.applyStartPositionAndAutoplay();
+      void this.applyAutoplayOnly();
+    });
+    this.hls.on(Hls.Events.FRAG_BUFFERED, () => {
+      if (this.destroyed || this.startPositionApplied) return;
+      void this.applyStartPositionOnly();
     });
     this.hls.on(Hls.Events.SUBTITLE_TRACKS_UPDATED, () => {
       if (this.destroyed) return;
@@ -1342,8 +1452,16 @@ var HlsEngine = class {
         callbacks.onAuthRecoveryNeeded?.("key_error");
         if (!data.fatal) return;
       } else if (!data.fatal) {
+        if (!status) {
+          return;
+        }
         callbacks.onFatalError?.(
-          status ? `Encryption key load failed (HTTP ${status}).` : "Encryption key load failed (network/CORS). Ensure signed query params are applied, or use keyProxyUrlBuilder / getKeyAccessToken when the key host requires API Bearer."
+          `Encryption key load failed (HTTP ${status}).`
+        );
+        return;
+      } else if (!status) {
+        callbacks.onFatalError?.(
+          "Encryption key load aborted or failed. Retry playback; if it persists, check the key proxy / CDN path."
         );
         return;
       }
@@ -1368,30 +1486,67 @@ var HlsEngine = class {
     }
     if (data.type === Hls.ErrorTypes.MEDIA_ERROR) {
       this.mediaRecoveryCount += 1;
-      if (this.mediaRecoveryCount <= hlsConfig.fatalRecoveryLimit) {
-        this.hls?.recoverMediaError();
+      if (this.mediaRecoveryCount > hlsConfig.fatalRecoveryLimit) {
+        callbacks.onFatalError?.(data.details || "Fatal HLS error");
         return;
       }
+      if (data.details === Hls.ErrorDetails.BUFFER_APPEND_ERROR || data.details === Hls.ErrorDetails.BUFFER_FULL_ERROR) {
+        this.lockPlaybackToSafeLevel();
+      }
+      if (this.mediaRecoveryCount === 2) {
+        this.hls?.swapAudioCodec();
+      }
+      this.hls?.recoverMediaError();
+      return;
     }
     callbacks.onFatalError?.(data.details || "Fatal HLS error");
   }
-  async applyStartPositionAndAutoplay() {
-    if (this.destroyed) return;
-    const { videoEl, autoplay, startPosition } = this.options;
-    if (typeof startPosition === "number" && startPosition > 0) {
-      const seek = () => {
-        if (this.destroyed) return;
-        try {
-          videoEl.currentTime = startPosition;
-        } catch {
-        }
-      };
-      if (videoEl.seekable.length > 0) {
-        seek();
-      } else {
-        videoEl.addEventListener("loadedmetadata", seek, { once: true });
+  /** Pin the next load to the lowest ladder rung after MSE append failures. */
+  lockPlaybackToSafeLevel() {
+    if (!this.hls || this.qualities.length === 0) return;
+    try {
+      this.hls.currentLevel = 0;
+      this.hls.loadLevel = 0;
+      this.hls.nextLoadLevel = 0;
+    } catch {
+    }
+  }
+  clampStartPosition(raw, videoEl) {
+    let t = Math.max(0, raw);
+    const duration = videoEl.duration;
+    if (Number.isFinite(duration) && duration > 0) {
+      t = Math.min(t, Math.max(0, duration - 0.35));
+    }
+    if (videoEl.seekable.length > 0) {
+      const end = videoEl.seekable.end(videoEl.seekable.length - 1);
+      if (Number.isFinite(end)) {
+        t = Math.min(t, end);
       }
     }
+    return t;
+  }
+  async applyStartPositionOnly() {
+    if (this.destroyed || this.startPositionApplied) return;
+    const { videoEl, startPosition } = this.options;
+    this.startPositionApplied = true;
+    if (typeof startPosition !== "number" || startPosition <= 0) return;
+    const seek = () => {
+      if (this.destroyed) return;
+      try {
+        videoEl.currentTime = this.clampStartPosition(startPosition, videoEl);
+      } catch {
+      }
+    };
+    if (videoEl.seekable.length > 0 || Number.isFinite(videoEl.duration)) {
+      seek();
+    } else {
+      videoEl.addEventListener("loadedmetadata", seek, { once: true });
+    }
+  }
+  async applyAutoplayOnly() {
+    if (this.destroyed || this.autoplayApplied) return;
+    this.autoplayApplied = true;
+    const { videoEl, autoplay } = this.options;
     if (!autoplay) return;
     try {
       await videoEl.play();
@@ -1406,6 +1561,10 @@ var HlsEngine = class {
       }
     }
   }
+  async applyStartPositionAndAutoplay() {
+    await this.applyStartPositionOnly();
+    await this.applyAutoplayOnly();
+  }
   bindMediaEvents() {
     const { videoEl, callbacks } = this.options;
     videoEl.addEventListener(
@@ -1649,11 +1808,20 @@ function createVideoPlayer(options) {
       }
       events.emit("progress", { bufferedEnd });
     };
+    const onVolumeChange = () => {
+      if (destroyed) return;
+      events.emit("volumechange", {
+        volume: el.volume,
+        muted: el.muted
+      });
+    };
     el.addEventListener("timeupdate", onTimeUpdate);
     el.addEventListener("progress", onProgress);
+    el.addEventListener("volumechange", onVolumeChange);
     mediaCleanup = () => {
       el.removeEventListener("timeupdate", onTimeUpdate);
       el.removeEventListener("progress", onProgress);
+      el.removeEventListener("volumechange", onVolumeChange);
     };
   };
   const authManager = new AuthManager(
@@ -1706,6 +1874,9 @@ function createVideoPlayer(options) {
         isLiveStream = Boolean(source.live);
       }
       const el = ensureVideoElement();
+      if (isLiveStream) {
+        el.playbackRate = 1;
+      }
       bindMediaProgressEvents(el);
       engine?.destroy();
       engine = new HlsEngine({
@@ -1794,6 +1965,12 @@ function createVideoPlayer(options) {
         }
       });
       await engine.start();
+      if (!destroyed && videoEl) {
+        events.emit("volumechange", {
+          volume: videoEl.volume,
+          muted: videoEl.muted
+        });
+      }
       if (!options.sourceUrl && options.playback) {
         refreshManager?.stop();
         refreshManager = new RefreshManager({
@@ -1913,7 +2090,8 @@ function createVideoPlayer(options) {
       return videoEl?.muted ?? false;
     },
     setPlaybackRate(rate) {
-      ensureVideoElement().playbackRate = rate;
+      const el = ensureVideoElement();
+      el.playbackRate = isLiveStream ? 1 : rate;
     },
     getPlaybackRate() {
       return videoEl?.playbackRate ?? 1;