@dolby-optiview/ads-sdk-core 1.0.0-beta.1

package/dist/types/OptiViewAdsConfig.d.ts

@@ -0,0 +1,425 @@
+import { PlayerAdapter } from '../interfaces/PlayerAdapter';
+import { AssetParameterMacros } from '../services/assetParameterMacros';
+import { BreakManifest } from './BreakManifest';
+/**
+ * Factory for a custom ad player: create media elements inside the supplied container
+ * and return a {@link PlayerAdapter}. When `video` is provided, use that existing content
+ * video element so ads remain visible in picture-in-picture or native fullscreen.
+ * If the factory ignores it, the SDK falls back to the content player.
+ *
+ * @example
+ * createAdAdapter: (container, video) => {
+ *   const el = video ?? container.appendChild(document.createElement('video'));
+ *   const hls = new Hls(); hls.attachMedia(el);
+ *   return new HlsJsAdapter(hls, el);
+ * }
+ * @category Player Integration */
+export type CreateAdAdapter = (container: HTMLElement, video?: HTMLVideoElement) => PlayerAdapter;
+/** Context passed to a {@link ManifestResponseInterceptor}. @category Manifest Customization */
+export interface ManifestInterceptContext {
+    /** The fully-resolved channel-manifest URL that was fetched. */
+    url: string;
+}
+/**
+ * Hook to inspect/modify the parsed, validated {@link BreakManifest} before it is scheduled
+ * (initial fetch and every poll). The returned manifest is used without re-validation. May be
+ * async; on throw the SDK emits `DA-MANIFEST-INTERCEPT-FAILED` and uses the unmodified manifest.
+ *
+ * @example
+ * interceptManifestResponse: (manifest) => ({
+ *   ...manifest,
+ *   breaks: [preRollBreak, ...manifest.breaks],
+ * })
+ * @category Manifest Customization */
+export type ManifestResponseInterceptor = (manifest: BreakManifest, context: ManifestInterceptContext) => BreakManifest | Promise<BreakManifest>;
+/** Context passed to a {@link ManifestRequestInterceptor}. @category Manifest Customization */
+export interface ManifestRequestContext {
+    /** The fully-resolved channel-manifest URL the SDK was about to fetch. */
+    url: string;
+}
+/** The outgoing manifest request; an interceptor may return a modified copy (URL and/or headers). @category Manifest Customization */
+export interface ManifestRequest {
+    /** The URL to fetch the manifest from. */
+    url: string;
+    /** Request headers to send with the fetch. */
+    headers?: Record<string, string>;
+}
+/** Mocked manifest response: the SDK skips the network and parses/validates {@link body} as a real response. @category Manifest Customization */
+export interface ManifestMockResponse {
+    /** Raw manifest body. A `string` is parsed as JSON; an object is used as-is. */
+    body: string | object;
+}
+/** {@link ManifestRequest} (redirect/headers), {@link ManifestMockResponse} (skip network), or `void` (fetch unchanged). @category Manifest Customization */
+export type ManifestRequestInterceptorResult = ManifestRequest | ManifestMockResponse | void;
+/**
+ * Hook to inspect/modify the manifest HTTP request before each fetch (initial and every poll).
+ * May be async; on throw the SDK emits `DA-MANIFEST-REQUEST-INTERCEPT-FAILED` and fetches the original URL.
+ *
+ * @example
+ * interceptManifestRequest: (request) => ({
+ *   ...request,
+ *   headers: { ...request.headers, 'X-Debug': '1' },
+ * })
+ * @category Manifest Customization */
+export type ManifestRequestInterceptor = (request: ManifestRequest, context: ManifestRequestContext) => ManifestRequestInterceptorResult | Promise<ManifestRequestInterceptorResult>;
+/**
+ * Ad preload strategy.
+ * - `parallel`: buffer the next ad into the attached ad player while content plays. Needs two
+ *   simultaneous MediaSources — safe on desktop and modern Smart TVs.
+ * - `single-decoder`: cache warming + detached prefetch only; attach/decode at break start.
+ *   Safe on single-decoder TVs (Tizen, webOS, VIZIO SmartCast).
+ * - `none`: disable preloading; load the ad when the break starts.
+ * - `auto` (default): User-Agent based — single-decoder TVs → `single-decoder`, else `parallel`.
+ *
+ * On single-decoder TVs, preloading avoids attaching a second MediaSource so the
+ * content player can continue using the device's decoder until the break starts.
+ * @category Configuration */
+export type AdPreloadMode = 'parallel' | 'single-decoder' | 'none' | 'auto';
+/**
+ * Ad insertion strategy (compositing).
+ * - `overlay`: separate `<video>` over the content player; all break formats.
+ * - `shared-element`: ad plays through the content `<video>` so iOS native fullscreen is kept.
+ *   Single fullscreen ads only; advanced formats are downgraded, `lshape_content` is skipped.
+ * - `adaptive`: iPhone/iPod on iOS 17.1+ (Managed Media Source): `overlay` while inline,
+ *   `shared-element` while in OS-native fullscreen (DOM overlays cannot render there).
+ * - `auto`: iPhone/iPod → `adaptive` when MMS is available, else `shared-element`; otherwise `overlay`.
+ * @category Configuration */
+export type AdInsertionMode = 'overlay' | 'shared-element' | 'adaptive' | 'auto';
+/**
+ * Ad insertion *type* — how an ad break relates to the content timeline. This is
+ * orthogonal to {@link AdInsertionMode} (which controls compositing) and is set
+ * per-session on {@link SessionConfig.adInsertionType}.
+ * - `replacement` (DAR): the break replaces a window of content; after
+ *   the break, content resumes at `breakStart + (resumeOffset ?? duration)` — the
+ *   replaced window is skipped.
+ * - `insertion` (DAI): the break is inserted and content resumes at the exact
+ *   pre-break position (`breakStart + (resumeOffset ?? 0)`); the content timeline
+ *   is not consumed. Primarily for VOD (PTS timebase).
+ * @category SDK & Sessions */
+export type AdInsertionType = 'replacement' | 'insertion';
+/**
+ * - `sgai` (default): the SDK polls the break manifest, schedules breaks and plays ads in its own overlay.
+ * - `ssai`: the content player plays a pre-stitched stream; the SDK only creates the IMA DAI
+ *   stream, loads the stitched master, forwards timed metadata to IMA and re-emits ad events.
+ * @category Configuration */
+export type OptiViewAdsMode = 'sgai' | 'ssai';
+/** How a PTS-timebase break's `start` value is resolved. @category Configuration */
+export type PtsSource = 'mediaTime' | 'anvatoCue';
+/** Default ad insertion architecture. */
+export declare const DEFAULT_MODE: OptiViewAdsMode;
+/**
+ * `auto` protects single-decoder TVs without configuration: `parallel` attaches a second
+ * MediaSource before the break and wedges their only hardware decoder (black screen, no `adbreakbegin`).
+ */
+export declare const DEFAULT_AD_PRELOAD_MODE: AdPreloadMode;
+/** `auto` switches iPhone/iPod to shared-element insertion and leaves every other platform on overlay. */
+export declare const DEFAULT_AD_INSERTION_MODE: AdInsertionMode;
+/**
+ * Which side gets audio during a `double`-format break, where the content and
+ * ad boxes play side-by-side. The non-focused side is muted for the duration
+ * of the break; the SDK's unified `sdk.muted`/`sdk.volume` controls the
+ * focused side only, and the pre-break
+ * unified state is restored to the non-focused side when the break ends.
+ * - `ad` (default): the ad is audible; content is muted for the break.
+ * - `content`: content keeps its audio; the ad is muted for the break.
+ * @category Configuration */
+export type DoubleBoxAudio = 'ad' | 'content';
+/** Default double-box audio focus: the ad, the side being monetised. */
+export declare const DEFAULT_DOUBLE_BOX_AUDIO: DoubleBoxAudio;
+/**
+ * Default hard-cut margin (seconds): a break always returns to content at
+ * `effectiveDuration + margin`, whatever the ad media does. The margin lets an ad close to the
+ * break length finish cleanly.
+ */
+export declare const DEFAULT_AD_BREAK_CUT_SAFETY_MARGIN_SEC = 2;
+/**
+ * Consecutive-break chaining: breaks separated by at most `maxGapSeconds` play as one sequence —
+ * the overlay is held, content is not resumed, and the next break preloads during the current one.
+ * @category Configuration */
+export interface ChainingConfig {
+    /**
+     * Whether chaining is enabled.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Maximum gap (seconds) between one break's end and the next break's start. `0` disables chaining.
+     * @default 2
+     */
+    maxGapSeconds?: number;
+}
+/**
+ * Chaining configuration with all fields resolved to concrete values.
+ * @category Configuration */
+export interface ResolvedChaining {
+    enabled: boolean;
+    maxGapSeconds: number;
+}
+/** Chaining on with a 2s gap, covering the common "two back-to-back breaks with a ~1s gap" case. */
+export declare const DEFAULT_CHAINING: ResolvedChaining;
+/** Resolve a partial {@link ChainingConfig}. */
+export declare function resolveChaining(config?: ChainingConfig): ResolvedChaining;
+/**
+ * Tune-in (join-in-progress): a viewer joining during a break sees it for its remaining
+ * duration. Breaks with less than `minBreakDurationSeconds` remaining are skipped.
+ * @category Configuration */
+export interface TuneInConfig {
+    /**
+     * Whether tune-in breaks are enabled.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Minimum remaining seconds for a join-in-progress break to be monetized.
+     * @default 5
+     */
+    minBreakDurationSeconds?: number;
+}
+/** {@link TuneInConfig} with all fields resolved. @category Configuration */
+export interface ResolvedTuneIn {
+    enabled: boolean;
+    minBreakDurationSeconds: number;
+}
+/** Tune-in on with a 5s minimum, matching the scheduler's timing tolerance. */
+export declare const DEFAULT_TUNE_IN: ResolvedTuneIn;
+/** Resolve a partial {@link TuneInConfig}. */
+export declare function resolveTuneIn(config?: TuneInConfig): ResolvedTuneIn;
+/**
+ * Default grace (seconds) for a `wallclock` stream's Program Date Time to appear. 5s covers the
+ * observed startup gap (~1.2-1.5s of ticks before the source is loaded) with margin. A
+ * backstop, not a delay: playing content with no PDT concludes after a ~1s settle.
+ */
+export declare const DEFAULT_PDT_GRACE_SECONDS = 5;
+/** Resolve the PDT grace window, clamping negatives to 0. */
+export declare function resolvePdtGraceSeconds(pdtGraceSeconds?: number): number;
+/**
+ * Pre-break warnings: seconds before a break at which `adbreakstatus` fires with
+ * `phase: 'upcoming'`. Once per threshold; pre-rolls are skipped.
+ * @category Configuration */
+export interface BreakWarningsConfig {
+    /**
+     * Seconds before a non-pre-roll break to fire warnings. Normalised to positive integers, deduplicated, sorted.
+     * @default []
+     */
+    seconds?: number[];
+}
+/** Normalised pre-break warning configuration. @category Configuration */
+export interface ResolvedBreakWarnings {
+    seconds: number[];
+}
+/** Default: no proactive warnings. */
+export declare const DEFAULT_BREAK_WARNINGS: ResolvedBreakWarnings;
+/** Resolve a partial {@link BreakWarningsConfig}: drop non-positive values, round, deduplicate, sort ascending. */
+export declare function resolveBreakWarnings(config?: BreakWarningsConfig): ResolvedBreakWarnings;
+/** Structured diagnostics configuration. @category Diagnostics */
+export interface DiagnosticsConfig {
+    /**
+     * Maximum records in the ring buffer behind `exportDiagnostics()`; oldest are evicted first.
+     * @default 200
+     */
+    bufferSize?: number;
+}
+/** SDK instance configuration, fixed for its lifetime (org-level). @category Configuration */
+export interface OptiViewAdsConfig {
+    /**
+     * Ad insertion architecture. With `ssai`, `gam` and `ssai` are both required and each session
+     * supplies `stitcherUrl` + `customAssetKey`.
+     * @default 'sgai'
+     * @see OptiViewAdsMode
+     */
+    mode?: OptiViewAdsMode;
+    /** Maximum rendition bitrate (bits/sec) sent to the stitcher as `max_bitrate`; variants above it are dropped. SSAI only. */
+    maxBitrate?: number;
+    /**
+     * Start playback automatically after loading the stitched master (SSAI only).
+     * @default false
+     */
+    autoplay?: boolean;
+    /** The content player adapter; the SDK only interacts with the player through it. */
+    player: PlayerAdapter;
+    /**
+     * Outer stage element containing the customer's player and all SDK-managed ad elements. The SDK
+     * appends its elements here and sets position:relative if not already set.
+     */
+    container: HTMLElement;
+    /**
+     * Inner wrapper around the customer's player UI, repositioned to a pip corner during lshape
+     * breaks. Must be a child of container. If omitted the SDK wraps the existing children itself.
+     */
+    playerContainer?: HTMLElement;
+    /**
+     * Factory for a custom ad player, given an SDK-created container. Optional with
+     * `@dolby-optiview/ads-sdk`, which includes a default player for progressive video and HLS.
+     * Required when using the bare `@dolby-optiview/ads-sdk-core` package.
+     *
+     * @example
+     * createAdAdapter: (container) => {
+     *   const video = document.createElement('video');
+     *   container.appendChild(video);
+     *   const hls = new Hls(); hls.attachMedia(video);
+     *   return new HlsJsAdapter(hls, video);
+     * }
+     */
+    createAdAdapter?: CreateAdAdapter;
+    /**
+     * Ad preload strategy.
+     * @default 'auto'
+     * @see AdPreloadMode
+     */
+    adPreload?: AdPreloadMode;
+    /**
+     * Ad insertion strategy. `auto` switches iPhone/iPod to shared-element insertion, all other platforms overlay.
+     * @default 'auto'
+     * @see AdInsertionMode
+     */
+    adInsertion?: AdInsertionMode;
+    /**
+     * Consecutive-break chaining. Defaults to enabled with a 2s gap.
+     * @see ChainingConfig
+     */
+    chaining?: ChainingConfig;
+    /**
+     * Tune-in (join-in-progress) configuration. Defaults to enabled with a 5s minimum.
+     * @see TuneInConfig
+     */
+    tuneIn?: TuneInConfig;
+    /**
+     * Pre-break warnings: `adbreakstatus` events N seconds before each non-pre-roll break.
+     * @see BreakWarningsConfig
+     */
+    breakWarnings?: BreakWarningsConfig;
+    /**
+     * Seconds to wait for `EXT-X-PROGRAM-DATE-TIME` on a `wallclock` session before concluding the
+     * stream carries none. Until then no scheduling decision is made: the system clock runs ahead
+     * of the live playhead by the stream latency and would fire a break early.
+     *
+     * A backstop, not a fixed delay: content playing for ~1s with no PDT concludes immediately
+     * (`DA-PDT-MISSING`); the window only governs a player that never starts. Set `0` to use the
+     * system clock immediately. No effect on `pts` manifests.
+     * @default 5
+     */
+    pdtGraceSeconds?: number;
+    /**
+     * How a `timebase: "pts"` break's `start` is resolved. `mediaTime` reads it directly as player
+     * media time. `anvatoCue` tracks Anvato in-stream cues — HLS ID3 GEOB frames (description
+     * `Anvatos`, MIME `application/json`) and DASH emsg (`urn:anvato:es1:052016`) with payload
+     * `type=cue&pts=<seconds>` — and schedules the break at the media time of the cue whose `pts`
+     * matches its `start` (±5 ms); until then it stays pending (`DA-ANVATO-CUE-PENDING`). SGAI only.
+     * @default 'mediaTime'
+     */
+    ptsSource?: PtsSource;
+    /**
+     * Keep content playing, muted and hidden, through eligible replacement single-format breaks.
+     * Requires SGAI and an explicit `adInsertionType: 'replacement'`. The content player's
+     * optional `setVideoQuality` operation constrains background bandwidth when available.
+     * @default false
+     */
+    continueContentDuringBreak?: boolean;
+    /** Hook on the parsed manifest before scheduling (initial fetch and every poll). See {@link ManifestResponseInterceptor}. */
+    interceptManifestResponse?: ManifestResponseInterceptor;
+    /**
+     * Hook on the manifest HTTP request (redirect, headers, or a mocked body). On throw the SDK emits
+     * `DA-MANIFEST-REQUEST-INTERCEPT-FAILED` and fetches normally. See {@link ManifestRequestInterceptor}.
+     */
+    interceptManifestRequest?: ManifestRequestInterceptor;
+    /**
+     * Seconds added to a break's effective duration to form the hard cut back to content, so an
+     * over-long or stalled ad cannot hold the break open. `0` cuts exactly at the boundary.
+     * @default 2
+     */
+    adBreakCutSafetyMarginSec?: number;
+    /**
+     * Which side gets audio during a `double`-format break; the other side is muted for the break.
+     * @default 'ad'
+     * @see DoubleBoxAudio
+     */
+    doubleBoxAudio?: DoubleBoxAudio;
+    /**
+     * Enable debug logging.
+     * @default false
+     */
+    debug?: boolean;
+    /** Ring buffer behind `onDiagnostic()` and `exportDiagnostics()`. */
+    diagnostics?: DiagnosticsConfig;
+    /**
+     * Google Ad Manager configuration. Its PRESENCE enables GAM. It carries no stream identity: in
+     * `sgai` that comes from the manifest's `vendorConfiguration`, in `ssai` from {@link ssai} + `customAssetKey`.
+     */
+    gam?: GamConfig;
+    /** SSAI-only GAM identity (required with `mode: 'ssai'`): SSAI has no break manifest to read it from. */
+    ssai?: SsaiConfig;
+}
+/** The GAM identity for `mode: 'ssai'`. @category Configuration */
+export interface SsaiConfig {
+    /** Network code for the GAM account serving the stitched stream. */
+    networkCode: string;
+}
+/** 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;
+    /**
+     * Ad insertion type for this content — how breaks relate to the content
+     * timeline (DAR vs DAI). `replacement` replaces a content window; `insertion`
+     * inserts the break and resumes at the exact pre-break position. When omitted,
+     * the manifest's `resumeOffset` drives the resume point.
+     * SGAI only — ignored in SSAI mode (the stitcher controls insertion, surfaced
+     * via a `DA-INSERTION-TYPE-IGNORED-SSAI` diagnostic).
+     * @see AdInsertionType
+     */
+    adInsertionType?: AdInsertionType;
+    /**
+     * Ad parameters for this session (for GAM: IMA `adTagParameters`). Per-key precedence is
+     * SessionConfig, `updateAssetParameters()`, manifest session parameters, then asset parameters.
+     * @see updateAssetParameters
+     */
+    assetParameters?: Record<string, string>;
+    /**
+     * Customer macros for the `$NAME$` tokens in asset-parameter values — a fixed
+     * string or a zero-argument callback per macro name, e.g.
+     * `{ '$CUSTOM_TEAM$': () => currentTeam() }`. Every `$NAME$` token inside a
+     * manifest / session / update value is replaced when the ad request is built,
+     * so `"$OPTIVIEW_PLAYER_WIDTH$x$OPTIVIEW_PLAYER_HEIGHT$"` becomes `"1920x1080"`.
+     * Customer macros are consulted before the built-in `$OPTIVIEW_*` set, so a
+     * built-in can be overridden. `$OPTIVIEW_*` and registered customer macros without
+     * values stay literal; the parameter is sent and `DA-ASSET-MACRO-UNKNOWN` is raised
+     * once per key/macro (context: `key`, `macro`). Other unresolved `$NAME$` tokens
+     * stay literal without a diagnostic. `$` without a closing `$` is unchanged.
+     * Callbacks are evaluated per ad request and cleared when the session ends.
+     * Session-scoped parameters are sent to IMA DAI with
+     * built-in and customer macros resolved; break-duration macros are omitted.
+     *
+     * @see OPTIVIEW_ASSET_PARAMETER_MACROS
+     */
+    assetParameterMacros?: AssetParameterMacros;
+}
+/**
+ * Per-session configuration for `mode: 'ssai'`: keyed on the stitched master URL instead of a
+ * manifest URL. The SDK appends `stream_id`, `max_bitrate` and extra params and never rebuilds the path.
+ * @category SDK & Sessions */
+export type SsaiSessionConfig = Omit<SessionConfig, 'manifestUrl'> & {
+    /** Full URL of the stitcher master playlist for this content. */
+    stitcherUrl: string;
+    /** Custom asset key for the GAM DAI stream. Required: SSAI has no break manifest to take it from. */
+    customAssetKey: string;
+};
+/** What {@link OptiViewAds.startSession} accepts. Narrow with `'stitcherUrl' in config`. @category SDK & Sessions */
+export type StartSessionConfig = SessionConfig | SsaiSessionConfig;
+/**
+ * Google Ad Manager pod serving. Presence is the opt-in. The stream identity comes from the break
+ * manifest's `vendorConfiguration`, so client and backend cannot disagree; SSAI declares its own
+ * on {@link SsaiConfig} and {@link SsaiSessionConfig}.
+ * @category Configuration */
+export interface GamConfig {
+    /**
+     * Set `false` to keep GAM off even when the manifest asks for it (consent prompts, builds that
+     * must not reach Google). GAM otherwise activates from the manifest.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Stream Activity Monitor ID for debugging in Google's SAM tool.
+     * @see https://support.google.com/admanager/answer/9388474
+     */
+    streamActivityMonitorId?: string;
+}

