Cuepoints

Cuepoints let you do custom actions during video playback on pre-defined points in time. You can for example

  • place/remove any HTML content - also AJAX loaded - over the video or next to it
  • trigger playback of a different sub clip, a mid-roll advert or an explanatory comment like in this demo
  • display subtitles with the subtitle extension
  • present chapter markers to your audience for easy navigation of your video content: clickable cuepoints are available out of the box and just an option switch and a few CSS rules away

Each cuepoint triggers a cuepoint event which lets you execute JavaScript of your choice. Combined with the fact that cuepoints accept custom properties the possibilities are endless. On top you get a CSS class name for each cuepoint so you can show/hide content or style elements without any scripting.

Setting up

Cuepoints are set up as an array of comma separated numbers inside square brackets; for example as data attribute to the container element:

<div class="flowplayer" data-cuepoints="[1.5, 2, 3, -1]">
 
</div>

HTML

Alternatively you can give the configuration in JavaScript and add custom properties of your choice to specific cues:

$(".player").flowplayer({
cuepoints: [10.4, 23.5, { time: 78, below: true }]
});

JavaScript

Clip specific cuepoints

You can have a separate set of cuepoints for each clip of a playlist. For example:

<div id="basic-playlist"
class="fp-custom-playlist is-closeable"
data-splash="true"
data-ratio="0.5625">
 
<video>
<source type="application/x-mpegurl"
src="//edge.flowplayer.org/night3.m3u8">
<source type="video/mp4"
src="//edge.flowplayer.org/night3.mp4">
</video>
 
<a class="fp-prev"></a>
<a class="fp-next"></a>
 
<div class="fp-playlist">
<a class="item1" href="//edge.flowplayer.org/night3.mp4"
data-cuepoints="[0.5, 1]"></a>
<a class="item2" href="//edge.flowplayer.org/night1.mp4"
data-cuepoints="[0.9, 1.5]"></a>
<a class="item3" href="//edge.flowplayer.org/night5.mp4"></a>
<a class="item4" href="//edge.flowplayer.org/night6.mp4"></a>
</div>
 
</div>
 
<div id="event-info"></div>

HTML

// listen to playlist events
$(function () {
function log() {
$("#event-info").css("opacity", 1)
.append("<p>" + [].slice.call(arguments).join(", ") + "</p>");
}
 
// install the player
$("#basic-playlist").flowplayer();
// grab the api and log events to the browser console
flowplayer(0).on("load", function(e, api, video) {
log("clip " + video.index, "is_last: " + video.is_last);
 
}).on("cuepoint", function(e, api, cuepoint) {
log("clip " + api.video.index, "cuepoint " + cuepoint.time);
});
 
});

JavaScript

view standalone page

Configuration

The cuepoints option can be set at player and clip level.

All options may be applied as data attributes in a HTML configuration. However, in this case the cuepoints array is restricted to contain numbers only.

Player options

propertydefault valuedescription
generate_cuepointsfalseIf set to true visual cuepoints inside the timeline are generated. Clicking on such a cuepoint element makes the player seek to its time position in the video.
cuepointsA list of cues at various time positions in the video.
Each time playback has reached a cue position a cuepoint event is triggered.

Clip options

propertydefault valuedescription
cuepointsA list of cues at various time positions in this clip. Replaces the cuepoints set at player level for this clip.
Each time playback has reached a cue position a cuepoint event is triggered.

Cues

An item in a list of cuepoints can be set as:

  • Number, integer or float, specifying the time position of the cuepoint in units of seconds - positive numbers indicate the position relative to the beginning of the video, negative numbers relative to its end
  • Object with an obligatory time property with the time position a as value, and arbitrary custom properties

Note: The subtitle, subtitleEnd and visible property names are reserved if cuepoints are applied in conjunction with subtitles.

CSS classes

A cue{index} CSS class name will be assigned for the root element while a cuepoint is active. For example:

<div class="flowplayer cue1">
 
<div class="info info1">show this on the first cuepoint</div>
<div class="info info2">and this on the second</div>
<div class="info info3">and this on the third</div>
 
</div>

HTML

CSS Example Fade-in / fade-out .info elements with cuepoints

.info {
opacity: 0;
}
 
.cue0 .info0, .cue1 .info1, .cue2 .info2 {
opacity: 1;
transition: opacity .5s;
}

CSS

Here we animate elements with CSS transitions.

  • Caveat If used in conjunction with subtitles the cue index includes user configured subtitles as well and is hardly useable as indicator.

JavaScript API

Properties

The cuepoints extension provides the following property for the player API:

propertydefault valuedescription
cuepointsarrayThe complete list of all currently loaded cuepoints.

Methods

The cuepoints extension provides the following methods for the player API:

methoddescription
addCuepoint(cuepoint)Adds the cuepoint (object or number of position in seconds) given in the argument to the current array of cuepoints
removeCuepoint(position)Removes the cuepoint at given position in seconds from the current array of cuepoints of the current clip.
Caveat: has no effect if the cuepoint at position is an object.
setCuepoints(cuepoints)Replaces the current array of cuepoints with the cuepoints given in the argument for the current clip.

Cuepoint event

You catch the cuepoint by binding a listener to the "cuepoint" event. For example:

var firstplayer = flowplayer($(".player:first"));
 
firstplayer.on("cuepoint", function(e, api, cuepoint) {
 
// here we use custom properties left, top and html
$("#info").html(cuepoint.html).animate({
left: cuepoint.left,
top: cuepoint.top
});
 
});

JavaScript

A cuepoint object given by the 3rd callback argument has the following properties:

  • time: the time in seconds; regardless of whether the cuepoint was configured as object or number
  • any data you have supplied via custom properties

Clickable cuepoints

Turning on the generate_cuepoints configuration option creates chapter markers by inserting a clickable Anchor element with class="fp-cuepoint" for each cuepoint into the timeline element of the player:

<div class="flowplayer">
<!-- ... -->
<div class="fp-player">
<!-- ... -->
<div class="fp-ui">
<!-- ... -->
<div class="fp-controls">
<!-- ... -->
 
<div class="fp-timeline">
<div class="fp-buffer"></div>
<div class="fp-progress" style="width: xx%; "></div>
 
<!-- generated cuepoints -->
<a class="fp-cuepoint" style="left: 10%; "></a>
<a class="fp-cuepoint" style="left: 20%; "></a>
<a class="fp-cuepoint" style="left: 50%; "></a>
<a class="fp-cuepoint" style="left: 90%; "></a>
 
</div>
 
<!-- ... -->

HTML

The CSS left property is generated based on the cuepoint position. The rest is custom CSS. Here is a demo.

Restrictions

Be aware that cuepoints are subject to restrictions regarding the HTML5 video API on devices which do not support inline video because they delegate playback to a system component (e.g. QuickTime on iPhone) the effect of cuepoints is next to none in real world setups. Once the video is loaded into the component the connection to the page is lost until you return to it. You can check the functionality of cuepoints e.g. by triggering an alert which propagates into the playback component, but any kind of operation acting on the page or triggering playback of a different movie etc. will have no effect.