API 文档

最近更新时间:2024-05-10 18:19:52

我的收藏
本文档将介绍 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
}
否,默认为 {beautify: true, segmentation: false}
auth
鉴权参数
type AuthConfig = {
licenseKey: string // 控制台 Web License 管理 获取
appId: string // 控制台 账号信息 > 基本信息 查看 APPID
authFunc:() => Promise<{
signature:string,
timestamp:string
}> // 请参见 License 配置使用
}
input
输入源
MediaStream|HTMLImageElement|String
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',
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
plugin3d
小程序专用, 0.3.0之后版本写法,按需初始化3d模块,如不需要3d模块,可以省略此参数。
plugin3d 模块

回调事件

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

事件
说明
回调参数
created
SDK 鉴权完成并成功创建实例时触发
-
cameraReady
SDK 的画面生成时触发,此时 output 已有画面但美颜仍无法生效
-
ready
SDK 内部检测初始化完成时触发,此时 output 画面已有美颜,也可以设置新的特效
-
error
SDK 发生错误时触发
error 对象

对象方法

接口
参数
返回
说明
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
}
-
设置美颜参数,需开启美颜模块,小程序仅支持前5个
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|blur|transparent',
src: string // 仅image类型需要
}
-
设置背景,Web 端需开启人像分割模块,小程序推流仅支持直接传入图片地址
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
-
更新输入流
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
特效强度参数不正确
-
10001201
调起用户摄像头失败(已授权)
-
10001202
媒体流中断
检查摄像头或麦克风设备
10001203
没有获取到摄像头权限
需要开启摄像头权限,设置-隐私中开启
10001204
无法访问媒体设备(已授权)
找不到满足请求参数的媒体类型 或 系统错误导致设备无法被访问。
10001205
没有获取到麦克风权限
需要开启麦克风权限,设置-隐私中开启
20002001
缺少鉴权参数
-
20001001
鉴权失败
请确认是否创建 License,请确认签名是否正确
20001002
接口请求失败
回调会回传接口返回的数据,具体信息请参见 接口错误码
20001003
设置特效接口鉴权失败
无权访问的接口,基础版 License 无法使用高级版License 功能
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)
}
})