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. Importing the Lura Player

Monitoring Playlist Events

Register an event listener 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).

sub init()
    m.player.observeField("event", "onEvent")
end sub

sub onEvent(msg) 
    event = msg.getData()
    if (event.type = "PLAYLIST_INITIALIZED") {
        ' Playlist ready
    }
    else if (event.type = "PLAYLIST_ITEM_CHANGED") {
        ' Item added or modified
    }
    else if (event.type = "PLAYLIST_ITEM_LOADED") {
        ' Item loaded
    }
    else if (event.type = "PLAYLIST_COMPLETED") {
        ' All items played
    }
    else if (event.type = "PLAYLIST_AUTO_SWITCH_COUNTER") {
        ' Countdown started
    }
    else if (event.type = "PLAYLIST_AUTO_SWITCH_ABORTED") {
        ' Countdown aborted
    }
    else if (event.type = "PLAYLIST_DISCARDED") {
        ' Playlist was discarded
    }
end sub

Creating a Playlist Configuration

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

danger

Always use quoted keys (e.g., "assetId" instead of assetId) when defining configuration objects in BrightScript.

• 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 repeat for repeating and autoSwitch to define the delay between videos.

' 1. Prepare the list of items
items = []

' Fill the items with your own assets
for i = 0 to 9 
    items.push({
        "lura": {
            "appKey": "<YOUR_APP_KEY>",
            "assetId": "<VIDEO_ID>" + i,
        }
    });
end for

' 2. Define the playlist behavior
config = {
    "startingIndex": 0,
    "repeat": false,
    "items": items,
    "autoSwitch": {
        "enabled": true,
        "duration": 5.0
    },
    "lura": {
        "appKey": "<YOUR_APP_KEY>",
        "assetId": "<PLAYLIST_ID>"
    }
    ...
};
' 3. Start playback
player.callFunc("setConfig", config);

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.

items = player.callFunc("getPlaylistItems"); ' Get all items
item = player.callFunc("getPlaylistItem", 0); ' Get item by index

• Add: Use addPlaylistItem(item, index) to insert new content.

newItem = {
    "lura": {
        "appKey": "YOUR_APP_KEY",
        "assetId": "YOUR_ASSET_ID",
    },
}
player.callFunc("addPlaylistItem", newItem, 0);

• Remove: Use removePlaylistItem(index) to delete item by index.

player.callFunc("removePlaylistItem", 0);

• Update: Use updatePlaylistItem(item, index) to refresh metadata like titles for a specific index.

item = player.callFunc("getPlaylistItem", 0);
if (item) {
    item.content.title = "NEW_TITLE";
    player.callFunc("updatePlaylistItem", item, 0);
}

Navigation & State Control

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

• Manual Jumps: Use loadNextPlaylistItem(), loadPreviousPlaylistItem(), or loadPlaylistItem(index).

player.callFunc("loadPreviousPlaylistItem"); ' Go to previous
player.callFunc("loadNextPlaylistItem"); ' Go to next
player.callFunc("loadPlaylistItem", 2); ' Jump to index 2

• State Tracking: Check the current position via getCurrentPlaylistItemIndex().

currentIndex = player.callFunc("getCurrentPlaylistItemIndex"); ' Get current index

• Behavior Toggles: Adjust looping with setPlaylistRepeat(boolean).

player.callFunc("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.callFunc("setPlaylistAutoSwitchMechanism", true); ' Enable automatic transitions
player.callFunc("setPlaylistAutoSwitchDuration", 10.0); ' Set a 10-second countdown delay
player.callFunc("abortPlaylistAutoSwitch"); ' Interrupt the countdown