接口文档

本文档将介绍 Web 美颜特效 SDK 核心参数及方法。
说明:
Web 美颜特效 SDK 需要浏览器支持并开启硬件加速才能够流畅渲染(小程序端无需判断),因此 SDK 提供了检测方法供业务提前判断,如不支持则进行屏蔽处理。
import {ArSdk, isWebGLSupported} from 'tencentcloud-webar'

if(isWebGLSupported()) {
const sdk = new ArSdk({
...
})
} else {
// 屏蔽逻辑
}

初始化参数

import { ArSdk } from 'tencentcloud-webar'
// 初始化SDK
const sdk = new ArSdk({
... // 参考下述 Config 定义
})
初始化 SDK 的 Config 支持以下参数:
参数
说明
类型
是否必传
module
模块配置
type SegmentationLevel = 0 | 1 | 2 // 1.0.19 之后的版本支持传参选择分割模型,数值越高,分割效果越好,资源占用越大,fps 越低
type ModuleConfig = {
beautify: boolean // 是否开启美颜,默认为true
segmentation: boolean // 是否开启背景分割,默认为false
segmentationLevel: SegmentationLevel // 背景分割精确度等级,默认为 0
handGesture: boolean // 是否开启手势识别,默认为 false, 1.0.23 之后版本支持
handLandmark: boolean // 是否开启手部追踪,默认为 false,1.0.23 之后版本支持, 不推荐和 beautify 同时启用
}
否,默认为 {beautify: true, segmentation: false, segmentationLevel: 0,
handLandmark: false}
auth
鉴权参数
type AuthConfig = {
licenseKey: string // 控制台 Web License 管理 获取
appId: string // 控制台 账号信息 > 基本信息 查看 APPID
authFunc:() => Promise<{
signature:string,
timestamp:string
}> // 请参见 License 配置使用
}
input
媒体输入源,支持处理 mediaStream,图片,及视频
MediaStream | HTMLImageElement | String | HTMLVideoElement
live
直播模式配置
type live = {
pusherContext: LivePusherContext
fps: 'low' | 'high' // 默认low,仅 mode 为 custom 时生效,开启高帧的情况下,部分设备性能无法支持,建议根据设备性能进行差异化设置。
mode: 'custom' | 'native' // 不可切换,默认custom,可使用除虚拟背景外全部 Arsdk 功能, native模式使用微信底层功能实现了虚拟背景,但 Arsdk 原有功能将无法使用。
}
否,仅小程序支持
camera
内置相机
type CameraConfig = {
width: number, // 拍摄画面宽度
height: number, // 拍摄画面高度
mirror: boolean, // 是否开启左右镜像
frameRate: number // 画面采集帧率
}
mirror
是否镜像,支持输入流的镜像(1.0.19 新增)
Boolean
beautify
美颜参数
type BeautifyOptions = {
whiten?: number; // 美白 0-1
dermabrasion?: number; // 磨皮0-1
lift?: number; // 窄脸0-1
shave?: number; // 削脸0-1
eye?: number; // 大眼0-1
chin?: number; // 下巴0-1
// 注意:以下参数仅在1.0.11及以上版本可用
darkCircle?: number; // 黑眼圈0-1
nasolabialFolds?: number; // 法令纹0-1
cheekbone?: number; // 颧骨0-1
head?: number; // 小头0-1
eyeBrightness?: number; // 亮眼0-1
lip?: number; //嘴唇 -1 - 1
forehead?: number; //发际线 0-1
nose?: number; // 鼻子 -1 - 1
usm?: number; // 清晰 0-1
}
background
背景参数
type BackgroundOptions = {
type: 'image' | 'blur' | 'transparent' | 'video', // 1.0.23 版本开始支持 video 类型动态背景
src?: string, // image 或 video 类型指定的图片地址
edgeBlur ?: number, // 1.0.25 版本开始支持,取值范围:0-10, 控制边缘模糊程度,取值越小,边缘切割得越锋利,模糊程度越低。
}
loading
内置 loading icon 配置
type loadingConfig = {
enable: boolean,
size?: number
lineWidth?: number
strokeColor?: number
}

