API Document
This document describes the core parameters and methods of the Beauty AR Web SDK.
Note:
The Beauty AR Web SDK relies on hardware acceleration to achieve smooth rendering. The SDK allows you to check whether a browser supports hardware acceleration. You can block the browser if it does not support hardware acceleration.
import {ArSdk, isWebGLSupported} from 'tencentcloud-webar'if(isWebGLSupported()) {const sdk = new ArSdk({...})} else {// The browser blocking logic}
Initialization Parameters
import { ArSdk } from 'tencentcloud-webar'// Initialize the SDKconst sdk = new ArSdk({...})
Config
of the SDK supports the following initialization parameters:Parameters | Description | Type | Required |
module | The module configuration |
| No. It is {beautify: true, segmentation: false} by default. |
auth | The authentication parameter |
| Yes |
input | Source | MediaStream|HTMLImageElement|String | No |
camera | Built-in Camera |
| No |
mirror | Mirrored or not, mirroring of input streams is supported.(supported since 1.0.19) | Boolean | No |
beautify | The beauty filter parameter |
| No |
background | The background parameter |
| No |
loading | The configuration of the built-in loading icon |
| No |
language | i18n | String: zh | en | No, default is 'zh' |
Callbacks
let effectList = [];let filterList = [];// Using the callbacks of the SDKsdk.on('created', () => {// Pull and display the filter and effect list in the `created` callbacksdk.getEffectList({Type: 'Preset',Label: 'Makeup',}).then(res => {effectList = res});sdk.getCommonFilter().then(res => {filterList = res})})sdk.on('cameraReady', async () => {// By getting the output stream in the `cameraReady` callback, you can display a video image sooner, but the initialization parameters have not taken effect at this point.// You can choose this method if you want to display a video image as soon as possible but do not need to apply effects to the video the moment it is displayed.// You don’t need to update the stream after the effects start to work.const arStream = await ar.getOutput();// Play the stream locally// localVideo.srcObject = arStream})sdk.on('ready', () => {// Get the output stream in the `ready` callback. The initialization parameters have taken effect at this point.// You can get the output stream in `ready` if you want your video to show effects the moment it is displayed but do not expect it to be displayed as soon as possible.// Between the two methods, choose the one that fits your needs.const arStream = await ar.getOutput();// Play the stream locally// localVideo.srcObject = arStream// Call `setBeautify`, `setEffect`, or `setFilter` in the `ready` callbacksdk.setBeautify({whiten: 0.3});sdk.setEffect({id: effectList[0].EffectId,intensity: 0.7});sdk.setEffect({id: effectList[0].EffectId,intensity: 0.7,filterIntensity: 0.5 // In v0.1.18 and later, you can use this parameter to set the filter strength of a special effect. If you do not pass this parameter, the strength specified for the effect will be used.});sdk.setFilter(filterList[0].EffectId, 0.5)})
Events | Description | Callback Parameter |
created | The SDK authentication was completed and the instance was created successfully. | - |
cameraReady | The SDK generated a video output (the video is not yet processed). | - |
ready | Detection has been initialized. Effects are now applied to the output video. You can change the effect settings. | - |
error | This callback is triggered when the SDK encounters an error. | The error object |
APIs
API | Parameters | Back | Description |
async initCore() |
| - | For pre-initialization scenarios only, it provides input information to the SDK. For details, see Loading Optimization |
async getOutput(fps) | fps (optional): The output frame rate. | MediaStream|String | - |
setBeautify(options) |
| - | This API is used to set the beauty filter parameter. You need to enable the beauty filter module. |
setEffect(effects, callback) | effects: Effect ID | Effect object | Effect ID / An effect array
callback: The callback for successful configuration | - | This API is used to set an effect. You need to enable the beauty filter module. 3D effects are supported by Advanced licenses only. |
setAvatar(params) |
| - | This API is used to set an animoji or virtual avatar. Supported by Advanced licenses only |
setBackground(options) |
| - | |
setSegmentationLevel(level) | level: 0 | 1 | 2 | - | Switch the background segmentation model |
setFilter(id, intensity, callback) | id: The filter ID intensity: The filter strength. Value range: 0 - 1. callback: The callback for successful configuration. | - | This API is used to set a filter. |
getEffectList(params) |
| | This API is used to pull the list of effects. |
getAvatarList(type) |
| The list of virtual avatars | |
getEffect(effectId) | effectId: The effect ID | The information of a single effect | This API is used to pull the information of the specified effect. |
getCommonFilter() | - | The list of built-in filters | This API is used to get the list of built-in filters. |
async updateInputStream(src:MediaStream) | src: New input stream ( MediaStream ) | - | This API is used to update the input stream. |
disable() | - | - | This API is used to disable facial detection, which can reduce CPU usage. After it's disabled, the original stream will be returned. |
enable() | - | - | This API is used to enable facial detection. After it's enabled, the stream returned will have been processed. |
async takePhoto() | - |
| This API is used to take a photo and return an object containing the buffer data. |
destroy() | - | - | This API is used to terminate the current SDK instance and relevant texture resources. |
Error Handling
The error object returned by the error callback includes the error code and error message, which facilitate troubleshooting.
sdk.on('error', (error) => {// Handle an error in the error callbackconst {code, message} = error...})
Error Code | Description | Remarks |
10000001 | The current browser environment is incompatible. | Recommend the user to use Chrome, Firefox, Safari, or the Weixin browser. |
10000002 | The render context is missing. | - |
10000003 | The rendering is slow. | Consider reducing the video resolution or disabling the feature. |
10000005 | An error occurred while parsing the input source. | - |
10000006 | Lag may occur due to insufficient browser support. | Recommend the user to use Chrome, Firefox, Safari, or the Weixin browser. |
10001101 | An error occurred while configuring the effect. | - |
10001102 | An error occurred while configuring the filter. | - |
10001103 | The effect strength parameter is incorrect. | - |
10001201 | Failed to turn on the camera. | - |
10001202 | The camera stopped. | - |
10001203 | Failed to get the camera permission. | The user needs to enable the camera permission by going to Settings > Privacy > Camera. |
20002001 | The authentication parameter is missing. | - |
20001001 | Authentication failed | Make sure you have created a license and the signature is correct. |
20001002 | The API request failed. | |
20001003 | Failed to authenticate the effect configuration API. | The API is inaccessible. A Standard license cannot use the features of an Advanced license. |
40000000 | An uncaught exception occurred. | - |
40000001 | As the current SDK version is too low, certain effects cannot be correctly displayed. Upgrade the SDK version. | - |
50000002 | The effect is lost due to the resolution change. | The effect needs to be reconfigured. |
Handling the missing render context error
On some computers, if the SDK is in the background for a long time, the
contextlost
error may occur. In such cases, you can call ArSdk.prototype.resetCore(input: MediaStream)
to resume rendering.sdk.on('error', async (error) => {if (error.code === 10000002) {const newInput = await navigator.mediaDevices.getUserMedia({...})await sdk.resetCore(newInput)}})