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.

liveEdge

open val liveEdge: Double?

End of the newest published media segment (the live edge); defaults to the seekable end.

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.

playbackReady

open val playbackReady: Boolean

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

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.)

seekableEnd

open val seekableEnd: Double?

End of the available media in seconds; null when unknown.

seekableStart

open val seekableStart: Double?

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

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.

targetDuration

open val targetDuration: Double?

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

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.

requestLiveStartOffset

open fun requestLiveStartOffset(targetDurations: Double?, fallbackTargetDuration: Double?): Boolean

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. Returns false when the engine cannot honour it for the upcoming start; the SDK then seeks after the first frame.

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.