tencent cloud

文档反馈

最后更新时间:2023-05-06 15:45:49
    本文档将介绍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 ModuleConfig = {
    beautify: boolean // 默认为true
    segmentation: boolean // 默认为false
    }
    否,默认为 {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
    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
    }
    
    language
    国际化对应(1.0.6版本开始支持),中文(zh)和英文(en)
    String: zh | en
    否,默认zh

    回调事件

    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:滤镜 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,
    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)
    }
    })
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持