TimeKit JavaScript API

While TimeKit's HTML data attribute provides a simple API for effecting an element's style across a timeline, inline CSS manipulation is only the beginning of what TimeKitJS is able to manage. With TimeKit's JavaScript API, developers can integrate TimeKit's time-keeping capabilities with the immense range of resources and libraries available within a JavaScript application.

Like the HTML API, the JavaScript API is still able to manage multiple TimeKit-enabled videos on a single page, but in addition to permitting more control over timing events, the JavaScript API also supports a series of player methods. This standardizes video playback control across the supported player types, so a script written with TimeKit's JavaScript API will work identically line for line with a YouTube video and a Vimeo video.

Accessing the JavaScript API Methods

As in the HTML API, a new TimeKit constructor function should be created for each TimeKit/video instance. It should be called after the video element(s) have been created, but unlike in the data tag syntax, events can be added synchronously once the TimeKitJS library is loaded. The JavaScript API can be used in addition to the HTML API or alone.

In addition to the video element selector (required) and player type specification (optional), another optional argument, an on-ready callback, is accepted by the constructor for use in the JavaScript API. Our API methods can be attributed as a parameter of the callback function, or stored as a variable for a broader scope.

new TimeKit('#video', function(tk) {
    // Code using the tk parameter
});

var tk = new TimeKit('#video', onReady);

var onReady = function() {
    // Code using the tk variable
};

Player Methods

When TimeKit captures the video element, it creates a set of standard player methods within the .getPlayer() method. In the case of third party players, not only is TimeKit able to access and compile the player API from the distributor's most recent API specs, but it also centralizes the API commands within TimeKit's API. This means that applications can be written player agnostic, supporting multiple player types from the same code or player changes on the fly.

Player methods

`.getPlayer().isReady()` boolean	Returns true if player metadata has been retrieved.
`.getPlayer().play()`	Plays the video. Note: Many mobile web portals, Apple and Andriod devices included, and some tablets include default settings that prevent an initial play from occurring from an API call in an effort to prevent unintended data consumption. Thus, all play calls not attached to the video element are intercepted by the browser until the user has initiated play manually on the element.
`.getPlayer().pause()`	Pauses the video.
`.getPlayer().isPlaying()` boolean	Returns true if video is playing. False if paused or stopped.
`.getPlayer().isPaused()` boolean	Returns true if video is paused or stopped. False if playing.
`.getPlayer().getDuration()` integer	Returns the duration of the video in milliseconds.
`.getPlayer().getCurrentPosition()` integer	Returns the current time of the video in milliseconds from the beginning.
`.getPlayer().jumpTo(time)`	Seek to time (nearest keyframe). Accepts an integer in milliseconds or time string with units. h (hours), m (minutes), s (seconds), ms (milliseconds).
`.getPlayer().getObject()` element	Returns the video element. This can be used to affix custom or player-specific events to the DOM node.

Event Methods

Beyond CSS manipulation, TimeKit's event methods provide a simple but powerful means of building and synchronizing any number of JavaScript events to TimeKit's timeline. Each method accepts a primary callback argument, which fires its function whenever the timeline enters the supplied time range, allowing scripts to run custom logic at any point during video playback.

TimeKit's timing functions are made powerful by the fact that they account for not only normal video progress but also jumps in the video by manual or programmed seeking. To manage the latter, certain methods also accept a secondary, or "clean-up," function that is called if the video is abruptly seeked from within the time range to a point outside it. This provides for the difference of, say, animating an element's opacity to 0 as the video plays normally or changing its display property to none abruptly if the video has been seeked to a point beyond.

TimeKit's timeline is able to continuously monitor synchronization of elements and video. In the HTML API, each element state is verified with every new animation frame. This ensures absolute precision in synchrony, but it also means that even if an outside function acts on an element's synchronized CSS properties, TimeKit will reset the properties to its expected state in the TimeKit timeline at the next possible keyframe. TimeKit's JavaScript API, therefore, is made up of two companion methods for each of its event types, a continuous and singular update.

The continuous methods are used and recommended for instances where other events outside TimeKit are not expected to act on the synchronized elements during video playback. The once methods are also available in the JavaScript API for cases where other events may act after the TimeKit callback has been fired once. For example, imagine a popup scheduled to appear at the 30-second mark during the video that can then be dismissed manually by the user.

