Skip to main content

Playlist

The Playlist API is defined by the Player interface, which is implemented by Quickplay player implementations. Playlists enable sequential playback of multiple media items.

Queue management allows for the addition or removal of media items at any position in the playlist—whether at the beginning, end, or in the middle—providing dynamic control over the playback sequence.

Create a Player​

//Create a audio player 
val audioPlayer = AudioPlayerServiceBuilder()
    .playbackProperties(playbackProperties) //Configures [PlaybackProperties] to apply for playback customization/optimization.
    .logger(logger) //Configures [Logger] used for call tracing.
    .mediaPlaylistItem(mediaPlaylistItem) //Adds media item to the builder
    .build() //This will return core audio player
// Create a video player
val player = PlayerBuilder()
  .mediaURL(url)
  .mediaType(MediaType.DASH)
  .drmScheme(DRMScheme.NONE)
  .drmLicenseURL("")
  .build(applicationContext)

Modifying the Playlist​

You can dynamically modify a playlist by adding, moving, removing or replacing media items. This can be done both before and during playback by calling the corresponding playlist API methods:

//Creating mediaPlaylistItem
val mediaPlaylistItem = MediaPlaylistItem.Builder(
  MediaPlaylistItem.BaseConfiguration(
    mediaURL,
    playbackSessionConfig.mediaType,
    playbackSessionConfig.mediaId,
    playbackSessionConfig.mediaMetadata,
    playbackSessionConfig.customMetadata
  )
).build()
// Adds a [MediaPlaylistItem] to the end of the playlist. 
player?.addMediaPlaylistItem(mediaPlaylistItem)
//Adds a [MediaPlaylistItem] at the given index of the playlist.   
player?.addMediaPlaylistItemAt(index, mediaPlaylistItem)
//Adds a collection of [MediaPlaylistItem]s to the end of the playlist. 
player?.addMediaPlaylistItems(listof(mediaPlaylistItems))
//Adds a collection of [MediaPlaylistItem]s at the given index of the playlist.
player?.addMediaPlaylistItems(index,listof(mediaPlaylistItems))
//Removes the [MediaPlaylistItem]s from the playlist.   
player?.removeMediaPlaylistItems(toIndex)
//Moves the [MediaPlaylistItem] at the current index to the new index.
player?.removeMediaPlaylistItems(fromIndex, toIndex)

Replacing and clearing the entire playlist are also supported:

//Replaces the [MediaPlaylistItem] at the given index of the playlist.
player?.replaceMediaPlaylistItem(index, mediaPlaylistItem)
//Moves the [MediaPlaylistItem] at the current index to the new index.   
Player?.moveMediaPlaylistItem(currentIndex, newIndex)
//Clears the playlist.     
player?.clearMediaPlaylist()
note

The player automatically handles modifications during playback in the correct way:

  • If the currently playing MediaItem is moved, playback is not interrupted and its new successor will be played upon completion.
  • If the currently playing MediaItem is removed, the player will automatically play the first remaining successor, or transition to the ended state if no such successor exists.
  • If the currently playing MediaItem is replaced, playback is not interrupted if none of the properties in the MediaItem relevant for the playback changed. For example, it's possible to update the MediaItem.MediaMetadata fields in most cases without affecting playback.
  • The queue player offers a variety of functions, including the following:

Shuffle Mode​

Enables or disables (default state) the shuffle mode for the playlist at any time. If the shuffle mode is enabled one can specify the shuffle order with the specified random seed.

// Returns the index of the current [MediaPlaylistItem] in the timeline, or the prospective index if the current timeline is empty.
var enableShuffleMode = true
var shuffledIndices = intArrayOf(3, 1, 0, 4, 2)// Optional 
var randomSeed = 1234567890L// Optional
player?.setShuffleMode(enableShuffleMode, shuffledIndices, randomSeed)
note

When in shuffle mode, the player will play the playlist in a precomputed, randomized order. All items will be played once and the shuffle mode can also be combined with playlist repeat mode to repeat the same randomized order in an endless loop. When shuffle mode is turned off, playback continues from the current item at its original position in the playlist. That the indices as returned by methods like[getCurrentMediaPlaylistItemIndex] always refer to the original, un-shuffled order. Similarly, [seekToNextMediaPlaylistItem] will not play the item at [getCurrentMediaPlaylistItemIndex] + 1, but the next item according to the shuffle order. Inserting new items in the playlist or removing items will keep the existing shuffled order unchanged as far as possible.

Repeat Modes​

Enables or disables the repeat mode for the playlist at any time.

player?.setRepeatMode(enableRepeatMode, repeatTimeline)
note
  • When repeat mode is enabled and repeatTimeline is set to true (which is the default), the entire playlist will loop indefinitely.
  • If repeat mode is enabled and repeatTimeline is set to false, the currently playing media item will repeat continuously while it’s playing.
  • When repeat mode is disabled (default setting), the playlist will not repeat, and the player will return to the default state after the last item has finished playing.

Seeking Within a Playlist​

Seek to specific positions within a playlist or navigate between items.

//Seeks to a position specified in milliseconds in the specified [MediaPlaylistItem].
player?.seekTo(mediaItemIndex, positionMs)
//Seeks to the default position of the previous [MediaPlaylistItem], which may depend on the current repeat mode and whether shuffle mode is enabled. Does nothing if [hasPreviousMediaPlaylistItem] returns [Boolean.false]. 
player.seekToPreviousMediaPlaylistItem()
//Seeks to the default position of the next [MediaPlaylistItem], which may depend on the current repeat mode and whether shuffle mode is enabled. Does nothing if [hasNextMediaPlaylistItem] returns [Boolean.false].
player.seekToNextMediaPlaylistItem()

Querying the Playlist​

Query the state of the playlist to retrieve information about the current media item, its position in the playlist, and other details, considering factors like repeat mode and shuffle mode.

// Returns whether a previous [MediaPlaylistItem] exists, which may depend on the current repeat mode and whether shuffle mode is enabled.
player?.hasPreviousMediaPlaylistItemAsync(callback)
//Returns the index of the current [MediaPlaylistItem] in the timeline, or the prospective index if the current timeline is empty.
player?.getCurrentMediaPlaylistItemIndexAsync(callback)
//Returns the index of the [MediaPlaylistItem] that will be played if [seekToNextMediaPlaylistItem] is called, which may depend on the current repeat mode and whether shuffle mode is enabled.
player?.getNextMediaPlaylistItemIndexAsync(callback)
//Returns the index of the [MediaPlaylistItem] that will be played if [seekToPreviousMediaPlaylistItem] is called, which may depend on the current repeat mode and whether shuffle mode is enabled.
player?.getPreviousMediaPlaylistItemIndexAsync(callback)
// Returns the index of the [MediaPlaylistItem] that will be played if [seekToPreviousMediaPlaylistItem] is called, which may depend on the current repeat mode and whether shuffle mode is enabled.
player?.getCurrentMediaPlaylistItemAsync(callback)
//Returns the currently playing [MediaPlaylistItem]. May be null if the timeline is empty.
player?.getMediaPlaylistItemCountAsync(callback)
//Returns the [MediaPlaylistItem] at the given index.
player?.getMediaPlaylistItemAtAsync(callback)
//Returns the Entire list of [MediaPlaylistItem].
player?.getAllMediaPlaylistItemsAsync(callback)