iOS

腾讯特效 SDK 核心接口类 XMagic.h,用于初始化 SDK、更新美颜数值、调用动效等功能。

Public 成员函数

API
描述
初始化接口
初始化接口
配置美颜各种效果
setEffect
配置美颜各种效果(3.5.0.2新增)
设置后处理模糊强度(作用于所有模糊组件)
设置 renderSize
deinit
资源释放接口
process:
图像数据处理接口,输入美颜前的图像,返回美颜后的图像。
图像数据处理接口,输入美颜前的图像,返回美颜后的图像,比上接口多两个参数。
处理图片
获取美颜参数配置信息
日志注册接口
SDK 事件监听接口
注册回调清理接口
获取当前 GL 上下文接口
onPause
SDK 暂停接口
onResume
SDK 恢复接口
动效素材使用时是否开启静音(V2.5.0新增) 参数:YES表示静音,NO表示非静音
开启美颜增强模式(V2.5.1新增)。默认未开启。
未开启时,应用层可以设置的各美颜项的强度范围为 0到1 或 -1到1,如果超出此范围,SDK 会取边界值。例如应用层设置瘦脸为1.2,SDK判断其超出了最大值1.0,则在内部把瘦脸值修正为1.0。
开启增强模式后,应用层可以设置更大范围的数值。例如想要瘦脸程度更大,则可以把瘦脸值设置为1.2,SDK 会接受并使用1.2这个数值,不会将其修正为1.0。
说明:
开启增强模式后,需要应用层自己管理每个美颜项可以设置的最大值,让用户在此范围内调整数值。我们提供了一份 参考值,您可以根据产品需求自由调整,但不建议超出我们的推荐值,否则美颜效果可能变差。
如果想要某个动效/美妆/分割素材叠加在当前素材上,则设置该素材时,在 withExtraInfo 的字典中设置 mergeWithCurrentMotion 为 true
在 SDK 初始化时,字典中添加@"setDowngradePerformance":@(YES)。高性能模式开启后,美颜占用的系统 CPU/GPU 资源更少,可减少手机的发热和卡顿现象,更适合低端机长时间用。

initWithRenderSize

初始化接口
- (instancetype _Nonnull)initWithRenderSize:(CGSize)renderSize
assetsDict:(NSDictionary* _Nullable)assetsDict;
参数
参数
含义
renderSize
渲染尺寸
assetsDict
资源 Dict

initWithGlTexture

初始化接口
- (instancetype _Nonnull)initWithGlTexture:(unsigned)textureID
width:(int)width
height:(int)height
flipY:(bool)flipY
assetsDict:(NSDictionary* _Nullable)assetsDict;
参数
参数
含义
textureID
纹理 ID
width
渲染尺寸
height
渲染尺寸
flipY
是否翻转图片
assetsDict
资源 Dict

configPropertyWithType

配置美颜各种效果
- (int)configPropertyWithType:(NSString *_Nonnull)propertyType withName:(NSString *_Nonnull)propertyName withData:(NSString*_Nonnull)propertyValue withExtraInfo:(id _Nullable)extraInfo;
参数
参数
含义
propertyType
效果类型
propertyName
效果名称
propertyValue
效果数值
extraInfo
预留扩展, 附加额外配置 Dict

配置美颜效果示例

