tencent cloud

Tencent Effect SDK

iOS

Download
Focus Mode
Font Size
Last updated: 2026-07-21 11:27:00

Features

TEBeautyKit is the UI panel library for the Tencent Effect module, used for quick and convenient usage and management of the effect features. The effect is as shown in the figure below:


Integration Steps

1. Integration TEBeautyKit,Edit the Podfile and append the following code snippet and execution pod install.
# Replace S1-07 with the package you purchased
pod 'TEBeautyKit/S1-07', :podspec => 'https://mediacloud-76607.gzc.vod.tencent-cloud.com/TencentEffect/iOS/TEBeautyKit/latest/TEBeautyKit.podspec'
2. Integration Panel Resources, download the resource package and incorporate it into your main project. The contents can be found in the appendix.
3. Integration Effect Resources.

Usage Guide

Step 1. Authenticate

After the application is launched, a beauty filter authentication must be performed to enable the normal use of beauty features. See the authentication error code
[TEBeautyKit setTELicense:@"your license" key:@"your key" completion:^(NSInteger authresult, NSString * _Nullable errorMsg) {
NSLog(@"----------result: %zd %@",authresult,errorMsg);
}];

Step 2. Configuration Panel Resource Path

The beauty data and icon assets on the beauty panel are available in beauty_panel.zip. As per the API documentation, you may pass the corresponding JSON file path and customize the settings according to your specific requirements.
- (void)configPanel {
NSBundle *bundle = [NSBundle mainBundle];
NSString *beautyJsonPath = [bundle pathForResource:@"beauty" ofType:@"json"]; //Beauty
NSString *lutJsonPath = [bundle pathForResource:@"lut" ofType:@"json"]; //filter
NSString *motion2dJsonPath = [bundle pathForResource:@"motion_2d" ofType:@"json"]; //2D stickers
NSMutableArray *resArray = [[NSMutableArray alloc] init];
[resArray addObject:@{TEUI_BEAUTY : beautyJsonPath}];
[resArray addObject:@{TEUI_LUT : lutJsonPath}];
[resArray addObject:@{TEUI_MOTION_2D : motion2dJsonPath}];
/// Set up resources
[[TEUIConfig shareInstance] setTEPanelViewResources:resArray];
}
JSON files included in each package
Package
JSON
A1-00
beauty.json 、lut.json
A1-01
beauty.json 、beauty_image.json、beauty_base_shape.json、lut.json
A1-02
beauty.json 、beauty_image.json、beauty_base_shape.json、lut.json、motion_2d.json
A1-03
beauty.json 、beauty_image.json、beauty_general_shape.json、lut.json、motion_2d.json
A1-04
beauty.json 、beauty_image.json、beauty_general_shape.json、lut.json
A1-05
beauty.json 、beauty_image.json、beauty_base_shape.json、lut.json、motion_2d.json、segmentation.json
A1-06
beauty.json 、beauty_image.json、beauty_base_shape.json、lut.json、motion_2d.json、 makeup.json
S1-00
beauty.json 、beauty_image.json、beauty_shape.json、beauty_makeup.json、lut.json
S1-01
beauty.json 、beauty_image.json、beauty_shape.json、beauty_makeup.json、lut.json、motion_2d.json、motion_3d.json、(makeup.json & light_makeup.json)
S1-02
beauty.json 、beauty_image.json、beauty_shape.json、beauty_makeup.json、lut.json、motion_2d.json、motion_3d.json、(makeup.json & light_makeup.json)、motion_gesture.json
S1-03
beauty.json 、beauty_image.json、beauty_shape.json、beauty_makeup.json、lut.json、motion_2d.json、motion_3d.json、(makeup.json & light_makeup.json)、 segmentation.json
S1-04
beauty.json 、beauty_image.json、beauty_shape.json、beauty_makeup.json、lut.json、motion_2d.json、motion_3d.json、(makeup.json & light_makeup.json)、motion_gesture.json、segmentation.json
S1-07
beauty.json 、beauty_image.json、beauty_shape.json、beauty_makeup.json、lut.json、motion_2d.json、motion_3d.json、(makeup.json & light_makeup.json)、motion_gesture.json、segmentation.json、beauty_body.json
Attention:
The beauty template file (beauty_template.json) contains a set of preset beauty attributes, enabling one-click switching of makeup effects. This feature is available for the S1 series plans.

Step 3. Initialize and incorporate TEPanelView

TEPanelView is a custom panel view used to display the data configured in Step 2.
- (void)addPanelView {
TEPanelView *tePanelView = [[TEPanelView alloc] init];
tePanelView.delegate = self;
[self.view addSubview:tePanelView];
[tePanelView mas_makeConstraints:^(MASConstraintMaker *make) {
make.width.bottom.mas_equalTo(self.view);
make.left.right.mas_equalTo(self.view);
make.height.mas_equalTo(230 + self.view.safeAreaInsets.bottom);
}];
}

Step 4. Initialize the beauty filter object

1. Initialization
- (void)initXMagic {
__weak __typeof(self)weakSelf = self;
[TEBeautyKit createXMagic:EFFECT_MODE_PRO onInitListener:^(TEBeautyKit * _Nullable beautyKit) {
__strong typeof(self)strongSelf = weakSelf;
strongSelf.teBeautyKit = beautyKit;
strongSelf.tePanelView.teBeautyKit = strongSelf.teBeautyKit;
[strongSelf.tePanelView setDefaultBeauty];
}];
}
2. Processing video data
#pragma mark AVCaptureVideoDataOutputSampleBufferDelegate
- (void)captureOutput:(AVCaptureOutput *)captureOutput didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer fromConnection:(AVCaptureConnection *)connection {
if (captureOutput == self.videoDataOutput) {
[self mycaptureOutput:captureOutput didOutputSampleBuffer:sampleBuffer fromConnection:connection originImageProcess:YES];
}
}

- (void)mycaptureOutput:(AVCaptureOutput *)captureOutput didOutputSampleBuffer:(CMSampleBufferRef)inputSampleBuffer fromConnection:(AVCaptureConnection *)connection originImageProcess:(BOOL)originImageProcess {
CVPixelBufferRef pixelBuffer = CMSampleBufferGetImageBuffer(inputSampleBuffer);
YTProcessOutput *output = [self.teBeautyKit processPixelData:pixelBuffer
pixelDataWidth:(int)CVPixelBufferGetWidth(pixelBuffer)
pixelDataHeight:(int)CVPixelBufferGetHeight(pixelBuffer)
withOrigin:YtLightImageOriginTopLeft
withOrientation:YtLightCameraRotation0];
if (output.pixelData.data != nil) {
/// Output video data, render or other processing
}
if (output != nil) {
output.pixelData = nil;
output = nil;
}
}
3. Destroy Beauty Filter
- (void)destroyXMagic {
[self.teBeautyKit onDestroy];
self.teBeautyKit = nil;
}

Step 5: Export beauty parameters

Supports real-time export of beauty parameters during use; must be called before destruction.
/// export
- (void)exportEffectData {
self.exportBeautyString = [self.teBeautyKit exportInUseSDKParam];
NSLog(@"%@",self.exportBeautyString);
[[NSUserDefaults standardUserDefaults] setObject:self.exportBeautyString forKey:kExportEffectData];
}
/// set
- (void)setExportEffectData {
self.exportBeautyString = [[NSUserDefaults standardUserDefaults] objectForKey:kExportEffectData];
if (self.exportBeautyString) {
[self.tePanelView setExportParamList:self.exportBeautyString];
}
}

Appendix

Panel JSON File Description

JSON Description
Documentation
Explanation
beauty.json
Beauty Configuration File
beauty_body.json
Beauty Profile Configuration
beauty_image.json
Image Quality Adjustment Configuration File
beauty_makeup.json
Single-point Makeup Configuration File
beauty_shape.json
Premium Styling Configuration File
beauty_template.json
Beauty Filter Template Configuration File
light_makeup.json
Light Makeup Configuration File
lut.json
Filter configuration file.
Note: Since different clients utilize distinct filter assets, customers may customize the configuration according to the JSON structure after downloading.
makeup.json
Style Makeup Configuration File.
Note: Since different clients utilize distinct style makeup materials, customers may customize the configuration according to the JSON structure after downloading.
motion_2d.json
2D Animation Sticker Configuration File.
Note: Since different clients may utilize varying animation sticker materials, after downloading, clients can customize the configuration according to the JSON structure.
motion_3d.json
3D animated sticker configuration file.
Note: Since different clients may utilize varying animated sticker materials, customers can customize the configuration according to the JSON structure after downloading.
motion_gesture.json
Gesture animation sticker configuration file.
Note: Since different clients may use varying animation sticker materials, customers can customize the configuration according to the JSON structure after downloading.
segmentation.json
Background Segmentation (Virtual Background) Configuration File.
Note: As different clients utilize distinct segmentation materials, customers may customize the configuration according to the JSON structure after downloading.
panel_icon
This directory is designated for storing images configured in JSON files, which must be added.
Beauty, Body Shaping.

Field
Description
displayName
Chinese Name.
displayNameEn
English Name.
icon
Image address, supports setting local images and network images. Local images support assets resources and SD resources. Assets images are as shown in the image above. For SD card images, set the full path of the image. For network images, set the corresponding HTTP link.
sdkParam
The effect SDK requires four properties. Refer to the Effect Parameters table.
effectName
Effect attribute key, refer to the Effect Parameters table.
effectValue
Setting the attribute intensity, refer to the Effect Parameters table.
resourcePath
Setting the resource path, refer to the Effect Parameters table.
extraInfo
Setting other information, refer to the Effect Parameters table.
Filters, Animated Stickers and Segmentation.

Since the configuration of Filters, Animated Stickers and Segmentation is primarily identical, the JSON for filters is used here for illustration. The fields downloadPath and resourceUri are added here.
Field
Description
downloadPath
If your filter material is downloaded from the network, then the configuration here is the location of your material stored locally after download, which is a relative path, and the full path is set in TEDownloader.h using basicPath+the path set here.
resourceUri
If your material needs to be downloaded via network, configure the network address here, as in the third red box in the image above. However, if your filter material is local, configure the corresponding local address according to the figure above.
Makeup

In the Makeup, the makeupLutStrength field is added under extraInfo. This field is used to adjust the strength of the filter in the makeup material (if this makeup material supports adjusting the filter strength, configure it accordingly). This field can be referenced in the Effect Parameters table.

TEBeautyKit Method Descriptions

/// Creates a TEBeautyKit object
/// - Parameters:
/// - effectMode: EFFECT_MODE_NORMAL (High-performance mode) or EFFECT_MODE_PRO (Default mode)
/// When high-performance mode is enabled, the beauty features consume fewer system CPU/GPU resources, reducing phone overheating and lag; this mode is better suited for prolonged use on low-end devices.
/// Note: When high-performance mode is enabled, the following beauty features will be unavailable:
/// 1. Eyes: Eye width, eye height, eye bag removal
/// 2. Eyebrows: Angle, spacing, height, length, thickness, arch
/// 3. Mouth: Smile lips
/// 4. Face: Face slimming (Natural, Goddess, Handsome), jawline slimming, wrinkle removal, nasolabial fold removal. It is recommended to use the "Face Shape" feature to achieve comprehensive eye-enlarging and face-slimming effects.
/// - onInitListener: Callback
+ (void)createXMagic:(EffectMode)effectMode onInitListener:(OnInitListener _Nullable)onInitListener;

/// Beauty feature authorization
+ (void)setTELicense:(NSString *_Nullable)url key:(NSString *_Nullable)key completion:(callback _Nullable)completion;

/// Sets the beauty object
- (void)setXMagicApi:(XMagic *_Nullable)xmagicApi;

/// Sets the render size
- (void)setRenderSize:(CGSize)size;

/// Sets the image orientation
- (void)setImageOrientation:(YtLightDeviceCameraOrientation)orientation;

/// Gets the current GL context interface
- (nullable EAGLContext*)getCurrentGlContext;

/// Mutes audio
- (void)setMute:(BOOL)isMute;

/// Enables or disables a feature
- (void)setFeatureEnableDisable:(NSString *_Nullable)featureName enable:(BOOL)enable;

/// Sets the frame synchronization mode
/// @isSync Whether synchronization is enabled
/// @syncFrameCount The number of synchronized frames. -1 indicates no limit. If `isSync` is `false`, this parameter is ignored.
- (void)setSyncMode:(BOOL)isSync syncFrameCount:(int)syncFrameCount;

/// Gets the device level.
+ (DeviceLevel)getDeviceLevel;

/// Applies beauty effects to a UIImage.
- (UIImage *_Nullable)processUIImage:(UIImage *_Nullable)inputImage
imageWidth:(int)imageWidth
imageHeight:(int)imageHeight
needReset:(bool)needReset;

/// Processes a texture.
/// - Parameters:
/// - textureId: Texture ID.
/// - textureWidth: Texture width.
/// - textureHeight: Texture height.
/// - origin: Enum value; setting this to `YtLightImageOriginBottomLeft` flips the image vertically.
/// - orientation: Enum value; image rotation angle.
- (YTProcessOutput *_Nullable)processTexture:(unsigned int)textureId
textureWidth:(int)textureWidth
textureHeight:(int)textureHeight
withOrigin:(YtLightImageOrigin)origin
withOrientation:(YtLightDeviceCameraOrientation)orientation;

/// Processes a CVPixelBufferRef.
/// - Parameters:
/// - pixelData: Image data.
/// - pixelDataWidth: Image width.
/// - pixelDataHeight: Image height.
/// - origin: Enum value; setting this to `YtLightImageOriginBottomLeft` flips the image vertically.
/// - orientation: Enum value; image rotation angle.
- (YTProcessOutput * _Nullable)processPixelData:(CVPixelBufferRef _Nullable )pixelData
pixelDataWidth:(int)pixelDataWidth
pixelDataHeight:(int)pixelDataHeight
withOrigin:(YtLightImageOrigin)origin
withOrientation:(YtLightDeviceCameraOrientation)orientation;

/// Sets beauty effects.
- (void)setEffect:(TESDKParam *_Nullable)sdkParam;

/// Sets beauty effects.
- (void)setEffectList:(NSArray<TESDKParam *>*_Nullable)sdkParamList;

/// Checks if enhanced beauty mode is enabled.
- (BOOL)isEnableEnhancedMode;

/// Enables or disables enhanced beauty mode.
- (void)enableEnhancedMode:(BOOL)enable;

/// Resumes.
- (void)onResume;

/// Pause
- (void)onPause;

/// Destroy
- (void)onDestroy;

// Get the image from the current texture
- (void)exportCurrentTexture:(void (^_Nullable)(UIImage * _Nullable image))callback;

/// Set log listener
- (void)registerSDKLogListener:(id<YTSDKLogListener> _Nullable)listener level:(YtSDKLoggerLevel)level;

/// Register SDK event listener
- (void)registerSDKEventListener:(id<YTSDKEventListener> _Nullable)listener;

/// Save configured beauty parameters
- (void)saveEffectParam:(TESDKParam *_Nonnull)sdkParam;

/// Delete specific saved beauty parameters
- (void)deleteEffectParam:(TESDKParam *_Nonnull)sdkParam;

/// Clear all saved beauty parameters
- (void)clearEffectParam;

/// Set the center-crop ratio for the output texture
- (void)setOutputTextureKeepRatio:(float)ratio;

/// Get the list of beauty parameters currently in use
- (NSMutableArray<TESDKParam *> *_Nonnull)getInUseSDKParamList;

/// Export beauty parameters currently in use
/// Returns a JSON string
- (NSString *_Nullable)exportInUseSDKParam;

/// Set beauty parameters
/// - Parameter params: JSON string
/// To update the panel UI simultaneously, simply call setExportParamList on TEPanelView
- (void)setExportedSDKParam:(NSString *_Nonnull)params;

/// Enable or disable beauty effects
- (void)enableBeauty:(BOOL)enable;

/// Clear registered listeners
- (void)clearListeners;

TEUIConfig Descriptions

/// Colors for the following properties can be modified externally
/// Beauty panel background color
@property (nonatomic, strong) UIColor *panelBackgroundColor;
/// Divider line color
@property (nonatomic, strong) UIColor *panelDividerColor;
/// Selected item color
@property (nonatomic, strong) UIColor *panelItemCheckedColor;
/// Text color
@property (nonatomic, strong) UIColor *textColor;
/// Selected text color
@property (nonatomic, strong) UIColor *textCheckedColor;
/// Progress bar color
@property (nonatomic, strong) UIColor *seekBarProgressColor;
/// Sets the language for displaying names; default is YES (display displayName field), NO (display displayNameEn field)
@property (nonatomic, assign) BOOL useDisplayName;
/// Singleton instance
+ (instancetype)shareInstance;
/// Sets the panel resource paths
/// - Parameter resources: List of resource paths
/// e.g. @[@{TEUI_BEAUTY : @"json file path"}]
- (void)setTEPanelViewResources:(NSArray<NSDictionary *> *)resources;
/// Gets the panel resource paths
- (NSArray<NSDictionary *> *)getTEPanelViewResources;
/// Sets the LightCore.bundle path
- (void)setLightCoreBundlePath:(NSString *)corePath;
/// Gets the LightCore.bundle path
- (NSString *)getLightCoreBundlePath;
/// Sets the Resources bundle path
- (void)setResourcesBundlePath:(NSString *)resPath;
/// Gets the Resources bundle path
- (NSString *)getResourcesBundlePath;

TEPanelView Description

/// Beauty SDK object
@property (nonatomic, weak) XMagic *beautyKitApi;
/// beautyKit object
@property (nonatomic, strong) TEBeautyKit *teBeautyKit;
/// Delegate
@property (nonatomic, weak) id<TEPanelViewDelegate> delegate;
/// Set exported beauty parameters
- (void)setExportParamList:(NSString *)lastParamList;
/// Set default beauty settings
- (void)setDefaultBeauty;
/// Reset all effects
- (void)performFullReset;
/// Enhanced mode
- (void)setEnhancedMode:(BOOL)enhancedMode;
/// Show comparison button
- (void)isShowCompareBtn:(BOOL)isShow;

Configuring Multilingual Support

Panel language settings consist of two parts: system text and panel item names.
1. System Text
System text is located in the Localizable.strings file under Assets.
Default supported languages: Simplified Chinese, English.
To add other languages:
Create a Localizable.strings file in your project (or simply add the new language if the file already exists).
Add the new language under "Localizations" in the PROJECT list.
Translate the text content within TEBeautyKit.
2. Panel Item Names
Panel item names are defined in a JSON configuration file and controlled by the following two fields:
Field
Default Language
displayName
Simplified Chinese
displayNameEn
English
Switching between Chinese and English:
// Display Chinese (uses the displayName field)
[[TEUIConfig shareInstance] setUseDisplayName:YES];
// Display English (uses the displayNameEnField)
[[TEUIConfig shareInstance] setUseDisplayName:NO];
Adding other languages:
Copy the original JSON file and create a version for the target language (e.g., `panel_zh_hant.json` for Traditional Chinese).
Translate the value of the `displayName` field into the target language.
Detect the current system language in your code and load the corresponding JSON file.
Call `[[TEUIConfig shareInstance] setUseDisplayName:YES]`.

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback