The Player component provides an easy way to display video or audio.
Player
component provides an easy way to display video or audio.
It automatically handles different source types from a Livepeer provider, such
as WebRTC, MP4, and HLS. These are seamlessly integrated so that playback has
low latency under all network conditions.
useCreateAsset
or useCreateStream
, and the playbackId
was passed to the viewer.PosterImage
React component, which is
described in more detail below in poster
configuration.Browser | Version |
---|---|
Chrome | 102+ |
Chrome for Android | 105+ |
iOS Safari | 12.2+ |
Edge | 103+ |
Safari | 13.1+ |
Firefox | 103+ |
Opera | 89+ |
Samsung Internet | 17+ |
UC Browser | 13.4+ |
Firefox Android | 104+ |
Opera Mini | all |
playbackId
for an
asset
or
Stream,
or src
, a media source URL. One of these is required.
playbackId
passed to the Player
can be either a short playback ID which
is created on asset/stream creation, or, for an asset, an IPFS CID. If the
provided IPFS CID or IPFS/Arweave URL has not been uploaded yet, it can be
auto-uploaded and played back - see autoUrlUpload
for more
details.
src
that is not from a provider will not be transcoded
(unless autoUrlUpload
is used), and will take up
significant network bandwidth. It’s highly recommended to upload media to a
provider, and serve content to viewers with a playbackId
.src
URL which can correspond to any
common video or audio which most browsers support. See
caniuse video format for more
details on browser support.
src
(e.g. not a Studio
playback URL).src
is an IPFS/Arweave URL, it can be auto-uploaded and played back -
see autoUrlUpload
for more details.
jwt
playback policy.
Alternatively, accessKey
can be used for a webhook
playback policy. See the
Access Control example for more
details.
webhook
playback policy.
Alternatively, onAccessKeyRequest
can be used to return this access key in a
callback. See the
Access Control example for more
details.
accessKey
above, this is used to gate content based on a webhook
playback
policy. This is used instead of the accessKey
prop, and can be asynchronous
and accepts any Promise or simple callback which returns a string. See the
Access Control example for more
details.
priority
. You should use the
priority property on any media detected as the
Largest Contentful Paint (LCP) element. It may be
appropriate to have multiple, as different content may be the LCP element for
different viewport sizes.
Should only be used when the media is visible above the fold. Defaults to false.
true
. If this does not succeed in playing back (commonly
due to a slow network or connectivity issues), the Player will automatically
fall back to HLS playback. Also, if the stream contains B-frames (bidirectional
frames, which are common for users streaming with OBS or other streaming apps),
the Player will automatically switch to HLS, so that out-of-order frames are not
displayed.
"force"
, which forces WebRTC and disables fallback to
HLS. This is not a recommended default unless your application requires low
latency (and should not play if low latency is not available), due to the
possible connectivity issues which WebRTC can face, which HLS is not subject to.
Player
-
please reach out on Discord if you are interested.onClipStarted
,
onClipCreated
, and onClipError
callbacks for clips.
onClipStarted
, onClipCreated
, and onClipError
callbacks
to control UI outside of the Player, to show toasts or other loading
indicators, as well as track the status of the Asset which is created and
processed. See useAsset
for how to poll the status of the asset.title
for the content. This is highly recommended, since it is used for
accessibility labels in the Player. If you do
not want to show the title visually, see showTitle
.
16to9
.
false
.
poster
can be a simple image URL, and it will be rendered with a regular
img
HTML tag.img
above. In the below example, we show the use of
Next.js Image to
render an optimized image, which will automatically handle slow network
conditions/different device sizes.true
.
constant
and sdpTimeout
.
A constant=true
boolean indicates that audio will not be distorted if the
playhead falls behind the livestream. This is usually used for music
applications, where audio quality and consistency is more important than
latency.
The sdpTimeout
config sets the amount of time in milliseconds that the Player
will wait for a response from SDP negotiation before falling back to HLS.
autoPlay
is specified, muted
will be forced to be true
. This is
enforced in many modern browsers.
contain
. cover
is usually used when there is a
guarantee that the aspectRatio
matches the content displayed in the Player.
false
. See children for an example on how to use the
underlying <PictureInPictureButton />
.true
.
fallback
is specified, while the URL upload is being processed in the
background, the video will start non-transcoded playback immediately (defaulting
to w3s.link
for IPFS and arweave.net
for Arweave). Once this finishes, the
Player will switch to playing from the transcoded version from the Livepeer
provider. To show/hide the indicator of current upload progress, see
showUploadingIndicator
.
It is highly recommended for the best playback experience to upload from an
Arweave/IPFS URL using useCreateAsset
(with the format ipfs://<CID>
or
ar://<HASH>
) before presenting the content to the user - the first view with
automatic URL upload can take a few minutes, then it will be permanently cached
and play back quickly.
src
or
playbackID
to the Player, and it will automatically detect if it is a
dStorage identifier and attempt to play from a cached version. If the API does
not have a cached version with the corresponding ID, the Player will upload
the content using IPFS/Arweave, and then start playing the transcoded content
back. This may take a few minutes. If fallback
is specified, it will attempt
to play back instantly from the provided gateway or default gateway.autoUrlUpload
. Defaults to true
-
only used with autoUrlUpload
.
LivepeerConfig
for any global app
styles, and the theme
prop to override those styles on a per-Player basis.
Player
default controls
for more details on how the ControlsContainer
component is used.This can be used alongside renderChildrenOutsideContainer
to render the
children outside of the aspect ratio container. This is used for custom
controls, so children of the Player can use useMediaController
without any
parent elements.OfflineStreamError
component.
PrivateStreamError
component.
GenericError
component.
ref
passed to the underlying media element. Useful when integrating with third party
tools, or when access to the underlying video element is needed (usually it
isn’t!). Simple refs are not supported - only callback refs (which will be
called when the underlying media element is set/updated on initial render).
playbackStatusSelector
to limit state updates. This allows developers to use
the underlying state of the Player component in their UI.
usePlayerList
is currently only available for React Native, since there are
List primitives which provide a standard API to hook into. We are working on a
React version.usePlayerList
hook makes it easy to preload and display videos in a
FlatList
-compatible list, by using
viewabilityConfigCallbackPairs
to trigger preloading on upcoming videos, and automatically playing/pausing
media when it is shown/hidden from the list.
See our
Expo sample app for
a real-world example.
data
array which is passed into the hook, to add
Player-specific props to it. The viewabilityConfigCallbackPairs
prop is also
returned, which must be passed into the FlatList
-compatible list to maintain
the correct preloading/playing states for the Player(s).
item.playerProps
.
itemPreload
is set to 8 and there are 30 items in the Player
list, when the user is currently viewing the 5th item, the 6th-14th Players will
actively preload in the background. Defaults to 3.
null
to unset. See
FlatList’s viewabilityConfig
for more details.
null
to unset. See
FlatList’s viewabilityConfig
for more details.
viewabilityConfig
for more details.
recordInteraction
is called after render. Defaults to false. See
FlatList’s viewabilityConfig
for more details.
prefetchPlayer
, which makes it easy to prefetch the data used internally for
the Player during server-side rendering.
First, you add a
getStaticProps
function to the page which you want to prefetch data on. The props should match
the Player props to ensure that the correct data is prefetched.
_app.tsx
to pass the dehydratedState
in pageProps
to
the LivepeerConfig. We also move the livepeerClient
into a useMemo hook so
that a new client is created on each request.
clearClient
boolean which should be used to ensure that the client cache
is not reused across users.
x2.5
). This value is then compared to the
rendition widths, and the renditions are prioritized based on the distance
between these values. This results in a choice of a rendition which is close to
the screen size without visual quality issues. For instance, a device with a
1280 pixel width would compute 1280px * 2.5 = 3200px
, and then sort the MP4
renditions by which are closest to this value.