# 语音唤醒 iOS SDK 文档

# 1、简介

语音唤醒（ Voice Wakeuper ）通过辨别输入的音频中特定的词语（如“讯飞语点”），返回被命中（唤醒）结果，应用通过回调的结果，进行下一步的处理，如点亮屏幕，或与用户进行语音交互等。唤醒资源中含有一个或多个资源，只要命中其中一个，即可唤醒。需下载使用对应的语音唤醒SDK。

唤醒详细的接口介绍及说明请参考： MSC iOS API 文档 (opens new window) , 在集成过程中如有疑问，可登录 讯飞开放平台论坛 (opens new window) ，查找答案或与其他开发者交流。

# 2、SDK集成指南

# 第一步：获取appid

appid是第三方应用集成讯飞开放平台SDK的身份标识，SDK静态库和appid是绑定的，每款应用必须保持唯一，否则会出现10407错误码。appid在开放平台申请应用时可以获得，下载SDK后可从SDK中sample文件夹的Demo工程里找到（例如: /sample/MSCDemo/MSCDemo/Definition.h 的APPID_VALUE）。

# 第二步：工程配置

# 添加库

将开发工具包中lib目录下的iflyMSC.framework添加到工程中。同时请将Demo中依赖的其他库也添加到工程中。 按下图示例添加 SDK 所需要的 iOS系统库：

注意 ：

1. 添加iflyMSC.framework时，请检查工程BuildSetting中的framwork path的设置，如果出现找不到framework的情况，可以将path清空，在Xcode中删除framework，然后重新添加。
2. iflyMSC.framework最低支持iOS 8.0。

# 设置Bitcode

在Xcode 7,8默认开启了Bitcode，而Bitcode 需要工程依赖的所有类库同时支持。MSC SDK暂时还不支持Bitcode，可以先临时关闭。后续MSC SDK支持Bitcode 时，会在讯飞开放平台上进行SDK版本更新，请关注。关闭此设置，只需在Targets - Build Settings 中搜索Bitcode 即可，找到相应选项，设置为NO。

# 用户隐私权限配置

iOS 10发布以来，苹果为了用户信息安全，加入隐私权限设置机制，让用户来选择是否允许。 隐私权限配置可在info.plist 新增相关privacy字段，MSC SDK中需要用到的权限主要包括麦克风权限、联系人权限和地理位置权限：

<key>NSMicrophoneUsageDescription</key>
<string></string>
<key>NSLocationUsageDescription</key>
<string></string>
<key>NSLocationAlwaysUsageDescription</key>
<string></string>
<key>NSContactsUsageDescription</key>
<string></string>

即在Info.plist 中增加下图设置：

# 第三步：初始化

初始化示例：

//Appid是应用的身份信息，具有唯一性，初始化时必须要传入Appid。
NSString *initString = [[NSString alloc] initWithFormat:@"appid=%@", @"YourAppid"];
[IFlySpeechUtility createUtility:initString];

注意 ： 初始化是一个异步过程，可放在App启动时执行初始化，具体代码可以参照Demo的MSCAppDelegate.m。

# 第四步：启动服务

所有的服务皆遵循如下的流程，如下图：

所有服务的API详细说明可参见：https://www.xfyun.cn/doc/asr/awaken/Android-SDK.html。

# 3、唤醒流程

语音唤醒集成流程如下：

使用示例如下所示：( 注意，启动唤醒需要关注系统录音权限，目前iOS唤醒只支持应用级唤醒。 ）

#import "iflyMSC/IFlyMSC.h"
//获取唤醒单例对象
_iflyVoiceWakeuper = [IFlyVoiceWakeuper sharedInstance];
//设置唤醒协议委托
_iflyVoiceWakeuper.delegate = self;
//设置唤醒参数
//生成唤醒资源路径并设置唤醒资源，唤醒资源需要定制，与唤醒词一一对应。
NSString *resPath = [[NSBundle mainBundle] resourcePath];
NSString *wordPath = [[NSString alloc] initWithFormat:@"%@/ivw/%@.jet",resPath,APPID_VALUE];
NSString *ivwResourcePath = [IFlyResourceUtil generateResourcePath:wordPath];
[_iflyVoiceWakeuper setParameter:ivwResourcePath forKey:@"ivw_res_path"];
//设置唤醒门限值,新唤醒引擎的默认门限制值为1450
//门限设置要和资源中的唤醒词个数匹配，以;分割。
//例如：0:1450，0代表第一个唤醒词 1450，代表第一个唤醒词门限
//根据下载的SDK中的说明来设置。
//0：表示第一个唤醒词，1450表示唤醒词对应的门限值；
//1：表示第二个唤醒词，1450表示唤醒词对应的门限值
[_iflyVoiceWakeuper setParameter:@"0:1450;1:1450;" forKey:@"ivw_threshold"];
//设置唤醒的服务类型，目前仅支持wakeup
[_iflyVoiceWakeuper setParameter:@"wakeup" forKey:@"ivw_sst"];
//设置唤醒的工作模式
//keep_alive表示一次唤醒成功后是否继续录音等待唤醒。1：表示继续；0：表示唤醒终止
[_iflyVoiceWakeuper setParameter:@"1" forKey:@"keep_alive"];
//启动唤醒
int bRet = [self.iflyVoiceWakeuper startListening];
//唤醒实现delegate
//录音开始
-(void) onBeginOfSpeech{}
//录音结束
-(void) onEndOfSpeech{}
//会话错误
-(void) onCompleted:(IFlySpeechError *)error{}
//音量变化回调
- (void) onVolumeChanged: (int)volume{}
//唤醒结果回调
-(void) onResult:(NSMutableDictionary *)resultArray{}

注 ：新唤醒引擎门限的推荐默认值为1450，取值范围为非负数，一般可在0-3000之间调节。

# 4、语音唤醒OneShot

oneshot是唤醒的一种扩展方式，支持唤醒+识别，唤醒+听写，唤醒+语义的组合解决方案。 此处介绍唤醒+识别模式，可以适用于唤醒词数量有限，而命令词又无法常驻运行的场景。在游戏场景下，可采用声控的方式来操控游戏。例如：定义唤醒词为阿里巴巴，定义命令词序列：“打开城门”，“发起攻击”，这样就形成若干命令序列。用户可以说：

• 阿里巴巴打开城门
• 阿里巴巴发起攻击

除了游戏外，用户可以很容易的将唤醒+识别的应用扩展到其他领域，比如家电，车载等比较适合语音的场所。

# 详细demo

唤醒+识别的代码比较复杂，限于篇幅不在本文档描述，详细过程可以参考Demo中的OneshotViewController示例代码。

Demo的示例，用户可以说 叮咚叮咚 + 张三/李四/张海洋 的组合。

# 使用唤醒+识别步骤

# 唤醒+识别回调

//录音开始
- (void) onBeginOfSpeech{}
//录音结束
- (void) onEndOfSpeech{}
//音量回调
- (void) onVolumeChanged: (int)volume{}
//服务结束回调
- (void) onCompleted:(IFlySpeechError *) error{}
//唤醒结果回调
- (void) onResult:(NSMutableDictionary *)resultArray {}
//会话事件回调
- (void) onEvent:(int)eventType isLast:(BOOL)isLast arg1:(int)arg1 data:(NSMutableDictionary *)eventData(){}

# 音频流唤醒

音频流唤醒功能可以让开发者将已录制好的音频数据写入唤醒控件，最后得到唤醒结果。

//设置音频源为音频流（-1）
[self.iflyVoiceWakeuper setParameter:@"-1" forKey:@"audio_source"];
//启动识别服务
[self.iflyVoiceWakeuper startListening];
//写入音频数据
NSData *data = [NSData dataWithContentsOfFile:_pcmFilePath];    //从文件中读取音频
[self.iflyVoiceWakeuper writeAudio:data];//写入音频，让SDK判断是否唤醒。建议将音频数据分段写入。
//音频写入结束或出错时，必须调用结束唤醒接口
[self.iflyVoiceWakeuper stopListening];//音频数据写入完成，进入等待状态

# 闭环优化

闭环优化是针对开发者的唤醒资源由云端优化系统不断优化的功能。通过开发者 APP 使用场景，本地唤醒 SDK 自动挑选音频数据上传至云端，进行训练生成优化唤醒资源。开发者 APP 使用场景中，优化唤醒资源在相比原有资源在提升唤醒率及抑制误唤醒方面有良好的表现。持续优化包含两种网络模式：

• 模式 0：关闭优化功能，禁止向服务端发送本地挑选数据；
• 模式 1：开启优化功能，允许向服务端发送本地挑选数据；

// 设置开启优化功能
[self.iflyVoiceWakeuper setParameter:@"1" forKey:@"ivwnet_mode"];

# 5、视频教程

视频教程 (opens new window)

视频课程，快速入门。

# 6、常见问题

# 语音唤醒sdk如何下载试用？

答：文档中心--- 快速指引 (opens new window) 有介绍步骤---根据步骤下载相应平台的语音唤醒sdk，语音唤醒SDK包有10个装机量，试用期为90天。

# 语音唤醒支持什么平台？

答：语音唤醒目前支持：Android/iOS/Windows/Linux应用平台。

# 语音唤醒支持什么语言？

答：目前支持中文和英文。唤醒词设置最多支持8个，每个为4-6个汉字或不超过2个英文单词。中英文不可同时配置。

# 语音唤醒的主要功能有什么？

答：设备(手机、玩具、家电等)在休眠或锁屏状态下也能检测到用户的声音(设定的语音指令，即唤醒词)，让处于休眠状态下的设备直接进入到等待指令状态，开启语音交互第一步。

# 如何购买语音唤醒？

答：登录讯飞开放平台，点击进入语音唤醒页面，点击到语音唤醒页面，可查看到详细的价格表。点击对应套餐包的“立即购买”，可进行支付购买。