美颜:配置美白效果
NSString *propertyType = @"beauty"; //配置美颜的效果类型,这里以美颜为例
NSString *propertyName = @"beauty.whiten"; //配置美颜的名称,这里以美白为例
NSString *propertyValue = @"60"; //配置美白的效果数值
[self.xmagicApi configPropertyWithType:propertyType withName:propertyName withData:propertyValue withExtraInfo:nil];
滤镜:配置心动效果
NSString *propertyType = @"lut"; //配置美颜的效果类型,这里以滤镜为例
NSString *propertyName = [@"lut.bundle/" stringByAppendingPathComponent:@"xindong_lf.png"]; //配置美颜的名称,这里以心动为例
NSString *propertyValue = @"60"; //配置滤镜的效果数值
[self.xmagicApi configPropertyWithType:propertyType withName:propertyName withData:propertyValue withExtraInfo:nil];
美体:配置长腿效果
NSString *propertyType = @"body"; //配置美颜的效果类型,这里以美体为例
NSString *propertyName = @"body.legStretch"; //配置美颜的名称,这里以长腿为例
NSString *propertyValue = @"60"; //配置长腿的效果数值
[self.xmagicApi configPropertyWithType:propertyType withName:propertyName withData:propertyValue withExtraInfo:nil];
动效:配置2D动效的可爱涂鸦效果
NSString *motion2dResPath = [[NSBundle mainBundle] pathForResource:@"2dMotionRes" ofType:@"bundle"];//这里是2dMotionRes文件夹的绝对路径
NSString *propertyType = @"motion"; //配置美颜的效果类型,这里以动效为例
NSString *propertyName = @"video_keaituya"; //配置美颜的名称,这里以2D动效的可爱涂鸦为例
NSString *propertyValue = motion2dResPath; //配置动效的路径
[self.xmagicApi configPropertyWithType:propertyType withName:propertyName withData:propertyValue withExtraInfo:nil];
美妆:配置女团妆效果
NSString *motionMakeupResPath = [[NSBundle mainBundle] pathForResource:@"makeupMotionRes" ofType:@"bundle"];//这里是makeupMotionRes文件夹的绝对路径
NSString *propertyType = @"motion"; //配置美颜的效果类型,这里以美妆为例
NSString *propertyName = @"video_nvtuanzhuang"; //配置美颜的名称,这里以女团妆为例
NSString *propertyValue = motionMakeupResPath; //配置动效的路径
[self.xmagicApi configPropertyWithType:propertyType withName:propertyName withData:propertyValue withExtraInfo:nil];
//下面是要配置美妆的数值(上面的动效只需要调用一次,下面的配置美妆数值可以多次调用)
NSString *propertyTypeMakeup = @"custom"; //配置美颜的效果类型,这里以美妆为例
NSString *propertyNameMakeup = @"makeup.strength"; //配置美颜的名称,这里以女团妆为例
NSString *propertyValueMakeup = @"60"; //配置美妆的效果数值
[self.xmagicApi configPropertyWithType:propertyTypeMakeup withName:propertyNameMakeup withData:propertyValueMakeup withExtraInfo:nil];
分割:配置背景模糊(强效果)
NSString *motionSegResPath = [[NSBundle mainBundle] pathForResource:@"segmentMotionRes" ofType:@"bundle"];//这里是segmentMotionRes文件夹的绝对路径
NSString *propertyType = @"motion"; //配置美颜的效果类型,这里以分割为例
NSString *propertyName = @"video_segmentation_blur_75"; //配置美颜的名称,这里以背景模糊-强为例
NSString *propertyValue = motionSegResPath; //配置动效的路径
NSDictionary *dic = @{@"bgName":@"BgSegmentation.bg.png", @"bgType":@0, @"timeOffset": @0},@"icon":@"segmentation.linjian.png"};//配置预留字段
[self.xmagicApi configPropertyWithType:propertyType withName:propertyName withData:propertyValue withExtraInfo:dic];
自定义背景
NSString *motionSegResPath = [[NSBundle mainBundle] pathForResource:@"segmentMotionRes" ofType:@"bundle"];//这里是segmentMotionRes文件夹的绝对路径
NSString *propertyType = @"motion"; //配置美颜的效果类型,这里以分割为例
NSString *propertyName = @"video_empty_segmentation"; //配置美颜的名称,这里以自定义背景为例
NSString *propertyValue = motionSegResPath; //配置动效的路径
NSString *imagePath = @"/var/mobile/Containers/Data/Application/06B00BBC-9060-450F-8D3A-F6028D185682/Documents/MediaFile/image.png"; //自定义背景图片的绝对路径。如果自定义背景选择的是视频,需要对视频进行压缩转码处理,使用压缩转码处理后的绝对路径
int bgType = 0;//自定义背景的类型。 0表示图片,1表示视频
int timeOffset = 0//时长。图片背景时,为0;视频背景时为视频的时长
NSDictionary *dic = @{@"bgName":imagePath, @"bgType":@(bgType), @"timeOffset": @(timeOffset)},@"icon":@"segmentation.linjian.png"};//配置预留字段
[self.xmagicApi configPropertyWithType:propertyType withName:propertyName withData:propertyValue withExtraInfo:dic];

