Add API to dynamically manage timeline markers

[protyposis]

Currently it is possible to add generic TimelineMarker markers to the timeline (i.e. SeekBar), but only via the UIConfig at construction time of the UIManager.

The time line marker interface:

bitmovin-player-ui/src/ts/uimanager.ts

Lines 61 to 64 in d8a6978

	export interface TimelineMarker {
	time: number;
	title?: string;
	}

The UI config interface that takes an array of timeline markers:

bitmovin-player-ui/src/ts/uimanager.ts

Lines 66 to 78 in d8a6978

	export interface UIConfig {
	/**
	* Specifies the container in the DOM into which the UI will be added. Can be a CSS selector string or a
	* HTMLElement object. By default, the player figure will be used ({@link PlayerAPI#getFigure}).
	*/
	container?: string | HTMLElement;
	metadata?: {
	title?: string;
	description?: string;
	markers?: TimelineMarker[];
	};
	recommendations?: UIRecommendationConfig[];
	}

The constructor that takes the config:

bitmovin-player-ui/src/ts/uimanager.ts

Line 167 in d8a6978

constructor(player: PlayerAPI, uiVariants: UIVariant[], config?: UIConfig);

We need an API that allows dynamic management of these markers, i.e. add and remove during the lifetime of the UIManager. Additionally we want to be able to define different kinds of markers, e.g. chapter and ad markers that need to look and possibly work differently.

Currently these markers mark points in time. We also want to be able to mark time intervals. While this should be easily achievable to mark intervals of the main content, it is going to be more difficult for inserted ad breaks that modify the timeline, so we may want to handle this in a separate follow-up issue once necessary. The API for this would be quite simple, but the question of how this is rendered on a seek bar is to be discussed (e.g. how do we transform the timeline of the seekbar if an ad interval is inserted? how is the mapping from the seekbar to the content done? how do we even know in advance how long an ad break is going to be?).

[protyposis]

Proposed API extension:

interface TimelineMarker {
  /**
   * Optional CSS classes that are applied to the marker and can be used to differentiate 
   * different types of markers by their style (e.g. different color of chapter markers and 
   * ad break markers). 
   * The CSS classes are also propagated to a connected `SeekBarLabel`.
   * 
   * Multiple classes can be added to allow grouping of markers into types (e.g. chapter markers, 
   * ad break markers) by a shared class and still identify and style each marker with distinct 
   * classes (e.g. `['marker-type-chapter', 'chapter-number-1']`).
   */
  cssClasses?: string[];
  /**
   * Optional duration that makes the marker mark an interval instead of a single moment 
   * on the `SeekBar` timeline.
   */
  duration?: number;
}

class UIManager {
  /**
   * Returns the list of all added markers in undefined order.
   */
  getTimelineMarkers(): TimelineMarker[];
  /**
   * Adds a marker to the timeline. Does not check for duplicates/overlaps at the `time`.
   */
  addTimelineMarker(timelineMarker: TimelineMarker): void;
  /**
   * Removes a marker from the timeline (by reference) and returns `true` if the marker has 
   * been part of the timeline and successfully removed, or `false` if the marker could not
   * be found and thus not removed.
   */
  removeTimelineMarker(timelineMarker: TimelineMarker): boolean;
}

[protyposis]

Open questions:

• Do we want to support these markers on live streams as well? (the markers would have to be animated and move across the timeline as the playhead progresses/changes)
• Do we want to allow customization of the SeekBarLabel? (this label currently displays the time, an optional title text, and a thumbnail if available)
  • Deactivate the label per marker?
  • Allow a custom image instead of the thumbnail?
  • Allow custom content instead of the default content?

[unki2aut]

Notes from architectural meeting 2018-06-19

• We don't support markers on live streams right now
• Add cssClasses property to TimelineMarker, the same classes would be propagated to the label
• A content() callback which returns a DOM element could be added in the future

[protyposis]

API extension updated: #103 (comment)

[protyposis]

Renamed method names to include Timeline for more consistent naming that matches the object type's name, e.g. getMarkers -> getTimelineMarkers.

[protyposis]

Released in 2.16.0

[ghost]

Just a minor issue; is there any place where these API calls are documented? I tried to use the search functionality for version 7 and version 8, but no search results appeared. It shouldn’t be too difficult to figure it out from the code, but I was about to open an issue as I didn’t think this functionality was implemented.

[protyposis]

You were searching the player API docs which only contains player API, no UI API. The main documentation of the UI is this repository with the readme, changelog, source code and issues.

[ghost]

Ah, okay. I’ve had a bit of a struggle distinguishing the boundaries of the two, but I think I’m starting to get it.