@dolby-optiview/ads-sdk-core 1.5.1 → 1.6.0

package/dist/session/buildScheduledBreaks.js

@@ -0,0 +1 @@
+import{BreakEvent as t,Timebase as e,getBreakEvent as i}from"../types/BreakManifest";import{breakPlanEmptyReason as s}from"../services/AdBreakSequencer";export function buildScheduledBreaks(r,n={}){if(!r)return[];const o=[];for(const a of r.breaks){const d=i(a);if(null!==d&&d!==t.START&&d!==t.END)continue;const p=n.canPlay??(t=>null===s(t,"overlay"));if(n.excluded?.has(a.id)||!p(a))continue;const l=d===t.START?"pre":d===t.END?"post":"mid";let u="pre"===l?0:null,c=null;if("mid"===l)if(r.timebase===e.WALLCLOCK&&"string"==typeof a.start){const t=new Date(a.start);Number.isFinite(t.getTime())&&(c=t.toISOString())}else"number"==typeof a.start&&(u=r.timebase===e.MEDIATIME?a.start:n.mapPts?.(a.start)??null);o.push({id:a.id,position:l,startSec:u,startDate:c,durationSec:a.duration,played:n.played?.has(a.id)??!1})}const a={pre:0,mid:1,post:2},d=t=>t.startSec??(Date.parse(t.startDate??"")||0);return o.sort((t,e)=>a[t.position]-a[e.position]||("mid"===t.position?d(t)-d(e):0)||(t.id<e.id?-1:t.id>e.id?1:0))}

package/dist/session/contentSnapback.d.ts

@@ -1,9 +1,9 @@
 import type { PlayerAdapter } from '../interfaces/PlayerAdapter';
-import { type Break } from '../types/BreakManifest';
+import { type Break, type BreakFormat } from '../types/BreakManifest';
 import type { SessionState } from './SessionState';
 import type { BreakScheduler } from '../services/BreakScheduler';
 /** VOD snapback is unavailable on TV browsers, including React Native web TV shells. */
