Implementing Playlists

Product(s)
Video Cloud
Brightcove Player
Role(s)
Player Developer
Task(s)
Create & Use Playlists
Topic(s)
Playlists

In this topic, you will learn the how to use playlists to display a collection of videos that are grouped together in a particular order for playback in a Brightcove Player.

Overview

When using playlists the first decision you should make is where do you want the playlist in relation to the player. Normally, when using Brightcove Player you see playlists to the right of the player vertically or below the player horizontally. (As you will see later in this document, you have flexibility to locate the playlist in other places.) Implementations of a vertically and horizontally placed playlist follow.

Vertical playlist example

The following shows a vertical playlist:

Horizontal playlist example

The following shows a horizontal playlist:

Along with the direction of the playlist, you will also need to determine the HTML code you wish to use for implementation, Standard or Advanced. The following shows the four resulting options you have:

playlist enable studio

Implementation overview

To use playlists, complete the follow tasks:

  1. Create a playlist either in Studio or manually using JavaScript.
  2. Enable your player to use playlists using Studio's player properties Styling option.
  3. Implement the playlist using either the Standard (iframe) player or the Advanced (in-page embed) implementation.
  4. If you wish to programmatically control the playlist, use the Playlist API.

Create playlist

The following three documents show how to create playlists. The first two using Video Cloud Studio and the last one using JavaScript.

To create a playlist you need to use the player's playlist() method along with JSON to define the videos in the playlist. The following code shows an example.

<script type="text/javascript">
videojs.getPlayer('myPlayerID').ready(function() {
    var myPlayer = this;
    myPlayer.playlist([{
        "sources": [{
            "src": "http://solutions.brightcove.com/bcls/assets/videos/Sea_SeaHorse.mp4", "type": "video/mp4"
        }],
        "name": "Seahorse",
        "thumbnail": "http://solutions.brightcove.com/bcls/assets/images/Sea_Seahorse_poster.png",
        "poster": "http://solutions.brightcove.com/bcls/assets/images/Sea_Seahorse_poster.png"
    }, {
        "sources": [{
            "src": "http://solutions.brightcove.com/bcls/assets/videos/Sea_Anemone.mp4", "type": "video/mp4"
        }],
        "name": "Sea Anemone",
        "thumbnail": "http://solutions.brightcove.com/bcls/assets/images/Sea_Anemone_poster.png",
        "poster": "http://solutions.brightcove.com/bcls/assets/images/Sea_Anemone_poster.png"
    }, {
        "sources": [{
            "src": "http://solutions.brightcove.com/bcls/assets/videos/Tiger.mp4", "type": "video/mp4"
        }],
        "name": "Tiger",
        "thumbnail": "http://solutions.brightcove.com/bcls/assets/images/Tiger_poster.png",
        "poster": "http://solutions.brightcove.com/bcls/assets/images/Tiger_poster.png"
    }, {
        "sources": [{
            "src": "http://solutions.brightcove.com/bcls/assets/videos/Sea_ClownFish.mp4", "type": "video/mp4"
        }],
        "name": "Clownfish",
        "thumbnail": "http://solutions.brightcove.com/bcls/assets/images/Sea_ClownFish_poster.png",
        "poster": "http://solutions.brightcove.com/bcls/assets/images/Sea_ClownFish_poster.png"
    }, {
        "sources": [{
            "src": "http://solutions.brightcove.com/bcls/assets/videos/Sea_LionFish.mp4", "type": "video/mp4"
        }],
        "name": "Lionfish",
        "thumbnail": "http://solutions.brightcove.com/bcls/assets/images/Sea_LionFish_poster.png",
        "poster": "http://solutions.brightcove.com/bcls/assets/images/Sea_LionFish_poster.png"
    }]);
});
</script>

Enable player

You can use Studio to enable your player to use playlists. Follow these steps to do so:

  1. Open the PLAYERS module and either create a new player or locate the player to which you wish to enable for playlists.
  2. Click the link for the player to open the player's properties.
  3. In Player Information, for the Player Type click the Playlist radio button.
  4. Click Save.
  5. Click Styling in the left navigation menu.
  6. Choose your desired Playlist Type:
    enable playlist in Studio
  7. Click Playback in the left navigation menu.
  8. Check the radio buttons for the palylist options you wish to enable:
    playback section playlist options
  9. To publish the player, click Publish & Embed > Publish Changes.
  10. To close the open dialog, click Close.

