Livepeer React v4.0.0+
was a complete rewrite of the library to support
video primitives.
Introduction
This migration guide is designed to assist you in transitioning from the
previous version of the @livepeer/react
library to the new major release. This
update is a significant overhaul aimed at addressing several key issues with the
previous releases.
Before you start
Major changes
- The library has been rewritten to offer unstyled, composable
<Player />
and
<Broadcast />
primitives based on
Radix UI.
- The components are now highly composable, moving away from the monolithic
design of the previous versions.
- All components support the
asChild
pattern, where the component will instead clone the part’s child and passing
it the props and behavior required to make it functional.
- For instance:
<FullscreenTrigger asChild>{...}</FullscreenTrigger>
will
not render a DOM element, and instead copy all of it’s properties to the
child component, which will behave as a fullscreen trigger.
- The components are more aligned with web standards, allowing direct prop
passing to elements (notably the
Video
component).
- Automatic data fetching and CORS API key usage within components have been
removed to enhance security and reduce developer confusion.
- We highly recommend moving away from CORS API keys and making API requests
from your backend. We plan to deprecate CORS API keys in the future.
- The React Native package has been deprecated. The package was not
well-maintained and we have focused on web components for Livepeer React.
Migration steps
Primitives
Replace your usage of the single <Player />
and <Broadcast />
components
with the new composable primitives. These include:
Player
<Player.Root />
<Player.Container />
<Player.Video />
<Player.Controls />
<Player.LoadingIndicator />
<Player.FullscreenTrigger />
- …and more.
Check out our complete example for how these can
be composed to build a video player, modeled after the 3.x versions of the
Player.
Broadcast
<Broadcast.Root />
<Broadcast.Container />
<Broadcast.Video />
<Broadcast.Controls />
<Broadcast.SourceSelect />
<Broadcast.VideoEnabledIndicator />
- …and more.
Check out the complete example for how these
can be composed to build a complete in-browser broadcast experience.
Data fetching
- All data fetching logic from the Livepeer Studio API has been removed from
the Player and Broadcast components.
- This includes all of the
useCreateAsset
, useStream
, etc.
- You will now need to use the
livepeer
JS SDK (or
another SDK, depending on your applications’s API
language) for data fetching and interaction.
- You must now make API requests in your backend to fetch playback info for a
playback ID.
- Use
getSrc
utility function with
the Player or getIngest
utility function with Broadcast to parse the JSON responses from the API.
Unstyled by default
- The components are now unstyled by default. You will need to apply your own
styles.
- Refer to the documentation for example styles that mimic the previous
versions, which you can customize as needed.
Recommendations
- Embrace the flexibility of Composable components. Use the
asChild
pattern for more control over the rendering of components.
- Use automatic poster images by passing the
playback info response to
getSrc
.
- There are no changes required to resume progress on fallback, which
resumes playback from where it was interrupted when an error occurs, and the
player falls back to another playback protocol.
- Use
useMediaContext
for building custom components. See the implementation
of the primitives as an example of how to implement them.
Callouts
- Note the discontinuation of
autoUrlUpload
and direct IPFS playback. See
below for recommendations for how to migrate from this.
- The new build system includes
use client
and use server
directives in the
output. This means that you can directly import the client components into a
RSC and you don’t need to wrap them. If you don’t use React Server
Components, this doesn’t affect you.
React Native
The React Native package has been deprecated. Consider seeking alternative
solutions or consulting the team for future support plans.
Replacing autoUrlUpload
To replace the usage of autoUrlUpload
, use the following pseudocode as a guide
for how the logic used to work on the frontend.
import { Livepeer } from "livepeer";
import { parseCid, parseArweaveTxId } from "@livepeer/core/utils";
const livepeer = new Livepeer({
apiKey: process.env.STUDIO_API_KEY ?? "",
});
const possibleIpfsCid =
"https://cloudflare-ipfs.com/ipfs/bafybeie2hgozfameyzawq6kkzc3tuf67g4kkufm4hoefxczpfe2fen2riu";
// if the source contains a CID or Arweave TX ID, these utility functions will parse out the
// ID and be non-null
const decentralizedSource =
parseCid(possibleIpfsCid) ?? parseArweaveTxId(possibleIpfsCid);
if (decentralizedSource?.id) {
// we check if the CID/Arweave ID already exists in the playback info endpoint
const response = await livepeer.playback.get(decentralizedSource.id);
if (!response.playbackInfo) {
// the CID/Arweave ID doesn't exist, so we import it by the URL
await livepeer.asset.createViaURL({
// this is the IPFS CID, or Arweave transaction ID
name: decentralizedSource.id,
// the formatted IPFS CID or Arweave tx ID as a URL:
// ipfs://{CID} or ar://{CID}
url: decentralizedSource.url,
});
// ...continue to poll the created asset and use the decentralized identifier
// to get the playback info, and pass to `getSrc` to use with <Player.Root />
const imported = await livepeer.playback.get(decentralizedSource.id);
const source = getSrc(imported.playbackInfo);
return source;
}
}