Projector.js

A small no-dependencies JavaScript library that enables the display of overlays on native HTML5 video elements, or (optionally) video elements powered by videojs. Overlays can be triggered via time ranges or events. A set of useful overlays is (WIP) included to cover common use cases.

Getting Started

Raw browser

You need to include both the javascript and css files from the project. Both of these are located in the dist directory.

<head>
    <script src="projector.min.js"></script>
    <link rel="stylesheet" type="text/css" href="../dist/css/projector-js.min.css">
</head>
<body>
    <video id="video" controls>
        <source src="video.webm" type="video/webm">
    </video>
    <script>
    var v = Projector.init('video');
    v.addOverlay(
        Projector.TextBox({text: "Hello"}),
        {
            top: '50%',
            left: '50%',
            timings: [
                {
                    timing:'0-10,15-20'
                }
            ]
        }
    )
    </script>
</body>

Or you can use projector.js with videojs:

<head>
    <script src="video.js"></script>
    <link href="video-js.css" rel="stylesheet">
    <script src="projector.min.js"></script>
    <link rel="stylesheet" type="text/css" href="../dist/css/projector-js.min.css">
</head>
<body>
    <video id="videojs-test" controls>
        <source src="video.webm" type="video/webm">
    </video>
    <script>
    var v = videojs("videojs-test").projector();
    v.addOverlay(
        Projector.TextBox({text: "Hello"}),
        {
            top: '50%',
            left: '50%',
            timings: [
                {
                    start: 5,
                    end: 10
                },
                {
                    start: 15,
                    end: 20
                }
            ]
        }
    );
    </script>
</body>

Other require libs

Projector.js uses the UMD pattern and so should work with both require.js and browserify.

Considerations

Overlays block clicks

A common issue with video overlays is that one overlay blocks events from hitting other overlays that are underneath. E.g, you have 2 overlays that both provide user input, but because one is on top, the other is not accessible.

Projector.js attempts to counter this by assigning the pointer-events: none; CSS property to overlay wrappers (.projector-overlay). This allows child elements to be clickable, but the containing overlay div (which covers the whole video) allows events to "pass-through." However, this is a new property and support is limited on older browsers. It is of note that it is unsupported on < IE11.

A good way to avoid this issue is to keep all individual elements on a separate overlay. I.e. avoid having 2 separate divs in a single overlay. This would cause the overlay container to stretch to fit both, introducing transparent white space which would block clicks if on a browser that does not support pointer-events.

Scaling up videos

It is important to use percentage values for dimensions/margins/paddings if you want your overlay to scale up if the video size changes (I.e. full screen).

Projector.js sets the font-size of the overlay wrappers to 1% of the width of the video. This should allow you to use em or percentage values for font-size. You could also use viewport units if you don't care about older browsers.

Sub-second accuracy

Different browsers report the time elapsed at different intervals. This unfortunately limits the use of milliseconds. Projector.js does not currently support milliseconds, but is being considered for inclusion in the library via setTimeout() hacks. Regardless, exact precision is not easily achievable and is out of scope.

Dirty triggers

Projector.js ensures your overlay is active between the user-specified times. Consequentially, as the users elapsed video time breaches a user specified time period, the relevant overlay is triggered to be active.

However, the user may have seeked directly into this time period, and not naturally watched the video in real time. For this reason, callbacks such as beforeBeginOverlay are passed a "dirty" flag when the user has seeked into one of the specified time ranges. This allows the developer to disable certain affects when the player is used in this way, e.g. fade in animations.

Core API

Projector object

The projector object provides the intialization function to allow projectorjs to attach to your video element.

init(element, [options])

Type: function
Arguments: element<string|HTMLElement>, options<object>
Returns: pInstance

options

Instead of using the addOverlay function of a pInstance, you can use the shorthand method to specify all of your overlays in the initial options object. Please see the addOverlay documentation for full description of options.

var p = Projector.init(document.getElementById('video'), {
    overlays: [
        {
            overlay: Projector.TextBox({text: "Test"}),
            left:'40%',
            top: '50%',
            timings: [
                {
                    timing: '8-14'
                }
            ]
        }
    ]
});

// Add more overlays programmatically
p.addOverlay(...)

Init can also be called via video.js intialization.

var p = videojs("video").projector({
    // Options
    ...
});

// Add more overlays programmatically
p.addOverlay(...)

pInstance object

The pInstance (projector instance) object is attached to a single HTML or videojs video element. It exposes functions to attach overlays.

addOverlay

Type: function
Arguments: overlay<Overlay>, options<object>
Returns: pInstance

Attach an overlay object (see Bundled overlays) with the given options.