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>): void
    gatedidempotent
  • destroy(): void
    idempotent
  • exitFullscreen(): Promise<void>
    returns a promisegatedidempotent
  • exitPictureInPicture(): Promise<void>
    returns a promisegatedidempotent
  • getAudioTracks(): readonly AudioTrack[]
    idempotent
  • getCaptions(): readonly CaptionTrack[]
    idempotent
  • getMedia(): MediaDescriptor | null
    idempotent
  • getPlaylist(): readonly MediaDescriptor[]
    idempotent
  • getQualities(): readonly Quality[]
    idempotent
  • getState(): PlayerState
    idempotent
  • getVersion(): PlayerVersion
    idempotent
  • insertItem(item: MediaDescriptor, index?: number): void
    gated

    Queue an item at index in the playlist, or at its end when index is absent. Clamped to [0, length]. Never starts, stops or changes what is playing: an insert at or before playlistIndex moves the index along with the item. Emits playlistChanged. Added 2026-09-29.

  • load(source: LoadSource): Promise<void>
    returns a promisegated
  • mute(): void
    gatedidempotent
  • next(): Promise<void>
    returns a promisegated
  • off<K extends PlayerEventName>(event: K, handler: EventHandler<K>): void
    idempotent
  • on<K extends PlayerEventName>(event: K, handler: EventHandler<K>): () => void
  • once<K extends PlayerEventName>(event: K, handler: EventHandler<K>): () => void
  • pause(): void
    gatedidempotent
  • play(): Promise<void>
    returns a promisegatedidempotent
  • playIndex(index: number): Promise<void>
    returns a promisegated
  • previous(): Promise<void>
    returns a promisegated
  • removeItem(index: number): void
    gated

    Take the item at index out of the playlist. The item playing cannot be removed — next() first — and an index outside the playlist is ignored; neither emits anything. Emits playlistChanged. Added 2026-09-29.

  • requestFullscreen(): Promise<void>
    returns a promisegatedidempotent
  • requestPictureInPicture(): Promise<void>
    returns a promisegatedidempotent
  • seek(seconds: number): void
    gatedidempotent

    Clamped to seekable.

  • setAudioTrack(index: number): void
    gatedidempotent
  • setCaptions(index: number | null): void
    gatedidempotent
  • setPlaybackRate(rate: number): void
    gatedidempotent
  • setQuality(index: number | 'auto'): void
    gatedidempotent
  • setSleepTimer(timer: SleepTimer | null): void
    gatedidempotent

    A 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 promisegated

    load() for one address: a media file (mediaFromUrl) or a playback object's URL, exactly as the media attribute reads one. options names the title and poster a bare file has no way to carry. An address that yields nothing is an error event (PBP-104003), never a rejection. Added 2026-09-29.

  • setTheme(document: ThemeDocument): void
    gatedidempotent
  • setVolume(volume: number): void
    gatedidempotent
  • stop(): void
    gatedidempotent
  • unmute(): void
    gatedidempotent

Properties

Read-only. A value with a matching method is changed through the method: volume through setVolume, never by assignment.

  • audioOnly: boolean

    Drawn as an audio player: the item has no picture, or configuration audioOnly asked for one.

  • audioTracks: readonly AudioTrack[]
  • buffered: readonly (readonly [number, number])[]
  • captions: readonly CaptionTrack[]
  • config: PlayerConfig
  • currentAudioTrack: number
  • currentCaptions: number | null
  • currentQuality: number | 'auto'
  • currentTime: number
  • duration: number
  • engine: EngineInfo | null
  • fullscreen: boolean
  • licensed: boolean
  • live: boolean
  • liveEdge: number

    Seconds behind the live edge; 0 when not live or at the edge.

  • liveLatency: number | null

    Seconds behind the encoder's clock, measured by the engine; null when not live or not measurable.

  • media: MediaDescriptor | null
  • muted: boolean
  • offline: OfflineApi | null

    Offline copies, once the offline plugin has registered; null before and without it.

  • pictureInPicture: boolean
  • playbackRate: number
  • playlist: readonly MediaDescriptor[]
  • playlistIndex: number
  • qualities: readonly Quality[]
  • seekable: readonly [number, number]
  • sleepTimer: SleepTimer | null
  • state: PlayerState
  • theme: ThemeDocument
  • version: string
  • volume: 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 AdBreakPayload

    A 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 AdBreakPayload

    A break is about to show its first ad. Not emitted for a break whose ad server returned nothing — that break is an adError and 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 AdEventPayload
  • adError { readonly breakPosition: AdBreakPosition; readonly code: number }

    An ad did not play. code is 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 AdEventPayload

    An ad was displayed: the moment an advertiser is billed on.

  • adSkipped AdEventPayload

    The 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 }

    recoverable means a retry control is offered and load() 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 }

    insertItem or removeItem changed the playlist. index is playlistIndex afterwards, 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 — elapsed is true only for the last, and timer is 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.

StateCan move to
idleloading, destroyed
loadingloading, ready, error, idle, destroyed
readyplaying, paused, buffering, error, loading, idle, destroyed
playingpaused, buffering, ended, error, loading, idle, destroyed
pausedplaying, buffering, ended, error, loading, idle, destroyed
bufferingplaying, paused, ended, error, loading, idle, destroyed
endedplaying, paused, buffering, loading, error, idle, destroyed
errorloading, idle, destroyed
destroyed—

Keyboard

With the player focused. Every control is also reachable with Tab, and menus take the arrow keys.

SpacektogglePlay
ArrowLeftseekBack5
ArrowRightseekForward5
jseekBack10
lseekForward10
ArrowUpvolumeUp
ArrowDownvolumeDown
mtoggleMute
ftoggleFullscreen
ptogglePictureInPicture
ctoggleCaptions
0123456789seekToPercent
HomeseekToStart
EndseekToEnd
NnextItem
PpreviousItem
,frameBack
.frameForward
?showShortcuts
Ctrl+ArrowRightnextChapter
Ctrl+ArrowLeftpreviousChapter
itoggleFloat
<rateDown
>rateUp
Escapeescape

Playback rates

The only values setPlaybackRate accepts: 0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2.