PlayerAdapter Interface

Any adapter must implement all properties and methods below. The interface is imported from @dolby-ads/core.

import type { PlayerAdapter, PlayerAdapterEvent, PlayerAdapterEventHandler } from '@dolby-ads/core';

// Events the adapter must support
type PlayerAdapterEvent = 'timeupdate' | 'ended' | 'error' | 'seeked' | 'volumechange';

interface PlayerAdapter {
  /** Current playback position in seconds. */
  readonly currentTime: number;

  /** Total duration in seconds (Infinity for live streams). */
  readonly duration: number;

  /** True when playback is paused. */
  readonly paused: boolean;

  /** Whether the player is muted. */
  muted: boolean;

  /** Volume level in the range [0, 1]. */
  volume: number;

  /** Current Program Date Time from the HLS manifest.
   *  Required for wallclock-timebase break matching on live streams.
   *  Return null if not available. */
  readonly programDateTime: Date | null;

  /** Pause playback. Called by SDK at break start. */
  pause(): void;

  /** Resume playback. Called by SDK at break end. */
  play(): Promise<void>;

  /** Seek to a position in seconds.
   *  Required for SDK snapback enforcement during locked breaks. */
  seek(time: number): void;

  /** Load a media URL and resolve when ready to play (manifest parsed).
   *  Used for preloading ad content 5 seconds before break start. */
  load(url: string): Promise<void>;

  /** Subscribe to a player event. */
  on(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler): void;

  /** Unsubscribe from a player event. */
  off(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler): void;

  /** Release all resources. Called when SDK is destroyed. */
  destroy(): void;

  // ── optional ──────────────────────────────────────────────────────────────

  /** Stop driving the `<video>` without tearing the player down, so the SDK can
   *  play an ad through that same element (shared-element insertion). The SDK
   *  hands the element back at break end by calling `load()` again on this same
   *  adapter, so this must NOT destroy the player. Omit it if your engine is
   *  happy to share the element (hls.js is). */
  releaseMediaElement?(): void | Promise<void>;
}

HLS.js Adapter

The official HLS.js adapter is available as a separate package.

Install

npm install @dolby-ads/adapter-hlsjs hls.js

Requirements

• One Hls instance for content. The ad HLS instance is created inside createAdAdapter.
• One <video> element for content. The ad <video> is created by your factory inside the SDK-provided container.
• HLS streams must contain EXT-X-PROGRAM-DATE-TIME tags for wallclock-timebase channels.

Full setup example

import Hls from 'hls.js';
import { DolbyAds } from '@dolby-ads/core';
import { HlsJsAdapter } from '@dolby-ads/adapter-hlsjs';

const video = document.getElementById('video') as HTMLVideoElement;

const hls = new Hls();
hls.attachMedia(video);

const sdk = new DolbyAds({
  orgId:           'your-org-id',
  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);
  },
  gam: { networkCode: '23285652104' },
});

sdk.addEventListener('adbreakbegin', (e) => {
  console.log('Ad break', e.break.id, 'started —', e.break.duration, 's');
});
sdk.addEventListener('adbreakend', () => {
  console.log('Content resuming');
});

await sdk.startSession({
  channelId:      'your-channel-id',
  customAssetKey: 'your-asset-key',
});

hls.loadSource('https://example.com/live.m3u8');
video.play();

Seek & seeked event

The HLS.js adapter implements seek(time) by setting video.currentTime and forwards the native seeked video event. This enables the SDK to detect and correct unexpected seeks during locked ad breaks.

PDT (Program Date Time)

The HLS.js adapter automatically tracks EXT-X-PROGRAM-DATE-TIME from the manifest and exposes it via programDateTime. This is used by the SDK to match wallclock-timebase breaks against the live stream position.

Cleanup

// When the player is torn down:
sdk.destroy();   // also destroys the internal ad player
hls.destroy();

Shaka Player Adapter

The official Shaka Player adapter is available as a separate package. It supports HLS and DASH streams and extracts programDateTime from Shaka's presentation timeline for live streams.

Install

npm install @dolby-ads/adapter-shaka shaka-player

Requirements

• Shaka Player 4.x or 5.x
• Call shaka.polyfill.installAll() once before creating any shaka.Player instance

Full setup example

import shaka from 'shaka-player';
import { DolbyAds } from '@dolby-ads/core';
import { ShakaAdapter } from '@dolby-ads/adapter-shaka';

// 1. Install Shaka polyfills (once per page)
shaka.polyfill.installAll();

// 2. Content player
const video  = document.getElementById('video') as HTMLVideoElement;
const player = new shaka.Player(video);

// 3. SDK — pass Player WITHOUT video to avoid eager MediaSource init on the ad element
//    playerContainer is optional; SDK auto-wraps when omitted
const sdk = new DolbyAds({
  orgId: 'your-org-id',
  player: new ShakaAdapter(player, video),
  container: document.getElementById('container'),
  createAdAdapter: (adContainer) => {
    const adVideo = document.createElement('video');
    adContainer.appendChild(adVideo);
    return new ShakaAdapter(new shaka.Player(), adVideo);
  },
});

// 5. Start session and load stream
await sdk.startSession({ channelId: 'your-channel-id' });
await player.load('https://example.com/live.m3u8');
video.play();

PDT (Program Date Time)

For live HLS streams with EXT-X-PROGRAM-DATE-TIME, the Shaka adapter derives the wall-clock position from Shaka's PresentationTimeline.getPresentationStartTime() combined with video.currentTime. This is used to match wallclock-timebase breaks.

In-stream timed metadata (ID3 / emsg)

The Shaka adapter forwards in-stream markers to the SDK as timedmetadata cues — used to relay ad-tracking metadata to IMA during SSAI, and to match Anvato in-stream break signaling when useAnvatoID3 is enabled (see Configuration).

The adapter subscribes to three Shaka events:

Each marker is emitted once, de-duplicated across metadataadded and metadata, so IMA never receives a doubled tracking cue.

Two behaviours are specific to Shaka and handled inside the adapter:

• GEOB frames are decoded by the adapter, not by Shaka. shaka.util.Id3Utils has no GEOB decoder, so Shaka reports such frames with an empty description, a null MIME type and the whole undecoded frame body as data. The adapter parses that body itself so the cue carries the real description (Anvatos), mimeType (application/json) and payload (type=cue&pts=…). Players that already decode GEOB are passed through untouched.
• Anvato cues must be seen before their media time. An Anvato cue's media time is the break start, so a playhead-time-only subscription would learn it too late to arm and preload the break. Subscribing to metadataadded gives the adapter the same parse-time delivery HLS.js has.

Structural typing — no hard import on shaka-player

The ShakaAdapter constructor accepts any object that satisfies the ShakaPlayerLike interface exported from the package. The real shaka.Player satisfies this interface, but you can also pass a compatible mock in tests without importing the full Shaka library.

Cleanup

// When the player is torn down:
sdk.destroy();    // also destroys the internal ad player
await player.destroy();

THEOplayer Adapter

The official THEOplayer adapter is available as a separate package. Unlike HLS.js and Shaka, THEOplayer manages its own internal <video> element — you pass it a <div> container and it renders into that.

Install

npm install @dolby-ads/adapter-theoplayer theoplayer

Requirements

• THEOplayer v9 or later (peer dependency)
• A valid THEOplayer license key (passed in the player configuration)
• Set libraryLocation to serve THEOplayer's worker/WASM files — use a CDN or copy from node_modules/theoplayer/

Key difference — no raw <video> element

THEOplayer creates and manages its own <video> element inside the container div. The adapter exposes it via the videoElement getter (container.querySelector('video')) for GAM integration.

Full setup example

import { ChromelessPlayer } from 'theoplayer/chromeless';
import { DolbyAds } from '@dolby-ads/core';
import { THEOplayerAdapter } from '@dolby-ads/adapter-theoplayer';

const LICENSE = 'YOUR_THEOPLAYER_LICENSE';
const LIB     = 'https://cdn.jsdelivr.net/npm/theoplayer@11.4.0/';

// 1. Content player — THEOplayer mounts into a <div>
const playerDiv = document.getElementById('player') as HTMLElement;
const player = new ChromelessPlayer(playerDiv, {
  license: LICENSE,
  libraryLocation: LIB,
  allowMixedContent: true,
  mutedAutoplay: 'all',
});
// 2. SDK — playerContainer is optional; SDK auto-wraps when omitted
const sdk = new DolbyAds({
  orgId: 'your-org-id',
  player: new THEOplayerAdapter(player, playerDiv),
  container: document.getElementById('container'),
  createAdAdapter: (adContainer) => {
    const adPlayer = new ChromelessPlayer(adContainer, {
      license: LICENSE,
      libraryLocation: LIB,
      allowMixedContent: true,
      mutedAutoplay: 'all',
    });
    return new THEOplayerAdapter(adPlayer, adContainer);
  },
});

// 3. Start session and load stream
await sdk.startSession({ channelId: 'your-channel-id' });
player.source = { sources: [{ src: 'https://example.com/live.m3u8' }] };
player.play();

Autoplay configuration

The ad player's play() is triggered by the SDK's break scheduler — always outside a user gesture. Set mutedAutoplay: 'all' in the ChromelessPlayer config for both the content and ad player instances. This tells THEOplayer to permit autoplay regardless of browser policy.

PDT (Program Date Time)

The THEOplayer adapter reads player.currentProgramDateTime directly — THEOplayer exposes the wall-clock position as a Date on that property for live HLS/DASH streams. No custom manifest parsing is needed.

Cleanup

sdk.destroy();    // also destroys the internal ad player
player.destroy();

Native / Safari & iOS (NativeVideoAdapter)

@dolby-ads/sdk ships a NativeVideoAdapter backed by a plain HTMLVideoElement. The default ad player (a RoutingAdAdapter) chooses its playback technology from the ad creative, not from Hls.isSupported() alone — so it uses NativeVideoAdapter in two cases:

• a progressive STATIC creative (MP4/WebM/…) — routed to native <video> even on MSE browsers where HLS.js is available, because HLS.js can only parse HLS playlists (feeding it an MP4 fails with manifestParsingError);
• any creative on platforms without a Media Source engine (Hls.isSupported() === false), notably iPhone/iPod on iOS < 17.1 and older iOS/tvOS WebViews, which play HLS natively via video.src.

