Skip to main content

Getting started with DeepAR Beauty on Web

Install​

via NPM​

Install from NPM.

npm install @deepar/beauty

Import as ES6 module.

import * as Beauty from "@deepar/beauty"

Fetch from CDN​

Fetch from jsDelivr.

<script src="https://cdn.jsdelivr.net/npm/@deepar/beauty"></script>

Alternatively, you can import DeepAR as an ES6 module.

Via <script type='module'>.

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

Or via dynamic import.

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

Install DeepAR​

DeepAR Beauty works on top of DeepAR. Please install it and set it up first. There is a free license for development and testing.

Initialize Beauty API​

Initialize DeepAR first.

const deepAR = await deepar.initialize({
    licenseKey: "your_license_key_here",
    previewElement: document.querySelector('#deepar-div')
})

Then initialize DeepAR Beauty.

const beauty = await Beauty.initializeBeauty(deepAR, "https://cdn.jsdelivr.net/npm/@deepar/beauty/dist/");

You must provide a path to the root directory of the DeepAR Beauty library. That path will be used to fetch all assets. The easiest way is to provide a path to jsDelvr DeepAR Beauty package. Just make sure to pass the correct package version. The other way is to copy the whole DeepAR Beauty library directory from node_modules to dist and pass a relative path to the copied directory.

Getting started​

DeepAR Beauty API is straightforward to use. You can start experimenting with these API calls.

beauty.faceMorphing.eyeSize.set(-50)
beauty.skinSmoothing.set(85)
beauty.faceMakeup.blush.intensity.set(40)
beauty.faceMakeup.blush.color.set({r:226, g:132, b:130, a:255})
beauty.lipMakeup.lipstick.enable.set(true)
beauty.lipMakeup.lipstick.shade.setTemplate("matteNude")
beauty.lipMakeup.lipstick.amount.set(70)
beauty.colorFilters.filter.setTemplate("filmContrast")
beauty.disable(true)
beauty.disable(false)

API explained​

Beauty API consists of parameters grouped into namespaces based on functionality. For example, the eyeSize parameter is contained in the faceMorphing namespace. A full API call looks like this:

beauty.faceMorphing.eyeSize.set(-50)

Each namespace can have more namespaces nested in them. For example, lipMakeup namespace has two more namespaces nested: lipstick and lipGloss. Each is referenced like this:

  • lipMakeup.lipstick
  • lipMakeup.lipGloss

Each namespace can contain one or more parameters. For example, lipMakeup.lipstick namespace contains 3 parameters: enable, shade and amount. Example of calling all of them:

beauty.lipMakeup.lipstick.enable.set(true)
beauty.lipMakeup.lipstick.shade.setTemplate("matteNude")
beauty.lipMakeup.lipstick.amount.set(70)

Common parameter API​

Each Beauty parameter has 5 common API calls:

  • set(value, id?) - Set the value of the parameter (and optionally set the value id).
  • get() - Get the current value of the parameter.
  • reset() - Reset the parameter to its default value.
  • disable(boolean) - Disable/enable the parameter. If parameter is disabled it will use its default value. This is used to implement toggling before/after functionality.
  • getId() - Get the current id of the parameter.

Parameter types​

Parameters can be of 4 types:

  • Number.
  • Boolean.
  • Color.
  • Texture.

Number parameters have a valid range. For example, faceMoprhing.eyeSize is a number parameter with a valid range [-100, 100]. Example usage:

beauty.faceMorphing.eyeSize.set(-50)

Boolean parameter example usage:

beauty.lipMakeup.lipstick.enable.set(true)

Color parameters are RGBA values in range [0, 255]. Example usage:

beauty.faceMakeup.blush.color.set({r:226, g:132, b:130, a:255})

Texture parameters are images. They are most commonly set with template values (read next section). But they can also be set with custom images. Supported image types are:

  • png
  • jpeg
  • webp

Example usage:

// Set with template.
beauty.lipMakeup.lipstick.shade.setTemplate("matteNude")
// Set with custom image.
beauty.lipMakeup.lipstick.shade.set("url/to/some/image")

Common namespace API​

Each Beauty namespace has two common API calls:

  • reset() - Reset all child parameters and namespaces to default values.
  • disable(boolean) - Disable/enable all child parameters and namespaces. Works the same as parameter disable/enable, but just on a namespace level.

