What's under the hood

Svalbox is built using some dependencies, including:

• Vuejs 2 : because Svalbox is a Vue 2 component, it respects the usual (slightly different) Vue 2 lifecycle.
• Beyond Reality Face : real-time face tracking SDK.
• TensorFlow : end-to-end open source machine learning platform.
• Media Pipe : open source cross-platform, customizable ML solutions for live and streaming media.
• Face API : face tracker implemented on top of the TensorFlow.js core API.

Simple add a HTML tag which will contain the Svalbox component.

<!-- Component container -->
<div id="app"></div>

Now the HTML is placed, the component must be initialized using the following function:

// Initialize Svalbox with options
new Svalbox(
	container, // HTMLElement or string (CSS Selector) of container HTML element. Required.
	options // Object with Svalbox parameters. Optional.
) : <Svalbox> // Returns a not-yet initialized Svalbox instance.

For example:

// Initialize Svalbox with options
const sbox = new Svalbox('#app', {
	license: 'license_key',
	displayMode: 'cover',
	loader: {
		color: '#ff0000'
	}
});

Let's look on all available options, as follow.

This is the Svalbox lifecycle. The initialization process may be automatized by setting the autoPlay option to true.

[SCHEMA]

Once initialized, a Svalbox component provides a bunch of useful methods as follow. They all return a value if desired or return this. This mechanism makes the chaining possible.

create() : Svalbox

Create the HTMLElement and mount it into the page DOM. The component is resized to match the requested dimensions (width / height) if needed.

For example:

// Initialize the component
const sbox = new Svalbox('#app');

// Inject the component into the page DOM
sbox.create();

isCreated() : Boolean

Return true if the component is created (create() method executed and create event triggered), false otherwise.

For example:

sbox.on('create', (sbox) => {
	console.log(sbox.isCreated()); // true
});

console.log(sbox.isCreated()); // false

sbox.create();
console.log(sbox.isCreated()); // false

destroy() : Svalbox

Destroy the component, release the resources in memory and removes the HTMLElement from the page DOM.

For example:

sbox.destroy();

start() : Svalbox

Start the input stream. The component must be created before executing this method. If the autoPlay option is set to true , this method is automatically executed. If the inputStream.type option is set to 'live' , the customer will receive a browser notification requesting to allow the camera access. Once the input stream is started, the face tracker and renderer engines are initialized.

For example:

// Initialize the component
const sbox = new Svalbox('#app');

sbox.on('create', (sbox) => {
	// Start the input stream and initialize the face tracker and renderer
	sbox.start();
});

// Inject the component into the page DOM
sbox.create();

isStarted() : Boolean

Return true if the component is started (start() method executed and start event triggered), false otherwise.

For example:

// Initialize the component
const sbox = new Svalbox('#app');

sbox.on('create', (sbox) => {
	console.log(sbox.isStarted()); // false
	sbox.start();
	console.log(sbox.isStarted()); // false
});

sbox.on('start', (sbox) => {
	console.log(sbox.isStarted()); // true
});

sbox.create();
console.log(sbox.isStarted()); // false

stop() : Svalbox

Stop the input stream, including the physical camera.

For example:

sbox.stop();

toggleStart() : Svalbox

Shortcut to start the component if stopped, or stop it otherwise.

It does exactly as follow:

sbox.toggleStart = () => {
	if (sbox.isStarted()) {
		sbox.stop();
	} else {
		sbox.start();
	}
}

For example:

sbox.toggleStart();

play() : Svalbox

Play (or resume if previously paused) the input stream. The component must be created and started before executing this method. If the autoPlay option is set to true , this method is automatically executed.

Once the input stream is playing, the face tracking and rendering are processing.

For example:

// Initialize the component
const sbox = new Svalbox('#app');

sbox.on('create', (sbox) => {
	// Start the input stream and initialize the face tracker and renderer
	sbox.start();
});

sbox.on('start', (sbox) => {
	// Start the input stream and process the face tracking and rendering
	sbox.play();
});

// Inject the component into the page DOM
sbox.create();

isPlaying() : Boolean

Return true if the component is playing (play() method executed and play event triggered), false otherwise.

For example:

// Initialize the component
const sbox = new Svalbox('#app');

sbox.on('create', (sbox) => {
	console.log(sbox.isPlaying()); // false
	sbox.start();
	console.log(sbox.isPlaying()); // false
});

sbox.on('start', (sbox) => {
	console.log(sbox.isPlaying()); // false
	sbox.play();
	console.log(sbox.isPlaying()); // false
});

sbox.on('play', (sbox) => {
	console.log(sbox.isPlaying()); // true
});

sbox.create();
console.log(sbox.isPlaying()); // false

pause() : Svalbox

Pause the input stream, including the physical camera.

For example:

sbox.pause();

togglePlay() : Svalbox

Shortcut to play and resume the component if paused, or pause it otherwise.

It does exactly as follow:

sbox.togglePlay = () => {
	if (sbox.isPlaying()) {
		sbox.pause();
	} else {
		sbox.play();
	}
}

For example:

sbox.togglePlay();

on(event : String , callback : Function) : Svalbox

Provide a way to listen the Svalbox events and execute custom code. See the Events section to understand which events can be listened.

