Skip to main content

Migrating to DeepAR Web v5.0.0

The new DeepAR Web v5 comes with a refreshed modern API:

  • Easy to use.
  • Fast integration.
  • Better error handling.
  • It uses convention over configuration for new users.

Don't be intimidated! All the changes are made to help developers with an easier and more standard/modern integration.

👉 Migrating to new version takes about 5-10 minutes.

Getting started​

There are two main ways to get deepar.js in your JavaScript project: via script tags or by installing it from NPM and using a build tool like Parcel, WebPack, or Rollup.

via Script tag​

Add the following code to an HTML file:

<html>
<head>
  <!-- Load deepar.js -->
  <script src="https://cdn.jsdelivr.net/npm/deepar/js/deepar.js"> </script>
</head>

<body>
  <!-- Canvas element for AR preview -->
  <canvas width="640" height="360" id="deepar-canvas"></canvas>
  <!-- Initialize DeepAR and load AR effect/filter -->
  <script>
    (async function() {
      const deepAR = await deepar.initialize({
        licenseKey: 'your_license_key_here',
        canvas: document.getElementById('deepar-canvas'),
        effect: 'https://cdn.jsdelivr.net/npm/deepar/effects/aviators'
      });
    })();
  </script>
</body>
</html>

via NPM​

Add deepar.js to your project using yarn or npm.

Note: Because we use ES2017 syntax (such as import), this workflow assumes you are using a modern browser or a bundler/transpiler to convert your code to something older browsers understand. However, you are free to use any build tool that you prefer.

import * as deepar from 'deepar';

const deepAR = await deepar.initialize({
  licenseKey: 'your_license_key_here', 
  canvas: document.getElementById('deepar-canvas'),
  effect: 'https://cdn.jsdelivr.net/npm/deepar/effects/aviators' 
});

DeepAR initialization​

DeepAR is now initialized with deepar.initialize() function. The function is async which means you can use await keyword to wait for the DeepAR to initialize. No more need to use the onInitialize callback.

const deepAR = await deepar.initialize(...);

You can also use then() syntax instead of await which is similar to using onInitialize callback but has better error handling capabilities.

deepar.initialize(...)
      .then((deepAR) => {
        // DeepAR is initialized.
      });

Initialize parameters​

The only two required parameters you need to pass during initialization are:

  • License key.
  • Canvas.
const deepAR = await deepar.initialize({
    licenseKey: 'your_license_key_here',
    canvas: document.getElementById('deepar-canvas')
});

Default camera​

Previous versions of DeepAR Web required a call to startVideo() after the DeepAR initialized to connect DeepAr to the webcam. DeepAR v5 already starts connected to the camera and no further calls are necessary.

Loading AR filters​

Previous versions of DeepAR Web used switchEffect function. In v5, the function is now async and has different parameters:

  • path URL path to a effect file or an ArrayBuffer of an effect file.
  • slot and face parameters are now optional.
await deepAR.switchEffect('path/to/ar/effect');

If you only need to load a single AR filter, you can also pass the effect in the initialize function.

const deepAR = await deepar.initialize({
    // ...
    effect: 'path/to/ar/effect'
});

This approach is also good if you need for DeepAR and the AR filter to load as fast as possible.

Take screenshot or video​

In previous versions of DeepAR Web, you called takeScreenshot function and then the result was produced in the onScreenshotTaken callback. In v5, takeScreenshot is async and resolves with an image.

const image = await deepAR.takeScreenshot();

Similar story holds for recording a video.

deepAR.startVideoRecording();
// Video is now recording...
// When user is ready to stop recording.
const video = await deepAR.finishVideoRecording();

WASM files and ML models​

Previous versions of DeepAR Web, required specifying paths to :

  • deepar.wasm
  • Face tracking model in downloadFaceTrackingModel function.
  • Segmentation model.

The DeepAR v5, also needs those files, but they are now automatically fetched from the JsDelivr CDN so you don't have to worry about it. However, if you care about download speed optimizations, see this guide.

Custom video sources​

In case you need custom camera or video functionality, here are all the different options:

DeepAR will by default use the user facing camera. It will also ask the camera permission from the user.

Use the back camera on the phones:

const deepAR = await deepar.initialize({
  // ...
  additionalOptions: {
      cameraConfig: {
          facingMode: 'environment'
      }
  }
});

Set up your own camera or custom video source:

const deepAR = await deepar.initialize({
  // ...
  additionalOptions: {
      cameraConfig: {
          disableDefaultCamera: true
      }
  }
});

// HTMLVideoElement that can contain camera or any video.
const video = ...;

deepAR.setVideoElement(video, true);

Initialize DeepAR but start the camera later. This is used when you do not want to ask the camera permission right away.

const deepAR = await deepar.initialize({
    // ...
    additionalOptions: {
        cameraConfig: {
            disableDefaultCamera: true
        }
    }
});

// When you want to ask the camera permission and start the camera.
await deepAR.startCamera();