腾讯特效SDKAPI 文档_音视频解决方案_同尘科技

腾讯特效SDK 1年前 (2023-12-29) 浏览 160

本文档将介绍 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 SegmentationLevel = 0 | 1 | 2type ModuleConfig = {  beautify: boolean // 默认为true  segmentation: boolean // 默认为false  segmentationLevel: SegmentationLevel // 1.0.19 之后的版本支持传参选择分割模型}
否,默认为 {beautify: true, segmentation: false}
auth 鉴权参数
type AuthConfig = {  licenseKey: string // 控制台  Web License 管理 获取  appId: string // 控制台 账号信息 > 基本信息 查看 APPID  authFunc:() => Promise // 请参见 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}
设置美颜参数,需开启美颜模块
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:滤镜 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 | 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)    }})



对音视频的解决方案有疑惑?想了解解决方案收费? 联系解决方案专家

腾讯云限时活动1折起,即将结束: 马上收藏

同尘科技为腾讯云授权服务中心,购买腾讯云享受折上折,更有现金返利:同意关联,立享优惠

阿里云解决方案也看看?: 点击对比阿里云的解决方案

- 0人点赞 -

发表点评 (0条)

not found

暂无评论,你要说点什么吗?