setEffect(3.5.0.2新增)

配置美颜各种效果,具体使用示例请参考 美颜参数说明
- (void)setEffect:(NSString * _Nullable)effectName
effectValue:(int)effectValue
resourcePath:(NSString * _Nullable)resourcePath
extraInfo:(NSDictionary * _Nullable)extraInfo;

参数
参数
含义
effectName
效果类型
effectValue
效果数值
resourcePath
素材路径
extraInfo
预留扩展, 附加额外配置

emitBlurStrengthEvent

设置后处理模糊强度(作用于所有模糊组件)
- (void)emitBlurStrengthEvent:(int)strength;
参数
参数
含义
strength
效果数值

setRenderSize

设置 renderSize
- (void)setRenderSize:(CGSize)size;
参数
参数
含义
size
渲染尺寸

deinit

资源释放接口
- (void)deinit;

process

处理数据接口,输入的数据格式有YTImagePixelData、YTTextureData、YTImageRawData、YTUIImageData,输出对应的数据格式。其中YTImagePixelData中的像素格式为RGBA,YTTextureData中的纹理格式为OpenGL 2D
/// @brief 处理输入4选1 Process input 4 choose 1
@interface YTProcessInput : NSObject
/// 相机数据对象 camera data object
@property (nonatomic, strong) YTImagePixelData * _Nullable pixelData;
/// 纹理对象 texture object
@property (nonatomic, strong) YTTextureData * _Nullable textureData;
/// 原始数据对象 raw data object
@property (nonatomic, strong) YTImageRawData * _Nullable rawData;
/// UIImage对象 UIImage object
@property (nonatomic, strong) YTUIImageData * _Nullable UIImageData;
/// 输入数据类型 input data type
@property (nonatomic) enum YTProcessDataType dataType;
@end
/// @brief 处理输出 process output
@interface YTProcessOutput : NSObject
/// 纹理输出对象(一定会有) Texture output object (always output)
@property (nonatomic, strong) YTTextureData * _Nullable textureData;
/// 相机输出对象(如果输入是相机采集数据) Camera output object (if the input is camera acquisition data)
@property (nonatomic, strong) YTImagePixelData * _Nullable pixelData;
/// 原始输出对象(如果输入是原始数据) raw output object (if input is raw data)
@property (nonatomic, strong) YTImageRawData * _Nullable rawData;
/// UIImage输出对象(如果输入是UIImage对象) UIImage output object (if the input is a UIImage object)
@property (nonatomic, strong) YTUIImageData * _Nullable UIImageData;
/// 输出数据类型 output data type
@property (nonatomic) enum YTProcessDataType dataType;
@end

- (YTProcessOutput* _Nonnull)process:(YTProcessInput * _Nonnull)input;
参数
参数
含义
input
输入处理数据信息,输入的格式四选一(YTImagePixelData、YTTextureData、YTImageRawData、YTUIImageData)

YTProcessInput 输入数据类型和说明

调用 process 接口时,输出数据类型跟输入数据类型一致,YTTextureData 类型总是会输出。
类型
含义
YTImagePixelData
相机数据对象,像素格式为 RGBA
YTTextureData
纹理对象,纹理格式为 OpenGL 2D
YTImageRawData
原始数据对象
YTUIImageData
UIImage 对象

process:withOrigin:withOrientation:

处理数据接口,输入和输出的数据格式跟process一致。withOrigin:设置图像是否上下镜像翻转,withOrientation:设置图像旋转方向。

- (YTProcessOutput* _Nonnull)process:(YTProcessInput* _Nonnull)input withOrigin:(YtLightImageOrigin)origin withOrientation:(YtLightDeviceCameraOrientation)orientation;

参数
参数
含义
input
输入处理数据信息
withOrigin
枚举值(YtLightImageOriginTopLeft、YtLightImageOriginBottomLeft),设置成YtLightImageOriginBottomLeft 时,图像上下镜像翻转
withOrientation
枚举值:图像旋转角度,设置角度会修改输出的图像角度