For example:

sbox.on('create', (sbox) => console.log('Svalbox created!'));

resetTracking() : Svalbox

Reset the face tracker and perform a new face tracking. Useful when the tracking is stuck on a wrong face.

For example:

sbox.on('touch', (sbox) => sbox.resetTracking());

setFacesCount(facesCount : Integer) : Svalbox

Set the number of faces which must be tracked. The greater this value, the slower the component.

For example:

sbox.setFacesCount(3);

getFacesCount() : Integer

Return the number of tracked faces.

For example:

console.log(sbox.getFacesCount()); // 3

setFrame(frame : Object) : Svalbox

Set the frame options. The frame parameter must contain the following properties:

• front: front image url / data,
• leftTemple: left temple image url / data,
• rightTemple: right temple image url / data,
• lenses : lenses image url / data.

For example:

sbox.setFrame({
	front: 'https://site.com/front.png', // Absolute url
	leftTemple: '/images/leftTemple.png', // Relative url
	rightTemple: 'data:image/png;base64,iVBORGgoANSUh...AABJRErkJgg==', //Base 64 data
	lenses: await (await fetch('https://site.com/lenses.png')).text() //Lazyloaded image data
});

getFrame() : Object

Return the current frame options.

For example:

console.log(sbox.getFrame());
/*
{
	front: 'https://site.com/front.png',
	leftTemple: '/images/leftTemple.png',
	rightTemple: 'data:image/png;base64,iVBORGgoANSUh...AABJRErkJgg==',
	lenses: 'data:image/...'
}
*/

setLenses(lenses : Object ) : Svalbox

Set the lenses options. The lenses parameter must contain the following properties:

• color : array of 1 or 2 (if vertical gratient) colors,
• reflectivity : float between 0 (none) and 1 (full) reflectivity coefficient.

For example:

sbox.setLenses({
	color: '["#FF0000"]',
	reflectivity: 0.5
});

getLenses() : Object

Return the current lenses options.

For example:

console.log(sbox.getLenses());
/*
{
	color: '["#FF0000"]',
	reflectivity: 0.5
}
*/

setMirrorImage(mirrorImage : String) : Svalbox

Set the mirror image which is reflected in the lenses.

For example:

sbox.setMirrorImage('https://site.com/mirror.jpg'); // Absolute url
sbox.setMirrorImage('/images/mirror.png'); // Relative url
sbox.setMirrorImage('data:image/png;base64,iVBORGgoANSUh...AABJRErkJgg=='); //Base 64 data
sbox.setMirrorImage(await (await fetch('https://site.com/mirror.png')).text()); //Lazyloaded image data

getMirrorImage() : String

Return the current mirror image.

For example:

console.log(sbox.getMirrorImage(); // 'data:image/...'

setDebug(isDebug : Bool ) : Svalbox

Enable or disable the debug mode.

For example:

sbox.setDebug(true);

isDebug() : Bool

Return true if the debug mode is enabled, false otherwise.

For example:

console.log(sbox.isDebug()); // true

setLoading(isLoading : Bool) : Svalbox

Enable or disable the loading mode. When enabled, a spinned is displayed over the component.

For example:

sbox.setLoading(true);

isLoading() : Bool

Return true if the component is loading (trigerred by setLoading()), false otherwise.

For example:

console.log(sbox.isLoading());

setDisplayMode(displayMode : Enum) : Svalbox

Mode used to display the component, based on 3 values, as follow:

• 'default' : the rendering keeps the initial ratio,
• 'cover' : the rendering covers the component,
• 'contain' : the rendering is contained into the component.

For example:

sbox.setDisplayMode('cover');

getDisplayMode() : String

Return the current mode used to display the component.

For example:

console.log(sbox.getDisplayMode()); // 'cover'

getSnapshot() : String (ImageData)

Take a snapshot of the rendering and return the image data.

For example:

<img id="image">
<script>
	const image = document.getElementById('image');
	image.src = sbox.getSnapshot();
</script>

Svalbox also comes with a some events which can be listened. See the on() method to understand how to listen an event.

create : Function(sbox : Svalbox)

Fired when the component is created by manually calling the create() method or by setting the autoPlay option to true .

destroy : Function(sbox : Svalbox )

Fired when the component is destroyed by manually calling the destroy() method.

start : Function(sbox : Svalbox)

Fired when the component is created by manually calling the start() method or by setting the autoPlay option to true .

stop : Function(sbox : Svalbox )

Fired when the component is created by manually calling the stop() method.

play : Function(sbox : Svalbox)

Fired when the component is created by manually calling the create() method or by setting the autoPlay option to true .

pause : Function(sbox : Svalbox )

Fired when the component is created by manually calling the pause() method.

touch : Function(sbox : Svalbox)

Fired when the user touches (mobile) or clicks on (desktop) the component.

touchhold : Function(sbox : Svalbox)

Fired when the user touches and holds (mobile) the component.

swipe : Function(sbox : Svalbox, data : Object)

Fired when the user swipes (mobile and desktop) on the component. The direction is set in data.direction and can be 'top', 'bottom' , 'left' or 'right'.

error : Function(sbox : Svalbox, data : Object)

Fired when an error occured.