gl-chromakey

Chroma key a video/image/canvas element in real time using the GPU via WebGL 2.

• Supports multiple key colors with adjustable tolerance, edge smoothness and spill correction
• Supports automatic background color detection (best with solid backgrounds)
• Designed for requestAnimationFrame (when used with video)
• No dependencies

Installation

$ npm i gl-chromakey

API

new GLChroma(source: HTMLVideoElement | HTMLImageElement | HTMLCanvasElement, target: HTMLCanvasElement | WebGL2RenderingContext)

• source: Source video, image or canvas element to key
• target: Target canvas element on which to paint keyed image(s)

import GLChroma from 'gl-chromakey'

const video = document.getElementById('source-video')
const canvas = document.getElementById('target-canvas')

// initialize with source video and target canvas
const chroma = new GLChroma(video, canvas)

.key(...keys: Key[]): GLChromaKey

Sets one or more key colors in RGB, replacing any prior settings. Calling without parameters clears all key colors.

• key: any of the following:
  • the string 'auto'
  • RGB color in the form [r, g, b]
  • array of objects with properties:
    • color (required): the string 'auto' or an RGB color in the form [r, g, b]
    • tolerance: Color tolerance; float ranged 0-1. Higher values result in a larger range of colors being keyed (default=0.1)
    • smoothness: Edge smoothness; float ranged 0-1. Higher values result in more transparency near the key color (default=0.1)
    • spill: Spill suppression; float ranged 0-1. Higher values result in more desaturation near the key color (default=0.1)

The auto key color mode downsamples the source image, grabs each corner pixel, and keys on the two pixels with the most similar color. It works best on videos or images with simplistic backgrounds, and can cause flickering if the algorithm gets it wrong. Use with caution.

Examples:

// auto-detect background color
chroma.key('auto')

// which is equivalent to:
chroma.key({ 
  color: 'auto', 
  tolerance: 0.1,
  smoothness: 0.1,
  spill: 0.1
})

// specify a very, very greenscreen
chroma.key([0, 255, 0])

// which is equivalent to:
chroma.key({ 
  color: [0, 255, 0], 
  tolerance: 0.1,
  smoothness: 0.1,
  spill: 0.1
})

.render(options?: RenderOptions): GLChromaKey

Updates frame from source element and paints to target canvas. The following excerpt shows its use with a video element and a requestAnimationFrame loop:

let frameId

// methods for render loop
startChroma = () => {
  frameId = requestAnimationFrame(startChroma)
  chroma.render()
}
stopChroma = () => cancelAnimationFrame(frameId)

// follow <video> element events
video.addEventListener('play', startChroma)
video.addEventListener('pause', stopChroma)
video.addEventListener('ended', stopChroma)

.source(el: HTMLVideoElement | HTMLImageElement | HTMLCanvasElement): GLChromaKey

Sets a new source video, image or canvas element to key.

• el: the new video/image/canvas element

.target(canvas: HTMLCanvasElement | WebGL2RenderingContext): GLChromaKey

Sets a new target canvas on which to paint keyed image(s). The context webgl2 will be used.

• canvas: the new HTMLCanvasElement element

Utility methods

.getContentBounds(): [x1: number, y1: number, x2: number, y2: number]

Meant to be called after render(), returns the coordinates of a bounding box around non-transparent pixels in the form [x1, y1, x2, y2]

.supportsWebGL2(): boolean

Whether the browser supports WebGL 2.

Demo & Development

1. Clone the repo
2. Place your video file in the public folder
3. Update the videoUrl in src/demo.js, and optionally the video or canvas attributes in index.html
4. npm i
5. npm run dev

Acknowledgements

• Based on work by Brian Chirls