Skip to main content

Getting started with DeepAR Web

As you follow this tutorial, we recommend using our demo project reference to assist you in integrating the SDK into your project.

Web Demo Project

Prerequisites​

To follow along you should have basic knowledge of creating web apps with Javascript and it's ecosystem. In this tutorial we are going to use:

  • NPM - Javascript package manager.
  • Webpack - Bundler for your javascript apps.

Don't worry if you don't have a lot of experience with these (or any experience at all). It is pretty straightforward to use and we will explain everything along.

Install node.js to be able to use NPM and Webpack if you haven't already.

Set up DeepAR account​

First thing you need to do is set up DeepAR account on our DeepAR developer portal. Developer portal is used to:

  • Download DeepAR SDK.
  • Access documentation and examples.
  • Manage your projects and app license.

DeepAR License Key​

To deploy your DeepAR web apps it is required to use DeepAR license key.

🔥 DeepAR offers unlimited FREE licences for testing and small projects. 🔥

  1. On developer portal, go to projects and click + New Project.
  2. Enter the name of your project. For example "My First AR App".
  3. Choose a FREE plan.
  4. Under Web App choose + Add App.
  5. Enter the domain name under which you plan to deploy your app.

    ⚠️ IMPORTANT ⚠️
    You need to enter the DOMAIN NAME, not the URL where your app is running.
    For example, if your app is running on
    > https://www.domain.com/application/ar
    the domain you need to enter is www.domain.com.
    Be sure to leave out any protocol name (like https) and additional paths (like application/ar).

🦁 Wildcard domains​

DeepAR now support wildcard domains (eg. *.deepar.ai) as an enterprise feature subject to manual review. If you need to use a wildcard domain, please contact us.

Now you have a valid license key for your DeepAR web app. Note that you can delete existing or create new unlimited free projects.

Installation​

Once you've obtained your license key, you're ready to seamlessly integrate the DeepAR Web SDK into your JavaScript project. This can be achieved through two primary methods:

  1. Installing it from NPM or yarn and using a build tool such as Parcel, WebPack, or Rollup.
  2. Utilizing script tags

Installing from NPM or yarn​

Add DeepAR Web SDK to your project using yarn:

yarn add deepar

or npm:

npm install deepar

Then you can simply import DeepAR SDK as follows:

import * as deepar from 'deepar';

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.

Script tag​

Instead of NPM or yarn you can add DeepAR Web SDK using script tag. Add the following code to an HTML file:

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

Alternatively, you can import DeepAR as an ES6 module.

Via <script type='module'>.

<script type='module'>
  import * as deepar from 'https://cdn.jsdelivr.net/npm/deepar/js/deepar.esm.js';
</script>

Or via dynamic import.

const deepar = await import('https://cdn.jsdelivr.net/npm/deepar/js/deepar.esm.js');

Initialization​

Now that you've successfully imported the DeepAR Web SDK, you're ready to start using it. To get started, the first step is to initialize DeepAR by calling the initialize function:

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

If you imported DeepAR using a script tag, you can easily incorporate it into your HTML as follows:

<body>
  <!-- Div element where AR preview will be inserted -->
  <div style='width: 640px; height: 360px' id='deepar-div'></div>
  <!-- Initialize DeepAR and load AR effect/filter -->
  <script>
    (async function() {
      const deepAR = await deepar.initialize({
        licenseKey: 'your_license_key_here',
        previewElement: document.querySelector('#deepar-div'),
        effect: 'https://cdn.jsdelivr.net/npm/deepar/effects/aviators'
      });
    })();
  </script>
</body>

The initialize function sets up the DeepAR SDK, applies the AR filter specified in the effect field, and displays the output on the HTML element defined in the previewElement.

Switch effects​

AR filters are represented by effect files in DeepAR. You can load them to preview the effect.

Places you can get DeepAR effects:

Load an effect using the switchEffect method:

await deepAR.switchEffect('path/to/effect/alien');

Take screenshot or video​

Take a screenshot.

// The image is a data url.
const image = await deepAR.takeScreenshot();

Record a video.

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

Background blur​

Enable background blur with strength 5.

await deepAR.backgroundBlur(true, 5)

Background replacement​

This is also known as background removal or green screen effect.

Enable background replacement with an image of a sunny beach.

await deepAR.backgroundReplacement(true, 'images/sunny_beach.png')

Callbacks​

DeepAR has some callbacks you can implement for additional information. For example, to check if a face is visible in the camera preview.

await deepAR.switchEffect('path/to/effect');
deepAR.callbacks.onFaceVisibilityChanged = (visible) => {
    if (visible) {
      console.log("Face visible!");
    } else {
      console.log("Face not visible!");
    }
};

See all available callbacks here.

To remove callback if you don't need it anymore.

delete deepAR.callbacks.onFaceVisibilityChanged;

Different video sources​

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();

Providing your own canvas for rendering​

Create canvas directly in the HTML:

<canvas width='1280' height='720'></canvas>

Or you can create it in Javascript.

const canvas = document.createElement('canvas');
// Set canvas size, accounting screen resolution (to make it look 🤌 even on high definition displays)
const canvasSize = { width: 640, height: 360 };
const dpr = window.devicePixelRatio || 1;
canvas.style.maxWidth = `${canvasSize.width}px`;
canvas.style.maxHeight = `${canvasSize.height}px`;
canvas.width = Math.floor(canvasSize.width * dpr);
canvas.height = Math.floor(canvasSize.height * dpr);

⚠️ Note: Be sure to set width and height properties of the canvas!

You can always change the canvas dimensions and they don't have to match the input video resolution. DeepAR will fit the input camera/video stream correctly to any canvas size.

You pass the canvas when initializing DeepAR.

await deepar.initialize({
  canvas: canvas, 
  // ...
});