Standard (iframe) player

Once you have a playlist to use, and have enabled your player to use a playlist, you are ready to actually utilize the playlist with a player. As usual you have the Standard and Advanced player implementations available. In this section, instructions for using the playlist with the Standard implementation are shown. When using the Standard/Vertical Playlist implementation, the playlist will appear on the right side of the player, as you have seen in the example at the top of this document.

You publish a playlist very similarly as you publish a video. In Studio's MEDIA module, select your playlist then click the Publish Playlist button. Be sure to select the correct player.

playlist enable studio

Once you have published, you then choose your code. In this section, the Standard (iframe) code is demonstrated. You can select options for the code (highlighted) that deal with player sizing.

playlist enable studio

If you wish to have a responsive player, which is an excellent option, the player code appears as shown here:

<div style="position: relative; display: block; max-width: 640px;">
  <div style="padding-top: 56.25%;">
    <iframe src="https://players.brightcove.net/1752604059001/S13cJdUBz_default/index.html?playlistId=5718313430001"
      allowfullscreen
      webkitallowfullscreen
      mozallowfullscreen
      style="position: absolute; top: 0px; right: 0px; bottom: 0px; left: 0px; width: 100%; height: 100%;"></iframe>
  </div>
</div>

The two div elements and associated attributes are what make the player responsive.

Adjust padding-top for a horizontal playlist

The code just displayed is for the player ONLY. If you are using a horizontal playlist, you must manually adjust the code a bit to make room for the playlist. Use the following table to correctly change the <div style="padding-top: 56.25%;"> value.

Aspect Ration padding-top with player only padding-top with horizontal playlist
4:3 75% 93.75%
16:9 56.25% 70.31%

This means if you are using a video of 16:9 aspect ration, the padding-top value should appear as follows:

<div style="padding-top: 70.31%;">

Manually changing the playlist

If you wish to change the playlist used with the iframe implementation you simply need to change the src attribute of the iframe. If using an ID:

<iframe src="https://players.brightcove.net/.../index.html?playlistId=1754200320001"

or if you are using a reference ID:

<iframe src="https://players.brightcove.net/.../index.html?playlistId=ref:myrefid001"

Advanced (in-page embed) player

Once you have a playlist to use, and have enabled your player to use a playlist, you are ready to actually utilize the playlist with a player. As usual you have the Standard and Advanced player implementations available. In this section, instructions for using the playlist with the Advanced implementation are shown. Just below is a screenshot of an Advanced player implementation with a vertical playlist. Note that when using the Advanced/Vertical Playlist implementation you do NOT get the functionality to hide and show the playlist, that functionality is only available with Standard player implementations.

in-page embed playlist

When using the Advanced implementation of Brightcove Player the playlist element needs to be manually sized and positioned using CSS. This provides you with the flexibility to position the playlist separately from the player, in a location of your choice. When using a playlist with the Standard implementation of the player you simply don't have these options.

After you publish the playlist using your configured player (as detailed in the section above), you choose the Advanced code. It will appear similar to the following:

<div style="position: relative; display: block; max-width: 640px;">
  <div style="padding-top: 56.25%;">
    <video-js data-playlist-id="5718313430001"
      data-account="1752604059001"
      data-player="S13cJdUBz"
      data-embed="default"
      data-application-id
      class="video-js"
      controls
      style="position: absolute; top: 0px; right: 0px; bottom: 0px; left: 0px; width: 100%; height: 100%;"></video-js>
    <script src="https://players.brightcove.net/1752604059001/S13cJdUBz_default/index.min.js"></script>
  </div>
</div>

If you viewed the player as shown above, you would NOT see a playlist. When using the Advanced implementation of the player you MUST add an HTML element that specifies the location of the playlist. The element is:

<div class="vjs-playlist"></div>

Chances are you will wish to style the player and playlist to appear the way you wish. For instance, the styles used in the screenshot of the player just above are:

<style type="text/css">
    .video-js {
      height: 350px;
      width: 640px;
      float: left;
    }
    .vjs-playlist {
      width: 280px;
      height: 350px;
    }
</style>

