Premium SDK For IOS

Last updated: 2025-02-06 15:37:01

Note:
The current page is the development documentation for version v2.x.x SDK.
The offline and online SDK includes the features of the online SDK. For the online part, please refer to the development documentation for version v2.x.x online SDK.

Developer

Development Preparation

The device authorization method requires the mobile phone to be connected to a network (3G/4G/5G or Wi-Fi network, etc.).
iOS emulator is not supported.
iOS 11.0 and earlier systems are not supported.

Downloading and Installing SDK

Please refer to Authorization Activation and follow the instructions to activate and download the SDK file.

Importing SDK

The QCloudTTS.framework in the SDK folder is the SDK. Import <QCloudTTS/QCloudTTSEngine.h> and <QCloudTTS/QCloudMediaPlayer.h> to call the related SDK APIs.

Configuring Privacy Agreement

According to the Apple Privacy Policy, applications integrating the SDK need to complete the clauses in the PrivacyInfo.xcprivacy of the Xcode project. If it is not present in the project, you need to create a PrivacyInfo.xcprivacy file using Xcode 15 or above, following the official documentation, and add the privacy clauses required by the SDK as follows:
1. Select PrivacyInfo.xcprivacy in Xcode.
2. Add the Privacy Accessed API Types clause to PrivacyInfo.xcprivacy, configured as shown below:




API Description

Obtain a tts synthesizer instance

// Get the instance
QCloudTTSEngine *ttsEngine = [QCloudTTSEngine getShareInstance];

// Terminate instance
[QCloudTTSEngine instanceRelease];

Initialization engine

-(void) engineInit:(TtsMode)mode Delegate:(id<QCloudTTSEngineDelegate> _Nonnull) delegate;
TtsMode: TTS synthesizer working mode parameter (if the compressed package you downloaded is "xxx_mixed_*.zip", the following three modes are supported; if it is "xxx_online.zip", only the online mode is supported)
Error Example
Description
TTS_MODE_OFFLINE
Offline
TTS_MODE_ONLINE
Online
TTS_MODE_MIX
Mixed
QCloudTTSEngineDelegate: TTS synthesizer proxy for obtaining mix results.

Online mode parameter configuration (not required if not used)

QCloudTTSEngine configuration parameter method
API
Description
setOnlineAuthParam:(NSInteger)appId SecretId:(NSString* _Nonnull)secretId SecretKey:(NSString* _Nonnull)secretKey Token:(NSString* _Nullable)token
appid: Configure Tencent Cloud appid, SecretId, SecretKey, Token (token can be null. If using STS temporary credentials, both secretId and secretKey should be temporary, and the corresponding token is also required)
setOnlineVoiceSpeed:(float)voiceSpeed;
Set the speech speed of the synthetic audio online. Range: [-2, 2], corresponding to different speeds: -2 represents 0.6x, -1 represents 0.8x, 0 represents 1.0x (default), 1 represents 1.2x, 2 represents 1.5x. For more refined speeds, you can keep up to 2 decimal places, such as 0.5/1.25/2.81, etc.
setOnlineVoiceVolume:(float)voiceVolume;
Set the volume of the synthetic audio online, default is 0
setOnlineVoiceLanguage:(int)primaryLanguage;
Main language type: 1-Chinese (default) 2-English
setOnlineCodec:(NSString* _Nonnull) code;
Online mode encoding format, not recommended to change unless necessary: default is mp3, currently supports "mp3", "wav", "pcm". If changed to pcm, playback is not supported.
setOnlineVoiceType:(int)voiceType;
Set the timbre ID for the online synthesized audio. For the complete list of timbre IDs, see Text To Speech.
setTimeoutIntervalForRequest:(int)timeout;
Connection timeout default is 15,000 ms (15s), range [500, 30,000] ms. In Mix mode, it is recommended to reduce this value for a better experience.
setTimeoutIntervalForResource:(int) timeout;
Read timeout default is 30,000 ms (30s), range [2,200, 60,000] ms. In Mix mode, it is recommended to reduce this value for a better experience.
Example

[ttsEngine setOnlineAuthParam:123 SecretId:@"AK**Hp7" SecretKey:@"D9*c2" Token:nil];
[ttsEngine setOnlineVoiceSpeed:1.0];
[ttsEngine setOnlineVoiceType:1001];
[ttsEngine setOnlineVoiceLanguage:1];
[ttsEngine setOnlineVoiceVolume:0];
[ttsEngine setTimeoutIntervalForRequest:15 *1000];
[ttsEngine setTimeoutIntervalForResource:30 *1000];


Offline mode parameter configuration (not required if not used)

