Android
Tencent Effect SDKのコアインターフェースクラス
XmagicApi.java
は、SDKの初期化、美顔数値の更新、動的エフェクト呼び出しなどの機能に用いられます。Publicメンバー関数
API | 説明 |
コンストラクタです。 | |
属性の更新です。任意のスレッドで呼び出すことができます。 | |
属性の更新です。任意のスレッドで呼び出すことができます。 | |
動的エフェクトプロンプトのコールバック関数を設定します。プロンプトをフロントエンドのページ上に表示するために用いられます。 | |
顔の特徴点位置情報などのデータコールバックを設定します(S1-05およびS1-06パッケージのみコールバックあり)。 | |
顔、ジェスチャー、体の検出状態コールバックの設定。 | |
音声の再生を一時停止します。ActivityのonPauseライフサイクルにバインドできます。 | |
レンダリングを再開します。ActivityのonResumeライフサイクルにバインドできます。 | |
xmagicを破棄するには、GLスレッドで呼び出す必要があります。 | |
SDKレンダリングのデータを受信するメソッドです。カメラデータのコールバック関数内で使用できます。 | |
オーディオのみ停止する必要があり、GLスレッドをリリースする必要がない場合に、この関数を呼び出すことができます。 | |
現在のスマートフォンの回転の角度を判断し、それによってAIの顔認識の判断角度の根拠を調整するために用いられます。 | |
動的エフェクトリソースリストをSDKのチェック用に渡します。実行後、XmagicProperty.isSupportフィールドは、そのアトミック機能が利用可能かどうかを表します。 XmagicProperty.isSupport によってUIレイヤーのクリック制限を制御することや、直接リソースリストから削除することができます。 | |
動的エフェクトリソースリストを渡し、各リソースが使用できるSDKアトミック機能のリストを返します。 | |
現在のデバイスでサポートされているアトミック機能のテーブルを返します | |
現在のモデルが美顔(OpenGL3.0)をサポートしているかどうかを判断します。 | |
現在のlic権限がどの美顔をサポートしているかを判断します。BEAUTYおよびBODY_BEAUTYタイプの美顔項目のチェックのみサポートします。チェックした結果は、各美顔オブジェクトのXmagicProperty.isAuthフィールドに割り当てられます。 | |
入力データタイプを設定します。デフォルトは、Android cameraデータストリームです。 | |
setXmagicLogLevel | SDKのログレベルを設定します。開発デバッグの際はLog.DEBUGに、正式リリースの際はLog.WARNにそれぞれ設定することをお勧めします。正式リリースの際にLog.DEBUGに設定していると、大量のログがパフォーマンスに影響する場合があります。 new XmagicApi()の後に呼び出されます。 |
setAudioMute | 動的エフェクト素材を使用するときにミュートをオンにするかどうか(V2.5.0の新機能) パラメータ:trueはミュート、falseはミュートしないことを意味します |
enableEnhancedMode | 美顔拡張モードをオンにします(V2.5.1の新機能) |
XmagicApi
コンストラクタです。
XmagicApi(Context context, String resDir)XmagicApi(Context context, String resDir,OnXmagicPropertyErrorListener xmagicPropertyErrorListener)
パラメータ
パラメータ | 意味 |
Context context | コンテキストです。 |
String resDir | リソースファイルディレクトリです。 SDKリソースファイルがassets内にある場合は、SDKの初回使用前にリソースをAppのプライベートディレクトリにcopyしておく必要があります。先に XmagicResParser.setResPath(new File(getFilesDir(), "xmagic").getAbsolutePath()) によってリソースパスを設定してから、XmagicResParser.copyRes(getApplicationContext()) によってリソースのコピーを完了させます。詳細については、DemoのLaunchActivity.java をご参照ください。SDKリソースファイルがネットワークからダウンロードしたものの場合は、ダウンロード成功後に、 XmagicResParser.setResPath(validAssetsDirectory) によってリソースパスを設定しますXmagicResParser.getResPath() によって、先に設定したパスを取得します。 |
OnXmagicPropertyErrorListener xmagicPropertyErrorListener | エラーコールバックインターフェースです。 |
返されるエラーコードの意味対照表:
エラーコード | 意味 |
-1 | 不明なエラー。 |
-100 | 3Dエンジンリソースの初期化に失敗しました。 |
-200 | GAN素材をサポートしていません。 |
-300 | デバイスがこの素材コンポーネントをサポートしていません。 |
-400 | テンプレートのJSONの内容が空です。 |
-500 | SDKのバージョンが低すぎます。 |
-600 | 分割をサポートしていません。 |
-700 | OpenGLをサポートしていません。 |
-800 | スクリプトをサポートしていません。 |
5000 | 分割背景画像の解像度が2160×3840を超えています。 |
5001 | 分割背景画像に必要なメモリが不足しています。 |
5002 | 分割背景ビデオの解析に失敗しました。 |
5003 | 分割背景ビデオが200秒を超えています。 |
5004 | 分割背景ビデオのフォーマットをサポートしていません。 |
updateProperty
ある項目の美顔数値または動的エフェクト、フィルターの変更は、任意のスレッドで呼び出せます。
void updateProperty(XmagicProperty<?> p)
パラメータ
パラメータ | 意味 |
XmagicProperty<?> p | Tencent Effectのデータエンティティクラス。 「美肌」を例に取った場合、次のような方法で新しいインスタンスが作成できます。 new XmagicProperty<>(Category.BEAUTY, null, null, BeautyConstant.BEAUTY_SMOOTH, new XmagicPropertyValues(0, 100, 50, 0, 1))); 「2D動的エフェクト兔兔醤」を例にとると、次の方式でインスタンスを新しくすることができます。 new XmagicProperty<>(Category.MOTION, "video_tutujiang" , "動的エフェクトのファイルパス", null, null); その他の事例については、DemoプロジェクトのXmagicResParser.javaをご参照ください。 |
XmagicProperty
美顔
属性フィールド | 説明 |
category | Category.BEAUTY |
ID | null 特殊な状況: 顔やせの(ナチュラル、女神、イケメン)ID値は、それぞれ BeautyConstant.BEAUTY_FACE_NATURE_ID、 BeautyConstant.BEAUTY_FACE_FEMALE_GOD_ID、BeautyConstant.BEAUTY_FACE_MALE_GOD_ID ですリップのID値は、 XmagicConstant.BeautyConstant.BEAUTY_LIPS_LIPS_MASK ですチークのID値は、 XmagicConstant.BeautyConstant.BEAUTY_MAKEUP_MULTIPLY_MULTIPLY_MASK です立体のID値は、 XmagicConstant.BeautyConstant.BEAUTY_SOFTLIGHT_SOFTLIGHT_MASK です |
resPath | null 特殊な状況:リップ、チーク、立体のresPathリソース画像のパスです。詳細については、DemoのXmagicResParserクラスのparseBeauty()メソッドをご参照ください |
effkey | 入力必須です。Demo参照 事例:美白BeautyConstant.BEAUTY_TOOTH_WHITEN |
effValue | 入力必須です。DemoのXmagicResParserクラスのparseBeauty()メソッドをご参照ください |
美ボディ
属性フィールド | 説明 |
category | Category.BODY_BEAUTY |
ID | null |
resPath | null |
effkey | 入力必須です。Demo参照 事例:脚長BeautyConstant.BODY_LEG_STRETCH |
effValue | 入力必須です。DemoのXmagicResParserクラスのparseBeauty()メソッドをご参照ください |
フィルター
属性フィールド | 説明 |
category | Category.LUT |
ID | 画像名、入力必須 事例:dongjing_lf.png ID「なし」の場合は、XmagicProperty.ID_NONE |
resPath | フィルター画像のパス。入力必須です。「なし」の場合はnullに設定されます |
effkey | null |
effValue | 入力必須です。「なし」の場合はnullに設定されます |
動的エフェクト
属性フィールド | 説明 |
category | Category.MOTION |
ID | リソースソースファイル名、入力必須 事例:video_lianliancaomei ID「なし」の場合は、XmagicProperty.ID_NONE |
resPath | 入力必須です。Demo参照 |
effkey | null |
effValue | null |
メイクアップ
属性フィールド | 説明 |
category | Category.MAKEUP |
ID | リソースソースファイル名、入力必須 事例:video_xuejiezhuang ID「なし」の場合は、XmagicProperty.ID_NONE |
resPath | 入力必須です。Demo参照 |
effkey | 入力必須です。値は、makeup.strength「なし」の場合はnullに設定されます |
effValue | 入力必須です。「なし」の場合はnullに設定されます |
分割
属性フィールド | 説明 |
category | Category.SEGMENTATION |
ID | リソースソースファイル名、入力必須 事例:video_segmentation_blur_45 ID「なし」の場合は、XmagicProperty.ID_NONE カスタム分割ID値には、 XmagicConstant.SegmentationId.CUSTOM_SEG_ID を使用する必要があります |
resPath | 入力必須です。Demo参照 |
effkey | null(カスタム背景を除く)。カスタム背景の値は選択するリソースパスとします |
effValue | null |
updateProperties
ある項目の美顔数値または動的エフェクト、フィルターの一括変更は、任意のスレッドで呼び出せます。
void updateProperties(List<XmagicProperty<?>> properties)
パラメータ
パラメータ | 意味 |
(List<XmagicProperty<?>> properties | 詳細については、updatePropertyメソッドの説明をご参照ください。 |
setTipsListener
動的エフェクトプロンプトのコールバック関数を設定します。プロンプトをフロントエンドのページ上に表示するために用いられます。例えば素材の中には、ユーザーに、うなずく、手を伸ばす、指ハートなどを促すものがあります。
void setTipsListener(XmagicApi.XmagicTipsListener effectTipsListener)
パラメータ
パラメータ | 意味 |
XmagicApi.XmagicTipsListener effectTipsListener | コールバック関数の実装クラス、コールバックはメインスレッドにあるとは限りません。 |
setYTDataListener
顔の特徴点位置情報などのデータのコールバックを設定します。
void setYTDataListener(XmagicApi.XmagicYTDataListener ytDataListener)顔の情報などのデータのコールバックを設定しますpublic interface XmagicYTDataListener {void onYTDataUpdate(String data)}
onYTDataUpdateはJSON string構造を返します。最大で5つの顔の情報を返します。
{"face_info":[{"trace_id":5,"face_256_point":[180.0,112.2,...],"face_256_visible":[0.85,...],"out_of_screen":true,"left_eye_high_vis_ratio:1.0,"right_eye_high_vis_ratio":1.0,"left_eyebrow_high_vis_ratio":1.0,"right_eyebrow_high_vis_ratio":1.0,"mouth_high_vis_ratio":1.0},...]}
フィールドの意味
フィールド | タイプ | 値域 | 説明 |
trace_id | int | [1,INF) | 顔ID。連続ストリーム取得の過程で、IDが同一であれば同じ顔であると認識できます。 |
face_256_point | float | [0,screenWidth]または[0,screenHeight] | 計512個、顔のキーポイントは256個、画面左上隅は(0,0)です。 |
face_256_visible | float | [0,1] | 顔256キーポイントの視認性。 |
out_of_screen | bool | true/false | 顔がフレームから外れているかどうか。 |
left_eye_high_vis_ratio | float | [0,1] | 左目の高視認性特徴点の割合。 |
right_eye_high_vis_ratio | float | [0,1] | 右目の高視認性特徴点の割合。 |
left_eyebrow_high_vis_ratio | float | [0,1] | 左眉の高視認性特徴点の割合。 |
right_eyebrow_high_vis_ratio | float | [0,1] | 右眉の高視認性特徴点の割合。 |
mouth_high_vis_ratio | float | [0,1] | 口元の高視認性特徴点の割合。 |
パラメータ
パラメータ | 意味 |
XmagicApi.XmagicYTDataListener ytDataListener | コールバック関数の実装クラス。 |
setAIDataListener
顔、体、ジェスチャーを検出した際、これらの部位の特徴点位置情報をコールバックします
public interface OnAIDataListener {void onFaceDataUpdated(List<FaceData> faceDataList);void onHandDataUpdated(List<HandData> handDataList);void onBodyDataUpdated(List<BodyData> bodyDataList);}
onPause
レンダリングを一時停止します。ActivityのonPauseライフサイクルにバインドできます。現時点で内部では
onPauseAudio
のみ呼び出します。void onPause()
onResume
レンダリングを再開します。ActivityのonResumeライフサイクルにバインドできます。
void onResume()
onDestroy
GLスレッドのリソースをクリアします。GLスレッド内で呼び出す必要があります。サンプルコードは次のとおりです。
//サンプルコードはMainActivity.javaをご参照くださいglSurfaceView.queueEvent(() -> {if (mXmagicApi != null) {mXmagicApi.onPause();mXmagicApi.onDestroy();}});//サンプルコードはImageInputActivity.javをご参照ください@Overrideprotected void onDestroy() {if (mHandler != null) {mHandler.destroy(() -> {if (mXmagicApi != null) {mXmagicApi.onPause();mXmagicApi.onDestroy();}});mHandler.waitDone();}XmagicPanelDataManager.getInstance().clearData();super.onDestroy();}
process
SDKレンダリングのデータを受信するメソッドです。カメラデータのコールバック関数内で使用できます。
//テクスチャのレンダリングint process(int srcTextureId, int srcTextureWidth, int srcTextureHeight)//bitmapのレンダリングBitmap process(Bitmap bitmap, boolean needReset){
パラメータ
パラメータ | 意味 |
int srcTextureId | レンダリングが必要なテクスチャ。 |
id int srcTextureWidth | レンダリングが必要なテクスチャの幅。 |
int srcTextureHeight | レンダリングが必要なテクスチャの高さ。 |
Bitmap bitmap | 最大サイズは2160×4096までとすることをお勧めします。このサイズを超える画像は顔認識効果が低いか、または顔であると認識できない場合があり、またOOMの問題も起こりやすいため、大きな画像は縮小してから渡すことをお勧めします。 |
boolean needReset | 画像を切り替えます。 分割を初めて使用します。 動的エフェクトを初めて使用します。 メイクアップを初めて使用します。 これらのシナリオでは、needResetはtrueに設定されています。 |
onPauseAudio
オーディオのみ停止する必要があり、GLスレッドをリリースする必要がない場合に、この関数を呼び出すことができます。
void onPauseAudio()
sensorChanged
現在のスマートフォンの回転の角度を判断し、それによってAIの顔認識の判断角度の根拠を調整するために用いられます。ジャイロスコープセンサーコールバック関数内で呼び出す必要があります。
void sensorChanged(SensorEvent event, Sensor accelerometer)
パラメータ
パラメータ | 意味 |
SensorEvent event | ジャイロスコープセンサーのコールバック関数 onSensorChanged が返したイベントエンティティクラス。 |
Sensor accelerometer | ジャイロスコープセンサーの事例。 |
isDeviceSupport
動的エフェクトリソースリストをSDKのチェック用に渡します。実行後、XmagicProperty.isSupportフィールドは、その素材が利用可能かどうかを表します。
XmagicProperty.isSupport
によってUIレイヤーのクリック制限を制御することや、直接リソースリストから削除することができます。void isDeviceSupport(List<XmagicProperty<?>> assetsList)
パラメータ
パラメータ | 意味 |
List<XmagicProperty<?>> assetsList | 検査が必要な動的エフェクト素材リスト。 |
getPropertyRequiredAbilities
動的エフェクトリソースリストを渡し、各リソースが使用できるSDKアトミック機能のリストを返します。
メソッドのユースケースは次のとおりです。
いくつかの動的エフェクト素材を購入または制作し、このメソッドを呼び出すと、各素材が使用する必要があるアトミック機能のリストが返されます。例えば、素材1は機能A、B、Cを使用する必要があり、素材2は機能B、C、Dを使用する必要があるなどです。これらの機能リストをサーバー上で保持します。その後、ユーザーがサーバーから動的エフェクト素材をダウンロードしたい場合、先にgetDeviceAbilitiesメソッドによって、スマートフォンが備えるアトミック機能のリスト(このスマートフォンは機能A、B、Cを備えているが、機能Dは備えていないなど)を取得し、その機能リストをサーバーに渡すことで、サーバーがそのデバイスに機能Dが備わっていないと判断し、ユーザーに素材2を送信しないということが可能になります。
パラメータ
パラメータ | 意味 |
List<XmagicProperty<?>> assets | アトミック機能が必要な動的エフェクトリソースリスト。 |
戻る
戻り値
Map<XmagicProperty<?>,ArrayList<String>>
:key:動的エフェクトリソース素材のエンティティクラス。
value:使用するアトミック機能のリスト。
getDeviceAbilities
現在のデバイスがサポートするアトミック機能のテーブルを返します。getPropertyRequiredAbilitiesメソッドと合わせて使用します。詳細についてはgetPropertyRequiredAbilitiesの説明をご参照ください。
Map<String,Boolean> getDeviceAbilities()
戻る
戻り値
Map<String,Boolean>
:key:アトミック機能名(素材の機能名に対応)。
value:現在のデバイスがサポートしているかどうか。
isSupportBeauty
現在のモデルが美顔(OpenGL3.0)をサポートしているかどうかを判断します。
boolean isSupportBeauty()
戻る
戻り値boolean:美顔をサポートしているかどうか。
isBeautyAuthorized
現在のLicense権限がどの美顔または美ボディをサポートしているかを判断します。 BEAUTYおよびBODY_BEAUTYタイプの美顔項目のチェックのみサポートします。チェックの結果は各美顔オブジェクトの
XmagicProperty.isAuth
フィールドに割り当てられます。isAuthフィールドがfalseの場合は、UI上でこれらの項目へのエントリーをブロックすることができます。void isBeautyAuthorized(List<XmagicProperty<?>> properties)
パラメータ
パラメータ | 意味 |
List<XmagicProperty<?>> properties | 検出が必要な美顔アイテム。 |
setXmagicStreamType
入力データのタイプを設定します。デフォルトではAndroid cameraデータストリームです(XmagicApi.PROCESS_TYPE_CAMERA_STREAM)。
void setXmagicStreamType(int type)
パラメータ
パラメータ | 意味 |
int type | データソースタイプ、以下2つのオプションがあります。 XmagicApi.PROCESS_TYPE_CAMERA_STREAM :カメラデータソース。 XmagicApi.PROCESS_TYPE_PICTURE_DATA:画像データソース。 |
静的関数
API | 説明 |
libPathを設定します。 | |
アプリケーションassets下のLight3DPlugin、LightCore、LightHandPlugin、LightBodyPlugin、LightSegmentPluginフォルダの内容を、指定したディレクトリにコピーします | |
クライアントがダウンロードしたAIモデルファイルを対応するフォルダにコピーします |
setLibPathAndLoad
soのパスを設定し、ロードをトリガーします。soがassets内にある場合は、このメソッドを呼び出す必要はありません。soが動的ダウンロードしたものの場合は、認証および
new XmagicApi
の前に呼び出す必要があります。nullを渡す:デフォルトのパスからsoをロードすることを表します。soがAPKパッケージ内にあることを確認してください。
null以外を渡す:例えば、
data/data/パッケージ名/files/xmagic_libs
などです。このディレクトリからsoをロードすることを表します。static boolean setLibPathAndLoad(String path)
パラメータ
パラメータ | 意味 |
String path | soライブラリの格納パス。 |
addAiModeFilesFromAssets
アプリケーションassets下のLight3DPlugin、LightCore、LightHandPlugin、LightBodyPlugin、LightSegmentPluginフォルダの内容を、指定したディレクトリにコピーします。
contextアプリケーションのコンテキスト。
resDir 美顔リソースを格納するためのルートディレクトリです。このディレクトリは、xmagicApiオブジェクトを作成するために渡されたパスと同一です。
戻り値:0: コピーが成功したことを示します -1:contextがnullであることを示します -2:IOエラーを示します。
static int addAiModeFilesFromAssets(Context context, String resDir)
パラメータ
パラメータ | 意味 |
Context context | アプリケーションのコンテキスト。 |
String resDir | 美顔リソースを格納するためのルートディレクトリです。このディレクトリは、xmagicApiオブジェクトを作成するために渡されたパスと同一です。 |
addAiModeFiles
お客様がダウンロードしたAIモデルファイルを対応するフォルダにコピーします。
inputResDir ダウンロードに成功したモデルファイルのフォルダです。
resDir 美顔リソースを格納するためのルートディレクトリです。このディレクトリは、xmagicApiオブジェクトを作成するために渡されたパスと同一です。
戻り値:0は成功したことを示します -1:inputResDir is not exists -2:IOエラーを示します。
static int addAiModeFiles(String inputResDir, String resDir)
パラメータ
パラメータ | 意味 |
String inputResDir | ダウンロードに成功したモデルファイルのフォルダです。 |
String resDir | 美顔リソースを格納するためのルートディレクトリです。このディレクトリは、xmagicApiオブジェクトを作成するために渡されたパスと同一です。 |