ogplayer 1.1.0 → 1.2.0

package/README.md

@@ -1,9 +1,8 @@
 # OGPlayer — web SDK
 
-One video player API across **Android, iOS, web and React Native**. This package is the
-web implementation: the same model types, listener callbacks, error codes and
-UI behavior as the Android SDK (the reference platform), built on web
-standards.
+OGPlayer for the browser — built on web standards.
+
+Release notes: https://ogplayer.tv/docs/reference/changelog/
 
 > OGPlayer is a product of Inverse DOO.
 
@@ -18,9 +17,8 @@ standards.
   host-page CSS can't break the player (and vice versa).
 - **Types:** written in TypeScript — full type declarations ship with the
   package.
-- **License:** the same `OGP1.…` offline keys as Android/iOS, verified with
-  the browser's built-in WebCrypto — one license unlocks every
-  platform. On the web, `apps` patterns bind to the page **hostname**.
+- **License:** signed `OGP1.…` offline keys, verified with the browser's
+  built-in WebCrypto. `apps` patterns bind to the page **hostname**.
 
 ## Quick start
 
@@ -46,9 +44,8 @@ standards.
 <og-player style="width:100%;aspect-ratio:16/9"></og-player>
 ```
 
-Overlays (watermarks, logos) use the nine named slots, mirroring
-Android/iOS `OverlaySlot` — including the clearance choreography around the
-controls and rating icons:
+Overlays (watermarks, logos) use the nine named `OverlaySlot`s — including the
+clearance choreography around the controls and rating icons:
 
 ```html
 <og-player>
@@ -57,7 +54,7 @@ controls and rating icons:
 ```
 
 Custom action icons (max 8, inline in the top-end control row, hide with the
-controls — same contract as Android/iOS):
+controls):
 
 ```js
 el.config = {
@@ -90,24 +87,3 @@ el.config = {
 Evergreen Chrome / Edge / Firefox / Safari 16+ (desktop & mobile). Every API
 used (MSE, custom elements, shadow DOM, WebCrypto, Fullscreen) has been
 baseline for years; no polyfills.
-
-## Feature parity vs Android (reference)
-
-| Feature | Android | iOS | Web |
-|---|---|---|---|
-| Transport / state / listeners | ✅ | ✅ | ✅ same names |
-| Analytics events | ✅ | ✅ | ✅ same shapes |
-| Error taxonomy | ✅ | ✅ | ✅ same codes |
-| HLS + ABR qualities | ✅ | ✅ | ✅ (hls.js/native) |
-| DASH | ✅ | — | ⏳ later (dash.js/Shaka) |
-| Live & DVR | ✅ | ✅ | ✅ |
-| Embedded + sideloaded subtitles | ✅ | ✅ | ✅ (native cue rendering) |
-| Audio tracks | ✅ | ✅ | ✅ |
-| Offline license (shared keypair) | ✅ | ✅ | ✅ WebCrypto |
-| Controls chrome (tokens) | ✅ | ✅ | ✅ same tokens/icons |
-| Title / NICAM ratings / watermark slots | ✅ | ✅ | ✅ incl. reflow choreography |
-| Custom action icons (≤8) | ✅ | ✅ | ✅ |
-| Ads (IMA / FreeWheel) | ✅ | ✅ | ⏳ SPI defined, provider later |
-| DRM | Widevine/PlayReady | FairPlay | ⏳ EME later |
-| Casting | Chromecast module | AirPlay | ⏳ Remote Playback API later |
-| Trick-play thumbnails | ✅ | ✅ | ⏳ |

package/dist/core/errors.d.ts

@@ -1,4 +1,4 @@
-import { type ErrorCategory, type OGPlayerError } from "./types.js";
+import { type ErrorCategory, type OGPlayerError, type RecoveryReason } from "./types.js";
 export declare function makeError(code: number, category: ErrorCategory, message: string, retryable: boolean, httpStatusCode?: number, cause?: unknown): OGPlayerError;
 /** Map the native `<video>` element MediaError. */
 export declare function fromMediaError(err: MediaError | null): OGPlayerError;
@@ -12,3 +12,9 @@ export declare function fromHlsError(data: {
     };
     error?: Error;
 }): OGPlayerError;
+/** Classify a NON-fatal hls.js error (one hls.js is recovering from itself)
+ *  for `PlaybackRecovered.reason`. */
+export declare function recoveryReasonFor(data: {
+    type: string;
+    details: string;
+}): RecoveryReason;

package/dist/core/types.d.ts

@@ -168,6 +168,10 @@ export interface AnalyticsEventBase {
     sessionId?: string;
     assetUrl?: string;
 }
+/** Why a `PlaybackRecovered` happened. Web values are the hls.js self-healing
+ *  classes; the Android values (`DRM_RENEWAL_AFTERSHOCK`, `CODEC_RESTART`,
+ *  `LIVE_WINDOW_RESET`) are listed so shared mappers can switch over one type. */
+export type RecoveryReason = "NETWORK_RETRY" | "BUFFER_STALL" | "DRM_RETRY" | "MEDIA_RETRY" | "DRM_RENEWAL_AFTERSHOCK" | "CODEC_RESTART" | "LIVE_WINDOW_RESET";
 export type AnalyticsEvent = AnalyticsEventBase & ({
     type: "Play";
 } | {
@@ -243,6 +247,18 @@ export type AnalyticsEvent = AnalyticsEventBase & ({
     orientation: DeviceOrientation;
 } | {
     type: "DrmKeysLoaded";
+}
+/** The player healed a fault on its own — no `Error` was surfaced and
+ *  `onError` did not fire, but the viewer may have seen a short rebuffer.
+ *  Count these for QoE; they are recoveries, not failures. On web this is
+ *  hls.js's own retry/stall handling (`detail` carries the hls.js error
+ *  detail for diagnosis); Android reports its silent re-prepares here
+ *  under its own reasons. */
+ | {
+    type: "PlaybackRecovered";
+    reason: RecoveryReason;
+    positionMs: number;
+    detail?: string;
 } | {
     type: "Complete";
 } | {
@@ -271,11 +287,15 @@ export declare const ErrorCodes: {
     readonly NETWORK_CONNECTION_FAILED: 2000;
     readonly NETWORK_TIMEOUT: 2001;
     readonly NETWORK_HTTP_STATUS: 2002;
+    /** HTTP failures are BASE + status: 2404, 2503 … (4xx not retryable, 5xx retryable). */
+    readonly NETWORK_HTTP_STATUS_BASE: 2000;
     readonly SOURCE_MALFORMED: 3000;
     readonly SOURCE_UNSUPPORTED: 3001;
     readonly SOURCE_NOT_FOUND: 3002;
     readonly DRM_LICENSE_FAILED: 4000;
     readonly DRM_LICENSE_HTTP_STATUS: 4001;
+    /** License-server HTTP failures are BASE + status: 4403, 4500 … */
+    readonly DRM_LICENSE_HTTP_STATUS_BASE: 4000;
     readonly DRM_TOKEN_FETCH_FAILED: 4002;
     readonly DRM_PROVISIONING_FAILED: 4003;
     readonly DRM_SESSION_EXPIRED: 4004;