Playlist

Playlist support is implemented as a plugin that enables sequential playback of multiple media items over a single player: the playlist owns a queue of PlayerConfiguration items, opens them one after another and advances automatically when an item ends.

Setup

First, install the @castlabs/react-native-prestoplay-playlist package:

npm install @castlabs/react-native-prestoplay-playlist

Usage

Render a PlaylistProvider inside a PlayerProvider. The playlist drives the player of the enclosing provider; all player hooks keep working alongside the playlist hooks.

import {PlayerProvider, PlayerView} from '@castlabs/react-native-prestoplay';
import {PlaylistProvider} from '@castlabs/react-native-prestoplay-playlist';

const items = [
  {autoPlay: true, source: {url: '<URL_1>', type: ContentType.Hls}},
  {autoPlay: true, source: {url: '<URL_2>', type: ContentType.Hls}},
];

<PlayerProvider>
  <PlaylistProvider items={items}>
    <PlayerView />
  </PlaylistProvider>
</PlayerProvider>;

Use the hooks to drive and observe the playlist:

import {
  usePlaylist,
  useCurrentPlaylistItem,
} from '@castlabs/react-native-prestoplay-playlist';

function PlaylistControls() {
  const playlist = usePlaylist();
  const {item, index} = useCurrentPlaylistItem();

  return (
    <>
      <Button title="Previous" onPress={() => playlist.previous()} />
      <Text>{item?.metaData?.title ?? index + 1}</Text>
      <Button title="Next" onPress={() => playlist.next()} />
    </>
  );
}

The Playlist class can also be used directly — construct it synchronously after the Player, manage the queue with append/insert/remove/clear and navigate with start/next/previous/goTo. It emits ItemChanged, Modified, Ended and ItemFailed events.

Item load failures

Playlist item transitions happen natively, bypassing Player.open, so an item whose manifest cannot be loaded fails asynchronously. The failure is reported through the regular player error event with a typed code, and the playlist re-emits it as an ItemFailed event:

• ErrorCode.PlaylistItemTransitionFailed (fatal) — the item being navigated to failed to load.
• ErrorCode.PlaylistItemPrefetchFailed (recoverable, Android only) — an upcoming item failed to prefetch; playback of the current item continues.

playlist.addEventListener(PlaylistEventType.ItemFailed, event => {
  event.failedIndex; // index of the failed item, when reported
  event.item; // the failed PlayerConfiguration, when the index is known
  event.error; // the underlying PrestoPlayError
});

On Android the event carries the failed item's index, and the typed error is reported for DASH items; a broken HLS item keeps retrying without escalating to the playlist error (SDK limitation), so its failure surfaces only as recoverable download errors. On iOS the native playlist reports item creation failures without an index; on web item failures surface as regular player errors without playlist typing.

Media controls

When the now-playing plugin is installed, the platform media controls (lock screen, notification, media hub) can navigate the playlist items. See Next / Previous media controls in the Now Playing guide.

Limitations

• Clear and DRM-protected content cannot be mixed in the same playlist (iOS and Android). Playlist.append and Playlist.insert reject with a PrestoPlayError carrying the PlaylistMixedContent error code when an item would create such a mix, so the problem surfaces when the queue is built rather than as an opaque playback failure mid-queue:

  try {
    await playlist.append(protectedItem); // queue holds clear items
  } catch (e) {
    (e as PrestoPlayError).code; // ErrorCode.PlaylistMixedContent
  }

  Build separate playlists for clear and protected content instead.

• iOS supports HLS items only. The iOS implementation is backed by the native HLS queue, so DASH or progressive items cannot be part of a playlist on iOS. Playlist.append and Playlist.insert reject non-HLS items with a PrestoPlayError carrying the PlaylistUnsupportedContent error code.