Using Cue Points to Create Chapters in JavaScript

Cue points can have multiple uses. In this topic, we're going to look at how you can use cue points to create chapters in a video. Using chapters in a video lets your viewers seek to particular points in the video, without breaking the video up into separate files.

Note: The steps outlined in this topic are for Flash based players and will not work in HTML5 players and may prevent HTML5 players from functioning. The recommended way to do this now is using the Smart Player API — see this example for an explanation of how to do it.

The approach in this article uses JavaScript with the Flash-only Player API in the HTML page that hosts the player to get the cue points from the currently-loaded video, and creates links to the cue points. When a viewer clicks on a cue point link, the player automatically advances the video to the time of the cue point.  You can download a zip file that contains the source code for the example in this article. The resulting experience will look something like the screenshot below, with chapter links dynamically added to the page below the video player. Click here for a working example.

Enable the API for your player

It's important to first check your player to see if the Video Cloud APIs are enabled. Make sure the Enable ActionScript/JavaScript APIs checkbox is checked for your player.

Setting up the cue points

The first step in creating chapters is to create the code cue points in your video where the chapters should start. You can create cue points in a video using the Media module. You can also create cue points using the Media API or FTP batch provisioning, but for cue points that represent chapters, it's probably easiest to use the Media module, since the other methods require you to know the exact time in the video duration where you want each cue point, but don't let you review the video in the process.

It's worth noting that you can't create a cue point at the very beginning (00:00:00:000) because by default there's an ad cue point there. In this example a code cue point was created close to zero (00:00:01:000). It would also be possible to leave off the first one completely and just hard code your JavaScript to include a chapter at zero.

The screenshot below shows the 4th code cue point. It was created at 1 minute, 30 seconds into the video and was given the name "Part 4". The metadata field could also be leveraged to store any other information that could be used when rendering the links for the chapters in the page.

Setting up the HTML

Once your video has its cue points assigned, you can embed the Video Cloud player publishing code in your HTML page. We also need to create an area where the chapter links will be added when the video loads. In this case, we simply place a div below the player, with the id chapters.

<h1>Cuepoint Chapter Example</h1>

<!-- Start of Brightcove Player -->
		
<div style="display:none"></div>
	    
<!--
    By use of this code snippet, I agree to the Brightcove Publisher T and C 
    found at https://accounts.brightcove.com/en/terms-and-conditions/. 
-->
        
<object id="myExperience" class="BrightcoveExperience">
    <param name="bgcolor" value="#FFFFFF"/>
    <param name="width" value="486"/>
    <param name="height" value="412"/>
    <param name="playerID" value="<INSERT_YOUR_PLAYER_ID>"/>
    <param name="videoID" value="<INSERT_YOUR_VIDEO_ID>"/>
    <param name="publisherID" value="<INSERT_YOUR_PUBLISHER_ID>"/>
    <param name="isVid" value="true"/>
    <param name="dynamicStreaming" value="true"/>
</object>
		
<!-- End of Brightcove Player -->
		
<div id="chapters"></div>

Setting up the JavaScript

In the top of the page (within the head tags) we need to add the JavaScript we'll need in order to read the cue points from the video being played.

<script type="text/javascript" src="http://admin.brightcove.com/js/BrightcoveExperiences_all.js"></script>
<script type="text/javascript">
    var bcExp;
    var modExp;
    var modCue;
    var modVid;
    var queuedTime;
	
    /**
     * Automatically called by the Brightcove API.
     */
    function onTemplateLoaded(experienceId)
    {
        bcExp = brightcove.getExperience(experienceId);
		
        // get references to the modules we'll need
        modExp = bcExp.getModule(APIModules.EXPERIENCE);
        modCue = bcExp.getModule(APIModules.CUE_POINTS);
        modVid = bcExp.getModule(APIModules.VIDEO_PLAYER);
		
        // listen for the content load event so we can grab the videos cuepoints
        modExp.addEventListener(BCExperienceEvent.CONTENT_LOAD, onContentLoad);
    }
	
    /**
     * Called when the video content is loaded.
     */
    function onContentLoad(event)
    {
        // reference to the chapter div which we'll put our links into
        var chaptersElem = document.getElementById("chapters");

        // remove any previous links which already be in the div
        chaptersElem.innerHTML = "";
		
        // get the list of cuepoints for the video
        var cuepoints = modCue.getCuePoints(modVid.getCurrentVideo().id);
		
        // loop over all the cuepoints
        for (var i=0; i < cuepoints.length; i++)
        {
            // we're looking for "code" (type = 1) cuepoints, there will also be some
            // ad cuepoints in the list so check the type 
            if (cuepoints[i].type == 1) 
            {
                // only add the divider if at least one link has been added
                if (chaptersElem.children.length > 0) 
                {
                    chaptersElem.innerHTML += " | ";
                }
				
                // dynamically add a new link for the current cuepoint
                chaptersElem.innerHTML += "<a href='javascript:void();' onclick='seek(" + cuepoints[i].time + ");'>" + cuepoints[i].name + "</a>";
            }
        }
    }
	
    /**
     * Seeks to the given time in the video.
     */
    function seek(time)
    {
        // it's not possible to seek unless the video is playing
        // so check to see if it's playing and if it's not then
        // save the time and tell the video to play
        if (modVid.isPlaying()) 
        {
            modVid.seek(time);
        }
        else
        {
            queuedTime = time;
            modVid.addEventListener(BCMediaEvent.PROGRESS, onProgress);
            modVid.play();
        }
    }
	
    /**
     * Called when the video starts playing.
     */
    function onProgress(event)
    {
        // remove the progress event listener and seek to the saved time
        modVid.removeEventListener(BCMediaEvent.PROGRESS, onProgress);
        seek(queuedTime);
    }
</script>

Tips

As noted in the JavaScript comments, it's not possible to seek to a specific point in a video if it's not playing. The workaround is to save the desired time so that seek can be called after the video is told to play. It's also worth pointing out that you can store more data in a cue point's metadata, so in addition to the cue point name, things like a description or other notes could be displayed for each chapter. This example should serve as a starting point for more advanced versions.