An example HTML page using the Advanced implementation with a vertical playlist follows (no responsive elements are used in this case):

<!doctype html>
<html>

<head>
  <meta charset="UTF-8">
  <title>Untitled Document</title>
  <style type="text/css">
    .video-js {
      height: 350px;
      width: 640px;
      float: left;
    }
    .vjs-playlist {
      width: 280px;
      height: 350px;
    }
  </style>
</head>

<body>

  <video-js data-playlist-id="5126480959001"
    data-account="1752604059001"
    data-player="f50a2d3c-af51-4d8c-84e3-0c7cdec0edbe"
    data-embed="default"
    data-application-id
    class="video-js"
    controls></video-js>
  <script src="https://players.brightcove.net/1752604059001/f50a2d3c-af51-4d8c-84e3-0c7cdec0edbe_default/index.min.js"></script>

  <div class="vjs-playlist"></div>

</body>

</html>

Making the playlist horizontal

If you wish to have a horizontal playlist, there are only a couple of things you need to do. They are:

  1. As shown above, use Studio to set the style of the player to use a horizontal playlist.
  2. Style the player and playlist: Add the following CSS. Of course you may need to make minor adjustments to match your player to your video size.
    <style type="text/css">
      .video-js {
        height: 350px;
        width: 640px;
      }
    
      .vjs-playlist {
        width: 640px;
      }
    </style>

If you viewed the player as shown above you would NOT see a playlist. When using the Advanced implementation of the player you MUST add an HTML element that specifies the location of the playlist. The element is:

<div class="vjs-playlist"></div>

In the screenshot of the player below, you can see the playlist was separated from the actual player with relevant text added between them.

playlist enable studio

An example HTML page using the Advanced implementation with a horizontal playlist is (no responsive elements are used in this case):

<!doctype html>
<html>

<head>
  <meta charset="UTF-8">
  <title>Untitled Document</title>
  <style type="text/css">
    .video-js {
      height: 350px;
      width: 640px;
    }

    .vjs-playlist {
      width: 640px;
    }
  </style>
</head>

<body>

  <video-js data-playlist-id="5718313430001"
    data-account="1752604059001"
    data-player="ryhwJzBBf"
    data-embed="default"
    data-application-id
    class="video-js"
    controls></video-js>
  <p>Pick your favorite video from the playlist!</p>
  <div class="vjs-playlist"></div>

  <script src="https://players.brightcove.net/1752604059001/ryhwJzBBf_default/index.min.js"></script>

</body>

</html>

Set the initial video

By default, the first video in the playlist is initially loaded into the player. If you wish to load another video in the playlist first, there are four possibilities:

  1. If you are using the Advanced (in-page embed) player you can add the data-playlist-video-id as an attribute to set the initial video to play from the playlist, as shown here:
    <video-js data-playlist-id="5455901760001"
      data-playlist-video-id="5357926703001"
      data-account="1507807800001"
      data-player="BJQXwfiuG"
      data-embed="default"
      data-application-id
      class="video-js"
      controls></video-js>
    <script src="https://players.brightcove.net/1507807800001/BJQXwfiuG_default/index.min.js"></script>

    This is built in Brightcove Player functionality.

  2. If you are using the Advanced (in-page embed) player on a page. You can add the following URL parameter to the page request:
    ?playlistVideoId=5510487311001
    The player will automatically play the desired video from the playlist. This is built in Brightcove Player functionality.
  3. If you are using a Standard (iframe) player on a page. You can add a URL parameter to the iframe's src attribute:
    <iframe src=".../index.html?playlistId=5531423971001&playlistVideoId=5510487311001" ...
    The player will automatically play the desired video from the playlist. This is built in Brightcove Player functionality. A sample of this technique is shown here (You will need to scroll the code far to the right to see the use of the parameter):
    <div style="position: relative; display: block; max-width: 640px;">
    <div style="padding-top: 56.25%;">
      <iframe src="https://players.brightcove.net/1752604059001/HkYoUgMwW_default/index.html?playlistId=5531423971001&playlistVideoId=5510487311001"
          allowfullscreen
          webkitallowfullscreen
          mozallowfullscreen
          style="position: absolute; top: 0px; right: 0px; bottom: 0px; left: 0px; width: 100%; height: 100%;"></iframe>
    </div>
    </div>
  4. You are using an iframe player and wish to pass the desired video's ID on the URL page request. This differs from #3 as you do not want to have to edit the iframe's code on the actual page, but use the URL from the page request. This is NOT built in Brightcove Player functionality, but can be done with custom code on the HTML page. A sample of this technique is shown next.

