本文档将介绍 Web 美颜特效 SDK 核心参数及方法。
说明:
Web 美颜特效 SDK 需要浏览器支持并开启硬件加速才能够流畅渲染(小程序端无需判断),因此 SDK 提供了检测方法供业务提前判断,如不支持则进行屏蔽处理。
import {ArSdk, isWebGLSupported} from 'tencentcloud-webar'if(isWebGLSupported()) {const sdk = new ArSdk({...})} else {// 屏蔽逻辑}
初始化参数
import { ArSdk } from 'tencentcloud-webar'// 初始化SDKconst sdk = new ArSdk({...})
初始化 SDK 的 Config 支持以下参数:
参数 | 说明 | 类型 | 是否必传 |
module | 模块配置 |
| 否,默认为 {beautify: true, segmentation: false} |
auth | 鉴权参数 |
| 是 |
input | 输入源 | MediaStream|HTMLImageElement|String | 否 |
live | 直播模式配置 |
| 否 |
camera | 内置相机 |
| 否 |
mirror | 是否镜像,支持输入流的镜像(1.0.19 新增) | Boolean | 否 |
beautify | 美颜参数 |
| 否 |
background | 背景参数 |
| 否 |
loading | 内置 loading icon 配置 |
| |
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() |
| - | |
async getOutput(fps) | fps:设置输出的媒体流帧率,默认无须设置 | MediaStream|String | 仅 Web 端提供,小程序暂不支持 |
setBeautify(options) |
| - | 设置美颜参数,需开启美颜模块,小程序仅支持前5个 |
setEffect(effects, callback)
| effects:特效 ID | effect 对象 | 特效 ID / effect 数组
callback:设置成功的回调 | - | 设置特效,需开启美颜模块 3D 类特效仅高级版License 支持 |
setAvatar(params) |
| - | 设置 Animoji 表情或虚拟形象 仅高级版 License 支持 |
setBackground(options) |
| - |
设置背景,Web 端需开启人像分割模块,小程序推流仅支持直接传入图片地址 |
setSegmentationLevel(level) | level: 0 | 1 | 2 | - | 切换背景分割模型 |
setFilter(id, intensity, callback) | id:滤镜 ID intensity:滤镜强度,范围0-1 callback:设置成功回调 | - | 设置滤镜 |
getEffectList(params) |
|
特效列表 | 拉取特效列表 |
getAvatarList(type) |
| 虚拟形象列表 |
拉取虚拟形象列表 |
getEffect(effectId) | effectId:特效 ID | 单个特效信息 | 拉取指定特效的信息 |
getCommonFilter() | - | 内置滤镜列表 | 获取内置滤镜列表 |
async updateInputStream(src:MediaStream) (0.1.19版本后支持) | src:新的输入流MediaStream | - | 更新输入流 |
disable() | - | - | 停用面部检测,返回未处理的原始画面,可以降低 CPU 使用率 |
enable() | - | - | 恢复面部检测,返回美颜等特效生效的画面 |
async startRecord() | - | - | 开始录像(仅小程序端支持) |
async stopRecord() |
| 录像 | 结束录像并返回录像结果(仅小程序端支持) |
async takePhoto() | - |
| 拍照接口,返回一个包含 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)}})