TtsController offline authorization configuration
Device-based authorization
Parameter
Description
lic_pk
The corresponding licPk for the key can be obtained from the Tencent Cloud official website or issued offline by Tencent Cloud business.
lic_key
The corresponding licKey for the key can be obtained from the Tencent Cloud official website or issued offline by Tencent Cloud business.
secret_id
Tencent Cloud secretId (may not be the same account as the online mode, you need to enter the secretId of the account that purchased the offline SDK)
secret_key
Tencent Cloud secretKey (may not be the same account as the online mode, you need to enter the secretKey of the account that purchased the offline SDK)
Token
Can be empty. If using sts temporary certificate authentication, both secretId and secretKey should be temporary, and the corresponding token should also be provided.
RefreshAuth
Whether to force online refresh authorization (NO: only activate and download the authorization file the first time online; YES: refresh the authorization file online, activation will fail without a network)
Example
NSString* secret_id = @"************************************";
NSString* secret_key =@"***************************";
NSString* lic_key = @"*******";
NSString* lic_pk = @"*******";
[tts setOfflineAuthParamDoOnline:lic_pk LicKey:lic_key SecretId:secret_id SecretKey:secret_key Token:nil RefreshAuth:NO];
Application-based authorization
API
Description
lic
Authorization key, please obtain it from the Tencent Cloud official website or issued offline by Tencent Cloud business.
lic_sign
The licSign corresponding to the key, please obtain it from the Tencent Cloud official website or issued offline by Tencent Cloud business.
lic_pk
The licPk corresponding to the key, please obtain it from the Tencent Cloud official website or issued offline by Tencent Cloud business.
Example
NSString* lic_pk = @"hg93NdFojA**********v2Yh/M2BO";
NSString* lic = @"ZZ+MfsW*********HTXbt4=";
NSString* lic_sign = @"xK/7******w6CKE=";
[tts setOfflineAuthParamDoOffline:lic LicPk:lic_pk LicSign:lic_sign];
TtsController Configuration Parameter Method
API
Description
setOfflineVoiceVolume:(float) voiceVolume
Offline volume > 0
setOfflineVoiceSpeed:(float) voiceSpeed
Offline speech speed [0.5, 2.0]
setOfflineResourceDir:(NSString * _Nonnull) resourceDir
Set the path where the offline model resource is located
setOfflineVoiceType:(NSString * _Nonnull) voiceType
Offline voice name, the name configuration is located in the voice resource directory\voices\config.json. You can delete or add voices yourself. Voices need authorization, and an error will occur if the corresponding voice is not authorized for synthesis. You can contact Tencent Cloud for purchase. The default is as follows (Offline voice name - Voice name) M206 - Zhihao db1 - Zhiling db3 - Zhimeng db7 - Zhitian f0 - Zhili f2 - Zhiyun femozhifou - Zhirong fn - Zhiyu kefu - Zhimei kefu2 - Zhina kefu3 - Zhiqi m0 - Zhiyun m25 - Zhihua memozhifou - Zhijing newsman - Zhining pb - Zhixiaoyao xiaowei - Zhiyan
Example
NSString *resource_dir = [[NSBundle mainBundle] pathForResource:@"tts_resource" ofType:nil];
[ttsEngine setOfflineResourceDir:resource_dir];
[ttsEngine setOfflineVoiceType:@"pb"];
[ttsEngine setOfflineVoiceSpeed:1.0];
[ttsEngine setOfflineVoiceVolume:1.0];

Hybrid mode parameter configuration (no need to configure if not used)

The hybrid mode provides a strategy to switch between offline synthesis and online synthesis.
In online mode, it will switch to offline mode automatically based on network conditions (the SDK will switch when it detects poor network), and in offline mode, it will attempt to switch back to online mode periodically.
TtsController authorization configuration
Hybrid mode requires both online and offline authorization. Refer to the methods of online mode and offline mode for authorization configuration (both need to be configured).
TtsController Configuration Parameter Method
The configuration of online mode and offline mode will affect the synthesis behavior in the corresponding state under hybrid mode.
The following are specific configurations for hybrid mode that will affect the strategy selection.
API
Description
setCheckNetworkIntervalTime:(int) checkNetworkIntervalTime;
In Mix mode, when the network is connected but a network error or backend error occurs, the detection interval time is used to automatically switch back to online mode from offline mode. The default value is 5 minutes.
Example
[ttsEngine setCheckNetworkIntervalTime:5 * 60];

Synthesis text input parameter API

API
Description
(TtsError *_Nullable) synthesize:(NSString *_Nonnull)text UtteranceId:(NSString *_Nullable)utteranceId;
text is the text to be synthesized; utteranceId is the id marking the text, which will be returned to the host layer with the synthesis result. If not needed, it can be passed as nil.
Example
// There is an internal queue, statements can be continuously added, and the SDK will synthesize them sequentially
TtsError error = nil;
error = [ttsEngine synthesize:@"The weather is nice today".text UtteranceId:@"Sentence 1"];
error = [ttsEngine synthesize:@"Tencent Cloud TTS".text UtteranceId:@"Sentence 2"];
error = [ttsEngine synthesize:@"Tencent Cloud AI".text UtteranceId:@"Sentence 3"];
error = [ttsEngine synthesize:@"Tencent Cloud".text UtteranceId:nil];

