boss-web-player-sdk 1.1.11 → 1.1.13

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export declare interface AnalyticsEvent {
     speed?: number;
     errorMessage?: string;
     errorCode?: number;
+    isRecoverable?: boolean;
     sessionId?: string;
     videoId?: string;
     deviceType?: string;
@@ -35,6 +36,7 @@ export declare interface AnalyticsEvent {
     audioTrack?: string;
     subtitleLanguage?: string;
     subtitleEnabled?: boolean;
+    isAutoSwitch?: boolean;
 }
 
 declare class AnalyticsModule {
@@ -100,7 +102,7 @@ declare interface AnalyticsSessionSnapshot {
     milestonesHit: string[];
 }
 
-export declare function BossVideoPlayer({ playerKey, src, subtitles, licenseKey, themeColor, firebaseConfig, proxyDomains, apiBaseUrl, adTrackingUrl, overlayAdUrl, title, watermark, autoplay, muted, autoFullscreen, enableControls, enableSkipAd, skipAdAfterSeconds, chaptersDisplayMode, volumeControlType, subtitleStyle, drmConfig, onAnalyticsEvent, onKeyMomentsLoaded, initialTime, onTimeUpdate, }: BossVideoPlayerProps): JSX.Element;
+export declare function BossVideoPlayer({ playerKey, src, subtitles, licenseKey, themeColor, firebaseConfig, proxyDomains, apiBaseUrl, adTrackingUrl, overlayAdUrl, title, watermark, autoplay, muted, autoFullscreen, enableControls, enableSkipAd, skipAdAfterSeconds, chaptersDisplayMode, volumeControlType, subtitleStyle, drmConfig, onAnalyticsEvent, delegate, onKeyMomentsLoaded, initialTime, onTimeUpdate, }: BossVideoPlayerProps): JSX.Element;
 
 export declare interface BossVideoPlayerProps {
     /** Player key from the GoBOSS dashboard — identifies your tenant. */
@@ -154,6 +156,13 @@ export declare interface BossVideoPlayerProps {
     drmConfig?: DRMConfig;
     /** Called for every analytics event — lets consumers add custom tracking. */
     onAnalyticsEvent?: (event: AnalyticsEvent) => void;
+    /**
+     * Typed per-event callbacks (playerDidStartPlaying, playerDidPause, …) that
+     * receive only the arguments relevant to each event. Prefer this over
+     * `onAnalyticsEvent` for analytics, logging, and business logic; implement
+     * only the methods you need.
+     */
+    delegate?: PlayerDelegate;
     /** Called when chapter/key-moment data is parsed from the stream. */
     onKeyMomentsLoaded?: (keyMoments: Chapter[]) => void;
     /** Seek to this position (in seconds) when the video is ready. Use for resume-playback. */
@@ -177,6 +186,11 @@ declare class CastingModule {
         deviceName: string;
     };
     getRemoteState(): RemoteCastState | null;
+    /**
+     * Derives the Cast MediaInfo content type from the stream URL so HLS/DASH manifests
+     * aren't sent to the receiver mislabeled as video/mp4, which causes load failures.
+     */
+    private getContentType;
     /**
      * Prompts the native Google Cast device picker overlay, then loads media on the remote device.
      * The caller is responsible for pausing local playback before/after this resolves.
@@ -362,6 +376,62 @@ declare class KeyMomentsModule {
     onChapterChange(callback: (chapter: KeyMoment | null, index: number) => void): void;
 }
 
+/**
+ * Typed per-event callbacks for tenant applications.
+ *
+ * Unlike `AnalyticsCallback` (which receives the full analytics event for every
+ * event type), each delegate method receives only the arguments relevant to that
+ * event — clean signatures for logging, custom UI, and business logic.
+ *
+ * All methods are optional; implement only the ones you need.
+ *
+ * Conventions:
+ * - Arguments named `*Time` / `*At` are playback positions in seconds.
+ * - `watchDuration` and `seekDuration` are wall-clock seconds.
+ * - `from*` arguments are `undefined` when there was no previous value
+ *   (e.g. the first quality selection after load).
+ */
+export declare interface PlayerDelegate {
+    /** Playback started for the first time (or restarted after finishing). */
+    playerDidStartPlaying?(startTime: number, autoplay: boolean): void;
+    /** Playback resumed after a pause. */
+    playerDidResumePlaying?(resumedAt: number): void;
+    /** Playback paused by the user (not fired for the implicit pause at end of stream). */
+    playerDidPause?(pausedAt: number): void;
+    /** Playback reached the end of the stream. */
+    playerDidFinishPlaying?(finishedAt: number, watchDuration: number): void;
+    /** The player was torn down (unmount / tab close) before playback finished. Fired at most once. */
+    playerDidDismiss?(dismissedAt: number, watchDuration: number): void;
+    /** A seek started (scrubber, ±10s skip). Fired once per seek gesture. */
+    playerDidStartSeeking?(fromTime: number): void;
+    /** The seek landed. `fromTime` is where the gesture began, `seekDuration` is wall-clock seconds it took. */
+    playerDidFinishSeeking?(fromTime: number, toTime: number, seekDuration: number): void;
+    /** Playback position update — fires on every native `timeupdate` (roughly 4×/second). */
+    playerDidUpdateCurrentTime?(currentTime: number, duration: number): void;
+    playerDidStartBuffering?(startedAt: number): void;
+    playerDidFinishBuffering?(endedAt: number): void;
+    /** Rendition changed. `isAutoSwitch` is true when ABR picked the level, false for a manual selection. */
+    playerDidChangeQuality?(fromQuality: string | undefined, toQuality: string, isAutoSwitch: boolean): void;
+    /** Subtitle track changed (languages, e.g. 'en' → 'fr'). */
+    playerDidChangeSubtitle?(fromSubtitle: string | undefined, toSubtitle: string): void;
+    /** Subtitles were turned off. `disabledSubtitle` is the language that was active. */
+    playerDidDisableSubtitle?(disabledSubtitle: string | undefined): void;
+    /** Audio track changed (track labels). */
+    playerDidChangeAudioTrack?(fromAudioTrack: string | undefined, toAudioTrack: string): void;
+    playerDidChangePlaybackSpeed?(fromSpeed: number, toSpeed: number): void;
+    /** `orientation` is the current `screen.orientation.type` (e.g. 'landscape-primary') when available. */
+    playerDidEnterFullscreen?(orientation?: string): void;
+    playerDidExitFullscreen?(orientation?: string): void;
+    /** A key moment was selected. `fromTime`/`toTime` are the chapter's start/end. */
+    playerDidSelectKeyMoment?(chapterId: string | undefined, chapterTitle: string, fromTime: number, toTime: number): void;
+    playerDidEnterPictureInPicture?(enteredAt?: number): void;
+    playerDidExitPictureInPicture?(exitedAt?: number): void;
+    /** A media/playback error. `isRecoverable` is true when the player will attempt recovery itself. */
+    playerDidEncounterPlaybackError?(errorCode: string, message: string, isRecoverable: boolean): void;
+    /** A network/CDN error. `statusCode` is the HTTP status when known, 0 otherwise. */
+    playerDidEncounterNetworkError?(statusCode: number, message: string, isRecoverable: boolean): void;
+}
+
 /**
  * In-session telemetry payload for POST /api/player/sdk/events.
  * `eventType`, `sessionId` and `currentTime` are always required; `videoId` and any
@@ -663,6 +733,22 @@ export declare class VideoPlayerSDK {
     private parseAdBreaksFromFragments;
     private parseAdBreaksFromPlaylist;
     private isTimeInAdBreak;
+    /**
+     * Syncs isAdBreak/playbackRate/ad-mode UI state against `time` and emits
+     * adbreakchange on transitions. Called from timeupdate, but also called
+     * eagerly as soon as ad breaks or metadata become known — timeupdate alone
+     * doesn't fire until playback actually starts, which left a preroll ad's
+     * first frame briefly showing content controls (rewind/forward, etc.)
+     * while autoplay was blocked or the source was still buffering.
+     */
+    private refreshAdBreakState;
+    /**
+     * Converts raw (stitched) video time to content-only time by subtracting the
+     * ad time elapsed before `time`. During an ad break the result is frozen at
+     * the content timestamp where the break started. Identity when no ad breaks
+     * are known. Mirrors the seekbar mapping in the UI layer.
+     */
+    private videoTimeToContentTime;
     getAdBreaks(): Array<{
         startTime: number;
         endTime: number;