package/dist/types/OptiViewAdsConfig.js

@@ -0,0 +1 @@
+export const DEFAULT_MODE="sgai";export const DEFAULT_AD_PRELOAD_MODE="auto";export const DEFAULT_AD_INSERTION_MODE="auto";export const DEFAULT_DOUBLE_BOX_AUDIO="ad";export const DEFAULT_AD_BREAK_CUT_SAFETY_MARGIN_SEC=2;export const DEFAULT_CHAINING={enabled:!0,maxGapSeconds:2};export function resolveChaining(e){return{enabled:e?.enabled??DEFAULT_CHAINING.enabled,maxGapSeconds:e?.maxGapSeconds??DEFAULT_CHAINING.maxGapSeconds}}export const DEFAULT_TUNE_IN={enabled:!0,minBreakDurationSeconds:5};export function resolveTuneIn(e){return{enabled:e?.enabled??DEFAULT_TUNE_IN.enabled,minBreakDurationSeconds:e?.minBreakDurationSeconds??DEFAULT_TUNE_IN.minBreakDurationSeconds}}export const DEFAULT_PDT_GRACE_SECONDS=5;export function resolvePdtGraceSeconds(e){return Math.max(0,e??5)}export const DEFAULT_BREAK_WARNINGS={seconds:[]};export function resolveBreakWarnings(e){const n=e?.seconds??[];return{seconds:Array.from(new Set(n.map(e=>Math.round(e)).filter(e=>Number.isFinite(e)&&e>0))).sort((e,n)=>e-n)}}

package/dist/types/VendorAdError.d.ts

@@ -0,0 +1,12 @@
+/**
+ * An ad playback error that carries the ad vendor's own error code (e.g. the
+ * numeric IMA/VAST `AdError` code), so telemetry can report it (`adevc`)
+ * alongside the SDK's taxonomy code. Vendor integrations wrap their errors in
+ * this type when the vendor supplies a code; errors without one stay plain
+ * `Error`s.
+ */
+export declare class VendorAdError extends Error {
+    /** The vendor's error code, stringified (e.g. IMA's numeric AdError code). */
+    readonly vendorCode: string;
+    constructor(message: string, vendorCode: string);
+}

package/dist/types/VendorAdError.js

@@ -0,0 +1 @@
+export class VendorAdError extends Error{constructor(r,o){super(r),this.name="VendorAdError",this.vendorCode=o}}