Skip to main content

Playlist

Playlist feature enables seamless management of video sequences within your applications. This guide provides a comprehensive overview of playlist configuration, events, and implementation methods.

Initializing the Player​

To start, you must create a player object which will handle the playlist logic.

// Initialize the player instance
guard let player = try? LuraPlayer(
    playerView: playerView,
    playerViewController: playerViewController
) else { return }

Monitoring Playlist Events​

Register a LuraEventListener to monitor the lifecycle of the playlist and handle specific playback states.

  • Initialization & Loading: Track when a playlist is initialized (PLAYLIST_INITIALIZED) or when a specific item is loaded (PLAYLIST_ITEM_LOADED).
  • Lifecycle Completion: Handle scenarios where the playlist finishes (PLAYLIST_COMPLETED) or is replaced by a new configuration (PLAYLIST_DISCARDED).
  • Automation Triggers: Monitor the auto-switch countdown (PLAYLIST_AUTO_SWITCH_COUNTER) or its cancellation (PLAYLIST_AUTO_SWITCH_ABORTED).
let listener: LuraEventListener = { [weak self] eventBundle in
    DispatchQueue.main.async {
        switch eventBundle.type {
        case .PLAYLIST_INITIALIZED:
            /* Playlist ready */
        case .PLAYLIST_ITEM_CHANGED:
            /* Item added or modified */
        case .PLAYLIST_ITEM_LOADED:
            /* Item loaded */
        case .PLAYLIST_COMPLETED:
            /* All items played */
        case .PLAYLIST_AUTO_SWITCH_COUNTER:
            /* Countdown started */
        case .PLAYLIST_AUTO_SWITCH_ABORTED:
            /* Countdown aborted */
        case .PLAYLIST_DISCARDED:
            /* Playlist was discarded */
        default:
            break
        }
    }
}
player.addListener(listener: listener)

Creating a Playlist Configuration​

The LuraPlaylistConfiguration defines the content queue and the logic for automatic transitions.

  • Configuration Array: Define a list of LuraPlayerConfiguration objects for each video in the queue.
  • Starting State: Set the startingIndex to define which video loads first (defaults to 0).
  • Playback Rules: Configure loop for repeating and autoSwitch to define the delay between videos.
// 1. Prepare the list of items
var items: [LuraPlayerConfiguration] = []
for i in 0 ..< 10 {
    let item = LuraPlayerConfiguration(
        lura: Lura(appKey: "YOUR_APP_KEY", assetId: "VIDEO_ID_\(i)")
    )
    items.append(item)
}

// 2. Define the playlist behavior
let playlistConfiguration = LuraPlaylistConfiguration(
    startingIndex: 0,
    loop: false,
    items: items,
    autoSwitch: LuraAutoSwitch(enabled: true, duration: 5.0),
    lura: Lura(appKey: "YOUR_APP_KEY", assetId: "playlist")
)

// 3. Start playback
player.setConfig(playlistConfiguration)

Queue Manipulation​

Modify the playlist structure in real-time without re-initializing the player.

  • Access Items: Use getPlaylistItems() for the full list or getPlaylistItem(index) for a specific configuration.
let items = player.getPlaylistItems() // Get all items

let item = player.getPlaylistItem(index: 0) // Get item by index
  • Add: Use addPlaylistItem(item, index) to insert new content.
let newItem = LuraPlayerConfiguration(
    lura: Lura(appKey: "YOUR_APP_KEY", assetId: "YOUR_ASSET_ID"),
    cast: LuraCastConfiguration(
        chromecast: LuraChromecastConfiguration(enabled: true)
    )
)
player.addPlaylistItem(item: newItem, index: 0)
  • Remove: Use removePlaylistItem(index) to delete item by index.
player.removePlaylistItem(index: 0)
  • Update: Use updatePlaylistItem(item, index) to refresh metadata like titles for a specific index.
if var item = player.getPlaylistItem(index: 0) {
    item.content?.title = "NEW_TITLE"
    player.updatePlaylistItem(item: item, index: 0)
}

Navigation & State Control​

Control which video is playing and monitor the player's position.

  • Manual Jumps: Use loadNextPlaylistItem(), loadPreviousPlaylistItem(), or loadPlaylistItem(index).
player.loadPreviousPlaylistItem() // Go to previous
player.loadNextPlaylistItem() // Go to next
player.loadPlaylistItem(index: 2) // Jump to index 2
  • State Tracking: Check the current position via getCurrentPlaylistItemIndex().
let currentIndex = player.getCurrentPlaylistItemIndex() // Get current index
  • Behavior Toggles: Adjust looping with setPlaylistRepeat(boolean).
player.setPlaylistRepeat(true)

Auto-Switch Mechanism​

The auto-switch mechanism governs how the player transitions between videos in a sequence automatically. Developers can enable, configure, or interrupt these transitions based on user interaction or business logic.

  • Toggle Mechanism: Enable or disable the automatic transition to the next video using setPlaylistAutoSwitchMechanism(boolean).
  • Adjust Duration: Change the countdown timer (in seconds) that appears before the next video starts with setPlaylistAutoSwitchDuration(duration).
  • Abort Transition: Call abortPlaylistAutoSwitch() to stop an active countdown and remain on the current item. This action triggers the PLAYLIST_AUTO_SWITCH_ABORTED event.
player.setPlaylistAutoSwitchMechanism(true) // Enable automatic transitions

player.setPlaylistAutoSwitchDuration(10.0) // Set a 10-second countdown delay

player.abortPlaylistAutoSwitch() // Interrupt the countdown