Skip to main content
The shell plays the video in its own player: AVPlayer on iOS, ExoPlayer on Android, the shell’s player on desktop, and a remote-controlled player on TV. Your page passes a URL and gets back playback state. The platform provides the controls, including scrubbing, picture-in-picture, AirPlay and full screen. When the player closes, play resolves with the position where the viewer stopped.

Options

string
required
An http(s) URL: a progressive file (mp4, webm) or an HLS / DASH manifest.
'mp4' | 'webm' | 'hls' | 'dash'
Stream format. If you leave it out, the SDK infers it from the URL: .m3u8 is hls, .mpd is dash, .webm is webm, and anything else is mp4. Set it when a manifest’s URL doesn’t end in the usual extension.
string
Shown above the video.
string
Second line, such as a channel or show name.
string
Image shown until the first frame arrives.
number
Position to start from, in seconds. Ignored for live.
boolean
default:"true"
Start playing as soon as the video is ready.
boolean
default:"false"
Start again from the beginning when the video ends.
boolean
default:"false"
Start with the sound off.
boolean
default:"false"
A live stream. The player hides seeking and shows a LIVE badge.
boolean
default:"false"
Close the player when the video ends. Without it, the player stays open on the last frame. Ignored with loop.
number
default:"0"
While playing, send a progress event every this many seconds. With 0, no progress events are sent. The final position always comes with the result.
string
Returned on every event and on the result.

Events

The optional second argument of play (or openPlayer) receives every state change while the player is open:
'ready' | 'play' | 'pause' | 'buffering' | 'progress' | 'ended' | 'error'
What happened.
number
Current position, in seconds.
number
Length in seconds. It is 0 until the length is known, and stays 0 for a live stream.

Result

number
Where playback stopped, in seconds. Save it and pass it back as startAt to resume.
number
Length of the video in seconds.
boolean
Playback reached the end at least once.
'not_available' | 'busy' | 'invalid_source' | 'playback_failed'
not_available: this surface has no player. busy: another video is already open. invalid_source: the URL is not http(s), or this platform can’t play the format. playback_failed: the stream couldn’t be loaded.

Supported formats

Check availability.formats, or call getPlayerAvailability(), before you choose which URL to pass. The player doesn’t support DRM or custom request headers. To protect a stream, use a signed URL that carries its token in the query string. Only one video can be open at a time. To close it from your page, call close() (or closePlayer()). Without the hook, use openPlayer(options, onEvent?), closePlayer() and getPlayerAvailability().