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:
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)
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.
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)
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
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.
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.
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"];
// 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.
// 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.
// 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.
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