tencent cloud

Tencent Effect SDK

DocumentationTencent Effect SDKSDK Integration Guide（No UI）General Integration of Tencent EffectiOS

iOS

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

Comprehensive Integration Process



Environment requirements

Xcode 11 or later
Recommended runtime environment:
Device requirements: iPhone 5 or later. iPhone 6 and older models support up to 720p for the front camera.
System requirements: iOS 10.0 or later.

Importing the SDK

You can use CocoaPods or download and import the SDK manually into your project.
CocoaPods
Swift Package Manager
Manual import
Dynamic download and integration
1. Install CocoaPods.
Enter the following command in a terminal (you need to install Ruby on your Mac first):
sudo gem install cocoapods
2. Create a Podfile.
Go to the directory of your project and enter the following command to create a Podfile in the directory.
pod init
3. Edit the Podfile.
XMagic version before 3.0.1
Choose an edition for your project and edit the Podfile:
XMagic Standard.
Edit the Podfile as follows:
platform :ios, '9.0'

target 'App' do
pod 'XMagic'
end
XMagic Lite.
The installation package of XMagic Lite is smaller than XMagic Standard. It supports only Basic A1-00, Basic A1-01 and Advanced S1-00. Edit the Podfile as follows:
platform :ios, '9.0'

target 'App' do
pod 'XMagic_Smart'
end
XMagic version 3.0.1 and later:
Choose the appropriate version based on your project package and edit the Podfile file:
#Please install the corresponding library with 'pod install' based on your package
#For example: if your package is of type 'all', then you only need to use pod 'TencentEffect_All'.
#For example: if your package is of type 'S1-04', then you only need to use pod 'TencentEffect_S1-04'.
pod 'TencentEffect_All'
#pod 'TencentEffect_A1-00'
#pod 'TencentEffect_A1-01'
#pod 'TencentEffect_A1-02'
#pod 'TencentEffect_A1-03'
#pod 'TencentEffect_A1-04'
#pod 'TencentEffect_A1-05'
#pod 'TencentEffect_A1-06'
#pod 'TencentEffect_S1-00'
#pod 'TencentEffect_S1-01'
#pod 'TencentEffect_S1-02'
#pod 'TencentEffect_S1-03'
#pod 'TencentEffect_S1-04'
#pod 'TencentEffect_S1-05'
#pod 'TencentEffect_S1-06'
#pod 'TencentEffect_S1-07'
#pod 'TencentEffect_X1-01'
#pod 'TencentEffect_X1-02'
4. Update the local repository and install the SDK.
Enter the following command in a terminal window to update the local repository and install the SDK:
pod install
5. Under the Build Settings tab, add -ObjC to Other Linker Flags.
6. Change the bundle ID to the bundle ID bound to your license.
Starting from version 4.2.0.21, the Beauty Effects SDK supports integration via Swift Package Manager (SPM).
1. Open your Xcode project, select **File > Add Package Dependencies...**, paste the following URL into the search bar, wait for the results to appear, and then click **Add Package**.
For packages A1-00, A1-01, and S1-00, the addresses are as follows:
https://github.com/Tencent-RTC/TencentEffect_Basic_SwiftPM.git

The addresses for the other packages are as follows:
https://github.com/Tencent-RTC/TencentEffect_SwiftPM.git
2. Specify the SDK version and package you wish to integrate in "Choose Package Options."
1. Download the SDK and effect resources and decompress the file. The SDK is in the frameworks folder, and the bundle resources are in resources.
2. If your SDK version is earlier than 2.5.1:
Open your Xcode project and add the frameworks in the frameworks folder to your project: Choose the target to run, select the General tab, expand Frameworks, Libraries, and Embedded Content, and click + to add the frameworks downloaded, including XMagic.framework, YTCommonXMagic.framework, and libpag.framework, as well as MetalPerformanceShaders.framework, CoreTelephony.framework, JavaScriptCore.framework, VideoToolbox.framework, and libc++.tbd. You can also add Masonry.framework (control layout) and SSZipArchive (file decompression) if necessary.

If your SDK version is 2.5.1 or later:
Open your Xcode project and add the frameworks in the frameworks folder to your project: Choose the target to run, select the General tab, expand Frameworks, Libraries, and Embedded Content, and click + to add the frameworks downloaded, including XMagic.framework, YTCommonXMagic.framework, libpag.framework, Audio2Exp.framework, and TEFFmpeg.framework(Renamed to TECodec.framework after version 3.0.0.), as well as MetalPerformanceShaders.framework, CoreTelephony.framework, JavaScriptCore.framework, VideoToolbox.framework, and libc++.tbd. If necessary, you can also add Masonry.framework (control layout) and SSZipArchive (file decompression).

3. Add the effect resources in the resources folder to your project.
4. Under the Build Settings tab, add -ObjC to Other Linker Flags.
5. Change the bundle ID to the bundle ID bound to your license.
To reduce the SDK package size, you can dynamically download the necessary module resources and animated effect resources (MotionRes, not available in some basic editions of the SDK) from a URL and, after download, pass the path of the resources to the SDK.
You can use your existing download service, but we recommend you use the download logic of the demo. For detailed directions on implementing dynamic download, see Reducing SDK Size.

Importing the effect resources

