cubic-timingsrc

A library to synchronize a MediaElement with a TimingObject.

This libary is meant to synchronize a MediaElement (aka an <audio/> or <video/> element) with a TimingObject.

The Timing Object specification defines an extension of the MediaElement which would add timingsrc property. But so far this is not supported in any browser. Therefore this package can be used as a replacement as it provides the same functionality. But instead of patching the native protoypes this libary provides a function which can be used without modifying any built-in browser objects.

The code of this library is heavily inspired by the mediaSync() function that came with v1 of the timingsrc library. However all the code has been completely rewritten in TypeScript with the goal to make it more testable and easier to reason about.

The actual synchronization is handled by two different algorithms. By default the userAgent string gets parsed to determine which algorithm to use. Since Safari is not capable of processing changes of the currentTime or the plackbackRate of a MediaElement in a timely manner the position in Safari is set abbruptly whenever it changes. Firefox and Chromium based browsers happily handle frequent changes of both properties which is why they are adjusted gradually to keep a MediaElement in sync with a TimingObject in these browsers. The technique for doing so has been taken from Tom Jenkinon's media-element-syncer.

Usage

The timingsrc package is published on npm and can be installed as usual.

npm install timingsrc

The main function exported by this package is the setTimingsrc() function. It can be thought of as the replacement of the timingsrc property on a MediaElement. It can for example be used with a TimingObject created with the timing-object package.

import { TimingObject } from 'timing-object';
import { setTimingsrc } from 'timingsrc';

const mediaElement = document.getElementsByTagName('video')[0];
const timingObject = new TimingObject();

const updateSettings = {
    isGradually: true,
    stepwiseDelay: 0.01,
    threshold: 1,
    timeConstant: 0.5,
    tolerance: 0.025
};

const deleteTimingsrc = setTimingsrc(mediaElement, timingObject, updateSettings);

// The synchronization can be stopped again at any point in time.
deleteTimingsrc();

Please take a look at the video-synchronization-demo for a more comprehensive example.