インターフェースドキュメンテーション

このドキュメントでは、Web Beauty AR SDKのコアパラメータとメソッドについて説明します。
説明:
Web Beauty AR 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({
... // 以下のConfig定義を参照
})
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、画像、動画の処理が可能
MediaStream | HTMLImageElement | String | HTMLVideoElement
非必須
live
ライブ配信モードの設定
type live = {
pusherContext: LivePusherContext
fps: 'low' | 'high' // デフォルトでlow、modeがcustomの場合のみ有効、高フレームを有効にすると、一部デバイスの性能が足りない場合があるため、デバイス性能に応じて差別化された設定を行うことをお勧めします。
mode: 'custom' | 'native' // 切り替え不可、デフォルトでcustom、バーチャル背景以外のArsdk機能をすべて使用可能、nativeモードはWeChatのローレベル機能を使用してバーチャル背景を実装しますが、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' | 'video', // 1.0.23以降はvideoタイプの動的背景をサポート
src?: string, // imageまたはvideoタイプで指定される画像アドレス
edgeBlur ?: number, // 1.0.25以降はサポート、値の範囲:0~10、エッジぼかし度を制御、値が小さいほどエッジの切り取りが鋭く、ぼかし度が低くなります。
}
非必須
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、すべて出力
initReport
ログ報告モジュールを初期化
Boolean
非必須、デフォルトでtrue
worker
ブラウザworkerを無効化、特定シナリオのパフォーマンスを向上
String: auto | disable
非必須、デフォルトでauto、SDKは現在のブラウザ環境に基づいてworkerの使用を決定
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
})
// errorコールバック、sdkの使用に影響するエラーが発生した場合
sdk.on('error', (data)=>{
console.log('error', data.code, data.message)
})
// warningコールバック、SDKが処理時間の増加を検出した場合に警告を発します
sdk.on('warning', (data)=>{
console.log('warning', data.code, data.message)
})
イベント
説明
コールバックパラメータ
created
SDK認証完了時とインスタンス作成成功時にトリガー
-
cameraReady
SDKの画面生成時にトリガー、この時点でoutputには画面があるが美顔はまだ適用されていない
-
ready
SDK内部テスト初期化完了時にトリガー、この時点でoutput画面には美顔が適用され、新しいエフェクトを設定することもできる
-
error
SDKエラー発生時にトリガー
errorオブジェクト
warning
SDK警告発生時にトリガー
warningオブジェクト
handGesture
ジェスチャー認識を有効にした後、ジェスチャーの変化を検出したときにトリガーされる
認識されたジェスチャー
detectStatusChange
顔検出状態が変化したときにトリガー
Boolean、顔の認識の有無

オブジェクトメソッド

インターフェース
パラメータ
戻り値
説明
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
}
-
美顔パラメータを設定、美顔モジュールを有効にする必要があります。ミニプログラムは最初の5つのみサポート

setEffect(effects, callback, errCallback)
effects:エフェクトID | Effectオブジェクト | (エフェクトID | Effectオブジェクト) 配列
// Effectオブジェクト
type Effect = {
id: string; // エフェクトid
intensity: number; // エフェクト全体の強さ、値の範囲0~1、デフォルトで1
filterIntensity: number; // エフェクト内のフィルターの強さ、値の範囲0~1、デフォルトで1
};
callback:設定成功のコールバック
errCallback:失敗のコールバック
-
化粧、ステッカーエフェクトを設定、美顔モジュールを有効にする必要があります
3D系エフェクトはプレミアム版Licenseのみサポート
setAvatar(params)
{
mode: 'AR' | 'VR',
effectId?: string, // effectIdパススルーで内蔵モデルを使用
url?: string, // urlパススルーでカスタムモデルを使用
backgroundUrl?: string, // 背景画像リンク、VRモードでのみ有効
}
-
アニ文字スタンプまたはバーチャルアバターを設定
プレミアム版Licenseのみサポート
setBackground(options)
{
type: 'image|video|blur|transparent', // 1.0.23以降はvideoタイプの動的背景をサポート
src: string, // image|videoタイプに必要
edgeBlur: number, // 1.0.25以降はサポート、値の範囲:0~10、エッジぼかし度を制御、値が小さいほどエッジの切り取りが鋭く、ぼかし度が低くなります。
}
-

背景を設定、Web側ではシルエット切り抜きモジュールを有効にする必要があります、ミニプログラムプッシュストリームは画像アドレスの直接渡しのみサポート
setForeground(options) (1.0.23バージョン以降サポート)
{
type: 'image|video',
src: string // リソースパス、base64またはオンラインアドレス
}
-
画面に固定されたフルスクリーン前景効果を設定
setSegmentationLevel(level)
level: 0 | 1 | 2
-
背景切り抜きモデルのレベルを切り替え
setFilter(id, intensity, callback, errCallback)
id:フィルターID
intensity:フィルター強さ、値の範囲0~1、デフォルトで1
callback:設定成功のコールバック
errCallback:失敗のコールバック
-
フィルターを設定
getEffectList(params)
{
PageNumber: number, // ページ、デフォルトで0
PageSize: number, // ページサイズ、デフォルトで1000
Name: '', // エフェクト名
Label: string | Array<string>, // エフェクトタグ、エフェクトタグリスト
Type: 'Custom' | 'Preset' // エフェクトタイプ、Custom-ユーザーカスタムエフェクト、Preset-内蔵エフェクト
}