-export declare function configureVodSnapback(scheduler: BreakScheduler, player: PlayerAdapter, canPlay: (brk: Break) => boolean): void;
+export declare function configureVodSnapback(scheduler: BreakScheduler, player: PlayerAdapter, canPlay: (brk: Break) => boolean, selectFormat?: (brk: Break) => BreakFormat | undefined): void;
 export interface SnapbackDeps {
     player: PlayerAdapter;
     state: Pick<SessionState, 'snapbackSeekInFlight'>;

package/dist/session/contentSnapback.js

@@ -1 +1 @@
-import{DeviceType as e}from"../types/BreakManifest";import{detectDeviceProfile as t}from"../services/detectDeviceType";export function configureVodSnapback(a,n,r){a.setSnapbackOnSeek(t().deviceType!==e.TV,r),a.setOnSnapback(e=>n.seek(e.target))}export function createSnapbackHandler(e){return()=>{if(e.state.snapbackSeekInFlight)return void(e.state.snapbackSeekInFlight=!1);e.onViewerSeek(),e.onSeeked?.();const t=e.activeBreak();if(!t?.controls?.snapback)return;const a="number"==typeof t.start?t.start:e.player.currentTime;Math.abs(e.player.currentTime-a)<=.5||(e.log("Snapback: seek detected during locked break, snapping back to break start"),e.state.snapbackSeekInFlight=!0,e.player.seek(a))}}
+import{DeviceType as e}from"../types/BreakManifest";import{detectDeviceProfile as t}from"../services/detectDeviceType";export function configureVodSnapback(a,n,r,c){a.setSnapbackOnSeek(t().deviceType!==e.TV,r,c),a.setOnSnapback(e=>n.seek(e.target))}export function createSnapbackHandler(e){return()=>{if(e.state.snapbackSeekInFlight)return void(e.state.snapbackSeekInFlight=!1);e.onViewerSeek(),e.onSeeked?.();const t=e.activeBreak();if(!t?.controls?.snapback)return;const a="number"==typeof t.start?t.start:e.player.currentTime;Math.abs(e.player.currentTime-a)<=.5||(e.log("Snapback: seek detected during locked break, snapping back to break start"),e.state.snapbackSeekInFlight=!0,e.player.seek(a))}}

package/dist/session/scheduledBreaksSession.d.ts

@@ -0,0 +1,6 @@
+import type { AdPlayerController } from '../services/AdPlayerController';
+import type { MetadataCueTracker } from '../services/MetadataCueTracker';
+import type { OptiViewAdsEventMap, OptiViewAdsEventType } from '../types/Events';
+import { ScheduledBreaksTracker } from './ScheduledBreaksTracker';
+export declare function createScheduledBreaksTracker(controller: () => AdPlayerController | undefined, cues: () => MetadataCueTracker | null, emit: (event: 'scheduledbreakschange', data: OptiViewAdsEventMap['scheduledbreakschange']) => void): ScheduledBreaksTracker;
+export declare function noteScheduledBreakEvent(tracker: ScheduledBreaksTracker, event: OptiViewAdsEventMap[OptiViewAdsEventType]): void;

package/dist/session/scheduledBreaksSession.js

@@ -0,0 +1 @@
+import{ScheduledBreaksTracker as e}from"./ScheduledBreaksTracker";export function createScheduledBreaksTracker(a,r,d){return new e(e=>d("scheduledbreakschange",{type:"scheduledbreakschange",timestamp:Date.now(),breaks:e}),{canPlay:e=>null===a()?.breakNothingToPlayReason(e),mapPts:e=>r()?.mediaTimeForPts(e)??null})}export function noteScheduledBreakEvent(e,a){"adbreakbegin"===a.type&&e.markPlayed(a.break.id),"adbreakskipped"===a.type&&"overlap"===a.reason&&e.exclude(a.break.id)}

package/dist/types/BreakManifest.d.ts

@@ -1,4 +1,4 @@
-/** Break Manifest types, per https://github.com/Dolby-OptiView/optiview-ads-manifest-spec/blob/v1.9.0/spec.md. */
+/** Break Manifest types, per https://github.com/Dolby-OptiView/optiview-ads-manifest-spec/blob/v1.12.0/spec.md. */
 /** Which 'time' reference break start times use. @category Break Manifests & Ad Formats */
 export declare enum Timebase {
     /** An absolute ISO-8601 timestamp */
@@ -111,9 +111,26 @@ export interface BreakManifest {
     vendorConfiguration?: VendorConfiguration[];
     /** Event-specific configuration windows on a wallclock live stream. */
     events?: ChannelEvent[];
+    /** Media shown during the part of a break no ad covers (spec 1.12.0); absent when the channel has no slate. */
+    slate?: Slate;
     /** The available breaks */
     breaks: Break[];
 }
+/**
+ * Media that replaces the ad during the part of a break no ad covers, until the break ends
+ * (manifest spec 1.12.0). Video loops from its start; an image stays visible.
+ * @category Break Manifests & Ad Formats
+ */
+export interface Slate {
+    /**
+     * Seconds (>= 0) of the break that must remain for the slate to start; `0` starts it for any
+     * remaining time.
+     * @default 5
+     */
+    minDuration?: number;
+    /** Static assets without `duration`; the SDK plays the first, also when it cannot play it. */
+    assets: StaticAsset[];
+}
 /**
  * An event window on a wallclock live stream and the session configuration in effect while it
  * runs. Crossing its start or end emits `adchannelchange` with reason `event-boundary`.
@@ -297,15 +314,36 @@ export interface DoubleBreakVariant extends BaseBreakVariant {
     /** Paired ad + companion assets. */
     assets: AssetWithCompanion[];
 }
+/**
+ * The corner of the picture area the L-shape video box is anchored to (manifest spec 1.11.0).
+ * The box is 65% of the picture, inset 5% from the two edges of its corner.
+ * @category Break Manifests & Ad Formats
+ */
+export declare enum LshapeAnchor {
+    TOP_LEFT = "top_left",
+    TOP_RIGHT = "top_right",
+    BOTTOM_LEFT = "bottom_left",
+    BOTTOM_RIGHT = "bottom_right"
+}
 /** L-shape (ad) variant — content shrinks to pip, ad fills main area, companion fills the backdrop. Content pauses. @category Break Manifests & Ad Formats */
 export interface LshapeAdBreakVariant extends BaseBreakVariant {
     format: BreakFormat.LSHAPE_AD;
+    /**
+     * The corner the video box is anchored to. An unrecognised value renders `top_left`.
+     * @default LshapeAnchor.TOP_LEFT
+     */
+    anchor?: LshapeAnchor;
     /** Paired ad + companion assets. */
     assets: AssetWithCompanion[];
 }
 /** L-shape (content) variant — content shrinks to pip and keeps playing, ad fills the main area. @category Break Manifests & Ad Formats */
 export interface LshapeContentBreakVariant extends BaseBreakVariant {
     format: BreakFormat.LSHAPE_CONTENT;
+    /**
+     * The corner the video box is anchored to. An unrecognised value renders `top_left`.
+     * @default LshapeAnchor.TOP_LEFT
+     */
+    anchor?: LshapeAnchor;
     /** Ad assets (no companion). */
     assets: Asset[];
 }

package/dist/types/BreakManifest.js

@@ -1 +1 @@
-export var Timebase;!function(e){e.WALLCLOCK="wallclock",e.PTS="pts",e.MEDIATIME="mediatime"}(Timebase||(Timebase={}));export function isGamVendorConfiguration(e){return"gam"===e.type}export var DeliveryMode;!function(e){e.SGAI="sgai",e.SSAI="ssai"}(DeliveryMode||(DeliveryMode={}));export var BreakEvent;!function(e){e.START="start",e.PAUSE="pause",e.END="end"}(BreakEvent||(BreakEvent={}));export var BreakFormat;!function(e){e.SINGLE="single",e.DOUBLE="double",e.LSHAPE_AD="lshape_ad",e.LSHAPE_CONTENT="lshape_content",e.OVERLAY="overlay"}(BreakFormat||(BreakFormat={}));export var DeviceType;!function(e){e.CONSOLE="console",e.DESKTOP="desktop",e.MOBILE="mobile",e.TABLET="tablet",e.TV="tv"}(DeviceType||(DeviceType={}));export var Platform;!function(e){e.WEB="web",e.ANDROID="android",e.IOS="ios",e.TVOS="tvos",e.ROKU="roku"}(Platform||(Platform={}));export var Os;!function(e){e.ANDROID="android",e.CHROMEOS="chromeos",e.IOS="ios",e.IPADOS="ipados",e.LINUX="linux",e.MACOS="macos",e.ROKUOS="rokuos",e.TIZEN="tizen",e.TVOS="tvos",e.VIZIO="vizio",e.WEBOS="webos",e.WINDOWS="windows",e.XBOX="xbox"}(Os||(Os={}));export var AssetType;!function(e){e.STATIC="static",e.VAST="vast",e.VENDOR="vendor"}(AssetType||(AssetType={}));export var MediaType;!function(e){e.VIDEO="video",e.IMAGE="image"}(MediaType||(MediaType={}));export var Vendor;!function(e){e.GAM="gam"}(Vendor||(Vendor={}));export function isEventTrigger(e){return"object"==typeof e&&null!==e&&"event"===e.type}export function getBreakEvent(e){return"pre"===e.position?BreakEvent.START:isEventTrigger(e.start)?e.start.event:null}export function isPauseBreak(e){return getBreakEvent(e)===BreakEvent.PAUSE}export function getPreRollDelay(e){return getBreakEvent(e)!==BreakEvent.START?null:"pre"===e.position?e.delay??0:isEventTrigger(e.start)?e.start.delay??0:0}export function isPostRollBreak(e){return getBreakEvent(e)===BreakEvent.END}export function getPostRollDelay(e){return isEventTrigger(e.start)&&e.start.event===BreakEvent.END?e.start.delay??0:null}export function isStaticAsset(e){return e.type===AssetType.STATIC}export function isVastAsset(e){return e.type===AssetType.VAST}export function isVendorAsset(e){return e.type===AssetType.VENDOR}
+export var Timebase;!function(e){e.WALLCLOCK="wallclock",e.PTS="pts",e.MEDIATIME="mediatime"}(Timebase||(Timebase={}));export function isGamVendorConfiguration(e){return"gam"===e.type}export var DeliveryMode;!function(e){e.SGAI="sgai",e.SSAI="ssai"}(DeliveryMode||(DeliveryMode={}));export var BreakEvent;!function(e){e.START="start",e.PAUSE="pause",e.END="end"}(BreakEvent||(BreakEvent={}));export var BreakFormat;!function(e){e.SINGLE="single",e.DOUBLE="double",e.LSHAPE_AD="lshape_ad",e.LSHAPE_CONTENT="lshape_content",e.OVERLAY="overlay"}(BreakFormat||(BreakFormat={}));export var DeviceType;!function(e){e.CONSOLE="console",e.DESKTOP="desktop",e.MOBILE="mobile",e.TABLET="tablet",e.TV="tv"}(DeviceType||(DeviceType={}));export var Platform;!function(e){e.WEB="web",e.ANDROID="android",e.IOS="ios",e.TVOS="tvos",e.ROKU="roku"}(Platform||(Platform={}));export var Os;!function(e){e.ANDROID="android",e.CHROMEOS="chromeos",e.IOS="ios",e.IPADOS="ipados",e.LINUX="linux",e.MACOS="macos",e.ROKUOS="rokuos",e.TIZEN="tizen",e.TVOS="tvos",e.VIZIO="vizio",e.WEBOS="webos",e.WINDOWS="windows",e.XBOX="xbox"}(Os||(Os={}));export var LshapeAnchor;!function(e){e.TOP_LEFT="top_left",e.TOP_RIGHT="top_right",e.BOTTOM_LEFT="bottom_left",e.BOTTOM_RIGHT="bottom_right"}(LshapeAnchor||(LshapeAnchor={}));export var AssetType;!function(e){e.STATIC="static",e.VAST="vast",e.VENDOR="vendor"}(AssetType||(AssetType={}));export var MediaType;!function(e){e.VIDEO="video",e.IMAGE="image"}(MediaType||(MediaType={}));export var Vendor;!function(e){e.GAM="gam"}(Vendor||(Vendor={}));export function isEventTrigger(e){return"object"==typeof e&&null!==e&&"event"===e.type}export function getBreakEvent(e){return"pre"===e.position?BreakEvent.START:isEventTrigger(e.start)?e.start.event:null}export function isPauseBreak(e){return getBreakEvent(e)===BreakEvent.PAUSE}export function getPreRollDelay(e){return getBreakEvent(e)!==BreakEvent.START?null:"pre"===e.position?e.delay??0:isEventTrigger(e.start)?e.start.delay??0:0}export function isPostRollBreak(e){return getBreakEvent(e)===BreakEvent.END}export function getPostRollDelay(e){return isEventTrigger(e.start)&&e.start.event===BreakEvent.END?e.start.delay??0:null}export function isStaticAsset(e){return e.type===AssetType.STATIC}export function isVastAsset(e){return e.type===AssetType.VAST}export function isVendorAsset(e){return e.type===AssetType.VENDOR}

package/dist/types/Events.d.ts

@@ -1,10 +1,18 @@
 import { Break, Asset, BreakFormat } from './BreakManifest';
 import type { SessionDeliveryMode } from './OptiViewAdsConfig';
+import type { ScheduledBreak } from './ScheduledBreak';
+/** Viewer-specific schedule changed by value. @category Events */
+export interface ScheduledBreaksChangeEvent extends OptiViewAdsEvent {
+    type: 'scheduledbreakschange';
+    /** Independent snapshot of the current session schedule. */
+    breaks: ScheduledBreak[];
+}
 /**
  * Lifecycle phase reported by {@link AdBreakStatus}.
  * - `idle`: no break is upcoming or active.
  * - `upcoming`: a break is scheduled in the future (including pre-break warnings).
  * - `active`: a break is currently playing.
+ * - `complete`: an active break ended, including cuts/errors; emitted once before `idle` and `adbreakend`.
  * @category Events */
 export type AdBreakPhase = 'idle' | 'upcoming' | 'active' | 'complete';
 /** Why a scheduled ad break was refused before it began (`adbreakskipped` event). @category Events */
@@ -17,7 +25,7 @@ export interface AdBreakSkippedEvent extends OptiViewAdsEvent {
 }
 /** Playback-gated snapshot of an ad break for UI countdowns (`adbreakstatus` event, `sdk.getAdBreakStatus()`). @category Events */
 export interface AdBreakStatus {
-    /** Current lifecycle phase of the ad break. */
+    /** Current lifecycle phase. `complete` is transient; polling after cleanup returns `idle`. */
     phase: AdBreakPhase;
     /** The break this status describes; `null` when `phase` is `idle`. */
     break: Break | null;
@@ -25,13 +33,13 @@ export interface AdBreakStatus {
     format?: BreakFormat | undefined;
     /** Seconds until the break starts; for a pre-break warning, the countdown value when it fired. */
     secondsUntilBreak?: number | undefined;
-    /** Estimated seconds left in the active break; `undefined` when not yet derivable (e.g. a backdrop break with no per-ad `timeupdate`). */
+    /** Estimated seconds left in the active break; zero on `complete`, not a measure of ads watched. `undefined` when not yet derivable (e.g. a backdrop break with no per-ad `timeupdate`). */
     breakRemainingSec?: number | undefined;
     /** 0-based index of the ad currently playing within the break. */
     adIndex?: number | undefined;
     /** Total number of ads in the break, when known. */
     totalAds?: number | undefined;
-    /** Number of ads remaining including the currently playing one; after an ad ends, the ads still to come. */
+    /** Number of ads remaining including the currently playing one; after an ad ends, the ads still to come. Zero on `complete`, including cuts/errors. */
     adsRemaining?: number | undefined;
     /** Whether the countdown is advancing (ad rendered, playback progressing). `false` while buffering or before a held pre-roll's first frame. */
     ticking: boolean;
@@ -47,7 +55,7 @@ export interface AdBreakStatus {
     deliveryMode?: SessionDeliveryMode | undefined;
 }
 /** Event types emitted by the OptiViewAds SDK. @category Events */
-export type OptiViewAdsEventType = 'adbreakbegin' | 'adbreakend' | 'adbreakskipped' | 'adbegin' | 'adend' | 'aderror' | 'adfirstquartile' | 'admidpoint' | 'adthirdquartile' | 'adtimeupdate' | 'adbreakstatus' | 'adclick' | 'waiting' | 'playing' | 'volumechange' | 'adchannelchange' | 'externalvendorconfigurationchange';
+export type OptiViewAdsEventType = 'scheduledbreakschange' | 'adbreakbegin' | 'adbreakend' | 'adbreakskipped' | 'adbegin' | 'adend' | 'aderror' | 'adfirstquartile' | 'admidpoint' | 'adthirdquartile' | 'adtimeupdate' | 'adbreakstatus' | 'adclick' | 'waiting' | 'playing' | 'volumechange' | 'adchannelchange' | 'externalvendorconfigurationchange';
 /** Which player a playback event originated from. @category Events */
 export type PlaybackSource = 'ad' | 'content';
 /** Base event interface. @category Events */
@@ -249,6 +257,7 @@ export interface ExternalVendorConfigurationChangeEvent extends OptiViewAdsEvent
 }
 /** Union type of all SDK events. @category Events */
 export type OptiViewAdsEventMap = {
+    scheduledbreakschange: ScheduledBreaksChangeEvent;
     adbreakbegin: AdBreakBeginEvent;
     adbreakend: AdBreakEndEvent;
     adbreakskipped: AdBreakSkippedEvent;

package/dist/types/OptiViewAdsConfig.d.ts

@@ -357,6 +357,13 @@ export interface OptiViewAdsConfig {
      * @default false
      */
     continueContentDuringBreak?: boolean;
+    /**
+     * Let `startSession()` run without `manifestUrl` by using the ads manifest URL the content
+     * player discovers (THEOplayer with a THEOlive source on web and Android). Off by default:
+     * `startSession()` then requires `manifestUrl`, and adapters do not observe discovery.
+     * @default false
+     */
+    manifestUrlDiscovery?: boolean;
     /**
      * AirPlay (external playback) guard, active only when the manifest carries a server-side
      * beaconing (`ssb`) stream and the content adapter can gate external playback.
@@ -408,8 +415,14 @@ export interface SsaiConfig {
 }
 /** Per-session configuration passed to startSession(); changes per piece of content. @category SDK & Sessions */
 export interface SessionConfig {
-    /** Full break-manifest URL. The SDK fetches exactly this URL and never rewrites it (proxied, signed or opaque endpoints all work). */
-    manifestUrl: string;
+    /**
+     * Full break-manifest URL. The SDK fetches exactly this URL and never rewrites it (proxied,
+     * signed or opaque endpoints all work). When omitted, the SDK uses the ads manifest URL the
+     * content player discovered (see `PlayerAdapter.discoveredAdsManifestUrl`); the session then
+     * also auto-restarts when the player reports a different discovered URL, and ends when the
+     * player reports there is none.
+     */
+    manifestUrl?: string;
     /**
      * Ad insertion type for this content — how breaks relate to the content
      * timeline (DAR vs DAI). `replacement` replaces a content window; `insertion`

package/dist/types/ScheduledBreak.d.ts

@@ -0,0 +1,17 @@
+/** Placement of a scheduled break on the content timeline. @category Playback & UI */
+export type ScheduledBreakPosition = 'pre' | 'mid' | 'post';
+/** Viewer-specific opportunity for scrubber markers. @category Playback & UI */
+export interface ScheduledBreak {
+    /** Manifest break identifier. */
+    id: string;
+    /** Placement relative to content playback. */
+    position: ScheduledBreakPosition;
+    /** Content seconds; zero for pre-roll, null for post-roll, live or unresolved PTS. */
+    startSec: number | null;
+    /** ISO 8601 start for wallclock timeline breaks; otherwise null. */
+    startDate: string | null;
+    /** Manifest break duration in seconds, not the remaining playback duration. */
+    durationSec: number;
+    /** True once this session emitted adbreakbegin for this identifier. */
+    played: boolean;
+}

package/dist/types/ScheduledBreak.js

@@ -0,0 +1 @@
+export{};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dolby-optiview/ads-sdk-core",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "OptiView Ads SDK Core - Player-agnostic ad insertion",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",