@dolby-optiview/ads-sdk-adapter-hlsjs 1.0.0-beta.1

package/dist/HlsJsAdapter.d.ts

@@ -0,0 +1,251 @@
+import Hls from 'hls.js';
+import type { PlayerAdapter, PlayerAdapterEvent, PlayerAdapterEventHandler, VideoQuality } from '@dolby-optiview/ads-sdk-core';
+/**
+ * HLS.js adapter implementing the PlayerAdapter interface.
+ *
+ * @example
+ * ```typescript
+ * import Hls from 'hls.js';
+ * import { HlsJsAdapter } from '@dolby-optiview/ads-sdk-adapter-hlsjs';
+ *
+ * // Content player (pass existing video element)
+ * const video = document.getElementById('video') as HTMLVideoElement;
+ * const hls = new Hls();
+ * hls.loadSource('https://example.com/stream.m3u8');
+ * hls.attachMedia(video);
+ * const adapter = new HlsJsAdapter(hls, video);
+ *
+ * // Ad adapter factory (SDK creates a container div and passes it)
+ * createAdAdapter: (container) => {
+ *   const adVideo = document.createElement('video');
+ *   container.appendChild(adVideo);
+ *   const adHls = new Hls();
+ *   adHls.attachMedia(adVideo);
+ *   return new HlsJsAdapter(adHls, adVideo);
+ * }
+ * ```
+ */
+export declare class HlsJsAdapter implements PlayerAdapter {
+    private hls;
+    private video;
+    private eventListeners;
+    private boundHandlers;
+    private _programDateTime;
+    private deferredSeekTime;
+    /**
+     * The level selection in force before {@link pinLowestQuality}, or `null` when nothing is
+     * pinned. `-1` is hls.js's own value for automatic, so it is a meaningful snapshot rather
+     * than a sentinel — an application that had pinned a level itself gets that level back, not
+     * ABR.
+     */
+    private levelBeforePin;
+    /**
+     * Cues already emitted as `parsed`, keyed by their pts, awaiting presentation.
+     *
+     * hls.js hands us a cue at segment PARSE — 20-30s before the playhead reaches it —
+     * so the cue and the instant it refers to are two separate events. The `presented`
+     * twin is timed off the metadata TextTrack (see attachId3CueEnterListener) but its
+     * CONTENT comes from here: the track's own cue payload is hls.js's DataCue shape,
+     * and re-deriving the Anvato fields from it would be a second, divergent parse of
+     * the same bytes. Keyed by pts because hls.js sets the track cue's `startTime` from
+     * `sample.pts` — the identical value this handler reads (id3-track-controller:
+     * `const startTime = samples[i].pts`), so the two line up exactly rather than
+     * approximately.
+     *
+     * An array per pts: one ID3 sample can carry several GEOB frames, and they all
+     * share a timestamp.
+     */
+    private parsedCues;
+    /** pts already emitted as `presented`, so a re-entered cue fires once. */
+    private presentedPts;
+    /** The metadata track listener, kept for teardown. */
+    private id3TrackListener;
+    constructor(hls: Hls, videoElement: HTMLVideoElement);
+    /**
+     * Current playback time in seconds.
+     */
+    get currentTime(): number;
+    /**
+     * Total duration of the content in seconds.
+     */
+    get duration(): number;
+    /**
+     * Live per the PLAYLIST, not per the media duration.
+     *
+     * `video.duration` cannot answer this on hls.js: the engine sets it to Infinity for live
+     * only when `liveDurationInfinity` is configured, and that defaults to false — so a live
+     * stream normally reports a finite duration equal to the playlist edge. `latestLevelDetails`
+     * carries the real answer, taken straight from the absence of `#EXT-X-ENDLIST`.
+     *
+     * Cast and optional-chained because `latestLevelDetails` is newer than the hls.js this
+     * adapter must keep compiling against; an older build returns undefined and the core falls
+     * back to its duration proxy.
+     */
+    get isLive(): boolean | null;
+    /**
+     * Whether the player is currently paused.
+     */
+    get paused(): boolean;
+    /**
+     * Whether the player is muted.
+     */
+    get muted(): boolean;
+    set muted(value: boolean);
+    /**
+     * Volume level in the range [0, 1].
+     */
+    get volume(): number;
+    set volume(value: number);
+    /**
+     * Playback rate, `1` being normal speed.
+     *
+     * Proxies the element rather than remembering what was written. hls.js drives this property
+     * itself when `maxLiveSyncPlaybackRate` is configured, nudging the rate to hold live latency,
+     * and the SDK needs to see that so it can stop competing rather than fight it.
+     */
+    get playbackRate(): number;
+    set playbackRate(value: number);
+    /**
+     * The underlying HTMLVideoElement. Exposed so the SDK can pass it to GAM.
+     */
+    get videoElement(): HTMLVideoElement;
+    /**
+     * Whether the content and ad pipelines can buffer in parallel. True whenever
+     * HLS.js (MSE) is operational. On Web, `false` prevents continued content
+     * playout during a break because the two pipelines cannot remain buffered
+     * concurrently.
+     */
+    get supportsParallelBuffering(): boolean;
+    /**
+     * Program Date Time from the HLS manifest (EXT-X-PROGRAM-DATE-TIME).
+     */
+    get programDateTime(): Date | null;
+    /**
+     * Pause playback.
+     */
+    pause(): void;
+    /**
+     * Resume playback.
+     */
+    play(): Promise<void>;
+    /**
+     * Seek to a specific time in seconds.
+     */
+    seek(time: number): void;
+    /**
+     * Load a media source without playing.
+     * Used for preloading ad content.
+     */
+    /**
+     * The manifest hls.js currently has, read off the engine (`hls.url`) so it is correct even
+     * when the application called `loadSource()` itself. The element's own `src` is a `blob:`
+     * MediaSource and cannot be reloaded.
+     */
+    get sourceUrl(): string | null;
+    load(url: string): Promise<void>;
+    /**
+     * Detached prefetch for the single-decoder preload strategy.
+     *
+     * Spins up a throwaway HLS.js instance with `startFragPrefetch` that parses
+     * the manifest and fetches the first fragment WITHOUT attaching media — so no
+     * second MediaSource / decoder is engaged. The raw responses land in the
+     * browser HTTP cache; the instance is destroyed once the first fragment is
+     * loaded (or on error/timeout). Best-effort: never rejects.
+     */
+    preload(url: string): Promise<void>;
+    /**
+     * The closest-to-live position hls.js will actually hold — `null` on VOD.
+     *
+     * hls.js is the one engine that pre-computes this, so there is no offset arithmetic
+     * here: its own `hls.liveSyncPosition` is already `liveEdge - targetLatency`, clamped
+     * into the seekable window by the latency controller itself.
+     *
+     * The explicit liveness gate is NOT redundant, despite what hls.js's own docstring
+     * suggests ("@returns null prior to loading live Playlist"). On VOD the getter returns
+     * a NUMBER, not null: `targetLatency` falls back to `liveSyncDurationCount * targetduration`
+     * (3 x segment duration by default) whenever `holdBack` is absent, which is exactly the
+     * VOD case, and `estimateLiveEdge()` needs only `levelDetails` — which VOD has. The
+     * result is a plausible-looking position roughly 3 segments from the end of the asset.
+     * Handing that to the resume clamp would drag every VOD resume backwards, breaking the
+     * one guarantee this feature is supposed to keep: VOD is untouched.
+     *
+     * `latestLevelDetails.live` is the authoritative flag and is public API.
+     */
+    get maxLiveSeekPosition(): number | null;
+    /**
+     * Set the requested video quality, or restore the selection in force before the first set.
+     * Returns whether an override was applied or an outstanding override was restored.
+     *
+     * The lowest rendition is selected through `nextLevel`, which hls.js documents as taking
+     * effect without interrupting the fragment being decoded. `currentLevel` would flush the
+     * whole buffer and stall the content timeline. The argmin is computed because hls.js does
+     * not sort its level array by bitrate first.
+     */
+    setVideoQuality(quality: VideoQuality | null): boolean;
+    /**
+     * Subscribe to player events.
+     */
+    on(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler): void;
+    /**
+     * Unsubscribe from player events.
+     */
+    off(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler): void;
+    /**
+     * Clean up resources.
+     */
+    destroy(): void;
+    /**
+     * Set up HLS.js event listeners for program date time.
+     */
+    private setupHlsListeners;
+    /**
+     * Re-emit a held cue as `presented` when the playhead reaches it.
+     *
+     * The timing comes from the metadata TextTrack hls.js already maintains
+     * (`addTextTrack('metadata', 'id3')`, enabled by the default `enableID3MetadataCues`),
+     * via the standard `cuechange` event — the HTML "time marches on" algorithm, which is
+     * the same machinery THEOplayer's per-cue `enter` runs on. One listener on the track
+     * rather than one per cue: a metadata track accumulates a cue every few seconds for the
+     * life of a live stream, and per-cue listeners on that would be an unbounded leak.
+     *
+     * Note the precision of this path is the browser's, not ours. ADS-285 measures it; if
+     * it turns out to be the same ~250ms class as the scheduler's poll, this buys nothing
+     * on web and the native adapters carry the feature alone. It cannot make things worse:
+     * a cue enters when the playhead is genuinely at it, so this can only ever fire a break
+     * ON TIME or not at all, never early.
+     */
+    private attachId3CueEnterListener;
+    /**
+     * Drop held cues the playhead has passed.
+     *
+     * Without this a live stream accumulates every ID3 cue it has ever seen — hours of
+     * them. The window is generous because a cue may be parsed well before it presents,
+     * and dropping one early costs a `presented` emission; it is bounded by wall time,
+     * not by count, so it stays correct if the parse lead grows.
+     */
+    private pruneParsedCues;
+    /**
+     * Set up video element event listeners.
+     */
+    private setupVideoListeners;
+    /**
+     * Update program date time based on current playback position.
+     */
+    private updateProgramDateTime;
+    /**
+     * Set the reported PDT from a reference fragment, anchored to the playhead:
+     * `pdt = refFragPdt + (currentTime - refFragStart)`.
+     *
+     * All PDT update paths (timeupdate interpolation, FRAG_CHANGED,
+     * LEVEL_LOADED) MUST share this single affine mapping. On a live stream the
+     * playlist window slides (`firstFrag.start` grows), so any path that drops
+     * the `- refFragStart` term drifts ahead of the true PDT and then snaps
+     * back on the next fragment/playlist update — an oscillation that re-fired
+     * completed wallclock breaks and broke the countdown badge (PLAYG-280).
+     */
+    private anchorProgramDateTime;
+    /**
+     * Emit an event to all registered handlers.
+     */
+    private emit;
+}