If your package includes dynamic effect and filter features, you need to download the corresponding resources from the SDK Download Page, after unzipping, import the bundles from the `resources/motionRes` folder into any directory of your main project as needed. After importing, it should look like the image below, where `lut.bundle` contains the filter resources and the others contain the animation resources.

For more resources configurations, refer to effect resources usage guide.

Configuring permissions

Add permission descriptions in the Info.plist file. If you don’t do so, the application will crash on iOS 10. Grant the application camera access in Privacy - Camera Usage Description.

Directions

Step 1. Authenticate

1. Apply for a license and get the LicenseURL and LicenseKEY, refer to Activate the Service.
2. Set the URL and key in the initialization code of your business module to download the license. Avoid downloading it just before use. You can also trigger the download in the didFinishLaunchingWithOptions method of AppDelegate (the values of LicenseURL and LicenseKey are generated when you bound the license in the console).
If your SDK version is earlier than 2.5.1, you can find TELicenseCheck.h in XMagic.framework; if your SDK version is 2.5.1 or later, TELicenseCheck.h is in YTCommonXMagic.framework. The SDK can only be used after successful authentication.
[TELicenseCheck setTELicense:LicenseURL key:LicenseKey completion:^(NSInteger authresult, NSString * _Nonnull errorMsg) {
 if (authresult == TELicenseCheckOk) {
     NSLog(@"Authentication successful");
 } else {
     NSLog(@"Authentication failed");
 }
}];
Authentication error codes:
Error Codes
Description
0
Successful.
-1
The input parameter is invalid; for example, the URL or KEY is empty.
-3
Download failed. Check the network settings.
-4
Unable to obtain any Tencent Effect authentication information from the local system, which may be caused by an I/O failure.
-5
The VCUBE TEMP license file is empty, which may be caused by an I/O failure.
-6
The JSON field in the v_cube.license file is incorrect. Please contact Tencent Cloud team for help.
-7
Signature verification failed. Please contact Tencent Cloud team for help.
-8
Decryption failed. Please contact Tencent Cloud team for help.
-9
The JSON field in TELicense is incorrect. Please contact Tencent Cloud team for help.
-10
The Tencent Effect authentication information parsed online is empty. Please contact Tencent Cloud team for help.
-11
Failed to write Tencent Effect SDK authentication information to the local file, which may be caused by an I/O failure.
-12
Download failed, and failed to parse local assets.
-13
Authentication failed.
Others
Please contact Tencent Cloud team for help.

Step 2. Initialize and use the SDK

The following is the process of using the Tencent Effect SDK:
1. Initialize the Tencent Effect SDK.
/// root_path: Pass in the directory where LightCore.bundle is located.
NSDictionary *assetsDict = @{@"core_name" : @"LightCore.bundle",
                             @"root_path" : [[NSBundle mainBundle] bundlePath]};
self.xMagicApi = [[XMagic alloc] initWithRenderSize:previewSize assetsDict:assetsDict];
2. The SDK processes each frame of data and returns the results.
/// Take the device camera data output as an example
/// sampleBuffer：Data output by the device camera
-(CMSampleBufferRef)didProcessCPUData:(CMSampleBufferRef)sampleBuffer{
    CVPixelBufferRef pixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer);
    YTProcessInput *input = [[YTProcessInput alloc] init];
    input.pixelData = [[YTImagePixelData alloc] init];
    input.pixelData.data = pixelBuffer;
    input.dataType = kYTImagePixelData;
    YTProcessOutput *output = [self.xMagicKit process:input];
    if (output.pixelData.data != nil) { //output.pixelData.data：Data processed by Beauty Effect SDK
        CMSampleBufferRef outSampleBuffer = [self sampleBufferFromPixelBuffer:output.pixelData.data];
        return outSampleBuffer;
    }
    return nil;
}

/// PixelBuffer to sampleBuffer
- (CMSampleBufferRef)sampleBufferFromPixelBuffer:(CVPixelBufferRef)pixelBuffer
{
    CFRetain(pixelBuffer);
    CMSampleBufferRef outputSampleBuffer = NULL;
    CMSampleTimingInfo timing = {kCMTimeInvalid, kCMTimeInvalid, kCMTimeInvalid};
    CMVideoFormatDescriptionRef videoInfo = NULL;
    OSStatus result = CMVideoFormatDescriptionCreateForImageBuffer(NULL, pixelBuffer, &videoInfo);
    result = CMSampleBufferCreateForImageBuffer(kCFAllocatorDefault, pixelBuffer, true, NULL, NULL, videoInfo, &timing, &outputSampleBuffer);
    CFArrayRef attachments = CMSampleBufferGetSampleAttachmentsArray(outputSampleBuffer, YES);
    CFMutableDictionaryRef dict = (CFMutableDictionaryRef)CFArrayGetValueAtIndex(attachments, 0);
    CFDictionarySetValue(dict, kCMSampleAttachmentKey_DisplayImmediately, kCFBooleanTrue);
    CFRelease(videoInfo);
    CFRelease(pixelBuffer);
    return outputSampleBuffer;
}
3. Release the Tencent Effect SDK.
/// Called where SDK resources need to be released
[self.xMagicApi deinit]
Note:
After completing the above steps, you can control the display timing and other device environment parameters as needed.

Previous Topic: iOSNext Topic: Android

Help and Support

Was this page helpful?

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

Feedback