Documentation

Table of Contents

• Introduction
• Methods

Introduction

This add-on allows you to perform a JavaScript action when the viewer enters or exits a certain zone in the video timeline.

You’ve probably already heard about “cue points”. A cue point is a user defined marker at a specific time in the video when a custom event is designed to occur. The Cue Zones add-on allows you to define not only a starting but also an ending point – hence “zones” – in your video where those custom actions should start and end occurring. The fact you’re automatically notified when the playback leaves a zone can be extremely useful if the user is jumping ahead or back in the timeline, because you can easily keep in sync with the zones he might have skipped through.

You can use the Cue Zones API to trigger any custom action, such as synchronizing slides alongside a video presentation, displaying side-advertising or creating chapters in your video.

Methods

The Cue Zones API methods described in this section are to be called on a cuezones object, which you can retrieve in the following way

var cuezones = sublime.player(elementOrId).cuezones;

A player can manage multiple groups of cue zones, each dedicated to a particular task (e.g. change background images, show subtitles, popup advertisements). A group of cue zones is identified by a string (id). You always need to add at least a group, even if you are only registering a single cue zone.

Every id you set on the following methods must have the format /^[a-z0-9_-]+$/i
(dots and spaces not allowed).

cuezones.addGroup(group)

• group (Object) – The group object. This object has the following keys:
  • id The id of the group (required only if you plan to use the goTo or removeGroup methods).
  • cuezones a list of objects, each one representing a cue zone containing:
    – id the id of the zone (required if you plan to use the goTo method)
    – from The time in seconds defining the start of the zone. You can use a negative value for a time relative to the end of the video.
    – to The time in seconds defining the end of the zone. You can use a negative value for a time relative to the end of the video. If you omit this value, we’ll automatically set the end of the zone to match the start of the next cue zone in the group.
    – anything Any other custom data you might want to add, which you’ll be able to retrieve via the cuezone object passed to the onenter/onexit callback functions.
  • onenter The callback function to call when the playback enters a cue zone.
  • onexit The callback function to call when the playback exits a cue zone.

The addGroup method registers a group of cue zones to the player. If a group with the same id already exists, it will be replaced by the new group.

onenter/onexit callback parameters

• player (Object) – The player API object.
• groupId (String) – The id of the group (if specified when adding the group).
• cuezone (Object) – The cuezone API object. This object has the attributes:
  – id The id of the cue zone (may be undefined).
  – from The time in seconds defining the start of the zone (may be undefined).
  – computedFrom The computed time defining the start of the zone (negative values are replaced by their corresponding positive values).
  – to The time in seconds defining the end of the zone (may be undefined).
  – computedTo The computed time defining the end of the zone (negative values are replaced by their corresponding positive values).
  – anything Any other custom data you might have added to the cue zone.

Example – registering cue zones

var cuezones = [{
    id: 'Paris',
    from: 0,
    to: 5
  }, {
    id: 'London',
    from: 30
  }, {
    id: 'NYC',
    from: -10 // negative value => "10 seconds before the video ends"
}];

// we are now ready to register our cue zones
player.cuezones.addGroup({
  id: 'cities',
  cuezones: cuezones,
  onenter: function(player, groupId, cuezone, index) {
    console.log('entered cue zone ' + cuezone.id);
  },
  onexit: function(player, groupId, cuezone, index) {
    console.log('exited cue zone ' + cuezone.id);
  }
})

cuezones.goTo(cuezoneId)

• cuezoneId (<groupId>.<cuezoneId>) – The id of the cuezone you wish to seek to.

Seek to the start of the cue zone with the given id.

Example – seeking to the cue zone “London” of the group “cities”

// Let's say we added a group with id "cities"
// that contains a cue zone with id "London"
player.cuezones.goTo('cities.London');

cuezones.removeGroup(id)

• id (String) – The id of the group to be removed.

Remove the group of cue zones with the given id. The call has no effect if a group with the given id cannot be found.

Example – removing a list of cue zones

player.cuezones.removeGroup('my_group_id');

cuezones.removeAllGroups()

Remove all cue zones registered to the video player.

Example – removing all registered groups of cue zones

player.cuezones.removeAllGroups();