Example of resetting few namespaces:

beauty.faceMorphing.reset()
beauty.faceMakeup.blush.reset()
beauty.lipMakeup.lipstick.reset()
beauty.eyeMakeup.reset()

Reset all Beauty parameters:

beauty.reset()

Temporarily disable all face makeup to compare before and after:

beauty.faceMakeup.disable(true)
// Later re-enable...
beauty.faceMakeup.disable(false)

Temporarily disable all beauty to compare before and after:

beauty.disable(true)
// Later re-enable...
beauty.disable(false)

Template values​

Some Beauty parameters come with prepackaged values/assets for easier use. For example, blush and contours comes with few commonly used colors, eyelashes comes with many prepackaged looks, and lipstick comes with many prepackaged shades.

These prepackaged values/assets are called templates. Parameters that have templates share these 3 additional API calls:

  • setTemplate(template) - Set parameter template.
  • getTemplateValue(template) - Returns the underlying value of the given template.
  • getTemplates() - Returns a full list of templates.

Templates are referenced with a string name or an enum. For example, these two API calls are equivalent.

beauty.lipMakeup.lipstick.shade.setTemplate("caramel")
beauty.lipMakeup.lipstick.shade.setTemplate(Beauty.LipstickShadeTemplate.caramel)

Looks and presets​

DeepAR Beauty comes with ready-made looks and presets. These can be used as-is, or they can be a great starting point for making new looks or presets. They are also used to save and share the creations made with DeepAR Beauty.

🎁 Download looks and presets here.

What is the difference between looks vs presets? Presets are part of a whole look and they can be combined to make a completely new look. For example, there are presets for each main category: face makeup, eye makeup and lip makeup.

To import a look/preset call:

beauty.importPreset("path/to/preset")

To export a look/preset call:

beauty.exportPreset(type)

Where type can be:

  • Beauty.ExportType.LOOK or "LOOK".
  • Beauty.ExportType.PRESET or "PRESET".
  • Beauty.ExportType.PARAMETER_PRESET or "PARAMETER_PRESET".

⚠️ NOTE: Disabled parameters will not be exported.

About IDs​

Each Beauty parameter has these 2 common API calls:

  • set(value, id?) - Set the value of the parameter (and optionally set the value id).
  • getId() - Get the current id of the parameter.

The ID parameter is just a plain string.

What are this IDs used for? They are used to match the exact assets/values for parameters when they are exported/imported. For example, when you import some look/preset, you may want to show in the UI value for some parameter. For number parameters, it's easy, you just show the number of getValue() API. But for texture parameters it's a bit trickier. You can also call getValue() but that will return a image, and it's hard to compare images. So you can instead call getId() which will return a string that you can easily compare.

Runtime API​

To list all the available parameters and inquire about their info, use the API in runtime namespace. Example call:

beauty.runtime.setParameterValue("faceMorphing.eyeSize", -50)

Here is a list of all the runtime API methods.

  1. getParametersInfo()​

    Get a list of all the parameters, their default values, valid ranges and templates.

Returns a list of ParameterInfo:

interface ParameterInfo {
    type: "float" | "boolean" | "rgb" | "rgba" | "texture",
    name: string,
    defaultValue: ParameterType,
    templates?: string[],
    validRange?: { min: number, max: number };
}

  1. setParameterValue(name: string, value: ParameterType, id?: string)​

    Set the value of the parameter by the given name.

  2. getParameterValue(name: string)​

    Get the value of the parameter by the given name.

Returns the current value of the parameter.

  1. reset(name: string)​

    Reset the parameter/namespace by the given name.

  2. disable(name: string)​

    Disable/enable the parameter/namespace by the given name.

  3. getParameterId(name: string)​

    Get the id of the parameter by the given name.

Returns the current id of the parameter.

  1. setParameterTemplate(name: string, template: string)​

    Set the template for the parameter by the given name.

  2. getParameterTemplates: (name: string)​

    Get all the templates available of the parameter by the given name.

Returns the list of template names.

  1. getParameterTemplateValue: (name: string, template: string)​

    Get the value associated with the template of the parameter by the given name.

Returns the template value.