インターフェースドキュメンテーション
このドキュメントでは、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 | モジュール設定 |
| 非必須、デフォルトで {beautify: true, segmentation: false, segmentationLevel: 0, handLandmark: false} |
auth | 認証パラメータ |
| 必須 |
input | メディア入力ソース、mediaStream、画像、動画の処理が可能 | MediaStream | HTMLImageElement | String | HTMLVideoElement | 非必須 |
live | ライブ配信モードの設定 |
| 非必須、ミニプログラムのみサポート |
camera | 内蔵カメラ |
| 非必須 |
mirror | リバーサルミラーのオン・オフ、入力ストリームのミラーリングをサポート(1.0.19の新機能) | Boolean | 非必須 |
beautify | 美顔パラメータ |
| 非必須 |
background | 背景パラメータ |
| 非必須 |
loading | 内蔵loading icon設定 |
| |
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 | イントラネットプロキシモード用 |
| 非必須 |
コールバックイベント
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) |
| - | 美顔パラメータを設定、美顔モジュールを有効にする必要があります。ミニプログラムは最初の5つのみサポート |
setEffect(effects, callback, errCallback) | effects:エフェクトID | Effectオブジェクト | (エフェクトID | Effectオブジェクト) 配列
callback:設定成功のコールバック errCallback:失敗のコールバック | - | 化粧、ステッカーエフェクトを設定、美顔モジュールを有効にする必要があります 3D系エフェクトはプレミアム版Licenseのみサポート |
setAvatar(params) |
| - | アニ文字スタンプまたはバーチャルアバターを設定 プレミアム版Licenseのみサポート |
setBackground(options) |
| - | 背景を設定、Web側ではシルエット切り抜きモジュールを有効にする必要があります、ミニプログラムプッシュストリームは画像アドレスの直接渡しのみサポート |
setForeground(options) (1.0.23バージョン以降サポート) |
| - | 画面に固定されたフルスクリーン前景効果を設定 |
setSegmentationLevel(level) | level: 0 | 1 | 2 | - | 背景切り抜きモデルのレベルを切り替え |
setFilter(id, intensity, callback, errCallback) | id:フィルターID intensity:フィルター強さ、値の範囲0~1、デフォルトで1 callback:設定成功のコールバック errCallback:失敗のコールバック | - | フィルターを設定 |
getEffectList(params) |
| エフェクトリスト | エフェクトリストを取得 |
getAvatarList(type) |
| アニ文字/バーチャルアバターリスト | アニ文字/バーチャルアバターリストを取得 |
getEffect(effectId) | effectId:エフェクトID | 単一エフェクト情報 | 指定されたエフェクトの情報を取得 |
getCommonFilter() | - | 内蔵フィルターリスト | 内蔵フィルターリストを取得 |
async initCore() |
| - | |
async updateInputStream(src, stopOldTracks) (0.1.19バージョン以降サポート) | src:新しい入力ストリームMediaStream stopOldTracks: 古いMediaTrackの使用停止 | - | 入力メディアストリームを更新 |
updateInputImage(options) (1.0.24バージョン以降サポート) |
| - | 入力画像を更新 |
async getOutput(type:OUTPUT_TYPES, fps:number) |
type: 3 | 4 // 3-image、4-mediastream、入力が画像の場合、デフォルトで出力は3、入力が非画像の場合、デフォルトで出力は4 fps:出力メディアストリームのフレームレートを設定、デフォルトで入力メディアのfpsと一致 | MediaStream | String | Web側のみでサポート、ミニプログラムは現在サポートしていません |
disable() | - | - | 顔検出を無効にし、未処理の元画像を返し、CPU使用率を下げることができます |
enable() | - | - | 顔検出を再開し、美顔などのエフェクトが適用された画面を返します |
stop() | - | - | 画面を一時停止し、画面が止まります |
resume() | - | - | 画面を再開し、画面を再生します |
async startRecord(options) |
| - | 録画開始(ミニプログラム側のみサポート) |
async stopRecord() |
| 録画 | 録画を終了して録画結果を返します(ミニプログラム側のみでサポート) |
async takePhoto() | - |
| 撮影インターフェース、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)}})