TEImageTransform 工具类

图像处理工具类,输入/输出的数据格式有 CVPixelBufferref、texture id。支持 CVPixelBufferref 数据的 bgra<-->yuv 格式的相互转换、旋转和上下/左右镜像。支持 texture id 格式输入的旋转和上下/左右镜像。

/// @param context 如果使用本类OpenGL接口,建议使用本方法初始化,可传[xMgiac getCurrentGlContext]
- (instancetype)initWithEAGLContext:(EAGLContext *)context;
参数
含义
context
使用OpenGLES的上下文环境,可传[xMagic getCurrentGlContext]

/// @brief CVPixelBufferRef yuv/rgb相互转换接口,目前只支持TEPixelFormatType内的三种类型转换 CVPixelBufferRef yuv/rgb transfor interface
/// @param pixelBuffer 输入pixelBuffer input pixelBuffer
/// @param outputFormat 指定输出pixelBuffer的类型 out pixelBuffer format
- (CVPixelBufferRef)transformCVPixelBufferToBuffer:(CVPixelBufferRef)pixelBuffer outputFormat:(TEPixelFormatType)outputFormat;

参数
含义
pixelBuffer
输入的 pixelBuffer 数据
outputFormat
输出的 pixelBuffer 格式,支持 BGRA、NV12F(kCVPixelFormatType_420YpCbCr8BiPlanarFullRange)、NV12V(kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange)

/// 将yuv/rgb pixelBuffer转换为bgra格式的纹理id
/// @param pixelBuffer 输入pixelBuffer
- (GLuint)transformPixelBufferToBGRATexture:(CVPixelBufferRef)pixelBuffer;
参数
含义
pixelBuffer
输入的 pixelBuffer 数据,支持 BGRA、NV12F(kCVPixelFormatType_420YpCbCr8BiPlanarFullRange)、NV12V(kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange)


/// 对CVPixelBufferRef进行旋转和镜像翻转, 如果同时传旋转和镜像,处理逻辑为先镜像再旋转
- (CVPixelBufferRef)convertCVPixelBuffer:(CVPixelBufferRef)pixelBuffer rotaion:(YtLightDeviceCameraOrientation)rotation flip:(TEFlipType)flipType;
参数
含义
pixelBuffer
输入的 pixelBuffer 数据
rotation
逆时针旋转角度,支持0度、90度、180度、270度。
flipType
镜像类型,水平镜像或者垂直镜像。如果同时传旋转和镜像,处理逻辑为先镜像再旋转

/// 对纹理Id进行旋转/镜像翻转,如果同时传旋转和镜像,处理逻辑为先镜像再旋转

- (GLuint)convert:(GLuint)srcId width:(int)width height:(int)height rotaion:(YtLightDeviceCameraOrientation)rotation flip:(TEFlipType)flipType;
参数
含义
srcId
输入的纹理 ID
width
纹理的宽度
height
纹理的高度
rotation
逆时针旋转角度,支持0度、90度、180度、270度。
flipType
镜像类型,水平镜像或者垂直镜像。如果同时传旋转和镜像,处理逻辑为先镜像再旋转

processUIImage

处理图片
- (UIImage* _Nullable)processUIImage:(UIImage* _Nonnull)inputImage needReset:(bool)needReset;
参数
参数
含义
inputImage
输入图片建议最大尺寸 2160×4096。超过这个尺寸的图片人脸识别效果不佳或无法识别到人脸,同时容易引起 OOM 问题,建议把大图缩小后再传入
needReset
以下场景中 needReset 需设置 为 true:
切换图片
首次使用分割
首次使用动效
首次使用美妆

getConfigPropertyWithName

获取美颜参数配置信息
- (YTBeautyPropertyInfo * _Nullable)getConfigPropertyWithName:(NSString *_Nonnull)propertyName;
参数
参数
含义
propertyName
配置名称

registerLoggerListener

