Android

Tencent 특수 효과 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 레벨을 설정하고, 개발 디버깅을 제안할 때는 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
오류 콜백 API.
에러 코드 반환 의미 대조표:
에러 코드
의미
-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 특수 효과 데이터 엔터티 클래스.
"피부 보정"을 예로 들면 다음과 같이 new 인스턴스를 만들 수 있습니다. new XmagicProperty<>(Category.BEAUTY, null, null, BeautyConstant.BEAUTY_SMOOTH, new XmagicPropertyValues(0, 100, 50, 0, 1)));
‘2D Animated Bunny Sauce’를 예로 들면 다음과 같이 새 인스턴스를 만들 수 있습니다. 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_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.java 참고
@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
데이터 원본 유형에는 두 가지 옵션이 있습니다.
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/packagename/files/xmagic_libs와 같이 이 디렉터리에서 로딩됩니다.
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 객체를 생성하기 위해 전달된 경로와 일치합니다.