iOS
腾讯特效 SDK 核心接口类
XMagic.h
,用于初始化 SDK、更新美颜数值、调用动效等功能。Public 成员函数
API | 描述 |
初始化接口 | |
初始化接口 | |
配置美颜各种效果 | |
配置美颜各种效果(3.5.0.2新增) | |
设置后处理模糊强度(作用于所有模糊组件) | |
设置 renderSize | |
资源释放接口 | |
图像数据处理接口,输入美颜前的图像,返回美颜后的图像。 | |
图像数据处理接口,输入美颜前的图像,返回美颜后的图像,比上接口多两个参数。 | |
处理图片 | |
获取美颜参数配置信息 | |
日志注册接口 | |
SDK 事件监听接口 | |
注册回调清理接口 | |
获取当前 GL 上下文接口 | |
SDK 暂停接口 | |
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)renderSizeassetsDict:(NSDictionary* _Nullable)assetsDict;
参数
参数 | 含义 |
renderSize | 渲染尺寸 |
assetsDict | 资源 Dict |
initWithGlTexture
初始化接口
- (instancetype _Nonnull)initWithGlTexture:(unsigned)textureIDwidth:(int)widthheight:(int)heightflipY:(bool)flipYassetsDict:(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)effectNameeffectValue:(int)effectValueresourcePath:(NSString * _Nullable)resourcePathextraInfo:(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 输入数据类型和说明
类型 | 含义 |
YTImagePixelData | 相机数据对象,像素格式为 RGBA |
YTTextureData | 纹理对象,纹理格式为 OpenGL 2D |
YTImageRawData | 原始数据对象 |
YTUIImageData | UIImage 对象 |
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 | |
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。
- Public 成员函数
- initWithRenderSize
- initWithGlTexture
- configPropertyWithType
- setEffect(3.5.0.2新增)
- emitBlurStrengthEvent
- setRenderSize
- deinit
- process
- process:withOrigin:withOrientation:
- TEImageTransform 工具类
- processUIImage
- getConfigPropertyWithName
- registerLoggerListener
- registerSDKEventListener
- clearListeners
- getCurrentGlContext
- onPause
- onResume
- setAudioMute
- enableEnhancedMode
- 高性能模式(V3.1.0新增)
- 静态函数
- 回调