Playlists

PlaylistAPI provides playlist loading, navigation, and item management for a PlayerAPI instance. Playlist implementations are exposed by plugins.

Both modes register every item they start with the SDK accounting, using the PlayerConfiguration of that item. An item is registered once, so changing the list of a playing playlist does not register the played item again.

Playlist modes

Two modes are currently provided.

PlaylistMode.nativeQueue is the most optimal mode on the Apple platforms, because it plays the items on the native AVQueuePlayer. Prefer it whenever the playlist holds HLS items only.

PlaylistMode.playerRecreate is meant for playlists that mix MPEG-DASH and HLS items, which the native queue cannot do. Since it does not play the items on the native queue, it may not be supported in purely Apple specific use cases.

Player Recreate

PlaylistMode.playerRecreate is provided by the core SDK, so it is available without any additional plugin, and it works with every player engine, HLS and MPEG-DASH alike. Mixing MPEG-DASH and HLS items in a single playlist is the use case it is meant for.

Every item is played by its own player instance. When the active index changes, the player of the previous item is released and a new one is built and opened for the selected item. Items are therefore not prepared upfront, and each item may use a completely different configuration, including a different engine or DRM system.

Every item is opened with its own PlayerConfiguration, so per item settings such as autoPlay and startTime are applied on every item change. An item with autoPlay set to false therefore stops the playlist until playback is resumed.

The playlist has to be attached to a player created by PRESTOplaySDK.player(). A player created by PRESTOplaySDK.player(for:) is bound to the configuration it was built with and reports ErrorType.playlist_error when a playlist is loaded on it.

load(items:) prepares the first item without starting playback, exactly as PlayerAPI.load(config:) does without a playlist, so the application opens the player as usual. Every following item is opened by the playlist itself.

Native Queue

PlaylistMode.nativeQueue is provided by HLSPlugin and is limited to native HLS playback, where it is the most efficient option.

Uses AVQueuePlayer internally, so the playlist is handled by the platform itself. The queue keeps upcoming items prepared and handles transitions between items, which makes this the most optimal mode on the Apple platforms.

Basic usage

Enable HLSPlugin during SDK setup:

import PRESTOplay
import CastlabsApple

let setupError = PRESTOplaySDK.shared.setup("LICENSE", [HLSPlugin()])

Create a player, create a playlist, and load items:

let player = PRESTOplaySDK.shared.player()
let playlist = PRESTOplaySDK.shared.playlist(for: player, mode: .nativeQueue)!

let items = [
    PlayerConfiguration(with: URL(string: "https://example.com/stream-1.m3u8")!),
    PlayerConfiguration(with: URL(string: "https://example.com/stream-2.m3u8")!)
]

playlist.load(items: items)

playlist.onItemChange = {
    print("Current index: \(playlist.getCurrentItemIndex())")
}

playlist.onPlaylistEnded = {
    print("Playlist ended")
}

playlist.nextItem()
playlist.previousItem()
playlist.playItem(at: 1)

let item3 = PlayerConfiguration(with: URL(string: "https://example.com/stream-3.m3u8")!)
playlist.addItem(item3)
playlist.removeItem(at: 0)

Create a playlist without passing mode to use the default PlaylistMode.playerRecreate:

let defaultPlaylist = PRESTOplaySDK.shared.playlist(for: player)

Configure loop behavior with loopList:

let loopingPlaylist = PRESTOplaySDK.shared.playlist(
    for: player,
    mode: .nativeQueue,
    loopList: true
)

loopList defaults to true. When false, navigation stops at the queue boundaries. playItem(at:) keeps the current item unchanged when the index is out of bounds.