Sample: Sending the video ID for the iframe on the page request

At the highest level the logic behind the following code is a query parameter is read that contains the video ID for the video that should play first, then the iframe player is dynamically generated using that ID. In more detail, the logic behind this application is:

  • An insertion point is designated by creating an HTML div element.
  • The query parameter named playlistVideoId is read from the page request URL with assistance of a helper function.
  • An iframe element is dynamically built that includes a src attribute that contains the query parameter.
  • The dynamically created iframe is inserted into the page.
  <!doctype html>
  <html>

  <head>
    <meta charset="UTF-8">
    <title>Untitled Document</title>
  </head>

  <body>

    <div id="place_player_here"></div>

    <script type="text/javascript">
      var theParamValue,
        iframe = document.createElement('iframe'),
        insertionPoint = document.getElementById("place_player_here");

      // Use the helper function below to get the value of the parameter
      theParamVideoID = getURLparam("playlistVideoId");

      // Dynamically build the iframe
      iframe.setAttribute('allowfullscreen', 'allowfullscreen');
      iframe.setAttribute('webkitallowfullscreen', 'webkitallowfullscreen');
      iframe.setAttribute('mozallowfullscreen', 'mozallowfullscreen');
      iframe.setAttribute('style', "width: 610px;height: 344px");
      iframe.src = 'https://players.brightcove.net/1752604059001/H1HpIEcCb_default/index.html?playlistId=4450721964001&playlistVideoId=' + theParamVideoID;
      // Insert the iframe into the page
      insertionPoint.appendChild(iframe);

      // Helper function to get value for a specific URL parameter
      function getURLparam(name) {
        var regex, results;
        name = name.replace(/[\[]/, "\\[").replace(/[\]]/, "\\]");
        regex = new RegExp("[\\?&]" + name + "=([^&#]*)");
        results = regex.exec(location.search);
        return results === null ?
          "" :
          decodeURIComponent(results[1].replace(/\+/g, " "));
      }
    </script>

  </body>

  </html>

Below is a working sample where the video loaded in the player is not the first one in the playlist, but the second.

Playlist API

The Playlist API gives you programmatic control over the usage of playlists, for instance next(), previous() and autoadvance() methods. The Guide: Playlist API document provides full details.

Implement using code

If you choose, you can implement playlists entirely in code and avoid Studio. The basic steps are:

  • Load the CSS and JavaScript for the Playlist UI Plugin.
  • Configure an options object to reflect your playlist setup.
  • Call the bcPlaylistUi() method, passing the configuration object as a parameter.

An example implementation follows:

<!doctype html>
<html>

<head>
  <meta charset="UTF-8">
  <title>Untitled Document</title>
  <style type="text/css">
    .video-js {
      height: 350px;
      width: 625px;
    }
    .vjs-playlist {
      width: 625px;
    }
  </style>
  <link href="https://players.brightcove.net/videojs-bc-playlist-ui/3/videojs-bc-playlist-ui.css" rel="stylesheet">
</head>

<body>

  <video-js id="myPlayerID"
    data-playlist-id="4450721964001"
    data-account="1752604059001"
    data-player="default"
    data-embed="default"
    data-application-id
    class="video-js"
    controls
    autoplay></video-js>
  <script src="https://players.brightcove.net/1752604059001/default_default/index.min.js"></script>

  <!-- Location of the playlist -->
  <div class="vjs-playlist"></div>

  <script src="https://players.brightcove.net/videojs-bc-playlist-ui/3/videojs-bc-playlist-ui.min.js"></script>

  <script type="text/javascript">
    videojs.getPlayer('myPlayerID').ready(function() {
      // Get a reference to the player
      var myPlayer = this,
        // Create an object in which you will place options
        options = {};
      // Set options
      options.horizontal = true;
      options.autoadvance = 3;
      // Call plugins method passing in options object
      myPlayer.bcPlaylistUi(options);
    });
  </script>

</body>

</html>