language
国际化对应(1.0.6版本开始支持),中文(zh)和英文(en)
String: zh | en
否,默认 zh
logLevel
打印控制台日志等级
'OFF' | 'ERROR' | 'WARN' | 'DEBUG' | 'TRACE' | 'INFO'
否,默认 INFO,全部打印
initReport
是否初始化日志上报模块
Boolean
否,默认为 true
worker
是否禁用浏览器 worker,以优化特定场景的性能
String: auto | disable
否,默认 auto,SDK 根据当前浏览器环境决定是否使用 worker
proxyServer
内网代理模式用
type proxyServeConfig = {
webarProxy: string; // 接口代理的内网地址
staticProxy: string; // 资源代理的内网地址
}

回调事件

let effectList = [];
let filterList = [];
// sdk 的回调用法
sdk.on('created', () => {
// 在 created 回调中拉取特效和滤镜列表供页面展示
sdk.getEffectList({
Type: 'Preset',
Label: '美妆',
}).then(res => {
effectList = res
});
sdk.getCommonFilter().then(res => {
filterList = res
})
})
sdk.on('cameraReady', async () => {
// 在 cameraReady 回调中可以更早地获取输出画面,此时初始化传入的美颜参数还未生效
// 适用于需要尽早地展示画面,但不要求画面一展示就有美颜的场景
// 后续美颜生效后无需更新stream,SDK内部已处理
const arStream = await ar.getOutput();
// 本地播放
// localVideo.srcObject = arStream

})
sdk.on('ready', () => {
// 在 ready 回调中获取输出画面,此时初始化传入的美颜参数已生效
// 区别上述cameraReady中获取output,适用于画面一展示就要有美颜的场景,但不要求尽早地展示画面
// 根据自身业务需求选择一种处理方式即可
const arStream = await ar.getOutput();
// 本地播放
// localVideo.srcObject = arStream

// 在 ready 回调中调用 setBeautify/setEffect/setFilter 等渲染方法
sdk.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 // 0.1.18及以上版本支持单独设置effect中滤镜的强度,不传则默认与特效的intensity保持一致
});
sdk.setFilter(filterList[0].EffectId, 0.5)
})
// 开启手势识别后,监听到手势变化时触发
sdk.on('handGesture',(hands)=>{
// 对应 hand 取值 none, thumb_up, thumb_down, victory, pointing_up, open_palm, iloveyou
})
// error 回调,影响 sdk 使用的 error 发生
sdk.on('error', (data)=>{
console.log('error', data.code, data.message)
})
// warning 回调,常见于 sdk 检测到耗时占用增加时抛出警告
sdk.on('warning', (data)=>{
console.log('warning', data.code, data.message)
})
事件
说明
回调参数
created
SDK 鉴权完成并成功创建实例时触发
-
cameraReady
SDK 的画面生成时触发,此时 output 已有画面但美颜仍无法生效
-
ready
SDK 内部检测初始化完成时触发,此时 output 画面已有美颜,也可以设置新的特效
-
error
SDK 发生错误时触发
error 对象
warning
SDK 发生警告时触发
warning 对象
handGesture
开启手势识别后,监听到手势变化时触发
识别到的手势
detectStatusChange
人脸检测状态发生变化时触发
Boolean, 是否识别到人脸

对象方法

接口
参数
返回
说明
setBeautify(options)
type BeautifyOptions = {
whiten?: number; // 美白 0-1
dermabrasion?: number; // 磨皮0-1
lift?: number; // 窄脸0-1
shave?: number; // 削脸0-1
eye?: number; // 大眼0-1
chin?: number; // 下巴0-1
// 注意:以下参数仅在1.0.11及以上版本可用
// 以下参数小程序不可用
darkCircle?: number; // 黑眼圈0-1
nasolabialFolds?: number; // 法令纹0-1
cheekbone?: number; // 颧骨0-1
head?: number; // 小头0-1
eyeBrightness?: number; // 亮眼0-1
lip?: number; //嘴唇 -1 - 1
forehead?: number; //发际线 0-1
nose?: number; // 鼻子 -1 - 1
usm?: number; // 清晰 0-1
}
-
设置美颜参数,需开启美颜模块,小程序仅支持前5个

