How to add Timeline Markers

Overview

Adding a marker to your playback timeline enables you to highlight specific positions (Chapters, Ad Breaks, special moments, etc) in your content to your viewers, so they can navigate and understand its structure with ease. You can add those markers to the timeline of the player. They are part of the bitmovin-player-ui and be either provided as part of the

player configuration,
source configuration,
UI configuration,
or on-demand using the UI Manager API.

What is a Timeline Marker?

This component comes as part of our open source player UI framework and provides a few properties to alter its appearance, and if clicked the player will seek to the given time in its configuration. Click here to get to its full interface description.

time - position in the playback timeline it shall be placed at
duration - marks a whole region on the timeline instead one single position. Starts at time
title - Text that is shown when the cursor hovers above it
imageUrl - Image that is shown above timeline marker
cssClasses - takes an array of CSS class names that are applied to it

Knowing all its capabilities now, lets continue with providing their configuration to the player UI.

Player configuration

Through the player configuration you can either enable/disable the player UI using the ui property providing a boolean value, or you provide it with a UIConfig that is used by the UIManager to configure it by default. A full example can be found here.

var playerConfiguration = {
    key: 'YOUR_PLAYER_KEY_HERE',
    ui: {
      metadata: {
        markers: [
          { time: 24, title: 'Salto on the edge' },
          { time: 69, title: 'Interview - Marcus Gustafsson' },
          { time: 105, title: 'Parcour rating explained' },
          { time: 188, duration: 11, title: 'And we have a winner!' },
        ],
      },
    },
  };

Source configuration

You can add the UI configuration for markers to the source configuration of the player. It expects an array of objects, where each object has a time property, that defines where the marker should be placed on the time, and a title property, which is shown when the mouse cursor points to the marker. A full example can be found here.

The player configuration would look like the following:

var sourceConfig = {
  title: "Bitmovin Player",
  description: "See how you can easily play markers on the timeline to highlight certain moments in your content!",
  dash: "https://bitmovin-a.akamaihd.net/content/MI201109210084_1/mpds/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.mpd",
  hls: "https://bitmovin-a.akamaihd.net/content/MI201109210084_1/m3u8s/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.m3u8",
  progressive: "https://bitmovin-a.akamaihd.net/content/MI201109210084_1/MI201109210084_mpeg-4_hd_high_1080p25_10mbits.mp4",
  markers: [
    { time: 24, title: 'Salto on the edge' },
    { time: 69, title: 'Interview - Marcus Gustafsson' },
    { time: 105, title: 'Parcour rating explained' },
    { time: 188, duration: 11, title: 'And we have a winner!' },  ],
};

UI configuration

If you are already using a customized version of our UI, or your own UI structure, you are already using the UI manager of our player UI framework most likely. When initialising this one, you can provide this marker configuration along with the UI configuration. The full example can be found here.

var playerElement = document.querySelector('#my-player');

var playerConfiguration = {
  key: 'YOUR_PLAYER_KEY_HERE',
  ui: false,
};

var uiConfig = {
  metadata: {
    markers: [
      { time: 24, title: 'Salto on the edge' },
      { time: 69, title: 'Interview - Marcus Gustafsson' },
      { time: 105, title: 'Parcour rating explained' },
      { time: 188, duration: 11, title: 'And we have a winner!' },
    ],
  },
};

var player = new bitmovin.player.Player(playerElement, playerConfiguration);
var myUiManager = new bitmovin.playerui.UIFactory.buildDefaultUI(player, uiConfig);

UI Manager API

The third way is to set them dynamically using the UI Manager API. As soon as the the player and its API is ready (e.g. ready event has been fired), you can start using the UI API call to add marker to the timeline. The full example can be found here.

var playerElement = document.querySelector('#player');
var playerConfiguration = {
  key: 'YOUR_PLAYER_KEY_HERE',
  ui: false,
};

var timelineMarkers = [
  { time: 24, title: 'Salto on the edge' },
  { time: 69, title: 'Interview - Marcus Gustafsson' },
  { time: 105, title: 'Parcour rating explained' },
  { time: 188, duration: 11, title: 'And we have a winner!', cssClasses: ['seekbar-marker-interval'] },
];

var player = new bitmovin.player.Player(playerElement, playerConfiguration);
var myUiManager = new bitmovin.playerui.UIFactory.buildDefaultUI(player);

//Once player/UI is ready you can interact with their respective API
player.on("ready", function() {
  //Add all available Timeline markers to the UI
  timelineMarkers.map(function(marker) {
    myUiManager.addTimelineMarker(marker);
  });
});

//myUIManager.getTimelineMarkers() returns all available timelime markers
//myUIManager.removeTimelineMarker(timelineMarkers[0]) can be used to remove an already added marker again

Custom CSS

In addition to the previous UI Manager API example, now we also add a custom CSS class called seekbar-marker-interval to the cssClasses property of the last marker in the configuration:

var timelineMarkers = [
  { time: 24, title: 'Salto on the edge' },
  { time: 69, title: 'Interview - Marcus Gustafsson' },
  { time: 105, title: 'Parcour rating explained' },
  { cssClasses: ['seekbar-marker-interval'], time: 188, duration: 11, title: 'And we have a winner!' },
];

By default, the UI framework expects a prefix like bmpui for its CSS classes. When providing a CSS class in a UI configuration this prefix has to be omitted (see the example below) therefore, so our CSS class definition would look like the following:

.bmpui-ui-seekbar .bmpui-seekbar .bmpui-seekbar-markers > .bmpui-seekbar-marker-interval {
    border-color: rgba(255, 255, 0, 0.4);
}

More details about customising the styling of our Player UI can be found in our CSS class reference.

Examples

All the configuration examples of this tutorial can be found in our Github repository bitmovin-player-demo as fully working examples as well.

Updated 5 months ago