// Cancel unsynthesized tasks and clear the internal queue
[ttsEngine cancel];

QCloudTTSEngineDelegate: tts synthesizer agent for obtaining mix result

onSynthesizeData method signature explanation
Parameter
Description
data
Voice data
utteranceId
Sentence id
text
Text
engineType
Engine type 0: online 1: offline
onError method signature description
Parameter
Description
error
Error information, null if no error
utteranceId
Sentence id (if available, return it)
text
Text (if available, return it)
onOfflineAuthInfo method signature description (can be ignored in online mode only)
Parameter
Description
OfflineAuthInfo
Returns offline synthesis module authorization information. When using hybrid or offline mode, you can call the synthesis API only after receiving the successful callback of this method. For details, see QCloudOfflineAuthInfo.h.
Example
-(void) onSynthesizeData:(NSData *_Nullable)data UtteranceId:(NSString *_Nullable)utteranceId Text:(NSString *_Nullable)text EngineType:(NSInteger)type{
// You can save the audio here or send it to the playback API for playing, and call the player input API
}

-(void) onError:(TtsError *_Nullable)error UtteranceId:(NSString *_Nullable)utteranceId Text:(NSString *_Nullable)text{
// You can add error post-processing here
// Note: In actual business, if the backend error code of online composition is returned in hybrid mode, it should be ignored and not processed. The SDK will call offline composition to continue working.
}


- (void)onOfflineAuthInfo:(QCloudOfflineAuthInfo * _Nonnull)OfflineAuthInfo {
// In offline or hybrid mode, this callback must be received after initialization, and the OfflineAuthInfo.err_code must be 0 to call the synthesis API. If err_code is not 0, please check the parameters or network and re-invoke engineInit.
NSString *msg = [NSString stringWithFormat:@"OfflineAuthInfo:err_code=%@,err_msg=%@\n,deviceId=%@\n,expireTime=%@\n,respose=%@",@(OfflineAuthInfo.err_code),OfflineAuthInfo.err_msg,OfflineAuthInfo.deviceId,OfflineAuthInfo.expireTime,OfflineAuthInfo.respose];
NSLog(@"%@",msg);

}



Playback APIs

Initialize the player

If the built-in player of the SDK does not meet your needs, you can also use your own player as a replacement. The demo additionally provides a player source code, which you can modify. The source code is located in MediaPlayerDemo.m, consistent with the built-in player of the SDK.
// Use the player provided in the SDK

QCloudMediaPlayer player = [[QCloudMediaPlayer alloc]init];

//---------QCloudPlayerDelegate---------
// Playback start
-(void) onTTSPlayStart{
NSLog(@"onTTSPlayStart");
}

// All audio in the queue finished playing, audio waiting
-(void) onTTSPlayWait{
NSLog(@"onTTSPlayWait");
}

// Resume playback
-(void) onTTSPlayResume{
NSLog(@"onTTSPlayResume");
}

// Pause and play
-(void) onTTSPlayPause{

NSLog(@"onTTSPlayPause");
}
// Playback stopped
-(void)onTTSPlayStop{
NSLog(@"onTTSPlayStop");
}
// Player exception
-(void)onTTSPlayError:(QCPlayerError* _Nullable)playError{
NSLog(@"playError.code==%@,playError.massage==%@",@(playError.mCode),playError.message);
}

// About to play the next sentence, the corresponding audio sentence, and its utteranceId
-(void) onTTSPlayNextWithText:(NSString* _Nullable)text UtteranceId:(NSString* _Nullable)utteranceId{
NSLog(@"text==%@,utteranceId==%@",text,utteranceId);
}

// Current character being played, index of the character in the sentence
```markdown
// currentIndex The index of the character being read in the current playing sentence
-(void)onTTSPlayProgressWithCurrentWord:(NSString*_Nullable)currentWord CurrentIndex:(NSInteger)currentIdex{
NSLog(@"CurrentWord==%@,currentIdex==%@",currentWord,@(currentIdex));
}



Player input parameter

Parameter
Description
data
Input audio stream, play by passing in a byte array
url
Input audio file, play by passing the file
String text
Text corresponding to the audio
String utteranceId
Text ID
Example
// Through audio data parameter
QCPlayerError err = [_player enqueueWithData:data Text:text UtteranceId:utteranceId];

// Through audio file parameter
NSString *str = [self filePathWithName:@"tmp.mp3"];
NSURL * url = [NSURL URLWithString:str];
QCPlayerError err = [_player enqueueWithFile:url Text:text UtteranceId:utteranceId];