setEffect(effects, callback, errCallback)
effects:特效 ID | Effect 对象 | (特效 ID | Effect对象) 数组
// effect对象
type Effect = {
id: string; // 特效 id
intensity: number; // 特效整体强度,取值范围 0-1,默认为 1
filterIntensity: number; // 特效中的滤镜强度啊,取值范围 0-1,默认为 1
};
callback:设置成功的回调
errCallback: 失败回调
-
设置美妆、贴纸特效,需开启美颜模块
3D 类特效仅高级版License 支持
setAvatar(params)
{
mode: 'AR' | 'VR',
effectId?: string, // 透传effectId使用内置模型
url?: string, // 透传url使用自定义模型
backgroundUrl?: string, // 背景图片链接,仅在VR模式下生效
}
-
设置 Animoji 表情或虚拟形象
仅高级版 License 支持
setBackground(options)
{
type: 'image|video|blur|transparent', // 1.0.23 版本开始支持 video 类型动态背景
src: string, // image|video类型需要
edgeBlur: number, // 1.0.25 版本开始支持,取值范围:0-10, 控制边缘模糊程度,取值越小,边缘切割得越锋利,模糊程度越低。
}
-

设置背景,Web 端需开启人像分割模块,小程序推流仅支持直接传入图片地址
setForeground(options)(1.0.23 版本开始支持)
{
type: 'image|video',
src: string // 资源路径,base64或者在线地址
}
-
设置固定于屏幕的全屏前景效果
setSegmentationLevel(level)
level: 0 | 1 | 2
-
切换背景分割模型的等级
setFilter(id, intensity, callback, errCallback)
id:滤镜 ID
intensity:滤镜强度,取值范围0-1,默认为 1
callback:设置成功回调
errCallback: 失败回调
-
设置滤镜
getEffectList(params)
{
PageNumber: number, // 分页,默认 0
PageSize: number, // 分页大小,默认 1000
Name: '', // 特效名称
Label: string | Array<string>, // 特效标签、特效标签列表
Type: 'Custom' | 'Preset' // 特效类型, Custom-用户自定义特效,Preset-内置特效
}

特效列表
拉取特效列表
getAvatarList(type)
type = 'AR' | 'VR' // AR-Animoji,VR-虚拟形象
Animoji/虚拟形象列表

拉取Animoji/虚拟形象列表
getEffect(effectId)
effectId:特效 ID
单个特效信息
拉取指定特效的信息
getCommonFilter()
-
内置滤镜列表
获取内置滤镜列表
async initCore()

{
input?: MediaStream|HTMLImageElement|String; // 输入源
camera?: CameraConfig; // 摄像头模式
mirror?: boolean; // 是否镜像
}
-
仅供预初始化方案使用,为 SDK 提供输入信息,详情参考 加载优化
async updateInputStream(src, stopOldTracks) (0.1.19版本后支持)
src:新的输入流 MediaStream
stopOldTracks: 是否停掉旧的 MediaTrack
-
更新输入媒体流
updateInputImage(options)(1.0.24版本后支持)
{
width: number;// 图片渲染高度
height: number; // 图片渲染宽度
input: string;// 图片地址
}
-
更新输入图片
async getOutput(type:OUTPUT_TYPES, fps:number)
enum OUTPUT_TYPES {
IMAGE = 3,
MEDIA_STREAM = 4,
}
type: 3 | 4 // 3-image, 4-mediastream, 输入为图片时,输出默认为 3, 输入为非图片时,输出默认为 4
fps:设置输出的媒体流帧率,默认与输入媒体的 fps 一致
MediaStream | String
仅 Web 端提供,小程序暂不支持
disable()
-
-
停用面部检测,返回未处理的原始画面,可以降低 CPU 使用率
enable()
-
-
恢复面部检测,返回美颜等特效生效的画面
stop()
-
-
暂停画面,画面静止
resume()
-
-
恢复画面,画面播放
async startRecord(options)
{
audio: {format: string}, // audioRecorder 配置,与小程序内置全局 AudioRecorder 参数一致
recordCamera: boolean // 是否录制原始摄像头流,默认 false
}
-
开始录像(仅小程序端支持)
async stopRecord()
{
useOriginAudio: boolean, // 是否录制视频原声
musicPath: string, // 背景音乐地址,useOriginAudio为false时生效
}
录像
结束录像并返回录像结果(仅小程序端支持)
async takePhoto()
-
{
data: Uint8Array | Uint8ClampedArray,
width: number,
height: number
}
拍照接口,返回一个包含 buffer 数据的对象,
小程序端返回为Uint8Array,web 端返回为 ImageData
async initLocalPlayer(id)
id: string // 本地预览用 dom id
-
提供一个便捷的,预览 SDK 输出效果的接口,将 SDK 输出的媒体流以 video 的方式,在指定的 dom 容器中播放
async resetCore(input)
input: MediaStream|HTMLImageElement|String; // 输入源
-
contextlost 错误发生时调用此接口恢复
destroy()
-
-
销毁当前 SDK 实例以及相关的纹理资源

