VideoStack

An extension for camera access and video rendering.

VideoStack is a JavaScript library for consistent camera access and video rendering. Contact the Adtile team with a request to access VideoStack.

Using VideoStack

Incorporating VideoStack into your code is straightfoward; just include the VideoStack script tag before your other javascript source files and reference the VideoStack object from the global window object.


<script src="path/to/VideoStack.min.js"></script>

More examples below provide further instructions on using VideoStack.

Video rendering

VideoStack works by layering rendered videos and images, including camera feeds. Each video or image is considered a Layer.

To instantiate a new image or video, simply call the constructor with a DOM element or url to the requested media.

Renderers

A Renderer controls how layers are drawn onto a canvas element. Once instantiated, call start on a Renderer to begin executing shaders on the layers and stop when the Renderer no longer needs to be run.

Renderer([canvas])

Argument Type Description
canvas DOM Element Canvas element to be rendered to (optional).
Default: a canvas element is created and can be accessed via the instance's canvas property.

Renderer.addLayer(layer, index)

Add a layer in the appropriate position of the renderer's stack.

Argument Type Description
layer VideoLayer or ImageLayer Layer to be added in the rendering loop.
index Number Position of the layer. Index 0 is drawn first, and higher indexed layers are drawn on top of lower indexed layers.
Default: The index is set to be the largest present index, incremented by 1.

Renderer.start([canvas])

Starts rendering an animation loop in which the canvas is redrawn for each cycle of the loop.

Argument Type Description
callback Function Callback function that fires once per animation. No arguments are provided as this is primarily used to handle the logic for calling updateUniforms for each Layer added into the instance of Renderer.
context Object Context in which to invoke the callback (optional).

Renderer.stop()

Stops executing the callback function that is passed into the start method.

Renderer.updateUniform(uniforms)

Calls updateUniforms for each Layer of the instance of Renderer. Each layer receives the values as indicated in the argument. See image and video layers for more details.

Image and video layers

Renderer's work by stacking several image and video layers on top of one another until the desired animation is achieved. Each of these layers is constructed separately.

ImageLayer/VideoLayer constructor(source, [options])

Creates a new layer for an image or video.

Argument Type Description
source String or DOM Element String specifying a url (or base-64 encoding for images). DOM elements may also be used.
options Object Object describing requested constraints on camera feed (optional). (Note: these requests are not guaranteed to be followed, as browser implementations vary.)

  • options.autoplay {Boolean}
    Whether feed autoplays (video only).
    Default: false
  • options.size {String}
    Can either be "contain" or "cover".
    Default: "cover"
  • options.vertexShader {String}
    GLSL code to be used as vertex shader. This will override the size option.
    Default: Samples image according to above options.
  • options.fragmentShader {String}
    GLSL code to be used as fragment shader.
    Default: Samples image according to above options.

ImageLayer/VideoLayer updateUniforms(uniforms)

Argument Type Description
uniforms Object Object updated values for some of the uniforms used in the vertex and fragment shaders. Uniform property names should match the values in the shaders exactly and the property values should be the updated values.

VideoLayer.play()

Start playing a video.

VideoLayer.stop()

Stop playing a video.

Accessing the camera

Accessing the camera is very easy across many devices. For privacy reasons, a browser requires users' consent before accessing the camera. It is strongly recommended that best practices are followed to give the users an optimal experience and increasing the engagement rate of your audience. (See here, for examples.)

Compatibility: Due to browser requirements, VideoStack is only able to access the camera on iOS 11 or later, and Android 6 or later.

getUserMedia(onSuccess, onError, [options, context])

Dispatch request for user's camera feed

Argument Type Description
onSuccess Function Callback function that receives an object as an argument with its context bound to the optionally provided context argument.

  • function(e)
  • e.videoLayer {VideoLayer}
    An instance of a VideoLayer as described above, where the video source is the camera feed.
  • e.selfie {Boolean}
    Whether the feed comes from the selfie camera.
onError Function Callback function that receives an Error as an argument with its context bound to the optionally provided context argument.

  • function(err)
  • err {Error}
    Error provided for failure to attain video feed.

options Object Object describing requested constraints on camera feed (optional). (Note: these requests are not guaranteed to be followed, as browser implementations vary.)

  • options.autoplay {Boolean}
    Whether video feed autoplays.
  • options.selfie {Boolean}
    Whether selfie camera should be used.
  • options.dimensions['width', 'height'] {Number}
    Requested dimensions of camera feed.
context Object Context in which to invoke the callback (optional).