接口文档

本文档将介绍 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({
...
})
初始化 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|HTMLImageElement|String
camera
内置相机
type CameraConfig = {
width: number, // 拍摄画面宽度
height: number, // 拍摄画面高度
mirror: boolean, // 是否开启左右镜像
frameRate: number // 画面采集帧率
}
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',
src?: string
}
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,全部打印
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
})
事件
说明
回调参数
created
SDK 鉴权完成并成功创建实例时触发
-
cameraReady
SDK 的画面生成时触发,此时 output 已有画面但美颜仍无法生效
-
ready
SDK 内部检测初始化完成时触发,此时 output 画面已有美颜,也可以设置新的特效
-
error
SDK 发生错误时触发
error 对象
handGesture
开启手势识别后,监听到手势变化时触发
识别到的手势

对象方法

接口
参数
返回
说明
async initCore()

{
input?:MediaStream|HTMLImageElement|String; // 输入源
camera?:CameraConfig; // 摄像头模式
mirror?:boolean; // 是否镜像
}

仅供预初始化方案使用,为 SDK 提供输入信息,详情参考 加载优化
async getOutput(fps)
fps:设置输出的媒体流帧率,默认无须设置
MediaStream|String
仅 Web 端提供,小程序暂不支持
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
}
-
设置美颜参数,需开启美颜模块
setEffect(effects, callback)
effects:特效 ID | effect 对象 | 特效 ID / effect 数组
effect:{
id: string,
intensity: number, // 特效强度,默认1,范围0-1
filterIntensity: number // 单独控制特效中的滤镜强度,默认取intensity,范围0-1 (0.1.18及以上版本支持)
}
callback:设置成功的回调
-
设置特效,需开启美颜模块
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类型需要
}
-
设置背景,需开启人像分割模块
setForeground(options)(1.0.23 版本开始支持)
{
type: 'image|video',
src: string // 资源路径,base64或者在线地址
}
-
设置固定于屏幕的全屏前景效果
setSegmentationLevel(level)
level: 0 | 1 | 2

切换背景分割模型精确度
setFilter(id, intensity, callback)
id:滤镜 ID
intensity:滤镜强度,范围0 - 1
callback:设置成功回调
-
设置滤镜
getEffectList(params)
{
PageNumber: number,
PageSize: number,
Name: '',
Label: Array,
Type: 'Custom|Preset'
}
特效列表
拉取特效列表
getAvatarList(type)
type = 'AR' | 'VR'
虚拟形象列表
拉取虚拟形象列表
getEffect(effectId)
effectId:特效 ID
单个特效信息
拉取指定特效的信息
getCommonFilter()
-
内置滤镜列表
获取内置滤镜列表
async updateInputStream(src:MediaStream) (0.1.19版本后支持)
src:新的输入流MediaStream
-
更新输入流
updateInputImage(options)(1.0.24版本后支持)
{
width: number;// 图片渲染高度
height: number; // 图片渲染宽度
input: string;// 图片地址
}
-
更新图片接口
disable()
-
-
停用面部检测,返回未处理的原始画面,可以降低 CPU 使用率
enable()
-
-
恢复面部检测,返回美颜等特效生效的画面
async startRecord()
-
-
开始录像(仅小程序端支持)
async stopRecord()
{
useOriginAudio: boolean, // 是否录制视频原声
musicPath: string, // 背景音乐地址,useOriginAudio为false时生效
}
录像
结束录像并返回录像结果(仅小程序端支持)
async takePhoto()
-
{
data: Uint8Array | Uint8ClampedArray, ,
width: number,
height: number
}
拍照接口,返回一个包含 buffer 数据的对象, 小程序端返回为Uint8Array,web 端返回为 ImageData
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
分辨率改变导致特效丢失
需要重新设置特效

处理当前渲染上下文丢失

部分 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)
}
})