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 참고@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)//렌더링 bitmapBitmap 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 객체를 생성하기 위해 전달된 경로와 일치합니다. |