日志注册接口
- (void)registerLoggerListener:(id<YTSDKLogListener> _Nullable)listener withDefaultLevel:(YtSDKLoggerLevel)level;
参数
参数
含义
listener
日志回调接口
level
日志输出 level,默认 ERROR

registerSDKEventListener

SDK 事件监听接口
- (void)registerSDKEventListener:(id<YTSDKEventListener> _Nullable)listener;
参数
参数
含义
listener
事件监听器回调,主要分为 AI 事件,Tips 提示事件,Asset 事件

clearListeners

注册回调清理接口
- (void)clearListeners;

getCurrentGlContext

获取当前 GL 上下文接口
- (nullable EAGLContext*)getCurrentGlContext;

onPause

SDK 暂停接口
/// @brief APP暂停时候需要调用SDK暂停接口
- (void)onPause;

onResume

SDK 恢复接口
/// @brief APP恢复时候需要调用SDK恢复接口
- (void)onResume;

setAudioMute

动效素材使用时是否开启静音(V2.5.0新增)
/// @brief 设置静音
- (void)setAudioMute:(BOOL)isMute;

enableEnhancedMode

/// @brief 开启美颜增强模式
- (void)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

高性能模式(V3.1.0新增)

高性能模式开启后,美颜占用的系统 CPU/GPU 资源更少,可减少手机的发热和卡顿现象,更适合低端机长时间用。
注意:开启高性能模式后,以下美颜项将不可用:
1. 眼部:眼宽、眼高、祛眼袋。
2. 眉毛:角度、距离、高度、长度、粗细、眉峰。
3. 嘴部:微笑唇。
4. 面部:瘦脸(自然,女神,英俊),收下颌,祛皱、祛法令纹。建议用“脸型”实现综合大眼瘦脸效果。
NSDictionary *assetsDict = @{@"core_name":@"LightCore.bundle",
@"root_path":[[NSBundle mainBundle] bundlePath],
@"setDowngradePerformance":@(YES) //开启高性能模式

};
self.beautyKit = [[XMagic alloc] initWithRenderSize:previewSize assetsDict:assetsDict];


静态函数

API
描述
获取该美颜参数的授权信息

isBeautyAuthorized

获取该美颜参数的授权信息(仅支持美颜和美体)
/// @param featureId 配置美颜参数
/// @return 返回对应美颜参数的授权结果
+ (BOOL)isBeautyAuthorized:(NSString * _Nullable)featureId;

回调

API
描述
SDK 内部事件回调接口
日志监听回调

YTSDKEventListener

SDK 内部事件回调接口
@protocol YTSDKEventListener <NSObject>

成员函数

返回类型
名称
void
onAIEvent
void
void

函数说明

onAIEvent
AI 事件回调
/// @param event dict格式的回调
- (void)onAIEvent:(id _Nonnull)event;
最多返回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]
嘴高可见度点位占比
onTipsEvent
提示事件回调
/// @param event dict格式的回调
- (void)onTipsEvent:(id _Nonnull)event;
onAssetEvent
资源包事件回调
/// @param event string格式的回调
- (void)onAssetEvent:(id _Nonnull)event;

YTSDKLogListener

日志监听回调
@protocol YTSDKLogListener <NSObject>

成员函数

返回类型
函数名称
void
onLog

函数说明

onLog
日志监听回调
/// @param loggerLevel 返回当前日志等级
/// @param logInfo 返回当前日志信息
- (void)onLog:(YtSDKLoggerLevel) loggerLevel withInfo:(NSString * _Nonnull) logInfo;

素材叠加(3.0.1.5新增)

如果想要某个动效/美妆/分割素材叠加在当前素材上,则设置该素材时,在 withExtraInfo 的字典中设置 mergeWithCurrentMotion 为 true,示例如下:
NSString *key = _xmagicUIProperty.property.Id;
NSString *value = [[NSBundle mainBundle] pathForResource:@"makeupMotionRes" ofType:@"bundle"];
NSDictionary* extraInfo = @{@"mergeWithCurrentMotion":@(true)};
[self.beautyKitRef configPropertyWithType:@"motion" withName:key withData:[NSString stringWithFormat:@"%@",value] withExtraInfo:extraInfo];
素材叠加注意事项:
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。