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をご参照ください
@Override
protected 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オブジェクトを作成するために渡されたパスと同一です。