@dolby-optiview/ads-sdk-adapter-hlsjs 1.0.0-beta.6 → 1.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @dolby-optiview/ads-sdk-adapter-hlsjs
+
+HLS.js `PlayerAdapter` for the OptiView Ads SDK. It connects an `Hls`
+instance and its `<video>` element to the SDK core, either as the content
+player or as the ad player.
+
+`@dolby-optiview/ads-sdk` already depends on this package and uses it for its
+default ad player; install it directly only when you use
+`@dolby-optiview/ads-sdk-core` on its own.
+
+## Installation
+
+```bash
+npm install @dolby-optiview/ads-sdk-core @dolby-optiview/ads-sdk-adapter-hlsjs hls.js
+```
+
+`hls.js` 1.x is a peer dependency.
+
+## Usage
+
+```typescript
+import Hls from 'hls.js';
+import { OptiViewAds } from '@dolby-optiview/ads-sdk-core';
+import { HlsJsAdapter } from '@dolby-optiview/ads-sdk-adapter-hlsjs';
+
+const video = document.getElementById('video') as HTMLVideoElement;
+const hls = new Hls();
+hls.attachMedia(video);
+
+const sdk = new OptiViewAds({
+  player: new HlsJsAdapter(hls, video),
+  container: document.getElementById('container')!,
+  createAdAdapter: (adContainer) => {
+    const adVideo = document.createElement('video');
+    adContainer.appendChild(adVideo);
+    const adHls = new Hls();
+    adHls.attachMedia(adVideo);
+    return new HlsJsAdapter(adHls, adVideo);
+  },
+});
+
+await sdk.startSession({
+  manifestUrl: 'https://manifest.example.com/v1/your-org/channels/your-channel',
+});
+hls.loadSource('https://example.com/content.m3u8');
+video.play();
+```
+
+The adapter forwards HLS.js program date time and ID3 metadata to the core, so
+breaks are scheduled against the stream timeline without extra configuration.
+
+## Documentation
+
+- [OptiView Ads SDK documentation](https://optiview.dolby.com/docs/ads/player-integration/optiview-ads-sdk/)
+- Entry package: `@dolby-optiview/ads-sdk`
+
+## License
+
+See <https://optiview.dolby.com/policies/terms-of-service/>.

package/dist/HlsJsAdapter.d.ts

@@ -1,8 +1,10 @@
 import Hls from 'hls.js';
 import type { PlayerAdapter, PlayerAdapterEvent, PlayerAdapterEventHandler, VideoQuality } from '@dolby-optiview/ads-sdk-core';
 /**
- * HLS.js adapter implementing the PlayerAdapter interface.
+ * The {@link PlayerAdapter} for HLS.js, from the `@dolby-optiview/ads-sdk-adapter-hlsjs` package
+ * (peer dependency: `hls.js` 1.x).
  *
+ * @category Player Integration
  * @example
  * ```typescript
  * import Hls from 'hls.js';
@@ -32,6 +34,8 @@ export declare class HlsJsAdapter implements PlayerAdapter {
     private boundHandlers;
     private _programDateTime;
     private deferredSeekTime;
+    /** `ended` already emitted for the current playback (element event and hls.js MEDIA_ENDED can both arrive). */
+    private endedEmitted;
     /**
      * 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
@@ -60,6 +64,10 @@ export declare class HlsJsAdapter implements PlayerAdapter {
     private presentedPts;
     /** The metadata track listener, kept for teardown. */
     private id3TrackListener;
+    /**
+     * @param hls The `Hls` instance that plays the content.
+     * @param videoElement The `<video>` element `hls` is attached to.
+     */
     constructor(hls: Hls, videoElement: HTMLVideoElement);
     /**
      * Current playback time in seconds.
@@ -86,6 +94,8 @@ export declare class HlsJsAdapter implements PlayerAdapter {
      * Whether the player is currently paused.
      */
     get paused(): boolean;
+    /** Content is ready and its initial engine seek has settled. */
+    get playbackReady(): boolean;
     /**
      * Whether the player is muted.
      */
@@ -143,6 +153,20 @@ export declare class HlsJsAdapter implements PlayerAdapter {
      */
     get sourceUrl(): string | null;
     load(url: string): Promise<void>;
+    /**
+     * Release the engine's media element and network loading — ad-role teardown at break end.
+     * The next `load()` re-attaches media, so nothing else is needed to reuse this adapter.
+     */
+    unload(): void;
+    /**
+     * Rebuild the pipeline for the CURRENT source positioned at `startTime` — see
+     * `PlayerAdapter.recreateMediaPipeline`. Resolves on the first of `loadedmetadata` /
+     * `FRAG_BUFFERED`; rejects on a fatal hls.js error. `recoverMediaError()` is deliberately
+     * not used: it seeds `startLoad` with the old currentTime, which double-seeks.
+     */
+    recreateMediaPipeline(options: {
+        startTime: number;
+    }): Promise<void>;
     /**
      * Detached prefetch for the single-decoder preload strategy.
      *
@@ -172,6 +196,14 @@ export declare class HlsJsAdapter implements PlayerAdapter {
      * `latestLevelDetails.live` is the authoritative flag and is public API.
      */
     get maxLiveSeekPosition(): number | null;
+    get targetDuration(): number | null;
+    /**
+     * Makes hls.js itself start a live stream `targetDurations` declared target durations behind the
+     * playlist edge, through its live-sync distance (`liveSyncDurationCount`). hls.js reads that when
+     * the first media playlist arrives, so this only works before then; afterwards it returns false
+     * and the SDK seeks. The distance stays hls.js's live-sync target for the rest of the session.
+     */
+    requestLiveStartOffset(targetDurations: number | null, _fallbackTargetDuration: number | null): boolean;
     /**
      * 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.
@@ -228,6 +260,7 @@ export declare class HlsJsAdapter implements PlayerAdapter {
      * Set up video element event listeners.
      */
     private setupVideoListeners;
+    private emitEndedOnce;
     /**
      * Update program date time based on current playback position.
      */

package/dist/HlsJsAdapter.js

@@ -1 +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)}}}
+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.endedEmitted=!1,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 playbackReady(){return this.video.readyState>=HTMLMediaElement.HAVE_CURRENT_DATA&&!this.video.seeking}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 this.endedEmitted=!1,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)})}unload(){this.deferredSeekTime=null,this.hls.stopLoad(),this.hls.detachMedia()}recreateMediaPipeline(t){return this.deferredSeekTime=null,new Promise((s,i)=>{const r=()=>{this.video.removeEventListener("loadedmetadata",n),this.hls.off(e.Events.FRAG_BUFFERED,a),this.hls.off(e.Events.ERROR,o)},n=()=>{d()},a=()=>{d()},d=()=>{Math.abs(this.video.currentTime-t.startTime)>.5&&(this.video.currentTime=t.startTime),r(),s()},o=(e,t)=>{t.fatal&&(r(),i(new Error(`HLS pipeline recreate error: ${t.details}`)))};this.video.addEventListener("loadedmetadata",n),this.hls.on(e.Events.FRAG_BUFFERED,a),this.hls.on(e.Events.ERROR,o),this.hls.detachMedia(),this.hls.attachMedia(this.video);try{this.video.currentTime=t.startTime}catch{}this.hls.startLoad(t.startTime)})}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(o),i.off(e.Events.FRAG_LOADED,a),i.off(e.Events.ERROR,d);try{i.destroy()}catch{}s()}},a=()=>n(),d=(e,t)=>{t.fatal&&n()},o=setTimeout(n,8e3);i.on(e.Events.FRAG_LOADED,a),i.on(e.Events.ERROR,d),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}get targetDuration(){const e=this.hls.latestLevelDetails,t=e?.targetduration;return e?.live&&"number"==typeof t&&Number.isFinite(t)&&t>0?t:null}requestLiveStartOffset(e,t){const s=e;if(null===s||!Number.isFinite(s)||s<=0)return!1;if(this.hls.latestLevelDetails)return!1;const i=this.hls.config;return!(void 0===i.liveMaxLatencyDuration&&i.liveMaxLatencyDurationCount<=s)&&(delete i.liveSyncDuration,i.liveSyncDurationCount=s,this.hls.userConfig.liveSyncDurationCount=s,!0)}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.MEDIA_ENDED,()=>{this.emitEndedOnce()}),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.emitEndedOnce()},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.endedEmitted=!1,this.emit("playing")},d=()=>{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",d),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",d)}emitEndedOnce(){this.endedEmitted||(this.endedEmitted=!0,this.emit("ended"))}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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dolby-optiview/ads-sdk-adapter-hlsjs",
-  "version": "1.0.0-beta.6",
+  "version": "1.1.0",
   "description": "HLS.js adapter for OptiView Ads SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -38,7 +38,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@dolby-optiview/ads-sdk-core": "1.0.0-beta.6"
+    "@dolby-optiview/ads-sdk-core": "^1.1.0"
   },
   "peerDependencies": {
     "hls.js": "^1.0.0"