Single methods

.during(start time, end time, primary function, secondary function)

Called continuously when the timeline is inside the interval between the two time arguments, the primary function of the during event can be used to maintain a fixed state or to animate integers in synchronization with the video using the value method. The optional secondary function will be called once when the timeline leaves the interval, either by normal play progress or via a seek outside the time boundaries.

Example

tk.during(
    '5s',
    '15s',
    function() {
        $('#block').css('opacity', this.value(1,0) );
    },
    function() {
        $('#block').css('opacity', 1);
    }
);

Watch

opacity	1
primary function	0 calls
secondary function	0 calls

.onceDuring(start time, end time, primary function, secondary function)

The primary function of the onceDuring event will be called only once when the video timeline moves from a point outside the time interval to a point inside it. This is useful for triggering a function that should only run once, such as a class toggle or a jQuery animation. Note, however, that only the triggering method would be synchronized with the video in this case and not the animation itself. The animation would continue to run even if the video is paused. The optional secondary function is queued when the primary function fires and is called when the timeline leaves the interval boundary.

Example

tk.onceDuring(
    '5s',
    '15s',
    function() {
        $('#block').css('visibility', 'hidden');
    },
    function() {
        $('#block').css('visibility', 'visible');
    }
);

Watch

visibility	visible
primary function	0 calls
secondary function	0 calls

.after(time, primary function, secondary function)

The primary function in the after method will be called at every keyframe after the time specified in the time argument. Effectively, this would be the same as calling the during method and using the duration as the second time argument. As such, the optional secondary function will not fire during normal play progress, but only be called if the viewer seeks back in the video.

Example

tk.after(
    '5s',
    function() {
        $('#block').css('visibility', 'hidden');
    },
    function() {
        $('#block').css('visibility', 'visible');
    }
);

Watch

visibility	visible
primary function	0 calls
secondary function	0 calls

.onceAfter(time, primary function, secondary function)

Like with onceDuring, onceAfter can be used for a simple toggle or one-time function call. Like the continuous after, it's useful for ensuring an element assumes the action of the primary function by the time a user reaches the end of the video, regardless of whether by normal play progress or a seek. The optional secondary function will only fire when the video is seeked back before the time argument.

Example

tk.onceAfter(
    '5s',
    function() {
        $('#block').css('visibility', 'hidden');
    },
    function() {
        $('#block').css('visibility', 'visible');
    }
);

Watch

visibility	visible
primary function	0 calls
secondary function	0 calls

Chain methods

.first(function)

Event chains are useful for managing multiple TimeKit events across a single element. The first event is used to create a continuous event chain. Its function will be called during the interval between 0 seconds and the next time string supplied by a then event.

.then(time, function)

When used after a first event, then becomes a during interval starting at the time listed in the event's argument and ending at the time listed in the following event. When no then follows, the duration is used as the final boundary.

Example

var element = $('#block');
tk.first(function() {
    element.css({left: 0, top: 0 });
}).then('2s', function() {
    element.css('left', this.value(0, 50) + '%');
}).then('7s', function() {
    element.css('top', this.value(0, 100));
}).then('9s', function() {
    element.css('left', this.value(50, 75) + '%');
}).then('13s', function() {
    element.css({left: this.value(75, 0) + '%', top: this.value(100, 0) });
});

Watch

function	first
left	0
top	0

.onceFirst(function)

The onceFirst chain is used to map a series of function calls to a single element throughout the video. The primary function will be called once between 0 and the time of the first then event.

.then(time, function)

When used after a onceFirst event, then becomes a onceDuring interval starting at the time listed in the event's argument and ending at the time listed in the following event. When no then follows, the duration is used as the final boundary.

Example

var element = $('#block');
tk.onceFirst(function() {
    element.css('background', 'green');
}).then('2s', function() {
    element.css('background', 'red');
}).then('7s', function() {
    element.css('background', 'blue');
}).then('9s', function() {
    element.css('background', 'yellow');
}).then('13s', function() {
    element.css('background', 'purple');
});

Watch

function	onceFirst
background	green