One Video

One Video is a harmonised video player API providing interaction with embedded YouTube, Vimeo and native HTML5 video players.

It works with any video embed HTML already present in the DOM - so an iframe element for YouTube/Vimeo embeds, or a video element for native HTML5 video.

Examples 🔗

Note, both examples below assume #my-video points to an embedded iframe (YouTube/Vimeo) or video (HTML 5) element.

Example 1: Listen for when the video player is ready to receive API requests.

onevideo('#my-video').then(player => {
    player.on('ready', () => {
        alert('ready!');
    });
});

Example 2: Get the video duration, then seek to and play 10 seconds before video end.

onevideo('#my-video').then(player => {
    player.on('ready', () => {
        player.getDuration().then(secs => {
            player.seekTo(secs - 10);
            player.play();
        });
    });
});

Note: A user's browser may block auto-play and API-induced play requests on videos. These will have no effect until the user manually interacts with the video.

Example 3: Prevent the video playing past the first 30 seconds, via the custom XSecondsReached Event.

onevideo('#my-video').then(player => {
    player.on('30+SecondsReached').then(secs => {
        player.pause();
    });
});

API 🔗

One Video is initiated on an element by passing it to the central onevideo() function:

onevideo(el) - registers One Video on a video, by passing it a reference or DOM selector pointing to the element, el, which is the YouTube/Vimeo embed iframe or the native video video element. Returns a promise, once the API (YouTube/Vimeo) has loaded, which is resolved with a Player object.

The Player object has the following methods:

on(evt, callback) - registers a callback, callback (function), to fire when an event, evt (string), happens. See Events.
play() - play the video. The user's browser may block this, however (see Examples).
pause() - pause/stop the video.
seekTo(secs) - seek to a point in the video corresponding to a number of seconds, secs (integer).
getCurrentTime() - get the current position of the video playhead. Returns a promise which is resolved with the number of seconds.
getDuration() - get the duration of the video. Returns a promise which is resolved with the duration of the video in seconds.
getAspect() - get the aspect ratio of the video. Returns a promise which is resolved with a string denoting the aspect ratio, either "4-3", "16-9" or "portrait" for phone videos.
getPlayer() - get the underlying player object, for deeper API interaction with the video. Returns either the API-wrapped object if YouTube/Vimeo or, if native video, the iframe element.

Events 🔗

One Video's harmonised API also means harmonised event names. Different video formats use different event names and structures, and you won't have to worry about that here.

One Video uses an eventset which is based on the Vimeo Player.JS API. Supported events are:

ready - fires when the video player is ready to receive API requests.
play - fires when the video is played.
pause - fires when the video is paused/stopped.
ended - fires when the video ends.
timeupdate - fires when the playhead is moved to a new position.
seeked - in practical terms, basically the same as the timeupdate event.

One Video also supports a custom event to fire when a specific number of seconds has been reached in the video:

XSecondsReached - where X is an integer e.g. 31SecondsReached. You can also set the event to fire when at least the specified numbed or seconds has reached, by adding a + after the integer i.e. 31+SecondsReached.

You can use other, player-specific events on the player by retrieving the player via the getPlayer() method. You'll obviously need to know the events the specific player supports; you can find the YouTube player API docs here, the Vimeo player API docs here, and the native player API docs here.

Download Download from Github

Did I help you? Feel free to be amazing and buy me a coffee on Ko-fi!