An HLS playlist creative (.m3u8 / application/vnd.apple.mpegurl) goes through the HlsJsAdapter when HLS.js is supported. The technology is decided at load() time from the URL extension, with a Content-Type HEAD probe for extensionless URLs (e.g. GAM pod manifests, which stay on HLS.js); anything that can't be classified defaults to HLS.js.

iOS 17.1+ uses HLS.js for HLS creatives. Apple's Managed Media Source (MMS) is available on iPhone from iOS 17.1, so Hls.isSupported() returns true and HLS playlist creatives play through the HlsJsAdapter (full ABR, quality/track selection, precise buffering); progressive MP4 creatives still use NativeVideoAdapter. On older iOS and other MSE-less runtimes everything falls back to NativeVideoAdapter.

// Inside @dolby-ads/sdk's default ad adapter, per creative at load() time:
const tech = selectAdTech(url); // 'native' | 'hls' (extension, then Content-Type)
if (tech === 'hls' && Hls.isSupported()) {
  // → HlsJsAdapter (MSE) for HLS playlists
} else {
  // → NativeVideoAdapter (progressive MP4/WebM, or native HLS fallback)
}

You normally never construct it directly — use @dolby-ads/sdk and it is selected for you. Import it explicitly only if you build a custom factory:

import { NativeVideoAdapter } from '@dolby-ads/sdk';

Demo content player (PLAYG-36). The same NativeVideoAdapter also backs the demo's "Native HLS" content player option. The demo auto-selects it for the content <video> whenever Hls.isSupported() is false (the MSE-less tail: iPhone Safari < 17.1, older iOS/tvOS WebViews) so content still plays via video.src; on MSE/MMS-capable runtimes hls.js stays the default. You can also force it via the ?player=native URL param to exercise the native path on an MSE-capable browser such as macOS Safari.

PDT (Program Date Time)

Wallclock break matching is supported on native HLS: NativeVideoAdapter derives programDateTime from WebKit's non-standard HTMLVideoElement.getStartDate() (the presentation origin's wallclock) plus currentTime, mirroring how the HLS.js adapter computes it. It returns null only on engines without getStartDate() or when the date is invalid — in which case wallclock matching is unavailable for that stream.

iPhone / iPod: adaptive & shared-element insertion

On iPhone/iPod, adInsertion: 'auto' (the default) resolves based on Managed Media Source availability:

• iOS 17.1+ (MMS present) → adaptive. Playback runs through HLS.js/MMS, so the SDK uses the full overlay compositor (all break formats) while the content video is inline, and falls back to a single fullscreen shared-element ad only while the content video is in OS-native fullscreen (where DOM overlays cannot render). The mode is re-evaluated per break from the content video's webkitDisplayingFullscreen state / webkitbeginfullscreen/webkitendfullscreen events.
• iOS < 17.1 (no MMS) → shared-element. The ad plays through the content <video> rather than a separate ad element; advanced formats are downgraded to a single fullscreen ad and lshape_content is skipped.

See SDK Configuration → Ad insertion behaviour.

AirPlay note: MMS sets disableRemotePlayback=true, disabling AirPlay on the SDK-owned ad element (ads are not AirPlayed). If you need AirPlay on your content player, append an HLS <source> element to your own content <video>.

Implementing a Custom Adapter

To use the SDK with Video.js, AVPlayer (iOS), or any other HLS-capable player, implement the PlayerAdapter interface.

TypeScript skeleton

import type {
  PlayerAdapter,
  PlayerAdapterEvent,
  PlayerAdapterEventHandler,
} from '@dolby-ads/core';

export class MyPlayerAdapter implements PlayerAdapter {
  private player: MyPlayer;          // ← your player instance
  private video:  HTMLVideoElement;
  private listeners = new Map<PlayerAdapterEvent, Set<PlayerAdapterEventHandler>>();
  private _programDateTime: Date | null = null;

  constructor(player: MyPlayer, videoElement: HTMLVideoElement) {
    this.player = player;
    this.video  = videoElement;
    this.setupListeners();
  }

  // ── Required properties ──────────────────

  get currentTime()  { return this.video.currentTime; }
  get duration()     { return this.video.duration; }
  get paused()       { return this.video.paused; }
  get muted()        { return this.video.muted; }
  set muted(v)       { this.video.muted = v; }
  get volume()       { return this.video.volume; }
  set volume(v)      { this.video.volume = v; }

  get programDateTime(): Date | null {
    // Track EXT-X-PROGRAM-DATE-TIME from your player's manifest events
    return this._programDateTime;
  }

  // ── Required methods ─────────────────────

  pause(): void {
    this.video.pause();
  }

  async play(): Promise<void> {
    await this.video.play();
  }

  seek(time: number): void {
    this.video.currentTime = time;   // adapt to your player's seek API if needed
  }

  /** Load URL — resolve when manifest is parsed and player is ready to play. */
  async load(url: string): Promise<void> {
    return new Promise((resolve, reject) => {
      this.player.once('manifestparsed', resolve);   // adapt to your player's event
      this.player.once('error', reject);
      this.player.load(url);
    });
  }

  on(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler): void {
    if (!this.listeners.has(event)) this.listeners.set(event, new Set());
    this.listeners.get(event)!.add(handler);
  }

  off(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler): void {
    this.listeners.get(event)?.delete(handler);
  }

  destroy(): void {
    this.listeners.clear();
    // Remove any event listeners added in setupListeners()
  }

  // ── Internal helpers ─────────────────────

  private emit(event: PlayerAdapterEvent, data?: unknown): void {
    this.listeners.get(event)?.forEach((h) => h(data));
  }

  private setupListeners(): void {
    // Forward native video events to SDK listeners
    this.video.addEventListener('timeupdate',    () => this.emit('timeupdate'));
    this.video.addEventListener('ended',         () => this.emit('ended'));
    this.video.addEventListener('error',         () => this.emit('error'));
    this.video.addEventListener('seeked',        () => this.emit('seeked'));
    this.video.addEventListener('volumechange',  () => this.emit('volumechange'));

    // Track PDT from your player's manifest events
    this.player.on('fragmentchanged', (frag) => {
      if (frag.programDateTime) this._programDateTime = new Date(frag.programDateTime);
    });
  }
}

Validate your adapter

@dolby-ads/adapter-test-kit provides a shared conformance suite so you can prove your adapter satisfies the contract the SDK relies on (event forwarding, state mirroring, seek, destroy cleanup, and optional capabilities). The official HLS.js and Shaka adapters run the same kit.

npm install -D @dolby-ads/adapter-test-kit

// MyPlayerAdapter.conformance.test.ts
import { runAdapterConformance } from '@dolby-ads/adapter-test-kit';
import { MyPlayerAdapter } from './MyPlayerAdapter';

runAdapterConformance('MyPlayerAdapter', {
  // Construct your adapter around the kit-provided <video> element.
  createAdapter: (video) => new MyPlayerAdapter(createMyPlayer(), video),
  // Declare which optional members you implement so the matching checks run.
  capabilities: { videoElement: true, preload: false, parallelBuffering: false },
});

The kit registers its own describe/it blocks, so just call runAdapterConformance(...) at the top level of a test file. By default it makes the underlying source emit each event by dispatching a native Event on the video element; pass a custom emit(video, event) if your player surfaces events differently.

Getting Started

Requirements

• Android minSdk 21 (Android TV supported), compileSdk 34
• Media3 / ExoPlayer 1.4.x
• For Google Ad Manager pod serving: the IMA SDK (com.google.ads.interactivemedia.v3:interactivemedia)

Installation

// build.gradle.kts (app module) — PREVIEW coordinates
dependencies {
    implementation("com.dolby.ads:dolbyads-runtime:<version>")  // ExoPlayerAdapter + OverlayAdRenderer + GAM/IMA
    // dolbyads-runtime re-exports the core + sdk layers transitively.

    implementation("androidx.media3:media3-exoplayer:1.4.1")
    implementation("androidx.media3:media3-ui:1.4.1")
}

Quick start

import androidx.media3.common.MediaItem
import androidx.media3.exoplayer.ExoPlayer
import androidx.media3.ui.PlayerView
import com.dolby.ads.runtime.ExoPlayerAdapter
import com.dolby.ads.runtime.OverlayAdRenderer
import com.dolby.ads.sdk.CoroutineSchedulerTicker
import com.dolby.ads.sdk.DolbyAds
import com.dolby.ads.sdk.DolbyAdsConfig
import com.dolby.ads.sdk.DolbyAdsEventType
import com.dolby.ads.sdk.HttpManifestSource
import com.dolby.ads.sdk.SessionConfig
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.launch

val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)

// 1. Content player — you own the ExoPlayer and attach it to your PlayerView.
val contentPlayer = ExoPlayer.Builder(context).build()
playerView.player = contentPlayer
val contentAdapter = ExoPlayerAdapter(contentPlayer)

// 2. Runtime seams: overlay ad renderer + HTTP manifest source + coroutine ticker.
//    `overlayContainer` is a FrameLayout stacked above your PlayerView.
val renderer       = OverlayAdRenderer(context, overlayContainer, contentAdapter)
val manifestSource = HttpManifestSource(scope)
val ticker         = CoroutineSchedulerTicker(scope)

// 3. Create the SDK.
val sdk = DolbyAds(
    config = DolbyAdsConfig(orgId = "your-org-id", player = contentAdapter, debug = true),
    renderer = renderer,
    manifestSource = manifestSource,
    ticker = ticker,
    scope = scope,
)

// 4. Listen to events.
sdk.addEventListener(DolbyAdsEventType.ADBREAKBEGIN) { e -> Log.d("Ads", "Break started: ${e.breakId}") }
sdk.addEventListener(DolbyAdsEventType.ADBREAKEND)   { e -> Log.d("Ads", "Break ended: ${e.breakId}") }

// 5. Load your content stream and start a monetization session.
contentPlayer.setMediaItem(MediaItem.fromUri("https://example.com/live.m3u8"))
contentPlayer.prepare()
contentPlayer.playWhenReady = true

scope.launch {
    sdk.startSession(SessionConfig(channelId = "your-channel-id"))
}

Ad formats & overlay rendering

