tencent cloud

文档反馈

API 文档

最后更新时间:2024-12-19 10:21:27
    本文档将介绍 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
    handGesture: boolean // 是否开启手势识别,默认为 false, 1.0.23 之后版本支持
    handLandmark: boolean // 是否开启手部追踪,默认为 false,1.0.23 之后版本支持, 不推荐和 beautify 同时启用
    }
    否,默认为 {beautify: true, segmentation: false, segmentationLevel: 0,
    handLandmark: 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
    // 注意:以下参数仅在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
    logLevel
    打印控制台日志等级
    'OFF' | 'ERROR' | 'WARN' | 'DEBUG' | 'TRACE' | 'INFO'
    否,默认 INFO,全部打印
    proxyServer
    内网代理模式用
    type proxyServeConfig = {
    webarProxy: string; // 接口代理的内网地址
    staticProxy: string; // 资源代理的内网地址
    }

    回调事件

    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)
    })
    // 开启手势识别后,监听到手势变化时触发
    sdk.on('handGesture',(hands)=>{
    // 对应 hand 取值 none, thumb_up, thumb_down, victory, pointing_up, open_palm, iloveyou
    })
    事件
    说明
    回调参数
    created
    SDK 鉴权完成并成功创建实例时触发
    -
    cameraReady
    SDK 的画面生成时触发,此时 output 已有画面但美颜仍无法生效
    -
    ready
    SDK 内部检测初始化完成时触发,此时 output 画面已有美颜,也可以设置新的特效
    -
    error
    SDK 发生错误时触发
    error 对象
    handGesture
    开启手势识别后,监听到手势变化时触发
    识别到的手势

    对象方法

    接口
    参数
    返回
    说明
    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|video|blur|transparent', //1.0.23 版本开始支持 video 类型动态背景
    src: string // image|video类型需要
    }
    -
    设置背景,需开启人像分割模块
    setForeground(options)(1.0.23 版本开始支持)
    {
    type: 'image|video',
    src: string // 资源路径,base64或者在线地址
    }
    -
    设置固定于屏幕的全屏前景效果
    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
    -
    更新输入流
    updateInputImage(options)(1.0.24版本后支持)
    {
    width: number;// 图片渲染高度
    height: number; // 图片渲染宽度
    input: string;// 图片地址
    }
    -
    更新图片接口
    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
    特效强度参数不正确
    -
    10001104
    sdk disabled 状态,无法设置特效
    -
    10001105
    无效的特效 ID
    -
    10001201
    调起用户摄像头失败
    -
    10001202
    摄像头中断
    -
    10001203
    没有获取到摄像头权限
    需要开启摄像头权限,设置-隐私-相机开启
    10001204
    无法访问媒体设备(已授权)
    找不到满足请求参数的媒体类型 或 系统错误导致设备无法被访问。
    10001205
    没有获取到麦克风权限
    需要开启麦克风权限,设置-隐私中开启
    10001206
    部分浏览器可能存在 getUserMedia 接口返回的宽高与用户设置的不同
    -
    10004001
    摄像头、麦克风权限问题需要刷新页面才能继续使用
    -
    20002001
    缺少鉴权参数
    -
    20001001
    鉴权失败
    请确认是否创建 License,请确认签名是否正确
    20001002
    接口请求失败
    回调会回传接口返回的数据,具体信息请参见 接口错误码
    20001003
    设置特效接口鉴权失败
    无权访问的接口,基础版 License 无法使用高级版License 功能
    20001004
    signature 超时
    签名超时,且重试后还是发生了错误
    20001005
    authorize 超时
    鉴权超时,且重试后还是发生了错误
    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 电话支持