tencentcloud-webar v1.0.21

本 SDK 主要功能在于提供给您快速、安全地接入 腾讯云视立方•美颜特效，并使用所有功能。

流程说明

SDK 实现了简洁低侵入性的接口提供接入，接入者只需要初始化实例，将渲染节点添加到自己的页面即可快速实现 Web 美颜特效功能。

!

• 用户只能设置通过控制台制作的特效以及平台内置的特效。
• Web和小程序接入流程略有差异，详见后文。

安装 SDK

SDK 以 npm 包的形式提供 Web 和小程序的兼容支持。

npm install tencentcloud-webar

Web 端接入 SDK

步骤1：引入SDK

import { ArSdk } from 'tencentcloud-webar';// SDK 类

步骤2：初始化实例

接下来初始化一个 SDK 实例用于显示：

// 获取鉴权参数
const authData = {
  licenseKey: 'xxxxxxxxx',
  appId: 'xxx',
  authFunc: authFunc // 详见「License 配置与使用 - 签名方法」
};
// 获取输入流
const stream = await navigator.mediaDevices.getUserMedia({
  audio: true,
  video: { width: 1280, height: 720 }
});
const config = {
  auth: authData, // 鉴权参数
  input: stream, // 输入
  beautify: { // 初始化美颜参数(可选)
    whiten: 0.1,
    dermabrasion: 0.3,
    eye: 0.2,
    chin: 0,
    lift: 0.1,
    shave: 0.2
  }
}
const sdk = new ArSdk(
  // 传入一个 config 对象用于初始化 sdk
  config
)

config中的input参数仅支持传入媒体流MediaStream与图片HTMLImageElement|String(图片url)。

如果您需要传入视频或canvas，则可以将加载完成的video或绘制完成的canvas转成MediaStream作为input。

const video = document.createElement('video')
video.oncanplay = () => {
  const inputStream = video.captureStream()
  const sdk = new ArSdk({
    input: inputStream,
    ...
  })
}
video.src = 'xxx'

SDK还内置了摄像头拍摄的实现，如果您没有流的处理需求，只是想快速地实现Web端的拍摄，可以缺省input，使用camera参数配置。

const sdk = new ArSdk({
  auth: authData,
  camera: {
    mirror: true,
    width: 720,
    height: 1280
  }
})

初始化 ArSdk 的 Config 支持以下参数：

步骤3：获取输出

可以使用ArSdk.prototype.getOutput方法获取输出的画面。

const output = await sdk.getOutput()

!

• 如果传入的input是图片，则返回为string类型的DataURL。
• 其他场景均返回MediaStream类型，其中的video轨道是ArSdk实时处理的画面轨，如果媒体流有音频则audio轨道保持不变。

拿到输出的MediaStream之后，可以进行推流等后续处理，也可以直接在页面里播放。

// 以直接播放为例
const output = await sdk.getOutput()
const video = document.createElement('video')
video.setAttribute('playsinline', '')
video.crossOrigin = 'anonymous'
video.oncanplay = () => {
  video.play()
}
video.srcObject = output
document.body.appendChild(video)

小程序端接入 SDK

小程序端接入需要自备小程序，详细请参见 微信小程序文档。

步骤1：配置域名白名单

SDK 内部会请求后台进行鉴权和资源加载，需要在小程序后台配置域名白名单。

1. 进入 小程序后台，进入 开发 > 开发管理 > 开发设置 > 服务器域名。
2. 点击修改，配置以下域名并保存。

• 请求域名：

https://webar.qcloud.com;
https://webar-static.tencent-cloud.com;
https://aegis.qq.com;
以及上述签名接口（get-ar-sign）的地址

• downloadFile 域名：

https://webar-static.tencent-cloud.com

步骤2：安装并构建 npm

1. 安装：

npm install tencentcloud-webar

2. 单击开发者工具菜单 > 工具 > 构建 npm。
3. 在app.json中配置workers路径：

"workers": "miniprogram_npm/tencentcloud-webar/worker"

步骤3：引入文件

import "../../miniprogram_npm/tencentcloud-webar/lib.js";
import { ArSdk } from "../../miniprogram_npm/tencentcloud-webar/index.js";

! 小程序有单文件不超过 500kb 的限制，因此 SDK 分为两个 js 文件提供。

步骤4：初始化实例

// wxml
  //打开相机
  <camera 
    device-position="{{'front'}}" 
    frame-size="large" flash="off" resolution="medium" 
    style="width: 750rpx; height: 134rpx;position:absolute;top:-9999px;" 
  />
  //sdk 将处理完的画面实时输出到此 canvas 上
  <canvas 
    type="webgl"
    canvas-id="main-canvas"
    id="main-canvas"
    style="width: 750rpx; height: 1334rpx;">
  </canvas>
  //拍照将 ImageData 对象绘制到此 canvas 上
  <canvas 
    type="2d" 
    canvas-id="photo-canvas" 
    id="photo-canvas" 
    style="position:absolute;width:720px;height:1280px;top:-9999px;left:-9999px;">
  </canvas>
// js
Component({
  methods: {
    async getCanvasNode(id) {
      return new Promise((resolve) => {
        this.createSelectorQuery()
          .select(`#${id}`)
          .node()
          .exec((res) => {
            const canvasNode = res[0].node;
            resolve(canvasNode);
          });
      });
    },
    
    // 初始化相机类型    
    async initSdkCamera() {
      // 获取在屏的 canvas，sdk 会将处理完的画面实时输出到 canvas 上
      const outputCanvas = await this.getCanvasNode("main-canvas");
      const sdk = new ArSdk({
        camera: {
          width:720,
          height:1280,
        },
        output: outputCanvas,
        loading: {
          enable: false,
        },
        auth: {
          licenseKey: LICENSE_KEY,
          appId: APP_ID,
          authFunc: authFunc
        }
      });
      this.sdk = sdk
    }
  }
})