OverlayAdRenderer renders every break format. For the overlay format it positions/sizes the ad surface from the manifest position/size/opacity and does not pause the content player (the ad plays on top of playing content); all other formats render full-surface and pause content. Overlay assets with mediaType: "image" are rendered in a ImageView (held for the asset's duration, falling back to the break duration), are preloaded for an instant transition, and on load failure dispatch aderror and are ignored — identical to the web and iOS runtimes. See Ad Formats.

Reading the SDK version

Read the current SDK version from the static DolbyAds.version accessor — no instance required. It is the same lockstep version as the web and iOS SDKs and the stitcher's GET /version.

import com.dolby.ads.sdk.DolbyAds

Log.d("Ads", DolbyAds.version) // e.g. "0.16.0"

Google Ad Manager (pod serving)

Supply a GamConfig to the renderer and a customAssetKey on the session. GAM vendor breaks are served via Google IMA DAI.

import com.dolby.ads.sdk.GamConfig

val gam = GamConfig(networkCode = "23285652104")
val renderer = OverlayAdRenderer(context, overlayContainer, contentAdapter, gamConfig = gam)

val sdk = DolbyAds(
    config = DolbyAdsConfig(orgId = "your-org-id", player = contentAdapter, gam = gam),
    renderer = renderer,
    manifestSource = manifestSource,
    ticker = ticker,
    scope = scope,
)

scope.launch {
    sdk.startSession(SessionConfig(channelId = "your-channel-id", customAssetKey = "your-asset-key"))
}

Existing Adapter — ExoPlayerAdapter

The runtime ships ExoPlayerAdapter, a Media3/ExoPlayer implementation of PlayerAdapter. It wraps an ExoPlayer instance you create and own (attached to your own PlayerView); the SDK drives the content player only through this adapter, keeping the brain player-agnostic.

import com.dolby.ads.runtime.ExoPlayerAdapter

val contentPlayer = ExoPlayer.Builder(context).build()
val contentAdapter = ExoPlayerAdapter(contentPlayer)
// → pass as DolbyAdsConfig.player (and to OverlayAdRenderer).

PlayerAdapter Interface

Any content player is integrated by implementing PlayerAdapter from com.dolby.ads.core. Unlike the web adapter (whose load/play return Promises), the Kotlin load/play are synchronous — they kick off preparation/playback and return immediately; readiness and completion are signalled via PlayerAdapterEvents.

package com.dolby.ads.core

/** Event types a PlayerAdapter must forward. */
enum class PlayerAdapterEvent(val value: String) {
    TIMEUPDATE("timeupdate"),
    ENDED("ended"),
    ERROR("error"),
    SEEKED("seeked"),
    VOLUMECHANGE("volumechange"),
    WAITING("waiting"),
    PLAYING("playing"),
}

/** Handler payload carries adapter-specific detail (e.g. a media error). */
typealias PlayerAdapterEventHandler = (event: Any?) -> Unit

interface PlayerAdapter {
    /** Current playback time in seconds. */
    val currentTime: Double

    /** Total content duration in seconds; Double.POSITIVE_INFINITY for live. */
    val duration: Double

    /** Whether the player is currently paused. */
    val paused: Boolean

    /** Muted state. Settable so the SDK can sync content↔ad mute. */
    var muted: Boolean

    /** Volume in [0, 1]. Settable so the SDK can sync content↔ad volume. */
    var volume: Double

    /** Program Date Time (EXT-X-PROGRAM-DATE-TIME) as epoch milliseconds,
     *  for wallclock-timebase break matching. Null when unavailable. */
    val programDateTime: Long?

    /** Pause playback (called when an ad break starts). */
    fun pause()

    /** Resume playback (called when an ad break ends). Returns immediately. */
    fun play()

    /** Seek to time seconds (used for snapback during locked breaks). */
    fun seek(time: Double)

    /** Load a media source without committing to immediate playback. */
    fun load(url: String)

    /** Optional: warm caches WITHOUT engaging a decoder (single-decoder preload). */
    fun preload(url: String) {}

    /** Optional capability hint: can this adapter buffer a second source in
     *  parallel without decoder contention? Null is treated as true. */
    val supportsParallelBuffering: Boolean?
        get() = null

    /** Subscribe to a player event. */
    fun on(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler)

    /** Unsubscribe a previously registered handler. */
    fun off(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler)

    /** Clean up resources (called when the SDK is destroyed). */
    fun destroy()
}

Implementing a Custom Adapter

To use the SDK with a different player, implement PlayerAdapter and forward your player's callbacks to the SDK event handlers.

import com.dolby.ads.core.PlayerAdapter
import com.dolby.ads.core.PlayerAdapterEvent
import com.dolby.ads.core.PlayerAdapterEventHandler

class MyPlayerAdapter(private val player: MyPlayer) : PlayerAdapter {

    private val handlers = mutableMapOf<PlayerAdapterEvent, MutableSet<PlayerAdapterEventHandler>>()

    init {
        // Forward your player's callbacks to the SDK.
        player.onPositionChanged { dispatch(PlayerAdapterEvent.TIMEUPDATE) }
        player.onEnded          { dispatch(PlayerAdapterEvent.ENDED) }
        player.onError          { err -> dispatch(PlayerAdapterEvent.ERROR, err) }
        player.onSeeked         { dispatch(PlayerAdapterEvent.SEEKED) }
        player.onVolumeChanged  { dispatch(PlayerAdapterEvent.VOLUMECHANGE) }
    }

    // ── Required properties ──────────────────
    override val currentTime: Double get() = player.positionMs / 1000.0
    override val duration: Double get() = if (player.isLive) Double.POSITIVE_INFINITY else player.durationMs / 1000.0
    override val paused: Boolean get() = !player.isPlaying

    override var muted: Boolean
        get() = player.volume == 0f
        set(value) { player.volume = if (value) 0f else 1f }

    override var volume: Double
        get() = player.volume.toDouble()
        set(value) { player.volume = value.coerceIn(0.0, 1.0).toFloat() }

    override val programDateTime: Long?
        get() = player.currentProgramDateEpochMs   // null for VOD / no PDT

    // ── Required methods ─────────────────────
    override fun pause() = player.pause()
    override fun play()  = player.play()
    override fun seek(time: Double) { player.seekTo((time * 1000).toLong()) }
    override fun load(url: String)  { player.setSource(url); player.prepare() }

    override fun on(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler) {
        handlers.getOrPut(event) { mutableSetOf() }.add(handler)
    }

    override fun off(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler) {
        handlers[event]?.remove(handler)
    }

    override fun destroy() {
        handlers.clear()
        // Remove any listeners registered on `player`.
    }

    private fun dispatch(event: PlayerAdapterEvent, payload: Any? = null) {
        handlers[event]?.toList()?.forEach { it(payload) }
    }
}

Getting Started

Requirements

• iOS / tvOS 15+ (the runtime depends on the Google IMA SDK, which requires 15+)
• AVFoundation / AVPlayer
• For Google Ad Manager pod serving: GoogleInteractiveMediaAds

Installation

// Package.swift — Swift Package Manager (PREVIEW)
dependencies: [
    .package(url: "https://github.com/dolby/dolby-ads-ios.git", from: "<version>"),
],
targets: [
    .target(name: "MyApp", dependencies: [
        .product(name: "DolbyAdsRuntime", package: "dolby-ads-ios"),
    ]),
]

# Podfile — CocoaPods (PREVIEW)
pod 'DolbyAdsRuntime', '~> <version>'

Quick start

import AVFoundation
import DolbyAdsRuntime   // re-exports DolbyAdsCore + DolbyAdsSDK

// 1. Content player — you own the AVPlayer and render it (AVPlayerLayer / AVPlayerViewController).
let contentPlayer = AVPlayer()
playerLayer.player = contentPlayer
let contentAdapter = AVPlayerAdapter(player: contentPlayer)

// 2. Runtime seams: overlay ad renderer + Foundation manifest source + dispatch ticker.
//    `overlayContainer` is a UIView stacked above your content surface.
let renderer = OverlayAdRenderer(overlayContainer: overlayContainer, contentPlayer: contentAdapter)

// 3. Create the SDK.
let sdk = DolbyAds(
    config: DolbyAdsConfig(orgId: "your-org-id", player: contentAdapter, debug: true),
    renderer: renderer,
    manifestSource: URLSessionManifestSource(),
    ticker: DispatchSchedulerTicker()
)

// 4. Listen to events (addEventListener returns a token for removeEventListener).
sdk.addEventListener(.adbreakbegin) { event in print("Break started:", event.breakId ?? "") }
sdk.addEventListener(.adbreakend)   { event in print("Break ended:", event.breakId ?? "") }

// 5. Load your content stream and start a monetization session.
if let url = URL(string: "https://example.com/live.m3u8") {
    contentPlayer.replaceCurrentItem(with: AVPlayerItem(url: url))
    contentPlayer.play()
}

Task {
    do {
        try await sdk.startSession(SessionConfig(channelId: "your-channel-id"))
    } catch {
        print("startSession failed:", error)
    }
}

Ad formats & overlay rendering

OverlayAdRenderer renders every break format. For the overlay format it positions/sizes the ad surface from the manifest position/size/opacity and does not pause the content player (the ad plays on top of playing content); all other formats render full-surface and pause content. Overlay assets with mediaType: "image" are rendered in a UIImageView (held for the asset's duration, falling back to the break duration), are preloaded for an instant transition, and on load failure dispatch aderror and are ignored — identical to the web and Android runtimes. See Ad Formats.

Reading the SDK version

Read the current SDK version from the static DolbyAds.version property — no instance required. It is the same lockstep version as the web and Android SDKs and the stitcher's GET /version.

print(DolbyAds.version) // e.g. "0.16.0"

Google Ad Manager (pod serving)

Supply a GamConfig to the renderer and a customAssetKey on the session. GAM vendor breaks are served via Google IMA DAI.

let gam = GamConfig(networkCode: "23285652104")
let renderer = OverlayAdRenderer(overlayContainer: overlayContainer, contentPlayer: contentAdapter, gamConfig: gam)

let sdk = DolbyAds(
    config: DolbyAdsConfig(orgId: "your-org-id", player: contentAdapter, gam: gam),
    renderer: renderer,
    manifestSource: URLSessionManifestSource(),
    ticker: DispatchSchedulerTicker()
)

Task {
    try await sdk.startSession(SessionConfig(channelId: "your-channel-id", customAssetKey: "your-asset-key"))
}

Existing Adapter — AVPlayerAdapter

The runtime ships AVPlayerAdapter, an AVFoundation implementation of PlayerAdapter. It wraps an AVPlayer you create and own (rendered in your own layer / AVPlayerViewController); the SDK drives the content player only through this adapter, keeping the brain player-agnostic.

import DolbyAdsRuntime

let contentPlayer = AVPlayer()
let contentAdapter = AVPlayerAdapter(player: contentPlayer)
// → pass as DolbyAdsConfig.player (and to OverlayAdRenderer).

PlayerAdapter Protocol

Any content player is integrated by conforming to PlayerAdapter from DolbyAdsCore. Subscriptions are tracked by an opaque PlayerEventToken (Swift closures are not identity-comparable), so on(_:_:) returns a token you pass to off(_:).

/// Event types a PlayerAdapter forwards.
public enum PlayerAdapterEvent: String {
    case timeupdate, ended, error, seeked, volumechange, waiting, playing
}

/// Handler payload carries adapter-specific detail (e.g. a media error).
public typealias PlayerAdapterEventHandler = (Any?) -> Void

/// Opaque token so a specific handler can later be removed via `off(_:)`.
public final class PlayerEventToken { public init() {} }

public protocol PlayerAdapter: AnyObject {
    /// Current playback time in seconds.
    var currentTime: Double { get }

    /// Total content duration in seconds; `.infinity` for live.
    var duration: Double { get }

    /// Whether the player is currently paused.
    var paused: Bool { get }

    /// Muted state. Settable so the SDK can sync content↔ad mute.
    var muted: Bool { get set }

    /// Volume in [0, 1]. Settable so the SDK can sync content↔ad volume.
    var volume: Double { get set }

    /// Program Date Time (EXT-X-PROGRAM-DATE-TIME) as epoch milliseconds,
    /// for wallclock-timebase break matching. Nil when unavailable.
    var programDateTime: Int64? { get }

    func pause()                  // called when an ad break starts
    func play()                   // called when an ad break ends
    func seek(_ time: Double)     // used for snapback during locked breaks
    func load(_ url: String)      // load without committing to immediate playback

    /// Optional: warm caches without engaging a decoder (single-decoder preload).
    func preload(_ url: String)

    /// Optional capability hint: can this adapter buffer a second source in
    /// parallel without decoder contention? Nil is treated as true.
    var supportsParallelBuffering: Bool? { get }

    /// Subscribe to a player event; returns a token for `off(_:)`.
    @discardableResult
    func on(_ event: PlayerAdapterEvent, _ handler: @escaping PlayerAdapterEventHandler) -> PlayerEventToken

    /// Unsubscribe a previously registered handler by its token.
    func off(_ token: PlayerEventToken)

    /// Clean up resources (called when the SDK is destroyed).
    func destroy()
}

// `preload` and `supportsParallelBuffering` have default implementations.
public extension PlayerAdapter {
    func preload(_ url: String) {}
    var supportsParallelBuffering: Bool? { nil }
}

Implementing a Custom Adapter

To use the SDK with a different player, conform to PlayerAdapter and forward your player's callbacks to the SDK event handlers.

import DolbyAdsCore

final class MyPlayerAdapter: PlayerAdapter {

    private let player: MyPlayer
    private var handlers: [PlayerAdapterEvent: [ObjectIdentifier: PlayerAdapterEventHandler]] = [:]

    init(player: MyPlayer) {
        self.player = player
        // Forward your player's callbacks to the SDK.
        player.onPositionChanged = { [weak self] in self?.dispatch(.timeupdate) }
        player.onEnded           = { [weak self] in self?.dispatch(.ended) }
        player.onError           = { [weak self] err in self?.dispatch(.error, err) }
        player.onSeeked          = { [weak self] in self?.dispatch(.seeked) }
        player.onVolumeChanged   = { [weak self] in self?.dispatch(.volumechange) }
    }

    // ── Required properties ──────────────────
    var currentTime: Double { player.positionSeconds }
    var duration: Double { player.isLive ? .infinity : player.durationSeconds }
    var paused: Bool { !player.isPlaying }

    var muted: Bool {
        get { player.volume == 0 }
        set { player.volume = newValue ? 0 : 1 }
    }

    var volume: Double {
        get { Double(player.volume) }
        set { player.volume = Float(max(0, min(1, newValue))) }
    }

    var programDateTime: Int64? { player.currentProgramDateEpochMs }   // nil for VOD / no PDT

    // ── Required methods ─────────────────────
    func pause() { player.pause() }
    func play()  { player.play() }
    func seek(_ time: Double) { player.seek(toSeconds: time) }
    func load(_ url: String)  { if let u = URL(string: url) { player.setSource(u) } }

    @discardableResult
    func on(_ event: PlayerAdapterEvent, _ handler: @escaping PlayerAdapterEventHandler) -> PlayerEventToken {
        let token = PlayerEventToken()
        handlers[event, default: [:]][ObjectIdentifier(token)] = handler
        return token
    }

    func off(_ token: PlayerEventToken) {
        let key = ObjectIdentifier(token)
        for event in handlers.keys { handlers[event]?.removeValue(forKey: key) }
    }

    func destroy() {
        handlers.removeAll()
        // Remove any observers registered on `player`.
    }

    private func dispatch(_ event: PlayerAdapterEvent, _ payload: Any? = nil) {
        handlers[event]?.values.forEach { $0(payload) }
    }
}

Web

DolbyAdsConfig constructor

Ad preload behaviour (adPreload)

Controls how the next ad is prepared before a break starts.

Ad insertion behaviour (adInsertion)

Controls how the ad is composited relative to the content player.

Consecutive-break chaining (chaining)

Some channels schedule two (or more) breaks back to back — for example two breaks with different ad targeting parameters separated by a ~1s gap. Without chaining, each break ends independently: content briefly resumes, the layout animates back to fullscreen, then the next break re-pauses content and re-applies its layout — a visible flash, often followed by a spinner while the next ad loads.

With chaining enabled (the default), breaks whose gap is ≤ maxGapSeconds are played as one continuous ad sequence:

• The ad overlay is held across the gap — content is never resumed and the layout is not torn down (no flash).
• The next break's first (static) asset is preloaded during the current break (HTTP cache warm + a detached prefetch), so it starts without a spinner. This never attaches a second MediaSource, so it is safe on single-decoder Smart TVs.
• Each break still emits its own adbreakbegin / adbreakend events and resolves its own targeting, so analytics and per-break ad requests are unchanged.

const sdk = new DolbyAds({
  // ...
  chaining: { enabled: true, maxGapSeconds: 2 },
});

Tune-in / join-in-progress (tuneIn)

Live viewers rarely join exactly at a break boundary — they often tune in while an ad break is already playing. By default the SDK detects this and presents the break for the time that remains, rather than skipping it entirely (the legacy behaviour, which left the join-in-progress window unmonetised).

With tune-in enabled (the default), when the SDK first observes a break that has already started:

• If at least minBreakDurationSeconds of the break remain, the break is triggered for its remaining duration. The adbreakbegin event carries a tuneIn: { elapsedSec, remainingSec } payload, and the break-cut timer ends the break at the real break boundary (not start + full duration).
• For GAM pod serving, the pod request is built for the remaining duration, so the ad server returns a pod that fits the time left.
• If less than minBreakDurationSeconds remain, the break is not triggered (no partial sliver of an ad is shown, and it is not monetised).

const sdk = new DolbyAds({
  // ...
  tuneIn: { enabled: true, minBreakDurationSeconds: 5 },
});

SSAI mode (mode: 'ssai')

By default the SDK runs SGAI (client-scheduled) insertion. Set mode: 'ssai' to switch to server-side ad insertion: the SDK plays a single pre-stitched stream from the @dolby-ads/stitcher service on the content player. It does not poll a break manifest, schedule breaks, or run an ad-player overlay. Instead it:

1. creates the IMA DAI stream (for a stream_id),
2. builds the stitcher master URL and loads it into the content player,
3. forwards in-stream timedmetadata cues to IMA for ad tracking, and
4. re-emits the usual ad-event stream (adbreakbegin / adbegin / quartiles / adend / adbreakend).

const sdk = new DolbyAds({
  mode: 'ssai',
  orgId: 'your-org-id',
  player: new HlsJsAdapter(hls, video), // must expose videoElement (IMA binds to it)
  stitcherBaseUrl: 'https://stitch.example.com',
  gam: { networkCode: '23285652104' },
  maxBitrate: 2000000, // optional — caps rendition bitrate (max_bitrate on the master URL)
  autoplay: true, // optional — SDK plays the stitched stream after load
});

// The SDK loads the stitched master itself — do not load a content URL.
await sdk.startSession({ channelId: 'your-channel-id', customAssetKey: 'asset-key' });

Manifest interception (interceptManifestRequest / interceptManifestResponse)

Two optional SGAI hooks bracket the manifest fetch:

• interceptManifestRequest runs before the network call (initial fetch + every poll). Return a ManifestRequest to redirect the URL or add headers, a ManifestMockResponse to short-circuit the network with a raw body (parsed + validated normally), or nothing to fetch unchanged. A throw is non-fatal (DA-MANIFEST-REQUEST-INTERCEPT-FAILED, falls back to the network fetch). Primarily a testing aid (mock/redirect without a proxy).
• interceptManifestResponse runs after fetch + validation, handing you the parsed, validated BreakManifest so you can transform it — inject a pre-roll, drop a break, rewrite an asset URL — before it is scheduled. The return value is used as-is; a throw is non-fatal (DA-MANIFEST-INTERCEPT-FAILED, falls back to the unmodified manifest).

Full guarantees, code examples, and the Android/iOS equivalents are documented under Manifest interception on the Break Manifest page.

SessionConfig startSession()

GamConfig optional

Example

const sdk = new DolbyAds({
  orgId: '0bda787b-b10a-4e9e-a5f2-c0952d1b8a88',
  player: new HlsJsAdapter(hls, video),
  container: document.getElementById('container'),
  playerContainer: document.getElementById('playerContainer'),
  createAdAdapter: (adContainer) => {
    const adVideo = document.createElement('video');
    adContainer.appendChild(adVideo);
    const adHls = new Hls();
    adHls.attachMedia(adVideo);
    return new HlsJsAdapter(adHls, adVideo);
  },
  gam: {
    networkCode: '23285652104',
    adTagParameters: { ott_placement: '0' }, // org-level defaults
    streamActivityMonitorId: 'my-debug-session',
  },
  debug: false,
});

Simplified setup with @dolby-ads/sdk

Import DolbyAds from @dolby-ads/sdk to drop the createAdAdapter boilerplate — the ad player defaults to HLS.js (with a native <video> fallback). Use adPreload: 'auto' to enable single-decoder preloading on Smart TVs.

import { DolbyAds, HlsJsAdapter } from '@dolby-ads/sdk';

const sdk = new DolbyAds({
  orgId: '0bda787b-b10a-4e9e-a5f2-c0952d1b8a88',
  player: new HlsJsAdapter(hls, video),
  container: document.getElementById('container'),
  // createAdAdapter omitted -> default HLS.js ad player (native fallback)
  adPreload: 'auto',
});

Android (Kotlin)

DolbyAdsConfig (com.dolby.ads.sdk) carries the org-level options. The web-only DOM fields (container, playerContainer, createAdAdapter) do not exist on Android — the ad surface is owned by the OverlayAdRenderer you pass to the DolbyAds constructor (its overlayContainer FrameLayout is the Android equivalent of container).

SessionConfig(channelId, customAssetKey? = null, adTagParameters = emptyMap()) and GamConfig(networkCode, adTagParameters = emptyMap(), streamActivityMonitorId? = null) mirror the web shapes.

import com.dolby.ads.sdk.*

val sdk = DolbyAds(
    config = DolbyAdsConfig(
        orgId = "0bda787b-b10a-4e9e-a5f2-c0952d1b8a88",
        player = ExoPlayerAdapter(contentPlayer),
        adPreload = AdPreloadMode.PARALLEL,
        chaining = ChainingConfig(enabled = true, maxGapSeconds = 2.0),
        tuneIn = TuneInConfig(enabled = true, minBreakDurationSeconds = 5.0),
        diagnostics = DiagnosticsConfig(bufferSize = 200),
        gam = GamConfig(
            networkCode = "23285652104",
            adTagParameters = mapOf("ott_placement" to "0"),   // org-level defaults
            streamActivityMonitorId = "my-debug-session",
        ),
        debug = false,
    ),
    renderer = OverlayAdRenderer(context, overlayContainer, contentAdapter, gamConfig = gam),
    manifestSource = HttpManifestSource(scope),
    ticker = CoroutineSchedulerTicker(scope),
)

iOS / tvOS (Swift)

DolbyAdsConfig (DolbyAdsSDK, re-exported by DolbyAdsRuntime) carries the org-level options. As on Android, the web-only DOM fields are omitted — the ad surface is owned by the OverlayAdRenderer (its overlayContainer UIView).

SessionConfig(channelId:customAssetKey:adTagParameters:) and GamConfig(networkCode:adTagParameters:streamActivityMonitorId:) mirror the web shapes.

import DolbyAdsRuntime

let gam = GamConfig(
    networkCode: "23285652104",
    adTagParameters: ["ott_placement": "0"],          // org-level defaults
    streamActivityMonitorId: "my-debug-session"
)

let sdk = DolbyAds(
    config: DolbyAdsConfig(
        orgId: "0bda787b-b10a-4e9e-a5f2-c0952d1b8a88",
        player: AVPlayerAdapter(player: contentPlayer),
        adPreload: .parallel,
        chaining: ChainingConfig(enabled: true, maxGapSeconds: 2.0),
        tuneIn: TuneInConfig(enabled: true, minBreakDurationSeconds: 5.0),
        diagnostics: DiagnosticsConfig(bufferSize: 200),
        debug: false,
        gam: gam
    ),
    renderer: OverlayAdRenderer(overlayContainer: overlayContainer, contentPlayer: contentAdapter, gamConfig: gam),
    manifestSource: URLSessionManifestSource(),
    ticker: DispatchSchedulerTicker()
)

Web

startSession(config: SessionConfig): Promise<void>

Starts manifest polling and (if GAM is configured) initializes the IMA stream session. Resolves when the first manifest has been fetched successfully.

await sdk.startSession({
  channelId: 'd7803a87-465a-4e43-b12e-6f479be119a1',
  customAssetKey: 'my-asset-key',
  adInsertionType: 'replacement', // 'replacement' (DAR, default) | 'insertion' (DAI)
  adTagParameters: { cust_params: 'genre=sports' },
});
// Now load and play your content
hls.loadSource(contentUrl);
video.play();

Immediate pre-rolls hold content automatically. When the first manifest contains a content-covering pre-roll (position: 'pre') with no delay (or delay: 0), the SDK holds the content player at session start — pausing it and re-pausing if your own play() (above) starts it — so no content frames are shown before the ad. The hold is released the moment the pre-roll begins (the break then owns content pause/resume) and on endSession(). A delay > 0 pre-roll plays content first, as configured. Reported via the DA-PREROLL-CONTENT-HELD diagnostic.

adInsertionType (DAR vs DAI, SGAI only). Controls how a break relates to the content timeline. replacement (DAR, the default) keeps the historical resume behaviour — the replaced content window is skipped only when a break carries an explicit resumeOffset. This is intended, not a bug: without a manifest resumeOffset, DAR resumes content from the same position the break started at (the classic "replace this window of content with an ad, then continue from where it left off" model); set resumeOffset on the break when you want DAR to skip forward past the replaced window. insertion (DAI) resumes content at the exact pre-break position. A break's manifest resumeOffset overrides the mode default in both cases. Resume-seek is applied on the pts (VOD) timebase for content-pausing break formats; it is ignored in SSAI mode (the stitcher controls insertion server-side, reported via the DA-INSERTION-TYPE-IGNORED-SSAI diagnostic). The demo's Ad Insertion Type selector drives this (and the ?adInsertionType= URL param). The dedicated VOD (DAR/DAI) demo page lets you contrast the two against your own VOD asset and break manifest: pick DAR or DAI, paste a PTS mid-roll manifest (provisioned via the break-manifest server — the hosted one on the deployed demo, or a local one under npm run dev), and watch the resume behaviour differ on break end.

endSession(): void

Stops manifest polling and resets the GAM session. Call this when the user navigates away, changes channel, or stops playback.

sdk.endSession();

updateAdTagParameters(params: Record<string, string>): void

Replaces the active GAM session's ad tag parameters in real time. Useful for updating targeting (e.g. sport segment changes) without restarting the session. The new parameters are merged with the base config params.

sdk.updateAdTagParameters({ cust_params: 'sport=basketball' });

destroy(): void

Tears down the entire SDK instance, releasing all resources. Call this when the player is unmounted.

sdk.destroy();

play(): Promise<void>

Proxy for contentPlayer.play(). Suppressed automatically during content-locking ad breaks (e.g. single format) so the ad is not interrupted. Prefer this over calling your player directly so break policies are honoured.

await sdk.play();

pause(): void

Proxy for contentPlayer.pause(). No-op during a content-locking ad break.

sdk.pause();

seek(time: number): void

Seek the content stream to a position in seconds. Blocked when the active break has controls.snapback: true. The SDK also listens to the native seeked event from the PlayerAdapter and will snap back automatically even if the customer seeks directly on the underlying player.

sdk.seek(180); // seek to 3:00 in the content stream

muted: boolean

Unified mute state. Reading or writing sdk.muted always targets whichever player is currently audible — the ad player while a break is playing, the content player otherwise — so a single mute control works correctly across break transitions in both directions. Setting it also bridges into IMA for a VAST/CSAI ad in progress, since IMA drives its own audio path independently of the underlying <video> element.

sdk.muted = true; // mute whatever is currently playing
const isMuted = sdk.muted;

volume: number

Unified volume (0-1). Same effective-player targeting as muted above.

sdk.volume = 0.5;

Event: volumechange

Fires whenever the unified mute/volume state changes — via the muted/volume setters above, a direct mutation of the content or ad element that the SDK's internal sync picked up, or an IMA CSAI ad's own UI. Carries the resulting muted/volume values so a UI can keep a mute button's label correct without polling:

muteButton.onclick = () => {
  sdk.muted = !sdk.muted;
};
sdk.addEventListener('volumechange', (e) => {
  muteButton.textContent = e.muted ? 'Unmute' : 'Mute';
});

Lifecycle example

// App startup
const sdk = new DolbyAds({ ... });

// User starts watching a channel
await sdk.startSession({ channelId, customAssetKey });
hls.loadSource(channelUrl);

// User switches to another channel
sdk.endSession();
await sdk.startSession({ channelId: newChannelId, customAssetKey: newKey });
hls.loadSource(newChannelUrl);

// App teardown
sdk.destroy();

Android (Kotlin)

The lifecycle methods mirror the web API. startSession is a suspend function (call it from a coroutine); the rest are synchronous. The method set is startSession / endSession / updateAdTagParameters / play / pause / seek / destroy, plus isSessionActive() / isAdPlaying().

// User starts watching a channel
scope.launch {
    sdk.startSession(
        SessionConfig(
            channelId = "d7803a87-465a-4e43-b12e-6f479be119a1",
            customAssetKey = "my-asset-key",
            adTagParameters = mapOf("cust_params" to "genre=sports"),
        ),
    )
    contentPlayer.setMediaItem(MediaItem.fromUri(channelUrl))
    contentPlayer.prepare()
    contentPlayer.playWhenReady = true
}

// Update targeting mid-session (no restart)
sdk.updateAdTagParameters(mapOf("cust_params" to "sport=basketball"))

// Switch channel
sdk.endSession()
scope.launch { sdk.startSession(SessionConfig(channelId = newChannelId, customAssetKey = newKey)) }

// Teardown (then release your ExoPlayer)
sdk.destroy()

iOS / tvOS (Swift)

startSession is async throws (call it from a Task); the rest are synchronous. Same method set as Android.

// User starts watching a channel
Task {
    do {
        try await sdk.startSession(
            SessionConfig(
                channelId: "d7803a87-465a-4e43-b12e-6f479be119a1",
                customAssetKey: "my-asset-key",
                adTagParameters: ["cust_params": "genre=sports"]
            )
        )
        contentPlayer.replaceCurrentItem(with: AVPlayerItem(url: channelUrl))
        contentPlayer.play()
    } catch {
        print("startSession failed:", error)
    }
}

// Update targeting mid-session (no restart)
sdk.updateAdTagParameters(["cust_params": "sport=basketball"])

// Switch channel
sdk.endSession()
Task { try await sdk.startSession(SessionConfig(channelId: newChannelId, customAssetKey: newKey)) }

// Teardown
sdk.destroy()

Web

TypeScript types

// Base — all events extend this
interface DolbyAdsEvent {
  type: string;
  timestamp: number;
}

// Break events
sdk.addEventListener('adbreakbegin', (e: AdBreakBeginEvent) => {
  // e.break.id, e.break.duration, e.break.start
});

// Ad events — one pair per ad, including each creative of a multi-ad GAM pod
sdk.addEventListener('adbegin', (e: AdBeginEvent) => {
  // e.asset.id, e.asset.type, e.adIndex, e.totalAds, e.format ('single' | 'double' | …)
  // e.adId / e.creativeId — IMA's ids, set only for the ads of a GAM pod
  console.log(`Ad ${e.adIndex + 1} of ${e.totalAds}`);
});

// Quartiles carry adIndex/totalAds when the SDK knows which ad they belong to
// (the ads of a GAM pod), so repeated cycles in one pod stay attributable.
sdk.addEventListener('admidpoint', (e: AdMidpointEvent) => {
  trackMidpoint(e.asset.id, e.adIndex, e.totalAds);
});

// Error events — covers both ad and content playback (check e.source)
sdk.addEventListener('aderror', (e: AdErrorEvent) => {
  console.error(`[${e.source}]`, e.error.message);
  // For ad errors the SDK automatically recovers — content will resume
});

// Buffering / playback state — fires for both content and ad (check e.source)
sdk.addEventListener('waiting', (e: WaitingEvent) => {
  if (e.source === 'content') showSpinner();
});
sdk.addEventListener('playing', (e: PlayingEvent) => {
  if (e.source === 'content') hideSpinner();
});

// Ad progress — track ad position to drive a custom progress bar
sdk.addEventListener('adtimeupdate', (e: AdTimeupdateEvent) => {
  const pct = (e.currentTime / e.duration) * 100;
  progressBar.style.width = `${pct}%`;
});

Unsubscribing

const handler = (e) => console.log(e);
sdk.addEventListener('adbreakbegin', handler);
// Later:
sdk.removeEventListener('adbreakbegin', handler);

Building a custom player UI

Replace the browser's native controls with your own UI so you can:

• Hide controls during ad breaks and show a countdown toast instead.
• Route play/pause through the SDK so break policies (content-lock, snapback) are honoured.

Key rules

• Use sdk.play() / sdk.pause() instead of video.play() / video.pause() — the SDK will no-op these during content-locking breaks, preventing the user from accidentally resuming content mid-break.
• Use sdk.seek(time) instead of setting video.currentTime directly — honours snapback enforcement.
• Drive your countdown from adbreakstatus — the SDK emits this event whenever the break state or countdown changes. Use sdk.getAdBreakStatus() at any time for the current status, or subscribe to adbreakstatus for live updates. The status object includes phase ('idle' | 'upcoming' | 'active' | 'complete'), secondsUntilBreak, breakRemainingSec, adsRemaining, adIndex, totalAds, and ticking.
• breakWarnings config controls pre-break warnings. Set breakWarnings: { seconds: [10, 5] } to receive adbreakstatus with phase: 'upcoming' at 10s and 5s before the break.
• Dismiss the countdown on adbreakend — adbreakend fires after all assets in the break have played (or been skipped/errored).

Minimal example

<!-- Remove the native controls attribute -->
<video id="video" muted playsinline></video>

<!-- Custom controls bar (inside the player wrapper) -->
<div id="playerControls" class="player-controls">
  <button id="btnPlay">▶</button>
  <button id="btnMute">🔇</button>
  <button id="btnFullscreen">⤢</button>
</div>

<!-- Break countdown toast (positioned over the player) -->
<div id="breakToast" class="break-toast hidden">
  <span class="toast-badge">AD</span>
  <span id="toastText">Ad break</span>
</div>

sdk.addEventListener('adbreakbegin', (e: AdBreakBeginEvent) => {
  // Hide player controls during the break
  document.getElementById('playerControls')!.classList.remove('visible');
});

sdk.addEventListener('adbreakstatus', (e: AdBreakStatusEvent) => {
  const { status } = e;
  const toast = document.getElementById('breakToast')!;
  const text = document.getElementById('toastText')!;

  if (status.phase === 'upcoming') {
    toast.classList.add('visible');
    text.textContent = `Ad break in ${status.secondsUntilBreak}s`;
    return;
  }

  if (status.phase === 'active') {
    toast.classList.add('visible');
    if (status.ticking && status.breakRemainingSec != null) {
      text.textContent = `Ad break · ${status.breakRemainingSec}s remaining`;
    } else {
      text.textContent = 'Ad break';
    }
    return;
  }

  if (status.phase === 'idle' || status.phase === 'complete') {
    toast.classList.remove('visible');
  }
});

sdk.addEventListener('adbreakend', () => {
  // Dismiss toast and restore controls
  document.getElementById('breakToast')!.classList.remove('visible');
  document.getElementById('playerControls')!.classList.add('visible');
});

// Route play/pause through the SDK
document.getElementById('btnPlay')!.addEventListener('click', () => {
  if (video.paused) sdk.play();
  else sdk.pause();
});

Android (Kotlin)

Subscribe with addEventListener(event: DolbyAdsEventType, handler: (DolbyAdsEvent) -> Unit) and unsubscribe with removeEventListener(event, handler). Events are modelled as a sealed class hierarchy — when (event) narrows to the concrete subtype. Note the property is break_ (Kotlin reserves break), and ad-level events carry assetId: String rather than a rich asset object.

import com.dolby.ads.sdk.*

// Break boundaries
sdk.addEventListener(DolbyAdsEventType.ADBREAKBEGIN) { event ->
    val e = event as AdBreakBeginEvent
    Log.d("Ads", "Break ${e.break_.id} (${e.break_.duration}s)")
}

// Individual ads
sdk.addEventListener(DolbyAdsEventType.ADBEGIN) { event ->
    val e = event as AdBeginEvent
    Log.d("Ads", "Ad ${e.adIndex + 1}/${e.totalAds} — asset ${e.assetId} [${e.format?.value}]")
}

// Errors — covers both ad and content (check source); SDK auto-recovers for ads
sdk.addEventListener(DolbyAdsEventType.ADERROR) { event ->
    val e = event as AdErrorEvent
    Log.e("Ads", "[${e.source.value}] ${e.error.message}")
}

// Buffering / playback state — fires for both content and ad (check source)
sdk.addEventListener(DolbyAdsEventType.WAITING) { event ->
    if ((event as WaitingEvent).source == PlaybackSource.CONTENT) showSpinner()
}

// Ad progress — drive a custom progress bar
sdk.addEventListener(DolbyAdsEventType.ADTIMEUPDATE) { event ->
    val e = event as AdTimeupdateEvent
    progressBar.progress = ((e.currentTime / e.duration) * 100).toInt()
}

// Unsubscribing
val handler: DolbyAdsEventListener = { event -> Log.d("Ads", "$event") }
sdk.addEventListener(DolbyAdsEventType.ADBREAKBEGIN, handler)
// Later:
sdk.removeEventListener(DolbyAdsEventType.ADBREAKBEGIN, handler)

iOS / tvOS (Swift)

addEventListener(_:_:) returns a Subscription token; pass it to removeEventListener(_:_:) to unsubscribe. Events are a Swift enum with associated values — switch to read the payload, or use the convenience accessors event.type / event.timestamp / event.source / event.breakId / event.assetId / event.format.

import DolbyAdsRuntime

// Break boundaries
sdk.addEventListener(.adbreakbegin) { event in
    if case let .adBreakBegin(brk, _, tuneIn, format) = event {
        // `tuneIn` is non-nil when the viewer joined mid-break; `format` is the ad format.
        print("Break \(brk.id) [\(format?.rawValue ?? "?")] (\(brk.duration ?? 0)s)", tuneIn.map { "tune-in, \($0.remainingSec)s left" } ?? "")
    }
}

// Individual ads
sdk.addEventListener(.adbegin) { event in
    if case let .adBegin(_, assetId, adIndex, totalAds, _, format) = event {
        print("Ad \(adIndex + 1)/\(totalAds) — asset \(assetId) [\(format?.rawValue ?? "?")]")
    }
    // Or, regardless of case: event.format
}

// Errors — covers both ad and content (check source); SDK auto-recovers for ads
sdk.addEventListener(.aderror) { event in
    if case let .adError(source, _, _, error, _, _) = event {
        print("[\(source.rawValue)] \(error.localizedDescription)")
    }
}

// Buffering / playback state — fires for both content and ad
sdk.addEventListener(.waiting) { event in
    if event.source == .content { showSpinner() }
}

// Ad progress — drive a custom progress bar
sdk.addEventListener(.adtimeupdate) { event in
    if case let .adTimeUpdate(_, _, currentTime, duration, _, _) = event {
        progressView.progress = Float(currentTime / duration)
    }
}

// Unsubscribing — keep the returned token
let token = sdk.addEventListener(.adbreakbegin) { event in print(event.type.rawValue) }
// Later:
sdk.removeEventListener(.adbreakbegin, token)

Web

Subscribe to diagnostics

sdk.onDiagnostic((d) => {
  console.log(`[${d.level}] ${d.code} — ${d.message}`, d.context);
});

// later
sdk.offDiagnostic(handler);

A DiagnosticEvent has this shape:

interface DiagnosticEvent {
  ts: number; // epoch ms
  level: 'debug' | 'info' | 'warn' | 'error';
  code: string; // stable, e.g. 'DA-MANIFEST-FETCH-FAILED'
  category:
    | 'manifest'
    | 'session'
    | 'break'
    | 'preload'
    | 'gam'
    | 'playback'
    | 'chaining'
    | 'event'
    | 'lifecycle';
  message: string;
  context?: Record<string, unknown>; // never contains secrets
}

Export a shareable report

exportDiagnostics() returns a self-contained, redacted report — the recent diagnostic + event timeline plus a redacted config summary, the SDK version, and the user agent. It contains no secrets: ad tag parameter values are stripped (only hasAdTagParameters is reported).

const report = sdk.exportDiagnostics();
navigator.clipboard.writeText(JSON.stringify(report, null, 2));

This is the single artifact to paste into a support ticket or feed to the AI troubleshooting assistant.

Configuration

The diagnostic ring buffer that backs exportDiagnostics() is bounded. Tune it via the diagnostics config:

new DolbyAds({
  // ...
  diagnostics: { bufferSize: 200 }, // default 200; older records are evicted first
});

Android (Kotlin)

onDiagnostic(handler) / offDiagnostic(handler) subscribe to the stream; exportDiagnostics() returns a redacted DiagnosticReport. The codes, categories, and levels are identical to the table above.

val handler: DiagnosticHandler = { d ->
    Log.d("Ads", "[${d.level}] ${d.code} — ${d.message} ${d.context ?: ""}")
}
sdk.onDiagnostic(handler)

// later
sdk.offDiagnostic(handler)

// Shareable, redacted report for a support ticket / AI tooling
val report = sdk.exportDiagnostics()

DiagnosticEvent (com.dolby.ads.sdk):

data class DiagnosticEvent(
    val ts: Long,                        // epoch ms
    val level: DiagnosticLevel,          // DEBUG | INFO | WARN | ERROR
    val code: String,                    // stable, e.g. "DA-MANIFEST-FETCH-FAILED"
    val category: DiagnosticCategory,    // MANIFEST | SESSION | BREAK | PRELOAD | GAM
                                         // | PLAYBACK | CHAINING | EVENT | LIFECYCLE
    val message: String,
    val context: Map<String, Any?>? = null,   // never contains secrets
)

Tune the ring buffer via DolbyAdsConfig.diagnostics = DiagnosticsConfig(bufferSize = 200).

iOS / tvOS (Swift)

onDiagnostic(_:) returns a Subscription token (pass it to offDiagnostic(_:)); exportDiagnostics() returns a redacted DiagnosticReport.

let token = sdk.onDiagnostic { d in
    print("[\(d.level)] \(d.code) — \(d.message)", d.context ?? [:])
}

// later
sdk.offDiagnostic(token)

// Shareable, redacted report
let report = sdk.exportDiagnostics()

DiagnosticEvent (DolbyAdsSDK):

public struct DiagnosticEvent {
    public let ts: Int64                 // epoch ms
    public let level: DiagnosticLevel    // .debug | .info | .warn | .error
    public let code: String              // stable, e.g. "DA-MANIFEST-FETCH-FAILED"
    public let category: DiagnosticCategory  // .manifest | .session | .break | .preload
                                             // | .gam | .playback | .chaining | .event | .lifecycle
    public let message: String
    public let context: [String: Any]?  // never contains secrets
}

Tune the ring buffer via DolbyAdsConfig(diagnostics: DiagnosticsConfig(bufferSize: 200)).

Web

Why custom controls?

Native browser controls have no awareness of ad breaks. A user could hit pause, seek, or unmute at exactly the wrong moment during a break. Routing all interactions through the SDK prevents this:

Setup

Remove the controls attribute and position your own UI elements inside the player container:

<!-- The SDK stage -->
<div id="container" style="position:relative;">
  <!--
    Provide an explicit playerContainer that wraps ONLY the content player(s)
    (<video>, and <div id="theoPlayerEl"> if you use THEOplayer). The SDK
    resizes/repositions playerContainer into a pip corner during a
    double/L-shape break — your controls and the break toast must live
    OUTSIDE it, as direct siblings on #container, so they keep spanning the
    full stage instead of shrinking into the pip. If you omit playerContainer
    the SDK auto-wraps ALL of #container's children (including your controls)
    into its own internal wrapper, which has the same shrinking problem.
  -->
  <div id="playerContainer" style="position:absolute;inset:0;">
    <video id="video" muted playsinline></video>
  </div>

  <!-- Controls bar: a sibling of playerContainer, always spans #container -->
  <div id="playerControls" class="player-controls">
    <button id="btnPlay" aria-label="Play/Pause"></button>
    <button id="btnMute" aria-label="Mute/Unmute"></button>
    <button id="btnFullscreen" aria-label="Fullscreen"></button>
  </div>

  <!-- Break toast: also a sibling, so it always covers the full stage -->
  <div id="breakToast" class="break-toast">
    <span class="toast-badge">AD</span>
    <span id="toastText">Ad break</span>
  </div>
</div>

Routing playback through the SDK

Always call sdk.play(), sdk.pause(), and sdk.seek() — never manipulate the video element directly from your UI:

btnPlay.addEventListener('click', () => {
  if (video.paused)
    sdk.play(); // SDK will block if break is content-locking
  else sdk.pause(); // SDK will no-op if break is content-locking
});

// Seek to 3:00 — SDK will snap back if a locked break is active
btnSeek.addEventListener('click', () => sdk.seek(180));

Hiding controls during ad breaks

The SDK fires adbreakbegin and adbreakend when a break starts and ends. Use these to swap your play/seek controls for a break indicator — but keep the mute control reachable: a viewer who cannot unmute a playing pre-roll has no way to hear it. The simplest approach is to only hide the controls that don't apply during a break (play/pause, seek) rather than the whole bar, or to include a Mute button in your break-toast markup too:

sdk.addEventListener('adbreakbegin', () => {
  // Keep the control bar (and its mute button) visible — do not hide it here.
  document.getElementById('breakToast')!.classList.add('visible');
});

sdk.addEventListener('adbreakend', () => {
  document.getElementById('breakToast')!.classList.remove('visible');
});

Break countdown timer

adbreakbegin gives you the total break duration via e.break.duration (seconds, may be undefined for dynamic breaks). Drive a countdown with setInterval:

let countdownTimer: ReturnType<typeof setInterval> | null = null;

sdk.addEventListener('adbreakbegin', (e: AdBreakBeginEvent) => {
  const toastText = document.getElementById('toastText')!;
  let remaining = Math.round(e.break.duration ?? 0);

  const fmt = (s: number) => (s >= 60 ? `${Math.floor(s / 60)}m ${s % 60}s` : `${s}s`);

  toastText.textContent = remaining > 0 ? `Ad break · ${fmt(remaining)} remaining` : 'Ad break';

  if (remaining > 0) {
    countdownTimer = setInterval(() => {
      remaining = Math.max(0, remaining - 1);
      toastText.textContent =
        remaining > 0 ? `Ad break · ${fmt(remaining)} remaining` : 'Ad break ending…';
      if (remaining === 0) {
        clearInterval(countdownTimer!);
        countdownTimer = null;
      }
    }, 1000);
  }
});

sdk.addEventListener('adbreakend', () => {
  clearInterval(countdownTimer!);
  countdownTimer = null;
});

For a more accurate countdown that stays in sync with actual ad playback, use adtimeupdate instead:

sdk.addEventListener('adtimeupdate', (e: AdTimeupdateEvent) => {
  const remaining = Math.ceil(e.duration - e.currentTime);
  document.getElementById('toastText')!.textContent = `Ad break · ${remaining}s remaining`;
});

Ad progress bar

adtimeupdate fires at ~4 Hz during ad playback and includes both currentTime and duration:

sdk.addEventListener('adtimeupdate', (e: AdTimeupdateEvent) => {
  const pct = e.duration > 0 ? (e.currentTime / e.duration) * 100 : 0;
  progressBar.style.width = `${pct}%`;
});

Auto-hiding controls

Show controls on mouse interaction and hide them after a timeout during playback:

let hideTimer: ReturnType<typeof setTimeout> | null = null;

function showControls() {
  controls.classList.add('visible');
  clearTimeout(hideTimer!);
  if (!video.paused) {
    hideTimer = setTimeout(() => controls.classList.remove('visible'), 3000);
  }
}

container.addEventListener('mousemove', showControls);
video.addEventListener('pause', showControls); // keep visible when paused

Fullscreen

Request fullscreen on the SDK container (not the video element) so ad overlays and companion banners are included:

btnFullscreen.addEventListener('click', () => {
  if (!document.fullscreenElement) container.requestFullscreen();
  else document.exitFullscreen();
});

document.addEventListener('fullscreenchange', () => {
  btnFullscreen.setAttribute(
    'aria-label',
    document.fullscreenElement ? 'Exit fullscreen' : 'Fullscreen'
  );
});

Mute / volume sync

Drive mute/volume through the SDK's unified sdk.muted / sdk.volume — they always target whichever player is currently audible (the ad player during a break, the content player otherwise), so one button works correctly through break transitions in both directions. Listen for the SDK's volumechange event to keep your icon in sync without polling — it fires on every change, whether triggered by your button, a direct mutation of the content/ad element, or an IMA CSAI ad's own UI:

btnMute.addEventListener('click', () => {
  sdk.muted = !sdk.muted;
});

sdk.addEventListener('volumechange', (e) => {
  btnMute.setAttribute('aria-label', e.muted ? 'Unmute' : 'Mute');
  // swap icon here
});

Current-time indicator

Show the elapsed content time by polling the player on a short interval and formatting currentTime. Reading the player's currentTime works the same way across HLS.js / Shaka / THEOplayer / native, so a single poll drives the label:

const fmt = (seconds: number) => {
  if (!Number.isFinite(seconds) || seconds <= 0) return '0:00';
  const t = Math.floor(seconds);
  const h = Math.floor(t / 3600);
  const m = Math.floor((t % 3600) / 60);
  const ss = String(t % 60).padStart(2, '0');
  return h > 0 ? `${h}:${String(m).padStart(2, '0')}:${ss}` : `${m}:${ss}`;
};

const timer = setInterval(() => {
  timeIndicator.textContent = fmt(video.currentTime);
}, 250); // ~4 Hz

// On teardown: clearInterval(timer);

Keep the indicator inside #playerControls so it auto-hides during ad breaks alongside the rest of your controls (the break toast covers the ad). The demo factors this into a shared formatPlayerTime() / createTimeIndicator() helper used by every demo page.

Skip forward / back

Add skip buttons that jump the content timeline by a fixed offset. Route them through sdk.seek() and clamp the target to the playable range so you never seek past the end (or before the start). Because the seek goes through the SDK, it is a no-op without an active session and is suppressed during snapback breaks:

const clampSeekTarget = (current: number, delta: number, duration: number) => {
  const target = (Number.isFinite(current) ? current : 0) + delta;
  if (target < 0) return 0;
  if (Number.isFinite(duration) && target > duration) return duration; // live: skip upper clamp
  return target;
};

function skip(delta: number) {
  sdk.seek(clampSeekTarget(video.currentTime, delta, video.duration));
}

btnBack15.addEventListener('click', () => skip(-15));
btnFwd30.addEventListener('click', () => skip(30));

The demo's VOD page wires exactly this (−15s / +30s) with the shared clampSeekTarget() helper in packages/demo/src/seek.ts. The buttons live inside #playerControls, so they auto-hide during ad breaks.

Remembered session fields

The demo's Player page remembers your per-user Org ID, Channel ID, Custom Asset Key, Content URL, and Ad Tag Parameters in localStorage, so edits survive a reload. The built-in defaults stay as the fallback for a fresh browser, and a Reset to defaults link under the Load button clears the saved values and restores them. This is a demo-page convenience (helper in packages/demo/src/field-storage.ts); the SDK itself stores nothing. URL query-param overrides used by the e2e suite still take precedence over stored values.

Predefined configurations via URL (?presets)

The Player page can be seeded with named, fully-formed configurations passed in the URL — handy for sharing reproducible setups without hand-editing the form. Pass a base64-encoded JSON array of configuration objects in the ?presets= query parameter. When present, a Predefined Configurations card appears at the top of the config column; choosing an entry fills the whole form and auto-loads it. The first entry is auto-selected and loaded on page open. With no ?presets parameter, the card is hidden and the page behaves exactly as before (the manual form stays available either way).

Every field on the page is configurable. All fields except name are optional — an omitted field keeps the form's current/default value. The one exception is preRoll: it is a full on/off toggle, so a preset that omits preRoll (or sets "enabled": false) turns pre-roll OFF. This means switching from a pre-roll preset to one without never inherits the previous pre-roll injection.

[
  {
    "name": "Sponsor A — SGAI DAR", // required, non-empty; the selector label
    "mode": "sgai", // "sgai" | "ssai"
    "player": "hlsjs", // "hlsjs" | "shaka" | "theo" | "native"
    "manifestBaseUrl": "https://optiview-ads.cdn.sneezysparrow.com/manifest/v1",
    "gam": true, // Enable GAM
    "networkCode": "23285652104",
    "orgId": "0bda787b-…",
    "channelId": "d7803a87-…",
    "customAssetKey": "assetkey_michel",
    "adInsertionType": "replacement", // "replacement" (DAR) | "insertion" (DAI)
    "contentUrl": "https://…/main.m3u8",
    "adTagParams": { "iu": "/23285652104/dcoffey-v2-adunit" }, // object or JSON string
    "preRoll": { "enabled": true, "format": "single", "delaySeconds": 0 },
    "stitcherBaseUrl": "http://localhost:4600", // SSAI only
    "stitcherOriginUrl": "https://…/main.m3u8",
    "maxBitrate": 2000000,
    "ssaiAutoplay": true,
    "stitcherPort": "4600",
    "snapPolicy": "nearest", // "nearest" | "start" | "end"
  },
]

Build the parameter by base64-encoding the JSON array (standard or URL-safe base64 is accepted), e.g. in the browser console:

const presets = [{ name: 'Sponsor A', orgId: '…', channelId: '…' }];
location.search = '?presets=' + encodeURIComponent(btoa(JSON.stringify(presets)));

Unknown keys are ignored and unknown enum values (mode, player, insertion type, snap policy, pre-roll format) are skipped with a logged warning, so a config is forward-compatible. A malformed, empty, or non-array ?presets value is ignored (with one warning in the event log) and the card is not shown. Decoding/applying is handled by the unit-tested packages/demo/src/demo-presets.ts helper (decodeUrlPresets / applyPreset); demo only — no SDK/core change.

Preset Builder

You don't have to hand-write that base64 array. The Preset Builder page (sidebar → Preset Builder, /preset-builder.html) lets you visually assemble one or more presets, generates the shareable URL-safe ?presets= link and the raw JSON live, and offers Copy + Open in Player. You can also paste an existing ?presets URL (or base64 token) to import and edit it — a full round-trip. The builder reuses the same demo-presets.ts primitives (encodeUrlPresetsSafe / decodeUrlPresets) and the pure packages/demo/src/preset-builder-model.ts helper (buildPreset / presetToValues / presetsToUrl / urlToPresets), so the links it produces are exactly what the Player page consumes.

Android (Kotlin)

The SDK plays ads on its own PlayerView inside the overlayContainer FrameLayout you pass to OverlayAdRenderer, stacked above your content surface. Build your own controls (or use a Compose overlay) and follow the same rules:

• Provide an overlay container above your content PlayerView — a FrameLayout matching the content bounds, passed to OverlayAdRenderer(context, overlayContainer, contentAdapter).
• Route playback through the SDK — call sdk.play() / sdk.pause() / sdk.seek(seconds) instead of touching the ExoPlayer directly, so content-lock and snapback are honoured.
• Swap controls for a break indicator on ADBREAKBEGIN / ADBREAKEND.
• Drive a countdown from the ADTIMEUPDATE event (currentTime / duration) or from break_.duration.

// Hide your controls + show a break indicator during the break
sdk.addEventListener(DolbyAdsEventType.ADBREAKBEGIN) {
    playerControls.isVisible = false
    breakToast.isVisible = true
}
sdk.addEventListener(DolbyAdsEventType.ADBREAKEND) {
    breakToast.isVisible = false
    playerControls.isVisible = true
}

// Countdown that stays in sync with actual ad playback
sdk.addEventListener(DolbyAdsEventType.ADTIMEUPDATE) { event ->
    val e = event as AdTimeupdateEvent
    val remaining = kotlin.math.ceil(e.duration - e.currentTime).toInt()
    toastText.text = "Ad break · ${remaining}s remaining"
}

// Route the play/pause button through the SDK (no-op during content-locking breaks)
playPauseButton.setOnClickListener {
    if (contentPlayer.isPlaying) sdk.pause() else sdk.play()
}

iOS / tvOS (Swift)

The SDK plays ads on its own AVPlayer in an AVPlayerLayer inside the overlayContainer UIView you pass to OverlayAdRenderer, stacked above your content surface. The same rules apply:

• Provide an overlay container above your content surface — a UIView matching the content bounds, passed to OverlayAdRenderer(overlayContainer:contentPlayer:).
• Route playback through the SDK — call sdk.play() / sdk.pause() / sdk.seek(seconds) instead of touching the AVPlayer directly.
• Swap controls for a break indicator on .adbreakbegin / .adbreakend.
• Drive a countdown from the .adtimeupdate event, or from the break duration.

// Hide your controls + show a break indicator during the break
sdk.addEventListener(.adbreakbegin) { _ in
    playerControls.isHidden = true
    breakToast.isHidden = false
}
sdk.addEventListener(.adbreakend) { _ in
    breakToast.isHidden = true
    playerControls.isHidden = false
}

// Countdown that stays in sync with actual ad playback
sdk.addEventListener(.adtimeupdate) { event in
    if case let .adTimeUpdate(_, _, currentTime, duration, _) = event {
        let remaining = Int(ceil(duration - currentTime))
        toastLabel.text = "Ad break · \(remaining)s remaining"
    }
}

// Route the play/pause button through the SDK (no-op during content-locking breaks)
playPauseButton.addAction(UIAction { _ in
    contentPlayer.timeControlStatus == .playing ? sdk.pause() : sdk.play()
}, for: .touchUpInside)

Manifest interception

Two optional SGAI hooks let you intercept the break manifest on the client — without standing up a proxy — at the two natural points around the fetch. Both run on the initial fetch and every subsequent poll.

• interceptManifestRequest runs before the network request (rewrite URL, add headers, or mock the response).
• interceptManifestResponse runs after fetch + validation (transform the parsed BreakManifest).

Request interception (interceptManifestRequest)

The interceptManifestRequest hook is invoked before the SDK fetches the manifest, so you can redirect the request, attach headers, or short-circuit the network entirely with a mocked response. It is primarily a testing aid (point the SDK at a fixture, or exercise header-based auth) but is a supported production hook.

Return one of:

• a ManifestRequest ({ url, headers? }) — fetch this (possibly rewritten) URL with the given headers;
• a ManifestMockResponse ({ body }) — skip the network and use body (a raw JSON string or object) as the fetched manifest body. The mock body goes through the normal parse + validation path — an invalid body still fails validation, and interceptManifestResponse (if set) still runs afterward;
• nothing (void/undefined) — fetch unchanged.

Failure is non-fatal: if the hook throws (or its promise rejects), the SDK emits DA-MANIFEST-REQUEST-INTERCEPT-FAILED and falls back to the normal network fetch of the original URL. May be async.

import { DolbyAds, type ManifestRequest } from '@dolby-ads/core';

const sdk = new DolbyAds({
  // ...
  // Add an auth header to every manifest request (initial fetch + every poll):
  interceptManifestRequest: (request: ManifestRequest) => ({
    ...request,
    headers: { ...request.headers, Authorization: `Bearer ${token}` },
  }),
});

// Or short-circuit the network with a fixture (great for tests):
new DolbyAds({
  // ...
  interceptManifestRequest: () => ({ body: JSON.stringify(myFixtureManifest) }),
});

Response interception (interceptManifestResponse)

Some integrations need to adjust the break manifest on the client — inject a pre-roll, drop a break, rewrite an asset URL, or layer in client-side targeting — without standing up a proxy. The optional interceptManifestResponse SDK config hook is invoked after the SDK has fetched and validated the manifest, on the initial fetch and on every subsequent poll, so you can transform it before it is scheduled.

Key guarantees:

• Typed, never raw. The callback receives the parsed BreakManifest (normalized variants arrays, parsed numbers/enums) — never the raw JSON. An invalid manifest fails validation before the hook runs, so it is never called with garbage.
• Its return value is used as-is. Return the (possibly new) BreakManifest to schedule; it is used directly, without re-validation. Returning the input unchanged is a no-op.
• Runs on every poll. Live channels re-poll; the hook is applied each time, so keep it pure/idempotent (e.g. guard against injecting the same break twice).
• Failure is non-fatal. If the hook throws (or its promise rejects), the SDK emits the DA-MANIFEST-INTERCEPT-FAILED diagnostic and falls back to the unmodified parsed manifest — the fetch/poll does not fail.
• May be async. Return a Promise<BreakManifest> to do async work (the poll awaits it).

import { DolbyAds, type BreakManifest } from '@dolby-ads/core';

const sdk = new DolbyAds({
  // ...
  interceptManifestResponse: (manifest: BreakManifest, ctx) => {
    // Inject a client-side pre-roll, idempotently (runs on every poll).
    if (manifest.breaks.some((b) => b.id === 'my-preroll')) return manifest;
    return {
      ...manifest,
      breaks: [
        {
          id: 'my-preroll',
          start: 0,
          position: 'pre',
          duration: 15,
          variants: [
            /* ... */
          ],
        },
        ...manifest.breaks,
      ],
    };
  },
});