错误处理

在 error 回调返回的对象中包含错误码与错误信息以方便进行错误处理。
sdk.on('error', (error) => {
// 在 error 回调中处理错误
const {code, message} = error
...
})
错误码
含义
备注
10000001
当前浏览器环境不兼容
建议用户使用 Chrome、Firefox、Safari、微信浏览器访问
10000002
当前渲染上下文丢失
-
10000003
渲染耗时长
考虑降低视频分辨率或屏蔽功能
10000005
输入源解析错误
-
10000006
浏览器特性支持不足,可能会出现卡顿情况
建议用户使用 Chrome、Firefox、Safari、微信浏览器访问
10001101
设置特效出错
-
10001102
设置滤镜出错
-
10001103
特效强度参数不正确
-
10001104
sdk disabled 状态,无法设置特效
-
10001105
无效的特效 ID
-
10001201
调起用户摄像头失败
-
10001202
摄像头中断
-
10001203
没有获取到摄像头权限
需要开启摄像头权限,设置-隐私-相机开启
10001204
无法访问媒体设备(已授权)
找不到满足请求参数的媒体类型 或 系统错误导致设备无法被访问。
10001205
没有获取到麦克风权限
需要开启麦克风权限,设置-隐私中开启
10001206
部分浏览器可能存在 getUserMedia 接口返回的宽高与用户设置的不同
-
10004001
摄像头、麦克风权限问题需要刷新页面才能继续使用
-
20002001
缺少鉴权参数
-
20001001
鉴权失败
请确认是否创建 License,请确认签名是否正确
20001002
接口请求失败
回调会回传接口返回的数据,具体信息请参见 接口错误码
20001003
设置特效接口鉴权失败
无权访问的接口,基础版 License 无法使用高级版License 功能
20001004
signature 超时
签名超时,且重试后还是发生了错误
20001005
authorize 超时
鉴权超时,且重试后还是发生了错误
30000001
小程序 startRecord 失败
-
30000002
小程序 stopRecord 失败
-
40000000
未捕获的异常
-
40000001
当前使用 SDK 版本过低,部分特效无法正确展示,请升级 SDK 版本
-
50000002
分辨率改变导致特效丢失
需要重新设置特效

警告处理

在 warning 回调返回的对象中包含警告码与警告信息。
sdk.on('warning', (warning) => {
// 在 warning 回调中处理警告
const {code, message} = warning
...
})
警告码
含义
备注
50005
检测耗时过长
动态监测,单帧耗时超过 150ms 时抛出警告,意味着此时渲染帧率达不到 10fps,有卡顿现象发生。

处理当前渲染上下文丢失

部分 PC 在长期切后台的场景可能触发处理 contextlost 错误,可以调用 ArSdk.prototype.resetCore(input: MediaStream) 恢复渲染上下文。
sdk.on('error', async (error) => {
if (error.code === 10000002) {
const newInput = await navigator.mediaDevices.getUserMedia({...})
await sdk.resetCore(newInput)
}
})