The Kaltura Web Video Player provides a robust playlist plugin that allows rendering a playlist of entries with many configuration options, such as:

  • Render the playlist to the right, left, top or bottom of the Player
  • Render a vertical or horizontal playlist
  • Render the playlist on the publisher’s page outside of the Player iFrame
  • Auto-play, auto-continue, loop, custom header
  • Multiple playlists for the same Player
  • Custom renderer for playlist items
  • Hidden playlists provide playlist functionality without rendering the playlist itself
  • Next / Play buttons
  • Robust API allowing communicating with the playlist from Javascript

You can create a playlist functionality on your page by calling the Kaltura list API and using the Kaltura Web Video Player changeMedia notification; however, using the Web Video Player’s built-in playlist plugin will shorten your time to launch, simplify the management of your code, and provide better playback control.

Playlist Config Parameters

The playlist plugin exposes the following Flashvars configuration parameters to configure the behavior of the playlist:

  • containerPosition: Sets the playlist position to left, right, top and bottom
  • layout: Sets the playlist layout to vertical or horizontal
  • autoPlay: Starts playing the first clip upon load
  • autoContinue: Continues to the next clip when the currently playing clip ends
  • loop: Loops the playlist playback (jumps to the first clip when the last clip ends)
  • hideClipPoster: Hides the clip poster when switching to another clip
  • initItemEntryId: Indicates that the entryId that should be played first

Configure Playlist via Player Studio UIVars

When configuring the playlist via the Player Studio UIVars, remember that each new line is key=value pair:

playlistAPI.containerPosition=bottom
playlistAPI.layout=horizontal
playlistAPI.autoContinue=true

Configure Playlist via Embeded Flashvars

flashvars: {
	"playlistAPI": {
		"containerPosition" : "bottom",
		"layout" : "horizontal",
		"autoContinue" : true
	}
}

Common Player Playlist Best Practices

This section provides common best practices for customizing and configuring your playlist Player.

Size Relationship of the Web Video Player and its Playlist UI

When adding a playlist to your Player, the playlist UI will take screen space from the dimensions of your Player. As such, you should set your Player dimensions accordingly to accommodate for the added playlist UI dimensions.

  • For vertical playlist on the right or left, add the playlist width to the Player width. The default playlist width is 320px.
  • For horizontal playlists on the top or bottom, add the playlist height to the player height. The default playlist height is 113px.
  • When using onPage playlists (playlists that render outside of the Player iFrame) you don’t need to change the Player size.

Customizing the Playlist Item Renderer UI

You can use a custom CSS with your playlist to change playlist item CSS definitions, such as color and fonts.
This is done by setting the playlistAPI iframeHTML5Css property to your custom CSS file.

See the article on playlists with custom template and paging for a well-developed example of using a custom template to customize the playlist plugin UI and behavior.

Customizing the Playlist Item Renderer Displayed Data

You can change the data displayed for each clip by setting your own custom template for the playlist item renderer. The custom template overrides the base playlist template and defines which data to show, as well as the HTML markup used to render the data.

See the base playlist template on GitHub for details.

You can override this template with your own template by setting the playlistAPI.templatePath property to link to your custom template.

OnPage Playlist (Rendered on the Hosting Page)

You can decide to render the playlist UI on the web page in which the player is embeded.

To render the playlist on the hosting page, provide the div element ID into which you’d like the playlist to render, by setting the playlistAPI.clipListTargetId property. If you don’t specify a div element ID, the playlist will default to render below the Player.

See the article on playlists for an example of rendering the playlist UI on the hosting page.

When rendering a playlist on the hosting page, consider the following:

  • The OnPage playlist will work only when using dynamic Javascript embed, because iFrame embeds prevent access to the hosting page.
  • You can add your own logic to the playlist div element using Javascript, for example, add an expand/collapse functionality.
  • You may define a custom CSS for your playlist by setting the playlsitAPI.onPageCss1 property and link to your CSS file.

Playlist API, Properties, and Events

The playlistAPI plugin exposes a Javascript API that can be used to communicate with the playlist using the Kaltura Player API.

Playlist API Properties

Property Description
dataProvider Holds all of the playlist items
selectedIndex Current clip index
tabBar.selectedIndex Current playlist index when using multiple playlists

Examples

Here are some playlist API properties examples:

  • Play the second clip of the current playlist:
