腾讯特效 SDK 核心接口类
XmagicApi.java，用于初始化 SDK、更新美颜数值、调用动效等功能。Public 成员函数
API | 描述 |
构造函数。 | |
更新属性， 可在任意线程调用（V3.3.0及以前）。 | |
批量更新属性，可在任意线程调用（V3.3.0及以前）。 | |
设置美颜、美型、滤镜、美妆、贴纸、分割等效果，可在任意线程调用（V3.5.0版本新增） | |
设置动效提示语回调函数，用于将提示语展示到前端页面上。 | |
设置人脸点位信息等数据回调，需要获得人脸点位的 Licence 授权（例如原子能力X102）才会有回调。 | |
设置人脸、手势、身体检测状态回调。 | |
暂停声音播放，可与 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 数据流。 | |
设置 SDK 的 log 等级，默认为 WARN。开发调试阶段如有需要，可以将其设为Log.DEBUG。正式发布时务必设置为Log.WARN或Log.ERROR，否则大量的日志会影响性能。在 new XmagicApi() 之后调用。 | |
动效素材使用时是否开启静音（V2.5.0新增）： 参数：true 表示静音，false 表示非静音。 | |
开启美颜增强模式（V2.5.1新增）。默认未开启。 未开启时，应用层可以设置的各美颜项的强度范围为0到1或-1到1，如果超出此范围，SDK 会取边界值。例如应用层设置瘦脸为1.2，SDK 判断其超出了最大值1.0，则在内部把瘦脸值修正为1.0。 开启增强模式后，应用层可以设置更大范围的数值。例如想要瘦脸程度更大，则可以把瘦脸值设置为1.2，SDK会接受并使用1.2这个数值，不会将其修正为1.0。 说明： | |
| |
调用此方法开启高性能模式。高性能模式开启后，美颜占用的系统 CPU/GPU 资源更少，可减少手机的发热和卡顿现象，更适合低端机长时间使用。 | |
获取当前纹理上的画面 | |
开启或关闭某个能力 | |
XmagicApi
构造函数。
XmagicApi(Context context, String resDir)XmagicApi(Context context, String resDir,OnXmagicPropertyErrorListener xmagicPropertyErrorListener)
参数
参数 | 类型 | 含义 |
context | Context | 上下文。 |
resDir | String | 资源文件目录。 如果 SDK 资源文件是内置在 assets 的，那么首次使用 SDK 之前，需要把资源 copy 到 App 的私有目录：先通过 XmagicResParser.setResPath(new File(getFilesDir(), "xmagic").getAbsolutePath()) 设置资源路径，再通过 XmagicResParser.copyRes(getApplicationContext()) 完成资源拷贝，详见 Demo 的 TEMenuActivity.java。如果 SDK 资源文件是联网下载的，下载成功后，通过 XmagicResParser.setResPath(validAssetsDirectory) 设置资源路径。通过 XmagicResParser.getResPath() 获取先前设置的路径。 |
xmagicPropertyErrorListener | OnXmagicPropertyErrorListener | 错误回调接口。 |
返回错误码含义对照表：
错误码 | 含义 |
-1 | 未知错误。 |
-100 | 3D 引擎资源初始化失败。 |
-200 | 不支持 GAN 素材。 |
-300 | 设备不支持此素材组件。 |
-400 | 模板 JSON 内容为空。 |
-500 | SDK 版本过低。 |
-600 | 不支持分割。 |
-700 | 不支持 OpenGL。 |
-800 | 不支持脚本。 |
5000 | 分割背景图片分辨率超过 2160×3840。 |
5001 | 分割背景图片所需内存不足。 |
5002 | 分割背景视频解析失败。 |
5003 | 分割背景视频超过200秒。 |
5004 | 分割背景视频格式不支持。 |
5005 | 分割背景图片存在旋转角度 |
updateProperty，updateProperties
更改某一项或批量更改多项美颜、动效、滤镜，可在任意线程调用。
void updateProperty(XmagicProperty<?> p)void updateProperties(List<XmagicProperty<?>> properties)
参数
参数 | 含义 |
XmagicProperty<?> p | 腾讯特效数据实体类。 以"磨皮"为例，可以按如下方式 new 一个实例： new XmagicProperty<>(Category.BEAUTY, null, null, BeautyConstant.BEAUTY_SMOOTH, new XmagicPropertyValues(0, 100, 50, 0, 1));以“2D 动效兔兔酱”为例，可以按如下方式 new 一个实例： new XmagicProperty<>(Category.MOTION, "video_tutujiang" , "动效的文件路径", null, null); 如果想要某个动效/美妆/分割素材叠加在当前素材上，则将该素材 XmagicProperty 对象的 mergeWithCurrentMotion 设置为 true。关于素材叠加的详细说明见 素材叠加。 更多的例子，请参见 Demo 工程 assets/beauty_panel 文件夹下的配置信息。 |
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 中 assets/beauty_panel/advanced_beauty.json 文件。 |
effkey | 必填，参考 Demo 示例：美白 BeautyConstant.BEAUTY_WHITEN |
effValue | 必填，参考 Demo 中 assets/beauty_panel/advanced_beauty.json 文件，demo工程中解析该文件构造一个XmagicPropertyValues对象，XmagicPropertyValues各个属性取值见美颜参数说明 |
美体
属性字段 | 说明 |
category | Category.BODY_BEAUTY |
ID | null |
resPath | null |
effkey | 必填，参考 Demo 示例：长腿 BeautyConstant.BODY_LEG_STRETCH |
effValue | 必填，参考 Demo 中 assets/beauty_panel/beauty_body.json 文件。demo工程中解析该文件构造一个XmagicPropertyValues对象，XmagicPropertyValues各个属性取值见美颜参数说明 |
滤镜
属性字段 | 说明 |
category | Category.LUT |
ID | 图片名称，必填 示例：dongjing_lf.png “无” ID 为 XmagicProperty.ID_NONE |
resPath | 滤镜图片路径，必填，“无”设置为 null |
effkey | null |
effValue |
动效
属性字段 | 说明 |
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 |
分割
属性字段 | 说明 |
category | Category.SEGMENTATION |
ID | 资源文件夹名称，必填 示例：video_segmentation_blur_45 “无” ID 为 XmagicProperty.ID_NONE 自定义分割 ID 值必须使用： XmagicConstant.SegmentationId.CUSTOM_SEG_ID |
resPath | 必填，参考 Demo |
effkey | null（自定义背景除外），自定义背景的值为选择的资源路径 |
effValue | null |
setEffect（V3.5.0新增）
void setEffect(String effectName, int effectValue, String resourcePath, Map<String, String> extraInfo)
setTipsListener
设置动效提示语回调函数，用于将提示语展示到前端页面上。例如某些素材会提示用户点点头、伸出手掌、比心等。
void setTipsListener(XmagicApi.XmagicTipsListener effectTipsListener)
参数
参数 | 含义 |
XmagicApi.XmagicTipsListener effectTipsListener | 回调函数实现类，回调不一定在主线程。 |
setYTDataListener（此接口在3.0.0版本已经删除，功能移植到了XmagicAIDataListener的onAIDataUpdated方法）
设置人脸点位信息等数据回调。
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
检测到人脸、身体、手势时，会回调这些部位的点位信息：
onFaceDataUpdated：开启美颜后就会有回调，识别到人脸时，回调 List<FaceData>，没有人脸时，回调一个空的 List。
onHandDataUpdated：设置了手势动效，且识别到手势时回调，其他情况不回调。
onBodyDataUpdated：设置了美体的属性并且识别到身体的时候回调，其他情况不回调。
public interface OnAIDataListener {void onFaceDataUpdated(List<TEFaceData> faceDataList);void onHandDataUpdated(List<TEHandData> handDataList);void onBodyDataUpdated(List<TEBodyData> bodyDataList);void onAIDataUpdated(String jsonString); //此方法是3.0.0版本新增方法，数据结构和之前XmagicYTDataListener接口的数据保持一致}
onPause
暂停渲染，可与 Activity onPause 生命周期绑定，目前内部仅调用
onPauseAudio。void onPause()
onResume
恢复渲染，可与 Activity onResume 生命周期绑定。
void onResume()
onDestroy
清理GL线程资源，需要在 GL 线程内调用。示例代码：
//示例代码见 TECameraBaseActivity.javapublic void onGLContextDestroy() { if (this.mXMagicApi != null) { this.mXMagicApi.onDestroy(); this.mXMagicApi = null; } }
process
SDK 渲染接受数据的方法，可在相机数据回调函数内使用。
//渲染纹理int process(int srcTextureId, int srcTextureWidth, int srcTextureHeight)//渲染bitmapBitmap process(Bitmap bitmap, boolean needReset)
参数
参数 | 含义 |
int srcTextureId | 需要被渲染的纹理。类型为：OpenGL 2D 纹理格式,像素格式为 RGBA。 |
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
3.5.0版本及以后。
/** * 检测当前设备是否支持此素材 * @param motionResPath 素材文件的路径 * @return true 表示支持，false 表示不支持 */boolean isDeviceSupport(String motionResPath)
3.3.0版本及之前。
将动效资源列表传入 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：图片数据源。 |
setXmagicLogLevel
设置 SDK 的 log 等级，默认为WARN。开发调试阶段如有需要，可以将其设为
Log.DEBUG。正式发布时务必设置为 Log.WARN 或 Log.ERROR，否则大量的日志会影响性能。在 new XmagicApi() 之后调用。
setAudioMute
动效素材使用时是否开启静音（V2.5.0新增）：
参数：true 表示静音，false 表示非静音。
enableEnhancedMode
开启美颜增强模式（V2.5.1新增）。默认未开启。
未开启时，应用层可以设置的各美颜项的强度范围为 0到1 或 -1到1，如果超出此范围，SDK会取边界值。例如应用层设置瘦脸为1.2，SDK判断其超出了最大值1.0，则在内部把瘦脸值修正为1.0。
开启增强模式后，应用层可以设置更大范围的数值。例如想要瘦脸程度更大，则可以把瘦脸值设置为1.2，SDK会接受并使用1.2这个数值，不会将其修正为1.0。
开启增强模式后，需要应用层自己管理每个美颜项可以设置的最大值，让用户在此范围内调整数值。我们提供了一份参考值，您可以根据产品需求自由调整，但不建议超出我们的推荐值，否则美颜效果可能变差。参考值如下：
美颜项名称 | 增强模式下，建议的最大值（放大倍数） |
美白，短脸，V脸，眼距，鼻子位置，祛法令纹，口红，立体 | 1.3 |
亮眼 | 1.5 |
腮红 | 1.8 |
其他 | 1.2 |
| |
| |
| |
素材叠加（3.0.1.2新增）
如果想要某个动效/美妆/分割素材叠加在当前素材上，则将该素材 XmagicProperty 对象的 mergeWithCurrentMotion 设置为 true。XMagicProperty 对象的其他属性设置见 美颜参数设置。
素材叠加注意事项：
1. 客户需要自行管理素材之间是否适合叠加。举两个例子：
例1：特效 A 是变成贵妃脸，特效 B 是变成童话脸，这两个特效叠加后可能会导致画面非常别扭。
例2：特效 A 是个兔耳朵，特效 B 是猪耳朵，两个叠加后，就有两种耳朵。
例1和例2这两种情况不适合叠加。如果特效 A 是兔耳朵，特效 B 是送一个飞吻，这两个特效不会冲突，就适合叠加。
2. 只支持简单素材之间的叠加。简单素材是指只有单动效能力、或者单美妆效果、或者单抠背等，复杂素材是指包含了多种效果。简单素材和复杂素材没有明确的界定，建议客户充分测试后，自行管理哪些素材之间可以叠加，哪些不能叠加。
3. 叠加时，有动作触发的特效（例如伸出手触发某个特效、微笑触发某个特效等）属于复杂特效，需要放在前面，简单特效放在后面叠加在它之上。
4. 使用示例：主播使用了特效 A，然后观众送礼物特效 B，B 要叠加在 A 之上，一段时间后 B 消失，恢复成特效 A。那么设置步骤如下：
4.1 设置特效 A，mergeWithCurrentMotion 设置为 false。
4.2 设置特效 B，mergeWithCurrentMotion 设置为 true。
4.3 一小段时间后，再设置 A，mergeWithCurrentMotion 设置为 false。
setDowngradePerformance（V3.1.0新增）
开启高性能模式后，美颜占用的系统 CPU/GPU 资源更少，可减少手机的发热和卡顿现象，更适合低端机长时间使用。
注意：开启高性能模式后，以下美颜项将不可用：
1. 眼部：眼宽、眼高、祛眼袋 。
2. 眉毛：角度、距离、高度、长度、粗细、眉峰。
3. 嘴部：微笑唇。
4. 面部：瘦脸（自然，女神，英俊），收下颌，祛皱、祛法令纹。建议用“脸型”实现综合大眼瘦脸效果。
void boolean setDowngradePerformance()
exportCurrentTexture
获取当前纹理上的画面
void exportCurrentTexture(ExportTextureCallback callback)
setFeatureEnableDisable
开启或关闭某个能力
void setFeatureEnableDisable(String featureName, boolean enable)
参数
参数 | 含义 |
String featureName | 原子能力名称 取值如下： XmagicConstant.FeatureName.ANIMOJI_52_EXPRESSION 人脸表情能力XmagicConstant.FeatureName.BODY_3D_POINT 身体点位能力XmagicConstant.FeatureName.HAND_DETECT 手势检测能力XmagicConstant.FeatureName.WHITEN_ONLY_SKIN_AREA 美白仅对皮肤生效XmagicConstant.FeatureName.SEGMENTATION_SKIN 皮肤分割能力XmagicConstant.FeatureName.SMART_BEAUTY 智能美颜(为男性、宝宝减淡美颜美妆效果) |
boolean enable | true 表示开启此能力，false 表示关闭此能力 注：如果是降级模式，则不允许开启皮肤分割 |
静态属性和方法
API | 描述 |
VERSION | 通过XmagicApi.VERSION可获取SDK的版本号（V3.5.0新增） |
设置 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 对象时传入的路径一致。 |
是
否
本页内容是否解决了您的问题？