OptiView Ads SDK
    Preparing search index...

    Interface PlayerAdapter

    The abstraction layer between the SDK and any video player. The core only talks to players through this interface; each player gets its own adapter package.

    class HlsJsAdapter implements PlayerAdapter {
      constructor(private hls: Hls, private video: HTMLVideoElement) {}
      // ... implement all methods
    }
    interface PlayerAdapter {
        currentTime: number;
        destroy(): void;
        duration: number;
        isLive?: boolean | null;
        liveEdge?: number | null;
        load(url: string): Promise<void>;
        maxLiveSeekPosition?: number | null;
        muted: boolean;
        off(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler): void;
        on(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler): void;
        pause(): void;
        paused: boolean;
        play(): Promise<void>;
        playbackRate?: number;
        playbackReady?: boolean;
        preload?(url: string): Promise<void>;
        programDateTime: Date | null;
        recreateMediaPipeline?(options: { startTime: number }): Promise<void>;
        releaseMediaElement?(): void | Promise<void>;
        requestLiveStartOffset?(
            targetDurations: number | null,
            fallbackTargetDuration: number | null,
        ): boolean;
        seek(time: number): void;
        seekableEnd?: number | null;
        seekableStart?: number | null;
        setVideoQuality?(quality: "lowest" | null): boolean;
        sourceUrl?: string | null;
        supportsParallelBuffering?: boolean;
        targetDuration?: number | null;
        unload?(): void | Promise<void>;
        videoElement?: HTMLVideoElement | null;
        volume: number;
    }

    Implemented by

    Index
    currentTime duration isLive? liveEdge? maxLiveSeekPosition? muted paused playbackRate? playbackReady? programDateTime seekableEnd? seekableStart? sourceUrl? supportsParallelBuffering? targetDuration? videoElement? volume
    destroy load off on pause play preload? recreateMediaPipeline? releaseMediaElement? requestLiveStartOffset? seek setVideoQuality? unload?
    currentTime: number

    Current playback time in seconds.

    duration: number

    Content duration in seconds; may be Infinity for live streams.

    isLive?: boolean | null

    Whether the content is live, as reported by the player engine. Return null or omit this property when unknown; the SDK then falls back to checking for an infinite duration. A finite duration does not reliably identify VOD: HLS.js can report a finite live playlist.

    Player Live status
    HLS.js hls.latestLevelDetails.live
    Shaka player.isLive()
    THEOplayer duration === Infinity

    Do not infer live status from maxLiveSeekPosition; a seek range can exist for VOD too.

    liveEdge?: number | null

    End of the newest published media segment in seconds (the live edge), or null when unknown. Report this when the engine's seekable range stops short of the published playlist end; AVFoundation, for example, ends seekableTimeRanges one hold-back before the edge. If omitted, the live start positioning uses seekableEnd as the edge.

    maxLiveSeekPosition?: number | null

    Latest live playback position the player can seek to without moving back to maintain its minimum live offset, in seconds. Return null when unknown or not live; the SDK then leaves the seek target unclamped. Use the player engine's seek limit rather than guessing an offset: HLS.js exposes liveSyncPosition, THEOplayer exposes latencyManager.currentLatency / minimumOffset, and Shaka exposes seekRange() / safeSeekEndOffset.

    muted: boolean

    Settable so the SDK can sync mute state between content and ad players.

    paused: boolean

    Whether the player is paused.

    playbackRate?: number

    Playback rate (1 = normal). Used to correct drift while content continues behind an ad with continueContentDuringBreak. Report the engine's current rate, not just the last assigned value, so the SDK can detect changes made by the player's live-latency controller. If omitted, drift is reported but not corrected.

    playbackReady?: boolean

    False while play expresses intent but the content timeline is not yet ready for a startup seek.

    programDateTime: Date | null

    Program Date Time (HLS EXT-X-PROGRAM-DATE-TIME) for wallclock break matching; null if unavailable.

    seekableEnd?: number | null

    End of the available media in seconds, or null when unknown. This differs from maxLiveSeekPosition, which includes the player's minimum live offset. Read the engine's seek range if the video element reports an unbounded sentinel value instead of the actual DVR window. If omitted, the SDK uses videoElement.seekable and rejects sentinel values.

    seekableStart?: number | null

    Start of the same seekable range as seekableEnd; null/omitted when unknown.

    sourceUrl?: string | null

    Current content manifest URL, used to restore content after a shared-element ad. Read it from the player engine, not the element's src (which can be a blob: URL) or the last load() argument, since applications may load sources directly. Return null when unavailable; shared-element insertion is then unsupported (DA-SHARED-ELEMENT-UNSUPPORTED).

    supportsParallelBuffering?: boolean

    Optional capability hint: can content and ad pipelines buffer in parallel without decoder contention? false prevents continued content playout during a break. Undefined counts as capable.

    targetDuration?: number | null

    Declared HLS EXT-X-TARGETDURATION in seconds, not average segment length; null when unknown.

    videoElement?: HTMLVideoElement | null

    The underlying HTMLVideoElement, if any. Required for GAM (the IMA SDK needs the element).

    volume: number

    Volume in [0, 1]; settable so the SDK can sync it between content and ad players.

    • Clean up resources when the SDK is destroyed.

      Returns void

    • Load a media source without playing; resolves when it is ready to play. Used to preload ads.

      Parameters

      • url: string

      Returns Promise<void>

    • Pause playback (called when an ad break starts).

      Returns void

    • Resume playback (called when an ad break ends); resolves when playback starts.

      Returns Promise<void>

    • Optional: warm caches (manifest, optionally the first fragment) WITHOUT attaching media or engaging a decoder, for single-decoder Smart TVs that cannot hold two MediaSources. Must not call attachMedia(). Leave undefined if unsupported; the SDK loads on demand at break start.

      Parameters

      • url: string

      Returns Promise<void>

    • Optional: tear down and rebuild the engine's media pipeline (MediaSource / source buffers) for the CURRENT source, positioned at startTime seconds. Called at break end on TVs that cannot resume content in the MediaSource an ad interrupted (VIZIO SmartCast). Resolve once metadata for the rebuilt pipeline is available; reject on failure — the SDK then falls back to seek+play. Must not destroy the adapter. Omit when the engine has no such operation.

      Parameters

      • options: { startTime: number }

      Returns Promise<void>

    • Release control of the content video element so a shared-element ad can use it. Resolve only when the element is free; do not destroy the adapter. The SDK restores content with load() when the break ends. Omit this method if your player supports sharing the element without an explicit release, as HLS.js does.

      The same method is called on the ad adapter that createAdAdapter(container, video) built for the content element, right before content is reloaded at break end. Leave the ad media on the element there: the content engine's load() replaces it in one step, and an element without a resource closes Safari's picture-in-picture window.

      Returns void | Promise<void>

    • Ask the engine to begin the upcoming live playback targetDurations declared target durations behind the live edge, before the first frame, instead of the SDK seeking after it. fallbackTargetDuration (seconds) applies when the engine cannot read the playlist's. null withdraws the request. Return false when the engine cannot honour it for the upcoming start; the SDK then seeks after the first frame. Omit when unsupported.

      Parameters

      • targetDurations: number | null
      • fallbackTargetDuration: number | null

      Returns boolean

    • Seek to a time in seconds. Needed for snapback during locked breaks without touching the video element.

      Parameters

      • time: number

      Returns void

    • Optionally select a content quality, or pass null to release the SDK's override. A successful lowest request snapshots the integrator's current selection and applies the cheapest rendition without flushing buffered media. Returns whether the request was applied; passing null restores the exact prior selection.

      Parameters

      • quality: "lowest" | null

      Returns boolean

    • Release the held media without destroying the adapter; the next load() must reattach it. Called on single-decoder TVs at break end, before content resumes, to free the hardware decoder and avoid MEDIA_ERR_DECODE. Not called in parallel-preload mode. When it returns a promise, the SDK awaits it before resuming content.

      Returns void | Promise<void>

    Settings
    Member Visibility

    On This Page
    Properties
    Methods