!

• 小程序初始化 SDK 前须在控制台配置小程序 APPID.
• 由于小程序的特性与 Web 不同，因此小程序支持的 input 参数目前只有 string 类型的图片链接。
• 相机配置与 Web 相同，input 参数不传，直接设置 camera 参数，前提是页面中必须插入 camera 标签。
• 小程序不支持 getOutput，需要自行传入一个在屏的 WEBGL canvas，SDK 直接输出到此 canvas。

步骤5：拍照和录像

小程序端支持拍照和录像功能。

::: 拍照

SDK 会返回包含宽高和 buffer 数据的对象，用户可以通过自己页面内的 2d canvas 绘制此数据并导出为图片文件。

Component({
  ...
  async takePhoto() {
    const {uint8ArrayData, width, height} = this.sdk.takePhoto(); // takePhoto 方法返回当前画面的 buffer 数据
    const photoCanvasNode = await this.getCanvasNode('photo-canvas');
    photoCanvasNode.width = parseInt(width);
    photoCanvasNode.height = parseInt(height);
    const ctx = photoCanvasNode.getContext('2d');
    // 用 sdk 返回的数据创建 ImageData 对象
    const imageData = photoCanvasNode.createImageData(uint8ArrayData, width, height);
    // 将 ImageData 对象绘制到 canvas 上
    ctx.putImageData(imageData,0,0,0,0,width,height);
    // 将 canvas 保存为本地图片
    wx.canvasToTempFilePath({
      canvas: photoCanvasNode,
      x: 0,
      y: 0,
      width: width,
      height: height,
      destWidth: width,
      destHeight: height,
      success: (res) => {
        // 保存照片到本地
        wx.saveImageToPhotosAlbum({
          filePath: res.tempFilePath
        });
      }
    })
  }
})

::: ::: 录像

! 当小程序切换后台或检测到手机锁屏时，需要调用 stopRecord 停止录像，否则可能出错。

Component({
  methods: {
    // 开始录像
    startRecord() {
      this.sdk.startRecord()
    }
    // 结束录像
    async stopRecord() {
      const res = await this.sdk.stopRecord();
      // 保存录像到本地
      wx.saveVideoToPhotosAlbum({
        filePath: res.tempFilePath
      })
    }
  }
})

:::

接入美颜和特效

SDK 内置提供以下几类效果：美颜、滤镜、特效。

美颜

除了初始化时可以传入美颜参数，也可以通过ArSdk的setBeautify方法设置美颜。

• SDK 目前支持的美颜效果有：

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
}

• 调用 SDK 实例的 setBeautify 方法设置美颜参数：

sdk.setBeautify({
  whiten: 0.2,
  dermabrasion: 0,
  lift: 0.3,
  shave:0.1,
  eye: 0.9,
  chin: 0
})

滤镜

由于制作滤镜图的成本较高，我们提供了一些内置滤镜供您直接使用。 1. 获取内置滤镜列表：

const filterList = await sdk.getCommonFilter()

2. 设置滤镜：

sdk.setFilter(filterList[0].EffectId, 0.5)

特效

您可以直接在 SDK 中设置您在 控制台 上制作的特效，也可以使用我们提供的内置效果。相关教程请参见 素材制作基础。

// 获取内置特效
const presetEffectList = await sdk.getEffectList({
  Type: 'Preset'
})

// 获取自制特效
const customEffectList = await sdk.getEffectList({
  Type: 'Custom'
})

// 传入列表请求参数
const lipList = await sdk.getEffectList({
  PageNumber: 0,
  PageSize: 10,
  Name: '',
  Label: '唇妆', // 用特效的标签筛选
  Type: 'Custom'
})
const eyeList = await sdk.getEffectList({
  PageNumber: 0,
  PageSize: 10,
  Name: '',
  Label: '眼妆', // 用特效的标签筛选
  Type: 'Custom'
})
// 设置特效
sdk.setEffect([lipList[0].EffectId, eyeList[0].EffectId])

// 设置特效+强度
sdk.setEffect([
{
  id: lipList[0].EffectId,
  intensity: 0.5
}, 
{
  id: eyeList[0].EffectId,
  intensity: 0.7
})

API 说明

SDK 支持的回调事件：

let effectList = [];
let filterList = [];
// sdk 的回调用法
sdk.on('created', () => {
  // 在 created 回调中拉取特效和滤镜列表供页面展示
  sdk.getEffectList({
    Label: 'xxx'
  }).then(res => {
    effectList = res
  });
  sdk.getCommonFilter().then(res => {
    filterList = res
  })
})
sdk.on('ready', () => {
  // 在 ready 回调中调用 setBeautify/setEffect/setFilter 等渲染方法
  sdk.setBeautify({
    whiten: 0.3
  });
  sdk.setEffect({
    id: effectList[0].EffectId,
    intensity: 0.7
  });
  sdk.setFilter(filterList[0].EffectId, 0.5)
})
sdk.on('error', (error) => {
  // 在 error 回调中处理错误
  const {code, message} = error
  ...
})

错误码及对应的错误详情如下：

兼容性： | 浏览器 | 支持平台 | | ----- | --- | | Chrome | 桌面端/Android/iOS | | Safari | 桌面端/Android/iOS | | FireFox | 桌面端/Android/iOS | | QQ webview | Android | | 微信webview | Android/iOS 微信8.0.16以上| | 微信小程序 | Android/iOS 微信8.0.16以上|

SDK 提供以下方法：

代码示例

请参见 快速上手。