A guide on using and configuring live media playback.
Live streams are currently supported via the HLS provider which uses hls.js, and in browsers that natively support HLS. The player will prefer using hls.js over the native engine when supported to enable a consistent and configurable experience across vendors.
Stream TypeSection titled Stream Type
See the Stream Types section for how to to configure the player for various playback/content types.
Live DVRSection titled Live DVR
Live DVR (Digital Video Recording) refers to live streams that support pausing, seeking back, and overall playing the live stream at the desired pace. Whether DVR is supported or not helps determine whether seeking operations are permitted during live streams, and consequently how to best configure UI components such as the time slider.
The player will try to infer whether a stream supports DVR but generally it’s inaccurate. Prefer
using the stream type property to specify whether DVR is supported or not. In
minLiveDVRWindow can be used to specify the minimum seekable length in seconds
before seeking operations are permitted (default value is 60 seconds):
The min DVR window is used in the following check:
seekableWindow >= minLiveDVRWindow.
Live EdgeSection titled Live Edge
The live edge is a window from the starting edge of the live stream (
liveEdgeStart) to the
furthest seekable part of the media (
seekableEnd). The media-ui-extensions live edge proposal
covers the complexities involved in determining the live edge and why it can’t be a single point in
time, but rather a window.
The method used to determine the starting edge of the live stream depends on the HLS playback engine used:
- The HLS provider uses the
liveSyncPositionprovided by hls.js to determine the live edge start. The starting edge is determined by a delay that’s set by the
liveSyncDurationCountconfiguration which represents a multiple of
EXT-X-TARGETDURATION(default multiple is safely 3).
- The native playback engine on iOS Safari simply uses the furthest seekable part of the
ToleranceSection titled Tolerance
liveEdgeTolerance value is used to further apply a safety buffer to account for buffering
delays or accidental skips. The default value is 10, meaning the playback position can be
10 seconds behind live edge start and still be considered at the edge. It can be configured on the
player like so:
ConditionsSection titled Conditions
The player determines whether it’s at the live edge by checking the following conditions:
- If seeking is not permitted (i.e.,
canSeekis false) then we’re always at the edge. This will be falsy if there’s no DVR support, seekable length is infinity, or the seekable window is not equal to
- The user hasn’t intentionally seeked behind the edge by more than 2 seconds.
- The current playback time is greater than
liveEdgeStart(minus the safety
If the user naturally falls behind through buffering delays or by pausing, the player will consider the user not to be at the edge and not catch them up automatically. The user can seek back to the edge by scrubbing to the end of the time slider or pressing the live indicator.
You can also programmatically seek to the edge by calling the
seekToLiveEdge method on the
player like so:
The following components will adapt to a live stream:
<Time>: Displays the text “LIVE” if the live stream is not seekable.
<TimeSlider>: Disabled if seeking operations are not permitted for the live stream. When disabled, it can not be interacted with, no pointer/drag events will be fired, and the thumb will pinned to the right edge.
<SliderValue>: Displays a negative offset from the current live time when used inside the time slider. The text “LIVE” will be displayed if the stream is not seekable.
StateSection titled State
The following live properties are available on the media store:
streamType: Indicates the type of live stream. This can be provided by you or inferred by the player.
live: Whether the current stream is live.
liveEdge: Whether the current stream is inside the live edge window (including the live edge tolerance buffer).
liveEdgeTolerance: The number of seconds that the current time can be behind the live edge start and still be considered at the edge.
liveEdgeWindow: The length of the live edge window in seconds starting from start of the live edge and ending at seekable end. If the duration of the stream is infinity or the stream is non-live then this value will default to 0.
minLiveDVRWindow: The minimum seekable length in seconds before media seeking operations are permitted on live DVR streams. The default value is 30.
canSeek: Whether seeking is permitted for the live stream. This value will be false if there is no DVR support, or the seekable window is smaller than the minimum live DVR window.
seekableStart: The earliest time in seconds at which media can be seeked to. Generally, this is zero, but for live streams it may start at a non-zero value. This value can be infinity.
seekableEnd: The furthest time in seconds at which media can be seeked to. This will default to infinity if no seekable range is found.
seekableWindow: The length of the seekable part of the media in seconds starting at seekable start and ending at seekable end. This value can be infinity.
userBehindLiveEdge: Whether the user has intentionally seeked behind the live edge. The user must’ve seeked 2 or more seconds behind during a live stream for this to be considered true.
StylingSection titled Styling
The following media data attributes are available for styling based on the current live state:
EventsSection titled Events
The following events are available for detecting live state changes: