腾讯特效SDKiOS_音视频解决方案_同尘科技

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

Public 成员函数

API	描述
initWithRenderSize	初始化接口
initWithGlTexture	初始化接口
configPropertyWithType	配置美颜各种效果
emitBlurStrengthEvent	设置后处理模糊强度（作用于所有模糊组件）
setRenderSize	设置 renderSize
deinit	资源释放接口
process:	图像数据处理接口，输入美颜前的图像，返回美颜后的图像。
process:withOrigin:withOrientation:	图像数据处理接口，输入美颜前的图像，返回美颜后的图像，比上接口多两个参数。
processUIImage	处理图片
getConfigPropertyWithName	获取美颜参数配置信息
registerLoggerListener	日志注册接口
registerSDKEventListener	SDK 事件监听接口
clearListeners	注册回调清理接口
getCurrentGlContext	获取当前 GL 上下文接口
onPause	SDK 暂停接口
onResume	SDK 恢复接口
setAudioMute	动效素材使用时是否开启静音（V2.5.0新增） 参数：YES表示静音，NO表示非静音
enableEnhancedMode	开启美颜增强模式（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];

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数据的bgrayuv格式的相互转换、旋转和上下/左右镜像。支持texture id格式输入的旋转和上下/左右镜像。


/// @param context 如果使用本类OpenGL接口,建议使用本方法初始化,可传[xMgiac getCurrentGlContext]- (instancetype)initWithEAGLContext:(EAGLContext *)context;

参数	含义
context	使用OpenGLES的上下文环境，可传[xMgiac 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 _Nullable)listener withDefaultLevel:(YtSDKLoggerLevel)level;

参数

参数	含义
listener	日志回调接口
level	日志输出 level，默认 ERROR

registerSDKEventListener

SDK 事件监听接口

- (void)registerSDKEventListener:(id _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	获取该美颜参数的授权信息

isBeautyAuthorized

获取该美颜参数的授权信息（仅支持美颜和美体）

/// @param featureId 配置美颜参数/// @return 返回对应美颜参数的授权结果+ (BOOL)isBeautyAuthorized:(NSString * _Nullable)featureId;

回调

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

YTSDKEventListener

SDK 内部事件回调接口

@protocol YTSDKEventListener 

成员函数

返回类型	名称
void	onAIEvent
void	onTipsEvent
void	onAssetEvent

函数说明

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 

成员函数

返回类型	函数名称
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。

对音视频的解决方案有疑惑？想了解解决方案收费？ 联系解决方案专家

腾讯云限时活动1折起，即将结束： 马上收藏

同尘科技为腾讯云授权服务中心，购买腾讯云享受折上折，更有现金返利:同意关联，立享优惠

阿里云解决方案也看看？： 点击对比阿里云的解决方案