iOS SDK 基础

最近更新时间:2024-11-07 11:17:42

我的收藏
说明:
当前页面为 v2.x.x 版本 SDK 开发文档
离在线 SDK 包含在线 SDK 功能,在线部分请参考 v2.x.x 版本在线 SDK 开发文档

开发相关

开发准备

按设备授权方式需要手机能够连接网络(3/4/5G 或 Wi-Fi 网络等)。
不支持 iOS 模拟器
不支持 iOS9.0 以下系统

下载安装SDK

请参考开通授权,根据指引开通并下载 SDK 文件

导入SDK

SDK 文件夹内的 QCloudTTS.framework 即为 SDK,引入 <QCloudTTS/QCloudTTSEngine.h> 及 <QCloudTTS/QCloudMediaPlayer.h> 即可调用 SDK 相关接口。

配置隐私协议

根据 苹果隐私政策 规定,集成 SDK 的应用需要在 Xcode 项目的 PrivacyInfo.xcprivacy 中补全条款,若项目中没有,需要根据 官方说明 使用 Xcode 15及以上的版本,新建一个 PrivacyInfo.xcprivacy 文件,参考以下方式,添加 SDK 依赖的隐私条款:
1. 在 Xcode 中选择 PrivacyInfo.xcprivacy
2. Privacy Accessed API Types条款添加到 PrivacyInfo.xcprivacy 中,具体配置如下图:




接口说明

获得 TTS 合成器实例

//获得实例
QCloudTTSEngine *ttsEngine = [QCloudTTSEngine getShareInstance];

//销毁实例
[QCloudTTSEngine instanceRelease];

初始化引擎

-(void) engineInit:(TtsMode)mode Delegate:(id<QCloudTTSEngineDelegate> _Nonnull) delegate;
TtsMode: TTS 合成器工作模式参数(如果您下载的压缩包为"xxx_mixed_*.zip",则支持以下三种模式,如果为"xxx_online.zip",则仅支持在线模式)
枚举
说明
TTS_MODE_OFFLINE
离线
TTS_MODE_ONLINE
在线
TTS_MODE_MIX
混合
QCloudTTSEngineDelegate: TTS 合成器代理,用于获取合成结果

在线模式参数配置(不使用则不需要配置)

QCloudTTSEngine 配置参数方法
接口
说明
setOnlineAuthParam:(NSInteger)appId SecretId:(NSString* _Nonnull)secretId SecretKey:(NSString* _Nonnull)secretKey Token:(NSString* _Nullable)token
appid:配置腾讯云appid、SecretId、SecretKey、Token( token,可为空,如果使用sts临时证书鉴权,secretId和secretKey均入参临时的,同时需要入参对应的token )
setOnlineVoiceSpeed:(float)voiceSpeed;
设置在线所合成音频的语速,语速,范围:[-2,2],分别对应不同语速:-2代表0.6倍,-1代表0.8倍,0代表1.0倍(默认),1代表1.2倍,2代表1.5倍, 如果需要更细化的语速,可以保留小数点后 2 位,例如0.5/1.25/2.81等。
setOnlineVoiceVolume:(float)voiceVolume;
设置在线所合成音频的音量,默认0
setOnlineVoiceLanguage:(int)primaryLanguage;
主语言类型:1-中文(默认)2-英文
setOnlineCodec:(NSString* _Nonnull) code;
在线模式编码格式,非业务必要不建议更改:默认mp3,目前支持"mp3"\\"wav"\\"pcm",如更改为pcm不支持播放
setOnlineVoiceType:(int)voiceType;
设置在线所合成音频的音色id,完整的音色id列表见 基础语音合成
setTimeoutIntervalForRequest:(int)timeout;
连接超时默认15000ms(15s) 范围[500,30000] 单位ms , Mix模式下建议调小此值,以获得更好的体验
setTimeoutIntervalForResource:(int) timeout;
读取超时默认30000ms(30s) 范围[2200,60000] 单位ms, Mix模式下建议调小此值,以获得更好的体验
示例

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

离线线模式参数配置(不使用则不需要配置)

TtsController 离线授权配置
按设备授权
参数
说明
lic_pk
密钥对应的 licPk,请在腾讯云官网页面获取,或者由腾讯云商务线下下发
lic_key
密钥对应的 licKey,请在腾讯云官网页面获取,或者由腾讯云商务线下下发
secret_id
腾讯云 secretId (可能与在线模式不是同一个账号,需要输入购买离线 SDK 对应的账号的 secretId)
secret_key
腾讯云 secretKey(可能与在线模式不是同一个账号,需要输入购买离线 SDK 对应的账号的 secretKey)
Token
可为空,如果使用sts临时证书鉴权,secretId 和 secretKey 均入参临时的,同时需要入参对应的 token
示例
NSString* secret_id = @"************************************";
NSString* secret_key =@"******************";
NSString* lic_key = @"*******";
[tts setOfflineAuthParamDoOnline:lic_pk LicKey:lic_key SecretId:secret_id SecretKey:secret_key Token:nil];
按应用授权
接口
说明
lic
授权密钥 ,请在腾讯云官网页面获取,或者由腾讯云商务线下下发
lic_sign
该密钥对应的 licSign,请在腾讯云官网页面获取,或者由腾讯云商务线下下发
lic_pk
该密钥对应的 licPk,请在腾讯云官网页面获取,或者由腾讯云商务线下下发
示例
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 配置参数方法
接口
说明
setOfflineVoiceVolume:(float) voiceVolume
离线音量 > 0
setOfflineVoiceSpeed:(float) voiceSpeed
离线语速[0.5,2.0]
setOfflineResourceDir:(NSString * _Nonnull) resourceDir
设置离线模型资源所在路径
setOfflineVoiceType:(NSString *_Nonnull)  voiceType
离线音色名称,名称配置位于音色资源目录\\voices\\config.json 中,可自行指定更多的音色,demo中仅提供"pb"、"femalen"两种
示例
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];

混合模式参数配置(不使用则不需要配置)

混合模式提供一种策略会在离线合成和在线合成之间进行切换
在线模式下根据网络情况会切换自动离线模式(SDK 判断网络较差时会切换),离线模式下每隔一段时间会尝试切回在线模式
TtsController 授权配置
混合模式需要在线和离线均有授权,授权配置参照在线模式与离线模式的方法(两个都需要配置)
TtsController 配置参数方法
在线模式配置和离线模式配置会影响混合模式下处于相应状态时合成行为
以下为混合模式特有配置会影响策略的选择
接口
说明
setCheckNetworkIntervalTime:(int) checkNetworkIntervalTime;
Mix模式下,已经连接网络,但出现网络错误或者后台错误后的检测间隔时间,用于从离线模式自动切换回在线模式,默认值5分钟
示例
[ttsEngine setCheckNetworkIntervalTime:5 * 60];

合成文本入参接口

接口
说明
(TtsError *_Nullable) synthesize:(NSString *_Nonnull)text UtteranceId:(NSString *_Nullable)utteranceId;
text为需要合成的文本;utteranceId为标记该文本的id, 将随合成结果返回宿主层,业务不需要可传nil
示例
//内部有维护队列,可持续添加语句,SDK内将依次合成
TtsError error = nil;
error = [ttsEngine synthesize:@"今天天气不错".text UtteranceId:@"第1句"];
error = [ttsEngine synthesize:@"腾讯云语音合成".text UtteranceId:@"第2句"];
error = [ttsEngine synthesize:@"腾讯云AI".text UtteranceId:@"第3句"];
error = [ttsEngine synthesize:@"腾讯云".text UtteranceId:nil];

//取消未合成的任务并清空内部队列
[ttsEngine cancel];

QCloudTTSEngineDelegate: TTS 合成器代理,用于获取合成结果

