|
欢迎使用iFLY Mobile Speech Platform 2.0讯飞移动语音平台！
iFLY Mobile Speech Platform 2.0讯飞移动语音平台是基于讯飞公司已有的ISP和IMS产品，开发出的一款符合移动互联网用户使用的语音应用开发平台，提供语音合成、语音听写、语音 识别、声纹识别等服务，为语音应用开发爱好者提供方便易用的开发接口，使得用户能够基于该开发接口进行多种语音应用开发。其主要功能有： 1) 实现基于HTTP协议的语音应用服务器，集成讯飞公司最新的语音引擎，支持语音合成、语音听写、语音识别、声纹识别等服务； 2) 提供基于移动平台和PC上的语音客户端子系统，内部集成音频处理和音频编解码模块，提供关于语音合成、语音听写、语音识别和声纹识别完善的API。 科大讯飞作为中国最大的智能语音技术提供商，在智能语音技术领域有着长期的研究积累，并在语音合成、语音识别、口语评测等多项技术上拥有国际领先的成果。 科大讯飞是我国唯一以语音技术为产业化方向的“国家863计划成果产业化基地”、“国家规划布局内重点软件企业”、“国家火炬计划重点高新技术企业”、 “国家高技术产业化示范工程”，并被信息产业部确定为中文语音交互技术标准工作组组长单位，牵头制定中文语音技术标准。2003年，科大讯飞获迄今中国语 音产业唯一的“国家科技进步二等奖”，2005年获中国信息产业自主创新最高荣誉“信息产业重大技术发明奖”。2006年至2010年连续五届在英文语音 合成国际大赛（Blizzard Challenge）中蝉联大赛第一名。 基于拥有自主知识产权的世界领先智能语音技术，科大讯飞已推出从大型电信级应用到小型嵌入式应用，从电信、金融等行业到企业和家庭用户，从PC到手机到 MP3/MP4/PMP和玩具，能够满足不同应用环境的多种产品。科大讯飞占有中文语音技术70%以上市场份额，在电信、金融、电力、社保等主流行业的份 额更达80%以上，开发伙伴超过800家，以讯飞为核心的中文语音产业链已初具规模。 本手册主要讲述如何利用iFLY Mobile Speech Platform 2.0客户端子系统提供的API进行语音合成、语音听写和语音识别等方面的应用开发，其适用的读者有： 语音服务的提供商
如果您希望根据现有资源扩大某种特定服务的规模，但又担心为某一种服务去开发应用平
台代价太大，通过阅读本手册，您会发现，只需要较少的编程就可以充分利用iFLY Mobile Speech Platform
2.0讯飞移动语音平台的诸多优势，实现服务拓展，缩短项目周期。
语音应用的开发商
如果您从事语音系统的二次开发，面向行业级、家庭级等最终用户提供语音合成产
品，iFLY Mobile Speech Platform
2.0讯飞移动语音平台简洁明了而又功能全面的API将帮助您迅速完成语音应用系统的开发，从而大大节约开发投入，丰富语音服务的内容。
语音技术的爱好者
如果您对语音应用系统具有浓厚的兴趣，并且具有一定的编程基础，您可以在本手册指导下学习语音方面的应用开发，体验语音世界的无穷乐趣。
本手册基本内容：
第1章 概述 简要概括讯飞移动语音平台的原理、特色、功能，以及一些名词、缩略语介绍等。 第2章 QTTS接口 介绍QTTS接口函数功能与应用，并详细列出开发步骤与例程。 第3章 QISR接口 介绍QISR接口函数功能与应用，并详细列出开发步骤与例程。 第4章 错误码定义 介绍讯飞移动语音平台开发过程中返回的错误码及其定义。 通过阅读本手册，读者可以： 了解科大讯飞语音应用技术的基本功能与特色 掌握语音合成、语音识别系统接口规范 了解语音合成系统、语音识别应用开发的基本思想和方法 利用语音应用系统接口规范地进行二次开发 下图为iFLY Mobile Speech Platform 2.0（MSP20）产品的典型网络拓扑结构：
 图 1 MSP20网络结构 从图中可以看到，完整的MSP平台架构在Internet上，分为服务器端、移动客户端和Internet客户端三个部分。 服务器端为MSP平台的核心部分，提供HTTP应用、用户管理、语音服务等服务，位于局域网内，对外统一接入Internet，为客户端提供唯一的访问 点。其中：HTTP服务器负责分发由客户端发送的服务请求，按照业务不同分发至业务服务器，然后由业务服务器按照具体的服务类型进行处理，调用ISP语音 应用平台获取具体的语音服务，而后把处理结果返回给HTTP服务器，再回复客户端。 互联网用户直接通过MSP服务器提供的Internet访问点使用语音服务，在集成了MSP平台提供的开发接口后即可在网络畅通的情况下在应用程序中调用语音服务。 移动用户使用智能手机用户通过移动运营商提供的2G（GPRS/EDGE/CDMA）或3G网络接入Internet，然后连接到MSP服务器获得服务。 TTS ( Text to Speech )
