JS objects to create hierarchies of clocks or timelines

dvbcss-clocks is a Javascript library of classes for representing clocks and timelines and their relationships to each other. It can be used in event driven real-time applications to drive and track the progress of time, such as synchronised companion screen applications based on DVB CSS or HbbTV 2.

This library is very similar to the clock objects in pydvbcss and uses the same concepts and overall model. There is a direct 1-to-1 correspondence of most classes and methods between the two.

This project was originally developed as part of the 2-IMMERSE project, co-funded by the European Commission’s Horizon 2020 Research Programme

Getting started

Use in your own project

Install via npm:

$ npm install --save dvbcss-clocks

Or download or clone this repository and build:

$ cd dvbcss-clocks 
$ npm install

Documentation

The full docs for the library can be read online here.

To build the docs yourself:

$ grunt jsdoc

Unit tests

Unit tests are written using the jasmine unit test framework.

$ grunt test

## Quick overview

In this library, objects represent clocks that can be chained together into a hierarchy and used to represent how one sense of time relates to another - e.g. how a timeline for media playback relates to real world time.

First we import the modules:

var CLOCKS = require("dvbcss-clocks")
var DateNowClock    = CLOCKS.DateNowClock;
var Correlation     = CLOCKS.Correlation;
var CorrelatedClock = CLOCKS.CorrelatedClock;

A DateNowClock can be used as the root of the hierarchy and is a simple wrapper around system time derived from Date.now().

var rootClock = new DateNowClock({tickRate:1000, maxFreqErrorPpm:50});

We can query the time position of this clock at any time:

console.log(rootClock.now())

A hierarchy can then be built up using CorrelatedClock objects where a correlation describes the relationship between that clock and its parent. For example, we will create a "wall clock" that is derived from the system clock:

var corr = new Correlation(5000, 0)
var wallClock = new CorrelatedClock(rootClock, {
    tickRate: 50,
    correlation: corr
})

This units for this clock are 50 ticks/second, and the correlation means that when its parent clock (rootClock) is at time position 5000, then this clock should be at time position 0.

If we query the position of this clock, we'll see that it is calculated from its parent by extrapolating from that point of correlation and converting to the different tick rate units. For example, executing this command several times:

console.log(rootClock.now(), wallClock.now())

Can give results like this:

> 5000, 0
> 5200, 10
> 5215, 10.75

Next we'll add another clock into the chain that is derived from the "wall clock" and we will imagine it represents the timeline of a video player that is due to start playing from time zero right now:

var videoTimeline = new CorrelatedClock(wallClock, {
    tickRate: 25,
    correlation: new Correlation(wallClock.now(), 0)
})

Lets listen for events:

videoTimeline.on("change", function() { console.log("Video timeline is notifying of a change")});
videoTimeline.on("available", function() { console.log("Video timeline has become available")});
videoTimeline.on("unavailable", function() { console.log("Video timeline has become unavailable")});

Lets change the wall clock correlation. This will generate a change event on all clocks that are descendents (as well as itself):

# reset wall clock to zero now

wallClock.correlation = new Correlation(rootClock.now(), 0);
console.log("Wall clock time = "+wallClock.now());

Lets also make some other changes (this will generate a change event and availability change events):

wallClock.speed = 2.0   // double the speed!

wallClock.availabilityFlag = false;
wallClock.availabilityFlag = true;

Lets schedule some timer callbacks:

# schedule a timer callback so we know to stop the video at frame 500
videoTimeline.setAtTime(function() { console.log("Time to stop video")}, 500);

Even if we make more changes to correlations this timer callback will only fire when the video timeline reaches (or jumps past) time position 500.

There are many other methods not covered here. See the documentation.

Clocks can be built up into arbitrarily complex hierarchies and these can be reconfigured dynamically. There are helper methods to provide easy conversion of time values between clocks. There are also ways to annotate clocks with quantified uncertainty bounds (dispersions) and have these tracked by their descendants.

Licence and Authors

All code and documentation is licensed by the original author and contributors under the Apache License v2.0:

• British Broadcasting Corporation (original author)
• British Telecommunications (BT) PLC

See AUTHORS file for a full list of individuals and organisations that have contributed to this code. .

Contributing

If you wish to contribute to this project, please get in touch with the authors.