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
val player = LuraPlayer(context = context, playerView = playerView)

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).
val listener: LuraEventListener = LuraEventListener { event: LuraEvent ->
    when (event.type) {
        LuraEventType.PLAYLIST_INITIALIZED -> { /* Playlist ready */ }
        LuraEventType.PLAYLIST_ITEM_CHANGED -> { /* Item added or modified */ }
        LuraEventType.PLAYLIST_ITEM_LOADED -> { /* Item loaded */ }
        LuraEventType.PLAYLIST_COMPLETED -> { /* All items played */ }
        LuraEventType.PLAYLIST_AUTO_SWITCH_COUNTER -> { /* Countdown started */ }
        LuraEventType.PLAYLIST_AUTO_SWITCH_ABORTED -> { /* Countdown aborted */ }
        LuraEventType.PLAYLIST_DISCARDED -> { /* Playlist was discarded */ }
    }
}
player.addListener(dispatcher = Dispatchers.Main, listener = listener)

Creating a Playlist Configuration​

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

  • Configuration Array: Define a list of LuraConfiguration objects for each video in the queue.
  • Starting State: Set the startingIndex to define which video loads first (defaults to 0).
  • Playback Rules: Configure repeat for looping and autoSwitch to define the delay between videos.
// 1. Prepare the list of items
val items: List<LuraConfiguration> = List(10) { index ->
    LuraConfiguration(
        lura = Lura(appKey = "YOUR_APP_KEY", assetId = "VIDEO_ID_$index")
    )
}

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

// 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.
val items = player.getPlaylistItems() // Get all items

val item = player.getPlaylistItem(0) // Get item by index
  • Add: Use addPlaylistItem(item, index) to insert new content.
val newItem = LuraConfiguration(
    lura = Lura(appKey = "YOUR_APP_KEY", assetId = "YOUR_ASSET_ID"),
    cast = LuraCastConfiguration(
        chromecast = LuraChromecastConfiguration(enabled = true)
    )
)
player.addPlaylistItem(item = newItem)
  • 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.
val item = player.getPlaylistItem(0)
val updatedItem = item?.copy(content = item.content?.copy(title = "NEW_TITLE"))
if (updatedItem != null) {
    player.updatePlaylistItem(item = updatedItem, 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().
val 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 between videos

player.abortPlaylistAutoSwitch() // Interrupt the countdown