语音合成（Text To Speech，TTS）技术能够自动将任意文字实时转换为连续的自然语音，是一种能够在任何时间、任何地点，向任何人提供语音信息服务的高效便捷手段，非常符合信息时代海量数据、动态更新和个性化查询的需求。 IAT( iFly Auto Transform ) & ASR ( Automatic Speech Recognition ) 语音听写和语音识别技术是一种使计算机能够识别人通过麦克风或者电话输入的词语或语句的技术，简单的说就是能够让计算机听懂人说话。它的最终目标是使得计算机不受词汇量限制，在各种噪声环境、语音信道下，能够实时、准确地识别不同方言、口音等特点的说话人的语句。 让机器听懂人类的语音，这是人们长期以来梦寐以求的事情。语音识别是一门交叉学科，关系到多学科的研究领域，不同领域上的研究成果都对语音识别的发展作了贡献。语音识别技术就是让机器通过识别和理解过程把语音信号转变为相应的文本或命令的技术。 ISP iFLY Speech Platform，讯飞语音应用平台，针对电信级应用场合开发的一个升级扩容方便、能提供高性能、高质量的负载均衡、方便部署、易于维护而且可以进行实时监控和维护的语音应用平台。 IMS iFLY MRCP Server，讯飞MRCP服务器，支持国际标准协议MRCP 1.0/2.0的语音服务平台，该平台基于ISP架构，提供对国际标准的支持。 MSP iFLY Mobile Speech Platform，或称为IMSP，讯飞移动语音平台的缩写，是讯飞面向移动互联网领域开发的语音服务平台，本项目是该产品的第二个版本。 MSSP Mobile Speech Service Protocol，移动语音服务协议，基于HTTP1.1协议扩展的语音应用协议。 本文针对的读者是具有Win32或者Android、iPhone、Windows Mobile等嵌入式平台编程经验的C/C++程序员。
文档中使用的符号约定：
在MSP2.0客户端子系统中关于TTS提供如下函数调用：
对应的宽字符接口如下：
宽字符接口的使用和窄字符并没有本质的不同，只是char型的数据换成了wchar_t，所以后面对各个函数的说明将以窄字符接口为例。 对于开发接口，如果调用成功，返回值为int型的接口都会返回0，否则返回错误代
码，错误代码参见msp_errors.h；对于返回值为指针类型的，函数执行成功返回非0指针，否则返回空指针0，错误代码可以通过相关的回传参数查
看。具体的错误原因可以结合MSC日志进行分析。
对于出现在参数列表中用于返回错误码的回传参数，如QTTSSessionBegin中的errorCode参数，用户可以传入NULL，此时MSC会忽略这个参数，此种情况下将不会有错误码返回，用户可以通过查看MSC的日志来了解程序执行中的一些信息。 Windows平台
Mobile平台
iPhone平台
函数原型
int TTSLIBAPI QTTSInit(const char* configs) 功能 对MSC在合成过程中用到的全局配置项参数进行初始化，如服务器地址、访问超时设置等。 参数 configs[in] 初始化时传入的字符串，以指定合成用到的一些配置参数，各个参数以“参数名=参数值”的形式出现，大小写不敏感，不同的参数之间以“,”或“\n”隔开，可以设置的参数列表如下（不设置任何值时可以传入NULL或空串）：
返回值 如果函数调用成功返回0，否则返回错误代码，错误代码参见msp_errors.h。主要的值如下：
说明 本函数在进行语音合成时必须第一个被调用。configs参数字符串中的参数对TTS有重要影响，如合成文本最大字节数这一参数，如果用户实际发送的合成文本长度大于设定的最大字节数，则QTTSTextPut接口会直接返回错误。 configs可设置的参数在MSC的配置文件中也有对应的配置项，优先级是configs字符串中的值高于配置文件中指定的值。 实际应用时，QTTSInit应当在应用程序初始化时仅调用一次，多次调用本函数（中间没有调QTTSFini）时只有第一次调用此函数会进行实际的初始 化工作，configs字符串中的内容会被配置到关于TTS的配置项中，后面的调用会返回成功，但不会完成实际的初始化工作。同样QTTSFini也应当 在应用程序退出时仅调用一次。 用法示例 const char* configs=“server_url=dev., coding_libs=amr_wb.dll;speex.dll”;
参见int ret = QTTSInit( configs ); if( 0 != ret ) { printf( “QTTSInit failed, error code is: %d”, ret ); } QTTSFini。 函数原型
TTSLIBAPI const char* QTTSSessionBegin(const char* params, int* errorCode) 功能 开始一路TTS会话，并在参数中指明本路会话用到的参数。 参数 params[in] 本路TTS会话使用的参数。可以设置的参数及其取值范围请参考《可设置参数列表_MSP20.xls》；各个参数以“参数名=参数值”的形式出现，不同的参数之间以“,”或者“\n”隔开。 errorCode [out] 如果函数调用成功返回0，否则返回错误代码，错误代码参见msp_errors.h，几个主要的返回值如下：
返回值 MSC为本路会话建立的ID，用来唯一的标识本路会话，供以后调用其他函数时使用。函数调用失败则会返回NULL。 说明 此处设定的参数在本路会话中一直有效。此函数需要和接口QTTSSessionEnd()配对使用，在这两个接口之间可以调用实际完成合成功能的接口如写入合成文本和取音频数据等。没有调用此函数则后续的函数调用会因为没有合法的会话ID而无法完成对应的功能。 用户调用此函数时，可以使用参数ssm=1或0来指定是否使用会话模式。在会话模式下，用户和服务器之间的多次交互都被相互关联起来，所以会话模式可以完 成一些较为复杂的功能，比如，将合成音频分段返回，返回当前音频对应的文本位置等信息。非会话模式下，MSC发往服务器的请求响应中携带合成参数和文本， 服务器在应答响应中返回全部合成音频，多次请求之间彼此独立，互不干扰。默认为非会话模式。 用法示例 /* 可设置的参数及含义请参考《可设置参数列表_MSP20》*/
参见const char* params= “ssm=1, ent=intp65, aue=speex-wb;7,auf=audio/L16;rate=16000”; int ret = 0; const char* session_id = QTTSSessionBegin( params, &ret ); if( 0 != ret ) { printf( “QTTSSessionBegin failed, error code is: %d”, ret ); } QTTSSessionEnd。 函数原型
int TTSLIBAPI QTTSTextPut(const char* sessionID, const char* textString, unsigned int textLen, const char* params) 功能 写入要合成的文本。 参数 sessionID [in] 由QTTSSessionBegin返回过来的会话ID。 textString [in] 用户将要进行合成的文本。 textLen [in] 合成文本的长度，该长度为合成文本的字节数，来明确指定。 params [in] 本次合成所用的参数，只对本次合成的文本有效。对于那些既可以出现在本接口中又可以出现在QTTSSessionBegin中的参数，此处的优先级要高于 QTTSSessionBegin中指定的值。可以设置的参数有：发音人、 语速、音量、音频格式、文本编码等，这些参数的具体名称和含义请参考《可设置参数列表_MSP20.xls》。 返回值 如果函数调用成功返回0，否则返回错误代码，错误代码参见msp_errors.h。几个主要的值如下：
说明 在非会话模式下，MSC会将文本暂时保存，等到用户调用QTTSAudioGet() 时，将文本发送到服务器端进行合成，如果连续多次调用本接口，则后面的文本会覆盖前面的文本。在会话模式下，MSC会将本次传入的全部文本发送到服务器 端，用户以后可以反复调用QTTSAudioGet()来获取音频。会话模式。 用法示例 const char* text_str = “安徽科大讯飞信息科技股份有限公司”;
参见unsigned int text_len = strlen( textString ); //textLen参数为合成文本所占字节数 const char* params = “vcn=xiaoyu, aue=amr-wb;7” int ret = QTTSTextPut( session_id, text_str, text_len, params ); if( 0 != ret ) { printf( “QTTSTextPut failed, error code is: %d”, ret ); } QTTSAudioGet。 函数原型
const void* TTSLIBAPI QTTSAudioGet(const char* sessionID, unsigned int* audioLen, int* synthStatus, int* errorCode) 功能 获取合成的音频。 参数 sessionID [in] 由QTTSSessionBegin返回过来的会话ID。 audioLen [out] 合成音频长度。 synthStatus [out] 合成音频状态，可能的值如下：
errorCode [out] 如果函数调用成功返回0，否则返回错误代码，错误代码参见msp_errors.h，几个主要的值如下：
返回值 如果函数调用成功返回合成音频的起始地址，否则返回空指针。 说明 用户需要反复调用此接口，在errorCode返回值为0的情况下直到synthStatus返回TTS_FLAG_DATA_END（音频已经取完）为止。 在非会话模式下，调用本函数时，MSC会将用户传入的文本和本次会话的参数打包成消息发送至服务器并阻塞当前线程等待服务器的响应，如果在此期间响应消息 到来，则本函数会成功得到合成的音频数据；在预定的时间内没有响应消息到来，errorCode会被设置为一个关于等待超时的错误码。 在会话模式下，调用本函数时，MSC会向服务器发送一个获取音频的命令，服务器返回一定数量的音频，并返回音频对应的文本位置以及音频是否取完等信息。音 频对应的文本信息可以通过调用QTTSAudioInfo获取到，由于服务器每次返回给MSC的只是部分音频，所以会话模式的响应速度可以达到很快。 用法示例 char* synth_speech = new char[ 2 * 1024 * 1024 ];
参见unsigned int speech_len = 0; void* audio_data = NULL; unsigned int audio_len = 0; int synth_status = 0; int ret = 0; while( TTS_FLAG_DATA_END != synth_status ) { audio_data = QTTSAudioGet( session_id, &audio_len, &synth_status, &ret ); if( 0 ! = ret ) { printf( “QTTSAudioGet failed, error code is: %d”, ret ); break; } If( NULL != audio && 0 != audio_len ) { /* 用户可以用其他的方式保存音频，如写入文件等 */ memcpy( synth_speech + speech_len, audio_data, audio_len ); speech_len += audio_len; } } 无。 函数原型
const char* TTSLIBAPI QTTSAudioInfo(const char* sessionID) 功能 获取关于合成音频的某些信息如合成音频对应的当前文本位置等。 参数 sessionID [in] 由QTTSSessionBegin返回过来的会话ID。 返回值 如果函数调用成功返回字符串指针，否则返回NULL。 说明 本接口用于在调用QTTSAudioGet后，获取关于此段音频的描述信息，目前支持的信息有：此次合成音频对应文本结束位置，用户可以利用此信息来做实时高亮度显示合成的文本等应用，格式为”ced=xxx”。 用法示例 const char* audio_info = QTTSAudioInfo( session_id );
参见if( NULL == audio_info ) { printf( “QTTSAudioInfo failed” ); } QTTSSAudioGet。 函数原型
int TTSLIBAPI QTTSSessionEnd(const char* sessionID, const char* hints) 功能 结束一路TTS会话。 参数 sessionID [in] 由QTTSSessionBegin返回过来的会话ID。 hints [in] 结束本次会话的原因描述，用于记录日志，便于用户查阅或者跟踪某些问题。 返回值 如果函数调用成功返回0，否则返回错误代码，错误代码参见msp_errors.h。几个主要的返回值如下：
说明 本接口对应于QTTSSessionBegin()接口，用来结束一路TTS会话。如果用户在完成一路TTS会话后，不调用本函数而直接调用QTTSFini()，则会返回错误码提示“仍有活跃的实例”。 调用本函数后，关于当前会话的所有资源（参数，合成文本，会话实例等）都会被释放，所以用户不应该再针对该实例做任何操作（比如使用其会话ID等）。 ed=xxx”。 用法示例 int ret = QTTSSessionEnd ( session_id, “normal end” );
参见if( 0 != ret ) { printf( “QTTSSessionEnd failed, error code is: %d”, ret ); } QTTSSessionBegin QTTSFini。 函数原型
int TTSLIBAPI QTTSGetParam(const char* sessionID, const char* paramName, char* paramValue, unsigned int* valueLen) 功能 查询MSC记录下来的一些信息如数据上传或下载的数据量等。 参数 sessionID [in] 由QISRSessionBegin返回过来的会话ID。 paramName [in] 要获取的参数名称；支持同时查询多个参数，查询多个参数时，参数名称按“,” 或“\n”分隔开来。 paraValue [out] 获取的参数值，以字符串形式返回；查询多个参数时，参数值之间按“;”分隔开来，不支持的参数将返回空的值。 valueLen [in/out] 输入的是存放参数值字符串paraValue缓冲区的长度，输出为参数值字符串的长度。 返回值 如果函数调用成功返回0，否则返回错误代码，错误代码参见msp_errors.h。几个主要的返回值如下：
说明 目前支持的参数如下：
用法示例 const char* para_name = “upflow;downflow”;
参见char* para_value[ 32 ] = “”; unsigned int value_len = 32; int ret = QTTSGetParam ( session_id, para_name, para_value, &value_len ); if( 0 != ret ) { printf( “QTTSGetParam failed, error code is: %d”, ret ); } 无。 函数原型
int TTSLIBAPI QTTSFini(void) 功能 对MSC进行逆初始化。 参数 无。 返回值 如果函数调用成功返回0，否则返回错误代码，错误代码参见msp_errors.h。主要的返回值如下：
说明 本接口对应于QTTSInit接口，在使用TTS功能时最后一个被调用，用来对MSC的TTS部分进行逆初始化。没有调用QTTSInit()直接调用本接口，则不会有任何效果，调用了QTTSInit()不调用本接口而直接结束线程，则MSC会产生资源泄漏。 本函数正常的调用场景是当前活跃的TTS实例数为0（释放一个活跃的实例使用QTTSSessionEnd()函数）。如果当前活跃的TTS实例数不为0，则说明用户在使用函数时的时序有问题，这种情况将会返回关于“活跃的实例数不为空”的错误码。 用法示例 int ret = QTTSFini();
参见if( 0 != ret ) { printf( “QTTSFini failed, error code is: %d”, ret ); } QTTSInit QTTSSessionEnd。。 在MSP2.0客户端子系统中关于ISR提供如下函数调用：
对应的宽字符接口如下：
宽字符接口的使用和窄字符并没有什么不同，只是char型的数据换成了wchar_t，所以后面对各个函数的说明将以窄字符接口为例。 本组接口不是线程安全的，用户需要自行保证某些数据的线程安全性，如sessionID。 对于开发接口，如果调用成功，返回值为int型的接口都会返回0，否则返回错误代
码，错误代码参见msp_errors.h；对于返回值为指针类型的，函数执行成功返回非0指针，否则返回空指针0，错误代码可以通过相关的回传参数查
看。具体的错误原因可以结合MSC日志进行分析。
对于出现在参数列表中用于返回错误码的回传参数，如QISRSessionBegin中的errorCode参数，用户可以传入NULL，此时MSC会忽略这个参数，此种情况下将不会有错误码返回，用户可以通过查看MSC的日志来了解程序执行中的一些信息。 Windows平台
Mobile平台
iPhone平台
函数原型
int ISRAPI QISRInit(const char* configs) 功能 对MSC在识别过程中用到的全局配置项参数进行初始化，如服务器地址、访问超时设置等。 参数 configs[in] 初始化时传入的字符串，以指定识别或听写用到的一些配置参数，各个参数以“参数名=参数值”的形式出现，大小写不敏感，不同的参数之间以“,”或“\n”隔开，可以设置的参数列表如下：
返回值 如果函数调用成功返回0，否则返回错误代码，错误代码参见msp_errors.h。主要的返回值如下：
说明 configs参数字符串中的参数对ISR有重要影响，如音频数据的最大长度这一参数，如果用户实际发送的音频数据量大于设定的最大字节数，则QISRAudioWrite接口会直接返回错误。 configs可设置的参数在MSC的配置文件中也有对应的配置项，优先级是configs字符串中的值高于配置文件中指定的值。 实际应用时，QISRInit应当在应用程序初始化时仅调用一次，多次调用本函数（中间没有调QISRFini）时只有第一次调用此函数会进行实际的初始 化工作，configs字符串中的内容会被配置到关于ISR的配置项中，后面的调用会返回成功，但不会完成实际的初始化工作。同样QISRFini也应当 在应用程序退出时仅调用一次。 时仅调用一次。 用法示例 const char* configs=“server_url=dev., timeout=10000, vad_enable=true”;
参见int ret = QISRInit( configs ); if( 0 != ret ) { printf( “QISRInit failed, error code is: %d”, ret ); } QISRFini。 函数原型
const char* ISRAPI QISRSessionBegin(const char* grammarList, const char* params, int *errorCode); 功能 本接口用来开始一路ISR会话，并在参数中指定本路ISR会话用到的语法列表，本次会话所用的参数等。 参数 grammarList[in] uri-list格式的语法，可以是一个语法文件的URL或者一个引擎内置语法列表。可以同时指定多个语法，不同的语法之间以“,”隔开。进行语音听写时 不需要语法，此参数设定为NULL或空串即可；进行语音识别时则需要语法，语法可以在此参数中指定，也可以随后调用 QISRGrammarActivate指定识别所用的语法。 params[in] 本路ISR会话使用的参数，可设置的参数及其取值范围请参考《可设置参数列表_MSP20.xls》，各个参数以“参数名=参数值”的形式出现，不同的参数之间以“,”或者“\n”隔开。 errorCode[out] 如果函数调用成功则其值为0，否则返回错误代码，错误代码参见msp_errors.h。几个主要的返回值如下：
返回值 MSC为本路会话建立的ID，用来唯一的标识本路会话，供以后调用其他函数时使用。函数调用失败则会返回NULL。 说明 此处设定的参数在本路会话中一直有效。此函数需要和接口 QISRSessionEnd()配对使用，在这两个接口之间可以调用实际完成识别功能的接口如激活语法、写入音频和获取结果等。没有调用此函数则MSC 不会建立和当前线程有关的会话实例，后续的函数调用会因为没有合法的会话ID而无法完成对应的功能。 用户调用此函数时，可以使用参数ssm=1或0来指定是否在本次会话中使用会话模式。在会话模式下，用户和服务器之间的多次交互都被相互关联，所以会话模 式可以完成一些较为复杂的功能，比如，当识别或转写音频数据量比较大时，可以把数据分段发往服务器端，这种工作方式可以使得用户边采集音频边发送，另一方 面也提高了服务器的响应速度。非会话模式下，MSC发往服务器的请求响应中携带识别参数和音频数据，服务器在应答响应中返回全部识别结果，多次请求之间彼 此独立，互不干扰。程序默认为非会话模式。 语音听写可以将用户输入的语音转换成与之对应的文字并返回给用户，同普通的识别相比，它不需要语法。用户需要在参数中使用sub=iat来指明本次会话为语音听写会话。程序默认的sub=asr即普通的识别会话。 对于那些可以出现在QISRInit函数的 configs字符串中又可以出现在本函数的params中的参数，比如音频编码格式“aue”，在本次会话中，这些参数的优先级次序是：params指 定的值>configs指定的值>配置文件中指定的值。本路会话params中指定的值不会影响到其他的会话。 用法示例 /* vad_timeout和vad_speech_tail两个参数只有在打开VAD功能时才生效 */
参见const char* params= “ssm=1,sub=iat,aue=speex-wb;7,auf=audio/L16;rate=16000,ent=sms16k,rst=plain,vad_timeout=1000,vad_speech_tail=1000”; int ret = 0; const char* session_id = QISRSessionBegin( NULL, params, &ret ); if( 0 != ret ) { printf( “QISRSessionBegin failed, error code is: %d”, ret ); } QISRSessionEnd。 函数原型
int ISRAPI QISRGrammarActivate(const char* sessionID, const char* grammar, const char* type, int weight); 功能 本函数用来激活一个指定的语法，语法类型可以是任何一种合法的语法。 参数 sessionID [in] 由QISRSessionBegin返回过来的会话ID。 grammar [in] 语法字符串。 type [in] 语法类型，可以是uri-list、abnf、xml等。 weight [in] 本次传入语法的权重，本参数在MSP 2.0中会被忽略。 返回值 如果函数调用成功返回0，否则返回错误代码，错误代码参见msp_errors.h。几个主要的返回值如下：
说明 在一路会话中，用户可以调用此接口定义一个或多个语法，多个语法之间以“,”隔开，此接 口定义的语法和QISRSessionBegin () 指定的语法彼此之间相互独立，地位平等，互不干扰，用户可以通过查看识别结果中的grammar字段来了解识别结果对应的语法。定义的语法从定义成功时刻 到会话结束时一直有效。 具体的识别语法编写规范可以参阅： Speech Recognition Grammar Specification Version 1.0 用法示例 /* 激活引擎内置的歌曲搜索的语法 */
参见const char* grammar=“"builtin:grammar/../search/song/song.abnf?language=zh-cn”; int ret = QISRGrammarActivate( session_id, grammar, “abnf”, 1 ); if( 0 != ret ) { printf( “QISRGrammarActivate failed, error code is: %d”, ret ); } 无。 函数原型
int ISRAPI QISRAudioWrite(const char* sessionID, const void* waveData, unsigned int waveLen, int audioStatus, int* epStatus, int* recogStatus ); 功能 写入本次识别的音频，音频可以一次性写入，也可以多次调用此接口分批写入。 参数 sessionID [in] 由QISRSessionBegin返回过来的会话ID。 waveData [in] 音频数据缓冲区起始地址。 waveLen [in] 音频数据长度，其大小不能超过设定的max_audio_size。 audioStatus [in] 用来指明用户本次识别的音频是否发送完毕，可能的值如下：
在MSP20中，ISR_AUDIO_SAMPLE_LAST（0x04）用来指明当前的音频已经发送完毕，除此之外的任何值都将被MSC视为还有后继的音频。 epStatus [out] 端点检测（End-point detected）器所处的状态，可能的值如下：
当epStatus大于等于3时，用户应当停止写入音频的操作，否则写入MSC的音频会被忽略。 recogStatus [out] 识别器所处的状态，可能的值如下：
返回值 如果函数调用成功返回0，否则返回错误代码，错误代码参见msp_errors.h。几个主要的返回值如下：
说明 在会话模式下，MSC处理音频的策略是边接收、边压缩（如果音频编码格式不为raw）、 边发送。由于音频压缩速度和网络速度的限制，如果音频发送太快太急（如20倍于音频码率），可能会造成原始音频或压缩音频在MSC中积累过多，从而造成缓 冲区无法再容纳更多的数据而产生“没有足够缓冲区”的错误。 在非会话模式下，当用户发送音频的累积长度超过了max_audio_size的值，则多余靠后音频会被忽略，不会被识别。当用户在宣布音频发送完毕后又 再次调用本接口发音频，则上次发送的音频会被清除，并被替换成新写入的音频。 无论是会话模式还是非会话模式，推荐用户在发送音频时采取“边录边发”的方式，即每隔一小段时间将采集到的音频通过本接口写入MSC。这种“边录边发”的 方式在非会话模式下可以减少压缩音频所用的时间，而在非会话模式下可以加快结果返回的速度：发送靠后的音频时，前面的音频或许已经被服务器处理过并将部分 结果返回了。 调用接口时请设置好audioStatus的值，并检查返回型参数epStatus的值，以便及时了解音频的前后端点等信息。如果当前写入的不是最后一块 音频，需要将audioStatus的值设为2（ISR_AUDIO_SAMPLE_CONTINUE）。如果在音频发送过程中检测到epStatus的 值为3（ISR_EP_AFTER_SPEECH），说明系统已经检测到音频的后端点，则应该立即结束音频发送；如果用户要在检测到音频后端点之前结束音 频的发送，需要将最后一个音频数据的audioStatus设为4（ISR_AUDIO_SAMPLE_LAST）。 在会话模式下，如果识别状态recogStatus值为0（ISR_REC_STATUS_SUCCESS）表示已经有部分或全部识别结果缓存在MSC中 了，用户可以调用QISRGetResult获取这部分结果，再继续调用QISRAudioWrite以发送后续的音频数据（如果结果还没取完的话），这 种两个接口混调的方式，可以很快的获得（部分）识别结果，特别是使用较大音频进行语音听写时。 用法示例 char audio_data[ 5120 ] = “”;
参见unsigned int audio_len = 0; int audio_status = 2; int ep_status = 0; int rec_status = 0; int ret = 0; while(ISR_AUDIO_SAMPLE_LAST != audio_status ) { … // 读取音频到缓冲区audio_data中，设置音频长度audio_len，音频状态audio_status。 ret = QISRAudioWrite( session_id, audio_data, audio_len, audio_status , &ep_status, &rec_status ); if( 0 ! = ret ) { printf( “QISRAudioWrite failed, error code is: %d”, ret ); break; } else if( ISR_EP_AFTER_SPEECH == ep_status ) /* 检测到音频后端点，停止发送音频 */ { printf( “end point of speech has been detected!” ); break; } /* 如果是实时采集音频，可以省略此操作。5KB大小的16KPCM持续的时间是160毫秒 */ Sleep( 160 ); } QISRGetResult。 函数原型
const char * ISRAPI QISRGetResult(const char* sessionID, int* rsltStatus, int waitTime, int *errorCode); 功能 获取识别结果。 参数 sessionID [in] 由QISRSessionBegin返回过来的会话ID。 rsltStatus [out] 识别结果的状态，其取值范围和含义请参考QISRAudioWrite的参数recogStatus。 waitTime [in] 与服务器交互的间隔时间，可以控制和服务器的交互频度。单位为ms，建议取值为5000。 errorCode [out] 如果函数调用成功返回0，否则返回错误代码，错误代码参见msp_errors.h。几个主要的返回值如下：
返回值 函数执行失败返回NULL。函数执行成功并且获取到识别结果时返回识别结果，函数执行成功没有获取到识别结果时返回NULL。 说明 在会话模式下，调用此函数只是获取缓存在MSC中的（部分）识别结果，程序不会阻塞，所 以用户需要反复调用此接口，直到识别结果获取完毕（rlstStatus值为5（ISR_REC_STATUS_SPEECH_COMPLETE））或返 回错误码。使用此接口时请注意，如果某此成功调用后没有获得识别结果，请将当前线程sleep一段时间后再次调用，以防止频繁调用浪费CPU资源。 在非会话模式下，调用本函数时，MSC会将用户传入的语法和音频以及本次会话所用的参数打包成消息发送至服务器并阻塞当前线程等待服务器的响应，如果在此 期间响应消息到来，则本函数会成功得到识别结果；如果在预定的时间内没有响应消息到来，则本函数会返回一个关于等待超时的错误码。 用法示例 char rslt_str[ 2048 ] = “”;
参见const char* rec_result = NULL; int rslt_status = 0; int ret = 0; while( ISR_REC_STATUS_SPEECH_COMPLETE != rslt_status ) { rec_result = QISRGetResult ( session_id, &rslt_status, 5000, &ret ); if( 0 != ret ) { printf( “QISRGetResult failed, error code is: %d”, ret ); break; } if( NULL != rec_result ) { /* 用户可以用其他的方式保存识别结果 */ strcat( rslt_str, rec_result ); continue; } /* sleep一下很有必要，防止MSC端无缓存的识别结果时浪费CPU资源 */ Sleep( 200 ); } QISRAudioWrite。 函数原型
int ISRAPI QISRSessionEnd(const char* sessionID, const char* hints) 功能 结束一路ISR会话。 参数 sessionID [in] 由QISRSessionBegin返回过来的会话ID。 hints [in] 结束本次会话的原因描述，用于记录日志，便于用户查阅或者跟踪某些问题。 返回值 如果函数调用成功返回0，否则返回错误代码，错误代码参见msp_errors.h和msp_error.h。几个主要的返回值如下：
说明 本接口需要和QISRSessionBegin()配合使用，用来结束一路ISR会话。 调用本函数后，关于当前会话的所有资源（参数，语法，音频，会话实例等）都会被释放，所以用户不应该再针对该实例做任何操作（比如使用其SessionID等）。 用法示例 int ret = QISRSessionEnd ( session_id, “normal end” );
参见if( 0 != ret ) { printf( “QISRSessionEnd failed, error code is: %d”, ret ); } QISRSessionBegin。 函数原型
int ISRAPI QISRGetParam(const char* sessionID, const char* paramName, char* paramValue, unsigned int* valueLen) 功能 查询MSC记录下来的一些信息如数据上传或下载的数据量等。 参数 sessionID [in] 由QISRSessionBegin返回过来的会话ID。 paramName [in] 要获取的参数名称；支持同时查询多个参数，查询多个参数时，参数名称按“,” 或“\n”分隔开来。 paraValue [out] 获取的参数值，以字符串形式返回；查询多个参数时，参数值之间按“;”分隔开来，不支持的参数将返回空的值。 valueLen [out] 参数值的长度。 返回值 如果函数调用成功返回0，否则返回错误代码，错误代码参见msp_errors.h。几个主要的返回值如下：
说明 目前支持的参数如下：
用法示例 参见2.2.7节QTTSGetParam。 参见 无。 函数原型
int ISRAPI QISRFini(void)； 功能 对MSC的ISR部分进行逆初始化。 参数 无。 返回值 如果函数调用成功返回0，否则返回错误代码，错误代码参见msp_errors.h。主要的返回值如下：
说明 本函数需要和QISRInit()配对使用，没有调用QISRInit()直接调用本接口，则不会有任何效果，调用了QISRInit()不调用本接口而直接结束线程，则MSC会产生资源泄漏。 本函数是对MSC关于ISR部分进行全局逆初始化，所以正常的调用情况是当前活跃的ISR实例数为0（释放一个活跃的实例使用 QISRSessionEnd()函数）。如果当前活跃的ISR实例数不为0，则说明用户在使用函数时的时序有问题，程序运行日志中将会出现警告信息。 用法示例 int ret = QISRFini();
if( 0 != ret ) { printf( “QISRFini failed, error code is: %d”, ret ); } 参见 QISRInit。 QISRSessionEnd。 MSP2.0 客户端子系统返回的错误码都在msp_errors.h中定义，大致可以分为一般错误、网络错误、资源错误和HTTP错误等。
和错误码有关的宏定义：
#define MSP_HTTP_ERROR (x) ((x) + MSP_ERROR_HTTP_BASE) 将HTTP错误码×××映射为12×××，即关于HTTP的错误码后三位同HTTP协议中定义的错误码是一致的。
|
|
|