kdp.setKDPAttribute("playlistAPI.dataProvider", "selectedIndex", 1 );
  • To get the currently selected clip index:
kdp.evaluate( "{playlistAPI.dataProvider.selectedIndex}" ) );

See the article Using Playlist Properties Examples for more information about the Playlist API, properties, and events.

Playlist API Methods

Method Description
playlistPlayNext Play next clip
playlistPlayPrevious Play previous clip

Examples

Here are some playlist API method examples:

  • Play the next entry in the playlist:
player.sendNotification("playlistPlayNext");
  • Play the previous entry in the playlist:
player.sendNotification("playlistPlayPrevious");

Playlist API Events (Hooks)

Event Description
playlistReady Playlist is ready to play
playlistFirstEntry The first clip in the playlist starts playing
playlistMiddleEntry Any middle clip in the playlist starts playing
playlistLastEntry The last clip in the playlist starts playing
playlistPlayNext The next clip is requested
playlistPlayPrevious The previous clip is requested
playlistSelected When using multiple playlists, the user selects a specific playlist
EmptyPlaylistCustomError The playlist was loaded without entries

Examples

Here are some playlist API events (hooks) examples:

  • A hook to when the next entry in the list will be played:
player.kBind("playlistPlayNext", function(){
	console.log("the next entry will now play");
});
  • Detect when a faulty playlist is loaded:
player.kBind("EmptyPlaylistCustomError", function(){
	console.log("faulty playlist, let's switch playlist and/or report error");
});

See the article Registering to Playlist Events for details.

Playing a Stitched Video Playlist

The Kaltura backend provides the capability to stitch manual playlists dynamically, by combining video entries into a single continuos video stream.
The Kaltura Player leverages the ability to play stitched playlists as if they were a single video entry.
This is an important capability that supports use cases of dynamic personalized video experiences.
To play a stitched playlist, simply pass the ID of the manual playlist you would like to stitch as the entryId parameter.

Important note: in the case of a stitched playlist, use the entry.msDuration property to get the accurate milliseconds duration of the stitched playlist video instead of the duration property.

For example, if the playlist ID 0_kh14ze3t consists of six entrie, instead of loading it as a playlist player, where the end user loads each video on its own, you can stitch the videos and play them as one instead. To achieve this option, simply pass the ID of the playlist (0_kh14ze3t) in the entryId parameter of the embed code as follows:

kWidget.embed({
	"targetId": "myTargetEmbedDiv",
	"wid": "_811441",
	"uiconf_id": 33991361,
	"entry_id": "0_kh14ze3t"
});

Which Flashvars are Used for Changing the Playlist Items Text Color in a Playlist Player?

In general, two flashvars are required for this action:

  • [labelId].dynamicColor=true
  • [labelId].color1=[your color]
    Whereby [labelId] should be replaced with the ID of the label you would like to change.

For example (relevant for the “new” templates, not “basic”):

If you would like to change the name text color to red , add:

  • nameLabel.dynamicColor=true
  • nameLabel.color1=0xFF0000
  • hoverNameLabel.dynamicColor=true
  • hoverNameLabel.color1=0xFF0000

Note: In this example both nameLabel and hoverNameLabel were changed. In the new templates, each item is represented by two labels, one is used in regular state, and the other is used on mouse over. In the “basic” player, only one item needs to be changed. In this example it would be “ irLinkIrScreen” label. Please note that there’s a difference between the IDs of labels in the ”new” templates and in the “basic” templates.

Here is a complete list of playlist item renderer labels and their matching IDs:

Playlist Item ID in “new” template:regular / hover ID in “basic” template
Name nameLabel / hoverNameLabel irLinkIrScreen
Description descriptionLabel / hoverDescriptionLabel irDescriptionIrScreen
Duration durationLabel / hoverDurationLabel irDurationIrScreen
plays playsLabel / hoverPlaysLabel irPlaysIrScreen
rank rankLabel / hoverRankLabel irRankIrScreen
votes votesLabel / hoverVotesLabel irVotesIrScreen
tags tagsLabel / hoverTagsLabel irTagsIrScreen
categories adminTagsLabel / hoverAdminTagsLabel irAdminTagsIrScreen
Created At createdAtLabel / hoverCreatedAtLabel irCreatedAtIrScreen
Created By createdByLabel/ hoverCreatedByLabel irCreatedByIrScreen