package/dist/HlsJsAdapter.js

@@ -0,0 +1 @@
+import e from"hls.js";import{decodeUtf8 as t,parseId3GeobFrames as s}from"@dolby-optiview/ads-sdk-core/id3";export class HlsJsAdapter{constructor(e,t){this.eventListeners=new Map,this.boundHandlers=new Map,this._programDateTime=null,this.deferredSeekTime=null,this.levelBeforePin=null,this.parsedCues=new Map,this.presentedPts=new Set,this.id3TrackListener=null,this.hls=e,this.video=t,this.setupHlsListeners(),this.setupVideoListeners()}get currentTime(){return this.video.currentTime}get duration(){return this.video.duration}get isLive(){const e=this.hls?.latestLevelDetails;return"boolean"==typeof e?.live?e.live:null}get paused(){return this.video.paused}get muted(){return this.video.muted}set muted(e){this.video.muted=e}get volume(){return this.video.volume}set volume(e){this.video.volume=e}get playbackRate(){return this.video.playbackRate}set playbackRate(e){this.video.playbackRate=e}get videoElement(){return this.video}get supportsParallelBuffering(){return e.isSupported()}get programDateTime(){return this._programDateTime}pause(){this.video.pause()}async play(){await this.video.play()}seek(e){this.video.seeking?this.deferredSeekTime=e:this.video.currentTime=e}get sourceUrl(){return this.hls.url??null}async load(t){return new Promise((s,i)=>{const r=()=>{this.hls.off(e.Events.MANIFEST_PARSED,r),this.hls.off(e.Events.ERROR,n),s()},n=(t,s)=>{s.fatal&&(this.hls.off(e.Events.MANIFEST_PARSED,r),this.hls.off(e.Events.ERROR,n),i(new Error(`HLS load error: ${s.details}`)))};this.hls.on(e.Events.MANIFEST_PARSED,r),this.hls.on(e.Events.ERROR,n),this.hls.loadSource(t),this.hls.attachMedia(this.video)})}async preload(t){if(e.isSupported())return new Promise(s=>{const i=new e({startFragPrefetch:!0,autoStartLoad:!0});let r=!1;const n=()=>{if(!r){r=!0,clearTimeout(d),i.off(e.Events.FRAG_LOADED,a),i.off(e.Events.ERROR,o);try{i.destroy()}catch{}s()}},a=()=>n(),o=(e,t)=>{t.fatal&&n()},d=setTimeout(n,8e3);i.on(e.Events.FRAG_LOADED,a),i.on(e.Events.ERROR,o),i.loadSource(t)})}get maxLiveSeekPosition(){const e=this.hls.latestLevelDetails;if(!e?.live)return null;const t=this.hls.liveSyncPosition;return"number"==typeof t&&Number.isFinite(t)?t:null}setVideoQuality(e){if(null===e){if(null===this.levelBeforePin)return!1;const e=this.levelBeforePin;try{return this.hls.nextLevel=e,this.hls.nextLevel!==e?!1:(this.levelBeforePin=null,!0)}catch{return!1}}const t=this.hls.levels;if(!t||t.length<2)return!1;let s=0;for(let e=1;e<t.length;e++)t[e].bitrate<t[s].bitrate&&(s=e);const i=t[s].bitrate;if("number"!=typeof i||!Number.isFinite(i)||i<=0)return!1;const r=null===this.levelBeforePin;let n;r&&(this.levelBeforePin=this.hls.manualLevel);try{this.hls.nextLevel=s,n=this.hls.nextLevel===s}catch{n=!1}return!!n||(r&&(this.levelBeforePin=null),!1)}on(e,t){this.eventListeners.has(e)||this.eventListeners.set(e,new Set),this.eventListeners.get(e).add(t)}off(e,t){const s=this.eventListeners.get(e);s&&s.delete(t)}destroy(){for(const[e,t]of this.boundHandlers)this.video.removeEventListener(e,t);this.boundHandlers.clear(),this.eventListeners.clear(),this.deferredSeekTime=null,this.id3TrackListener&&(this.id3TrackListener.track.removeEventListener("cuechange",this.id3TrackListener.handler),this.id3TrackListener=null),this.parsedCues.clear(),this.presentedPts.clear()}setupHlsListeners(){this.hls.on(e.Events.FRAG_CHANGED,(e,t)=>{t.frag.programDateTime&&this.anchorProgramDateTime(t.frag.programDateTime,t.frag.start)}),this.hls.on(e.Events.LEVEL_LOADED,(e,t)=>{if(t.details.hasProgramDateTime&&t.details.fragments.length>0){const e=t.details.fragments[0];e.programDateTime&&this.anchorProgramDateTime(e.programDateTime,e.start)}}),this.hls.on(e.Events.FRAG_PARSING_METADATA,(e,i)=>{for(const e of i.samples??[]){const i=s(e.data);if(0===i.length){const t={type:"id3",startTime:e.pts,raw:e.data,phase:"parsed"};this.emit("timedmetadata",t);continue}const r=[];for(const s of i){const i={type:"id3",startTime:e.pts,description:s.description,mimeType:s.mimeType,messageData:t(s.data),raw:e.data,phase:"parsed"};r.push(i),this.emit("timedmetadata",i)}this.parsedCues.set(e.pts,r),this.pruneParsedCues()}this.attachId3CueEnterListener()})}attachId3CueEnterListener(){if(this.id3TrackListener)return;const e=this.video.textTracks;if(!e)return;let t;for(let s=0;s<e.length;s++){const i=e[s];if("metadata"===i.kind&&"id3"===i.label){t=i;break}}if(!t||"function"!=typeof t.addEventListener)return;"disabled"===t.mode&&(t.mode="hidden");const s=()=>{const e=t?.activeCues;if(e)for(let t=0;t<e.length;t++){const s=e[t].startTime;if(this.presentedPts.has(s))continue;const i=this.parsedCues.get(s);if(i){this.presentedPts.add(s);for(const e of i)this.emit("timedmetadata",{...e,phase:"presented"})}}};t.addEventListener("cuechange",s),this.id3TrackListener={track:t,handler:s}}pruneParsedCues(){const e=this.video.currentTime-120;for(const t of this.parsedCues.keys())t<e&&(this.parsedCues.delete(t),this.presentedPts.delete(t))}setupVideoListeners(){const e=()=>{this.updateProgramDateTime(),this.emit("timeupdate")},t=()=>{this.emit("ended")},s=()=>{this.emit("error",this.video.error)},i=()=>{if(this.emit("seeked"),null!==this.deferredSeekTime){const e=this.deferredSeekTime;this.deferredSeekTime=null,this.seek(e)}},r=()=>{this.emit("volumechange")},n=()=>{this.emit("waiting")},a=()=>{this.emit("playing")},o=()=>{this.emit("pause")};this.video.addEventListener("timeupdate",e),this.video.addEventListener("ended",t),this.video.addEventListener("error",s),this.video.addEventListener("seeked",i),this.video.addEventListener("volumechange",r),this.video.addEventListener("waiting",n),this.video.addEventListener("playing",a),this.video.addEventListener("pause",o),this.boundHandlers.set("timeupdate",e),this.boundHandlers.set("ended",t),this.boundHandlers.set("error",s),this.boundHandlers.set("seeked",i),this.boundHandlers.set("volumechange",r),this.boundHandlers.set("waiting",n),this.boundHandlers.set("playing",a),this.boundHandlers.set("pause",o)}updateProgramDateTime(){const e=this.hls.levels,t=this.hls.currentLevel;if(t>=0&&e[t]?.details){const s=e[t].details;if(s?.hasProgramDateTime&&s.fragments.length>0){const e=s.fragments[0];e.programDateTime&&this.anchorProgramDateTime(e.programDateTime,e.start)}}}anchorProgramDateTime(e,t){this._programDateTime=new Date(e+1e3*(this.video.currentTime-t))}emit(e,t){const s=this.eventListeners.get(e);if(s)for(const e of s)try{e(t)}catch(e){console.error("[HlsJsAdapter] Event handler error:",e)}}}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { HlsJsAdapter } from './HlsJsAdapter';
+export { parseId3GeobFrames, parseId3GeobBody, decodeUtf8 } from '@dolby-optiview/ads-sdk-core/id3';
+export type { Id3GeobFrame } from '@dolby-optiview/ads-sdk-core/id3';

package/dist/index.js

@@ -0,0 +1 @@
+export{HlsJsAdapter}from"./HlsJsAdapter";export{parseId3GeobFrames,parseId3GeobBody,decodeUtf8}from"@dolby-optiview/ads-sdk-core/id3";

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@dolby-optiview/ads-sdk-adapter-hlsjs",
+  "version": "1.0.0-beta.1",
+  "description": "HLS.js adapter for OptiView Ads SDK",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "dolby",
+    "ads",
+    "hlsjs",
+    "hls.js",
+    "video",
+    "adapter"
+  ],
+  "author": "Dolby",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "homepage": "https://ads-sdk.xnappet.live",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@dolby-optiview/ads-sdk-core": "1.0.0-beta.1"
+  },
+  "peerDependencies": {
+    "hls.js": "^1.0.0"
+  }
+}