onSynthesizeData 方法签名说明
参数
说明
data
语音数据
utteranceId
语句id
text
文本
engineType
引擎类型 0:在线 1:离线
onError 方法签名说明
参数
说明
error
错误信息,无错误返回null
utteranceId
语句id(如果有则返回)
text
文本(如果有则返回)
onOfflineAuthInfo 方法签名说明(仅用在线模式可忽略)
参数
说明
OfflineAuthInfo
返回离线合成模块授权信息,使用混合或者离线模式时,收到此方法成功回调后才可以调用合成接口,详细说明详见QCloudOfflineAuthInfo.h
示例
-(void) onSynthesizeData:(NSData *_Nullable)data UtteranceId:(NSString *_Nullable)utteranceId Text:(NSString *_Nullable)text EngineType:(NSInteger)type{
// 您可以在这里将音频保存或者送入播放接口播放,可调用播放器入参接口入参
}

-(void) onError:(TtsError *_Nullable)error UtteranceId:(NSString *_Nullable)utteranceId Text:(NSString *_Nullable)text{
// 您可以在这里添加错误后处理
//注:实际业务上判断一下,如果是混合模式下返回在线合成的后端错误码,应当忽略,可不做处理,SDK内会调用离线合成继续工作
}


- (void)onOfflineAuthInfo:(QCloudOfflineAuthInfo * _Nonnull)OfflineAuthInfo {
//离线或者混合模式下,调用初始化后必须收到此回调,并且OfflineAuthInfo.err_code为0时,才可以调用合成接口,如果err_code不为0,请检查参数或者网络,并重新调用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);

}



播放接口

初始化播放器

如果 sdk 的内置播放器无法满足您的需求,您也可以使用自己实现的播放器替换。demo 中也额外提供了一份播放器源码,您可以修改播放器逻辑,源代码位于MediaPlayerDemo.m,与 SDK 内置播放器一致。
//使用SDK中提供的播放器

QCloudMediaPlayer player = [[QCloudMediaPlayer alloc]init];

//---------QCloudPlayerDelegate---------
//播放开始
-(void) onTTSPlayStart{
NSLog(@"onTTSPlayStart");
}

//队列所有音频播放完成,音频等待中
-(void) onTTSPlayWait{
NSLog(@"onTTSPlayWait");
}

//恢复播放
-(void) onTTSPlayResume{
NSLog(@"onTTSPlayResume");
}

//暂停播放
-(void) onTTSPlayPause{

NSLog(@"onTTSPlayPause");
}
//播放中止
-(void)onTTSPlayStop{
NSLog(@"onTTSPlayStop");
}
//播放器异常
-(void)onTTSPlayError:(QCPlayerError* _Nullable)playError{
NSLog(@"playError.code==%@,playError.massage==%@",@(playError.mCode),playError.message);
}

//即将播放播放下一句,即将播放音频对应的句子,以及这句话utteranceId
-(void) onTTSPlayNextWithText:(NSString* _Nullable)text UtteranceId:(NSString* _Nullable)utteranceId{
NSLog(@"text==%@,utteranceId==%@",text,utteranceId);
}

// 当前播放的字符,当前播放的字符在所在的句子中的下标.
// currentWord 当前读到的单个字,是一个估算值不一定准确
// currentIdex 当前播放句子中读到文字的下标
-(void)onTTSPlayProgressWithCurrentWord:(NSString*_Nullable)currentWord CurrentIndex:(NSInteger)currentIdex{
NSLog(@"CurrentWord==%@,currentIdex==%@",currentWord,@(currentIdex));
}



播放器入参

参数
说明
data
入参音频流,通过传入字节数组播放
url
入参音频文件,通过传入文件播放
String text
音频对应的文本
String utteranceId
文本id
示例
//通过音频数据入参
QCPlayerError err = [_player enqueueWithData:data Text:text UtteranceId:utteranceId];

//通过音频文件入参
NSString *str = [self filePathWithName:@"tmp.mp3"];
NSURL * url = [NSURL URLWithString:str];
QCPlayerError err = [_player enqueueWithFile:url Text:text UtteranceId:utteranceId];