腾讯特效SDKWeb_音视频解决方案_同尘科技
本文档将介绍 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 | 模块配置 |
type ModuleConfig = { beautify: boolean // 默认为true segmentation: boolean // 默认为false} |
否,默认为 {beautify: true, segmentation: false} |
auth | 鉴权参数 |
type AuthConfig = { licenseKey: string // 控制台 Web License 管理 获取 appId: string // 控制台 账号信息 > 基本信息 查看 APPID authFunc:() => Promise // 请参见 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} |
否 |
background | 背景参数 |
type BackgroundOptions = { type: 'image' | 'blur' | 'transparent', src?: string} |
否 |
loading | 内置 loading icon 配置 |
type loadingConfig = { enable: boolean, size?: number lineWidth?: number strokeColor?: number} |
|
回调事件
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 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} |
– | 设置美颜参数,需开启美颜模块 |
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类型需要} |
– | 设置背景,需开启人像分割模块 |
setFilter(id, intensity, callback) | id:滤镜 IDintensity:滤镜强度,范围0-1callback:设置成功回调 | – | 设置滤镜 |
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, width: number, height: number} |
拍照,返回一个包含 buffer 数据的对象(仅小程序端支持) |
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 | 没有获取到摄像头权限 | 需要开启摄像头权限,设置-隐私-相机开启 |
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) }})
对音视频的解决方案有疑惑?想了解解决方案收费? 联系解决方案专家
腾讯云限时活动1折起,即将结束: 马上收藏
同尘科技为腾讯云授权服务中心,购买腾讯云享受折上折,更有现金返利:同意关联,立享优惠
阿里云解决方案也看看?: 点击对比阿里云的解决方案
暂无评论,你要说点什么吗?