エフェクトリスト
エフェクトリストを取得
getAvatarList(type)
type = 'AR' | 'VR' // AR-アニ文字、VR-バーチャルアバター
アニ文字/バーチャルアバターリスト

アニ文字/バーチャルアバターリストを取得
getEffect(effectId)
effectId:エフェクトID
単一エフェクト情報
指定されたエフェクトの情報を取得
getCommonFilter()
-
内蔵フィルターリスト
内蔵フィルターリストを取得
async initCore()
{
input?: MediaStream|HTMLImageElement|String; // 入力ソース
camera?: CameraConfig; // カメラモード
mirror?: boolean; // リバーサルミラー効果のオン・オフ
}
-
プリ初期化のみ使用でき、SDKに入力情報を提供します。詳細は読み込み最適化を参照してください
async updateInputStream(src, stopOldTracks) (0.1.19バージョン以降サポート)
src:新しい入力ストリームMediaStream
stopOldTracks: 古いMediaTrackの使用停止
-
入力メディアストリームを更新
updateInputImage(options) (1.0.24バージョン以降サポート)
{
width: number;// 画像レンダリングの高さ
height: number; // 画像レンダリングの幅
input: string;// 画像アドレス
}
-
入力画像を更新
async getOutput(type:OUTPUT_TYPES, fps:number)
enum OUTPUT_TYPES {
IMAGE = 3,
MEDIA_STREAM = 4,
}
type: 3 | 4 // 3-image、4-mediastream、入力が画像の場合、デフォルトで出力は3、入力が非画像の場合、デフォルトで出力は4
fps:出力メディアストリームのフレームレートを設定、デフォルトで入力メディアのfpsと一致
MediaStream | String
Web側のみでサポート、ミニプログラムは現在サポートしていません
disable()
-
-
顔検出を無効にし、未処理の元画像を返し、CPU使用率を下げることができます
enable()
-
-
顔検出を再開し、美顔などのエフェクトが適用された画面を返します
stop()
-
-
画面を一時停止し、画面が止まります
resume()
-
-
画面を再開し、画面を再生します
async startRecord(options)
{
audio: {format: string}, // audioRecorder設定、ミニプログラム内蔵グローバルAudioRecorderパラメータと一致
recordCamera: boolean // オリジナルカメラストリームの録画、デフォルトでfalse
}
-
録画開始(ミニプログラム側のみサポート)
async stopRecord()
{
useOriginAudio: boolean, // 動画の元音声の録音
musicPath: string, // BGMアドレス、useOriginAudioがfalseの時に有効
}
録画
録画を終了して録画結果を返します(ミニプログラム側のみでサポート)
async takePhoto()
-
{
data: Uint8Array | Uint8ClampedArray,
width: number,
height: number
}
撮影インターフェース、bufferデータを含むオブジェクトを返し、
ミニプログラム側はUint8Arrayを返し、web側はImageDataを返します
async initLocalPlayer(id)
id: string // ローカルプレビュー用dom id
-
インターフェースはSDK出力効果をプレビューする便利なインターフェースを提供し、SDK出力のメディアストリームをvideoとして指定のdomコンテナで再生します
async resetCore(input)
input: MediaStream|HTMLImageElement|String; // 入力ソース
-
contextlostエラー発生時にこのインターフェースを呼び出して復元します
destroy()
-
-
現在のSDKインスタンスと関連テクスチャーリソースを破棄

エラー処理

errorコールバックで返されるオブジェクトにはエラーコードとエラー情報が含まれており、エラー処理に便利です。
sdk.on('error', (error) => {
// errorコールバックでエラーを処理
const {code, message} = error
...
})
エラーコード
意味
備考
10000001
現在のブラウザ環境は互換性がない
Chrome、Firefox、Safari、WeChatブラウザの使用を推奨します
10000002
現在のレンダリングコンテキストが紛失
-
10000003
レンダリング処理時間が長い
ビデオ解像度を下げるか一部機能を無効にすることを検討してください
10000005
入力ソース解析エラー
-
10000006
ブラウザ機能のサポートが不十分で、カクつくことがある
Chrome、Firefox、Safari、WeChatブラウザの使用を推奨します
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
解像度変更によりエフェクトが失われた
エフェクトを再設定する必要があります

警告処理

warningコールバックで返されるオブジェクトには警告コードと警告情報が含まれています。
sdk.on('warning', (warning) => {
// warningコールバックで警告を処理
const {code, message} = warning
...
})
警告コード
意味
備考
50005
検出処理時間が長すぎる
動的監視で、1フレームの処理時間が150msを超えると警告が発生します。これは、この時点でのレンダリングフレームレートが10fpsに達していないことを意味し、カクつきが発生しています。

現在のレンダリングコンテキスト喪失の処理

一部の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)
}
})