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]({{ config.flowplayer7.demos }}/scripting/midroll.html)
• 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>

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 }]
});

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>

jQuery code for above sample:

// 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);
    });

});

[View standalone page]({{ config.flowplayer7.standalonedemos }}/playlist/basic-cues)

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

Clip options

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>

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

.info {
   opacity: 0;
}

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

Here we animate elements with CSS transitions.

With cuepoint generation enabled the general fp-cuepoint and specific fp-cuepoint{index} classes are assigned automatically to the generated cuepoint elements in the timeline.

cuepoints: expand on the fp-cuepoint* classes

Automatic cuepoint generation can be enabled to assign cuepoints the general fp-cuepoint and specific fp-cuepoint{index} classes.

JavaScript API

Properties

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

Methods

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

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
   });

});

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>

          <!-- ... -->

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

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.