API
Everything a page can call, read and listen to on the player. Generated from the specification the player is built and tested against.
Getting the player
The loader adds the <pb-play> element when the player is ready to load, and the element fires pbp:ready once its first video has loaded. Every method below is on the element.
document.addEventListener('pbp:ready', event => {
const player = event.target;
player.on('stateChanged', ({ from, to }) => console.log(from, '→', to));
});Methods
A gated method is one a licence unlocks. Without one, calling it logs a warning and does nothing; the viewer can still use the player’s own controls. Idempotent means calling it twice is the same as calling it once.
configure(partial: Partial<PlayerConfig>): voidgatedidempotentdestroy(): voididempotentexitFullscreen(): Promise<void>returns a promisegatedidempotentexitPictureInPicture(): Promise<void>returns a promisegatedidempotentgetAudioTracks(): readonly AudioTrack[]idempotentgetCaptions(): readonly CaptionTrack[]idempotentgetMedia(): MediaDescriptor | nullidempotentgetPlaylist(): readonly MediaDescriptor[]idempotentgetQualities(): readonly Quality[]idempotentgetState(): PlayerStateidempotentgetVersion(): PlayerVersionidempotentinsertItem(item: MediaDescriptor, index?: number): voidgatedQueue an item at
indexin the playlist, or at its end whenindexis absent. Clamped to[0, length]. Never starts, stops or changes what is playing: an insert at or beforeplaylistIndexmoves the index along with the item. EmitsplaylistChanged. Added 2026-09-29.load(source: LoadSource): Promise<void>returns a promisegatedmute(): voidgatedidempotentnext(): Promise<void>returns a promisegatedoff<K extends PlayerEventName>(event: K, handler: EventHandler<K>): voididempotenton<K extends PlayerEventName>(event: K, handler: EventHandler<K>): () => voidonce<K extends PlayerEventName>(event: K, handler: EventHandler<K>): () => voidpause(): voidgatedidempotentplay(): Promise<void>returns a promisegatedidempotentplayIndex(index: number): Promise<void>returns a promisegatedprevious(): Promise<void>returns a promisegatedremoveItem(index: number): voidgatedTake the item at
indexout of the playlist. The item playing cannot be removed —next()first — and an index outside the playlist is ignored; neither emits anything. EmitsplaylistChanged. Added 2026-09-29.requestFullscreen(): Promise<void>returns a promisegatedidempotentrequestPictureInPicture(): Promise<void>returns a promisegatedidempotentseek(seconds: number): voidgatedidempotentClamped to
seekable.setAudioTrack(index: number): voidgatedidempotentsetCaptions(index: number | null): voidgatedidempotentsetPlaybackRate(rate: number): voidgatedidempotentsetQuality(index: number | 'auto'): voidgatedidempotentsetSleepTimer(timer: SleepTimer | null): voidgatedidempotentA value outside
SLEEP_TIMERS(or null) clears the timer. Works whether or not configuration offers the timer to the viewer.setSource(url: string, options?: SourceOptions): Promise<void>returns a promisegatedload()for one address: a media file (mediaFromUrl) or a playback object's URL, exactly as themediaattribute reads one.optionsnames the title and poster a bare file has no way to carry. An address that yields nothing is anerrorevent (PBP-104003), never a rejection. Added 2026-09-29.setTheme(document: ThemeDocument): voidgatedidempotentsetVolume(volume: number): voidgatedidempotentstop(): voidgatedidempotentunmute(): voidgatedidempotent
Properties
Read-only. A value with a matching method is changed through the method: volume through setVolume, never by assignment.
audioOnly: booleanDrawn as an audio player: the item has no picture, or configuration
audioOnlyasked for one.audioTracks: readonly AudioTrack[]buffered: readonly (readonly [number, number])[]captions: readonly CaptionTrack[]config: PlayerConfigcurrentAudioTrack: numbercurrentCaptions: number | nullcurrentQuality: number | 'auto'currentTime: numberduration: numberengine: EngineInfo | nullfullscreen: booleanlicensed: booleanlive: booleanliveEdge: numberSeconds behind the live edge; 0 when not live or at the edge.
liveLatency: number | nullSeconds behind the encoder's clock, measured by the engine; null when not live or not measurable.
media: MediaDescriptor | nullmuted: booleanoffline: OfflineApi | nullOffline copies, once the
offlineplugin has registered;nullbefore and without it.pictureInPicture: booleanplaybackRate: numberplaylist: readonly MediaDescriptor[]playlistIndex: numberqualities: readonly Quality[]seekable: readonly [number, number]sleepTimer: SleepTimer | nullstate: PlayerStatetheme: ThemeDocumentversion: stringvolume: number
Events
Subscribe with on(name, handler), which returns a function that unsubscribes. stateChanged fires before the event for the same change, ready fires once per load, and timeupdate at most 4 times a second.
adBreakEnd AdBreakPayloadA break ended, however it ended: every ad played, skipped or failed, or the item moved on. Exactly once after each
adBreakStart, and before the content resumes. Added 2026-09-29.adBreakStart AdBreakPayloadA break is about to show its first ad. Not emitted for a break whose ad server returned nothing — that break is an
adErrorand nothing else, because a page dimming its own chrome for a break that never shows is a page that was lied to. Added 2026-09-29.adComplete AdEventPayloadadError { readonly breakPosition: AdBreakPosition; readonly code: number }An ad did not play.
codeis the VAST error code (VAST 4.1 §2.3.6) — the same one the ad server's own<Error>URL was sent. The content plays on.adImpression AdEventPayloadAn ad was displayed: the moment an advertiser is billed on.
adSkipped AdEventPayloadThe viewer pressed skip.
audioTrackChanged { readonly index: number }buffered Record<string, never>buffering Record<string, never>captionsChanged { readonly index: number | null }destroyed Record<string, never>ended Record<string, never>error { readonly code: number; readonly message: string; readonly recoverable: boolean }recoverablemeans a retry control is offered andload()may be called again.fullscreenChanged { readonly fullscreen: boolean }mediaChanged { readonly index: number; readonly media: MediaDescriptor }pause Record<string, never>pictureInPictureChanged { readonly pictureInPicture: boolean }play Record<string, never>playing Record<string, never>playlistChanged { readonly index: number; readonly length: number }insertItemorremoveItemchanged the playlist.indexisplaylistIndexafterwards, which moves when an item is added or removed before it — the item playing never changes. Added 2026-09-29.playlistComplete Record<string, never>playlistItem { readonly index: number; readonly media: MediaDescriptor }progress { readonly buffered: readonly (readonly [number, number])[] }qualityChanged { readonly auto: boolean; readonly index: number | null }rateChanged { readonly rate: number }ready { readonly duration: number; readonly live: boolean }seeked { readonly currentTime: number }seeking { readonly to: number }sleepTimerChanged { readonly elapsed: boolean; readonly timer: SleepTimer | null }The timer was set, cleared, or ran out —
elapsedis true only for the last, andtimeris then null.stateChanged { readonly from: PlayerState; readonly to: PlayerState }timeupdate { readonly currentTime: number; readonly duration: number }volumeChanged { readonly muted: boolean; readonly volume: number }warning { readonly code: number; readonly message: string }
States
The player is always in exactly one state, and moves only along these transitions.
| State | Can move to |
|---|---|
| idle | loading, destroyed |
| loading | loading, ready, error, idle, destroyed |
| ready | playing, paused, buffering, error, loading, idle, destroyed |
| playing | paused, buffering, ended, error, loading, idle, destroyed |
| paused | playing, buffering, ended, error, loading, idle, destroyed |
| buffering | playing, paused, ended, error, loading, idle, destroyed |
| ended | playing, paused, buffering, loading, error, idle, destroyed |
| error | loading, idle, destroyed |
| destroyed | — |
Keyboard
With the player focused. Every control is also reachable with Tab, and menus take the arrow keys.
| Spacek | togglePlay |
| ArrowLeft | seekBack5 |
| ArrowRight | seekForward5 |
| j | seekBack10 |
| l | seekForward10 |
| ArrowUp | volumeUp |
| ArrowDown | volumeDown |
| m | toggleMute |
| f | toggleFullscreen |
| p | togglePictureInPicture |
| c | toggleCaptions |
| 0123456789 | seekToPercent |
| Home | seekToStart |
| End | seekToEnd |
| N | nextItem |
| P | previousItem |
| , | frameBack |
| . | frameForward |
| ? | showShortcuts |
| Ctrl+ArrowRight | nextChapter |
| Ctrl+ArrowLeft | previousChapter |
| i | toggleFloat |
| < | rateDown |
| > | rateUp |
| Escape | escape |
Playback rates
The only values setPlaybackRate accepts: 0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2.