ads-sdk-core/com.dolby.optiview.ads.core/PlayerAdapter

PlayerAdapter

The abstraction layer between the SDK and any content player — the Kotlin mirror of packages/core/src/interfaces/PlayerAdapter.ts.

The SDK core only interacts with players through this interface, so the brain stays player-agnostic and never imports Media3/ExoPlayer. The portable brain (BreakScheduler) reads only currentTime; the rest of the contract is used by the SDK orchestrator and the platform ad renderer.

Android idiom: unlike the web adapter (whose load/play return Promises), load/play are synchronous here — they kick off preparation/playback and return immediately; readiness/completion is signalled via PlayerAdapterEvents (e.g. playing, waiting, ended). There is also no web-only videoElement.

Properties

currentTime

abstract val currentTime: Double

Current playback time in seconds.

duration

abstract val duration: Double

Total content duration in seconds; Double.POSITIVE_INFINITY for live.

isLive

open val isLive: Boolean?

Optional hint: whether the loaded content is a LIVE (dynamic-timeline) stream. On live content duration is not a reliable signal on Android — ExoPlayer reports the (finite) sliding-window duration — so the runtime uses this to restore the viewer's live latency after a break that paused content, regardless of the channel's break timebase. Null means unknown and is treated as not live.

maxLiveSeekPosition

open val maxLiveSeekPosition: Double?

The furthest position on this player's timeline a seek will actually STICK on live content, in seconds — the engine pulls back anything closer to the live edge.

muted

abstract var muted: Boolean

Whether the player is muted. Settable so the SDK can sync content↔ad mute.

paused

abstract val paused: Boolean

Whether the player is currently paused.

playbackRate

open var playbackRate: Double

Playback rate, where 1.0 is normal speed. Optional, and settable.

positionIsWindowRelative

open val positionIsWindowRelative: Boolean

Whether currentTime is measured from the START OF A SLIDING WINDOW rather than from a fixed origin.

programDateTime

abstract val programDateTime: Long?

Program Date Time from the stream (EXT-X-PROGRAM-DATE-TIME for HLS), as epoch milliseconds, used for wallclock-timebase break matching. Null when unavailable. (Epoch ms rather than a Date/Instant to keep the brain dependency-free and conformance-portable.)

supportsParallelBuffering

open val supportsParallelBuffering: Boolean?

Optional capability hint: whether this adapter/platform can buffer a second media source in parallel with the content player without decoder contention. Null is treated as true by the auto preload resolver.

volume

abstract var volume: Double

Volume in [0, 1]. Settable so the SDK can sync content↔ad volume.

Functions

destroy

abstract fun destroy()

Clean up resources (called when the SDK is destroyed).

load

abstract fun load(url: String)

Load a media source without committing to immediate playback (preload at break start).

off

abstract fun off(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler)

Unsubscribe a previously registered handler.

abstract fun on(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler)

Subscribe to a player event.

pause

abstract fun pause()

Pause playback (called when an ad break starts).

play

abstract fun play()

Resume playback (called when an ad break ends). Returns immediately.

preload

open fun preload(url: String)

Optional: warm caches for url WITHOUT attaching media or engaging a decoder (single-decoder preload on decoder-limited TVs). Adapters that cannot do a detached prefetch leave this as the default no-op.

seek

abstract fun seek(time: Double)

Seek to time seconds (used for snapback during locked breaks).

seekExact

open fun seekExact(time: Double)

Seek to time seconds without applying an adapter-specific sync-point adjustment. Used for SDK-owned post-break resume seeks.

setVideoQuality

open fun setVideoQuality(quality: VideoQuality?): Boolean

Optionally select a content quality, or pass null to release the SDK's override. A successful VideoQuality.LOWEST request snapshots the integrator's current selection and applies the cheapest rendition without flushing. Returns true only when the requested override was applied or restoration of an outstanding override was successfully attempted.