目錄
前言1. 概述1.1. MSP20網(wǎng)絡(luò)拓?fù)浣Y(jié)構(gòu)說(shuō)明1.2. 名詞和縮略語(yǔ)1.3. 文檔說(shuō)明2. QTTS開(kāi)發(fā)接口說(shuō)明2.1. QTTS接口簡(jiǎn)介2.1.1. QTTS接口函數(shù)列表2.1.2. 返回值說(shuō)明2.1.3. 發(fā)包組件2.1.4. 開(kāi)發(fā)包支持情況2.2. 函數(shù)調(diào)用2.2.1. QTTSInit2.2.2. QTTSSessionBegin2.2.3. QTTSTextPut2.2.4. QTTSAudioGet2.2.5. QTTSAudioInfo2.2.6. QTTSSessionEnd2.2.7. QTTSLogEvent2.2.8. QTTSFini3. QISR開(kāi)發(fā)接口說(shuō)明3.1. QISR接口簡(jiǎn)介3.1.1. QISR接口函數(shù)列表3.1.2. 返回值說(shuō)明3.1.3. 發(fā)包組件3.1.4. 開(kāi)發(fā)包支持情況3.2. 函數(shù)調(diào)用3.2.1. QISRInit3.2.2. QISRSessionBegin3.2.3. QISRGrammarActivate3.2.4. QISRAudioWrite3.2.5. QISRGetResult3.2.6. QISRSessionEnd3.2.7. QISRGetParam3.2.8. QISRFini4. 錯(cuò)誤碼的定義4.1. 宏4.2. 錯(cuò)誤碼列表前言
歡迎使用iFLY Mobile Speech Platform 2.0訊飛移動(dòng)語(yǔ)音平臺(tái)！
iFLY Mobile Speech Platform 2.0訊飛移動(dòng)語(yǔ)音平臺(tái)是基于訊飛公司已有的ISP和IMS產(chǎn)品，開(kāi)發(fā)出的一款符合移動(dòng)互聯(lián)網(wǎng)用戶使用的語(yǔ)音應(yīng)用開(kāi)發(fā)平臺(tái)，提供語(yǔ)音合成、語(yǔ)音聽(tīng)寫(xiě)、語(yǔ)音識(shí)別、聲紋識(shí)別等服務(wù)，為語(yǔ)音應(yīng)用開(kāi)發(fā)愛(ài)好者提供方便易用的開(kāi)發(fā)接口，使得用戶能夠基于該開(kāi)發(fā)接口進(jìn)行多種語(yǔ)音應(yīng)用開(kāi)發(fā)。其主要功能有：
1) 實(shí)現(xiàn)基于HTTP協(xié)議的語(yǔ)音應(yīng)用服務(wù)器，集成訊飛公司最新的語(yǔ)音引擎，支持語(yǔ)音合成、語(yǔ)音聽(tīng)寫(xiě)、語(yǔ)音識(shí)別、聲紋識(shí)別等服務(wù)；
2) 提供基于移動(dòng)平臺(tái)和PC上的語(yǔ)音客戶端子系統(tǒng)，內(nèi)部集成音頻處理和音頻編解碼模塊，提供關(guān)于語(yǔ)音合成、語(yǔ)音聽(tīng)寫(xiě)、語(yǔ)音識(shí)別和聲紋識(shí)別完善的API。
科大訊飛作為中國(guó)最大的智能語(yǔ)音技術(shù)提供商，在智能語(yǔ)音技術(shù)領(lǐng)域有著長(zhǎng)期的研究積累，并在語(yǔ)音合成、語(yǔ)音識(shí)別、口語(yǔ)評(píng)測(cè)等多項(xiàng)技術(shù)上擁有國(guó)際領(lǐng)先的成果?？拼笥嶏w是我國(guó)唯一以語(yǔ)音技術(shù)為產(chǎn)業(yè)化方向的“國(guó)家863計(jì)劃成果產(chǎn)業(yè)化基地”、“國(guó)家規(guī)劃布局內(nèi)重點(diǎn)軟件企業(yè)”、“國(guó)家火炬計(jì)劃重點(diǎn)高新技術(shù)企業(yè)”、“國(guó)家高技術(shù)產(chǎn)業(yè)化示范工程”，并被信息產(chǎn)業(yè)部確定為中文語(yǔ)音交互技術(shù)標(biāo)準(zhǔn)工作組組長(zhǎng)單位，牽頭制定中文語(yǔ)音技術(shù)標(biāo)準(zhǔn)。2003年，科大訊飛獲迄今中國(guó)語(yǔ)音產(chǎn)業(yè)唯一的“國(guó)家科技進(jìn)步二等獎(jiǎng)”，2005年獲中國(guó)信息產(chǎn)業(yè)自主創(chuàng)新最高榮譽(yù)“信息產(chǎn)業(yè)重大技術(shù)發(fā)明獎(jiǎng)”。2006年至2010年連續(xù)五屆在英文語(yǔ)音合成國(guó)際大賽（Blizzard Challenge）中蟬聯(lián)大賽第一名。
基于擁有自主知識(shí)產(chǎn)權(quán)的世界領(lǐng)先智能語(yǔ)音技術(shù)，科大訊飛已推出從大型電信級(jí)應(yīng)用到小型嵌入式應(yīng)用，從電信、金融等行業(yè)到企業(yè)和家庭用戶，從PC到手機(jī)到MP3/MP4/PMP和玩具，能夠滿足不同應(yīng)用環(huán)境的多種產(chǎn)品?？拼笥嶏w占有中文語(yǔ)音技術(shù)70%以上市場(chǎng)份額，在電信、金融、電力、社保等主流行業(yè)的份額更達(dá)80%以上，開(kāi)發(fā)伙伴超過(guò)800家，以訊飛為核心的中文語(yǔ)音產(chǎn)業(yè)鏈已初具規(guī)模。
本手冊(cè)主要講述如何利用iFLY Mobile Speech Platform 2.0客戶端子系統(tǒng)提供的API進(jìn)行語(yǔ)音合成、語(yǔ)音聽(tīng)寫(xiě)和語(yǔ)音識(shí)別等方面的應(yīng)用開(kāi)發(fā)，其適用的讀者有：
語(yǔ)音服務(wù)的提供商
如果您希望根據(jù)現(xiàn)有資源擴(kuò)大某種特定服務(wù)的規(guī)模，但又擔(dān)心為某一種服務(wù)去開(kāi)發(fā)應(yīng)用平臺(tái)代價(jià)太大，通過(guò)閱讀本手冊(cè)，您會(huì)發(fā)現(xiàn)，只需要較少的編程就可以充分利用iFLY Mobile Speech Platform 2.0訊飛移動(dòng)語(yǔ)音平臺(tái)的諸多優(yōu)勢(shì)，實(shí)現(xiàn)服務(wù)拓展，縮短項(xiàng)目周期。
語(yǔ)音應(yīng)用的開(kāi)發(fā)商
如果您從事語(yǔ)音系統(tǒng)的二次開(kāi)發(fā)，面向行業(yè)級(jí)、家庭級(jí)等最終用戶提供語(yǔ)音合成產(chǎn)品，iFLY Mobile Speech Platform 2.0訊飛移動(dòng)語(yǔ)音平臺(tái)簡(jiǎn)潔明了而又功能全面的API將幫助您迅速完成語(yǔ)音應(yīng)用系統(tǒng)的開(kāi)發(fā)，從而大大節(jié)約開(kāi)發(fā)投入，豐富語(yǔ)音服務(wù)的內(nèi)容。
語(yǔ)音技術(shù)的愛(ài)好者
如果您對(duì)語(yǔ)音應(yīng)用系統(tǒng)具有濃厚的興趣，并且具有一定的編程基礎(chǔ)，您可以在本手冊(cè)指導(dǎo)下學(xué)習(xí)語(yǔ)音方面的應(yīng)用開(kāi)發(fā)，體驗(yàn)語(yǔ)音世界的無(wú)窮樂(lè)趣。
本手冊(cè)基本內(nèi)容：
第1章 概述
簡(jiǎn)要概括訊飛移動(dòng)語(yǔ)音平臺(tái)的原理、特色、功能，以及一些名詞、縮略語(yǔ)介紹等。
第2章 QTTS接口
介紹QTTS接口函數(shù)功能與應(yīng)用，并詳細(xì)列出開(kāi)發(fā)步驟與例程。
第3章 QISR接口
介紹QISR接口函數(shù)功能與應(yīng)用，并詳細(xì)列出開(kāi)發(fā)步驟與例程。
第4章 錯(cuò)誤碼定義
介紹訊飛移動(dòng)語(yǔ)音平臺(tái)開(kāi)發(fā)過(guò)程中返回的錯(cuò)誤碼及其定義。
通過(guò)閱讀本手冊(cè)，讀者可以：
了解科大訊飛語(yǔ)音應(yīng)用技術(shù)的基本功能與特色
掌握語(yǔ)音合成、語(yǔ)音識(shí)別系統(tǒng)接口規(guī)范
了解語(yǔ)音合成系統(tǒng)、語(yǔ)音識(shí)別應(yīng)用開(kāi)發(fā)的基本思想和方法
利用語(yǔ)音應(yīng)用系統(tǒng)接口規(guī)范地進(jìn)行二次開(kāi)發(fā)
第1章 概述
1.1 MSP20網(wǎng)絡(luò)拓?fù)浣Y(jié)構(gòu)說(shuō)明的
下圖為iFLY Mobile Speech Platform 2.0（MSP20）產(chǎn)品的典型網(wǎng)絡(luò)拓?fù)浣Y(jié)構(gòu)：
圖 1 MSP20網(wǎng)絡(luò)結(jié)構(gòu)
從圖中可以看到，完整的MSP平臺(tái)架構(gòu)在Internet上，分為服務(wù)器端、移動(dòng)客戶端和Internet客戶端三個(gè)部分。
服務(wù)器端為MSP平臺(tái)的核心部分，提供HTTP應(yīng)用、用戶管理、語(yǔ)音服務(wù)等服務(wù)，位于局域網(wǎng)內(nèi)，對(duì)外統(tǒng)一接入Internet，為客戶端提供唯一的訪問(wèn)點(diǎn)。其中：HTTP服務(wù)器負(fù)責(zé)分發(fā)由客戶端發(fā)送的服務(wù)請(qǐng)求，按照業(yè)務(wù)不同分發(fā)至業(yè)務(wù)服務(wù)器，然后由業(yè)務(wù)服務(wù)器按照具體的服務(wù)類型進(jìn)行處理，調(diào)用ISP語(yǔ)音應(yīng)用平臺(tái)獲取具體的語(yǔ)音服務(wù)，而后把處理結(jié)果返回給HTTP服務(wù)器，再回復(fù)客戶端。
互聯(lián)網(wǎng)用戶直接通過(guò)MSP服務(wù)器提供的Internet訪問(wèn)點(diǎn)使用語(yǔ)音服務(wù)，在集成了MSP平臺(tái)提供的開(kāi)發(fā)接口后即可在網(wǎng)絡(luò)暢通的情況下在應(yīng)用程序中調(diào)用語(yǔ)音服務(wù)。
移動(dòng)用戶使用智能手機(jī)用戶通過(guò)移動(dòng)運(yùn)營(yíng)商提供的2G（GPRS/EDGE/CDMA）或3G網(wǎng)絡(luò)接入Internet，然后連接到MSP服務(wù)器獲得服務(wù)。
1.2 名詞和縮略語(yǔ)
TTS ( Text to Speech )
語(yǔ)音合成（Text To Speech，TTS）技術(shù)能夠自動(dòng)將任意文字實(shí)時(shí)轉(zhuǎn)換為連續(xù)的自然語(yǔ)音，是一種能夠在任何時(shí)間、任何地點(diǎn)，向任何人提供語(yǔ)音信息服務(wù)的高效便捷手段，非常符合信息時(shí)代海量數(shù)據(jù)、動(dòng)態(tài)更新和個(gè)性化查詢的需求。
IAT( iFly Auto Transform ) & ASR ( Automatic Speech Recognition )
語(yǔ)音聽(tīng)寫(xiě)和語(yǔ)音識(shí)別技術(shù)是一種使計(jì)算機(jī)能夠識(shí)別人通過(guò)麥克風(fēng)或者電話輸入的詞語(yǔ)或語(yǔ)句的技術(shù)，簡(jiǎn)單的說(shuō)就是能夠讓計(jì)算機(jī)聽(tīng)懂人說(shuō)話。它的最終目標(biāo)是使得計(jì)算機(jī)不受詞匯量限制，在各種噪聲環(huán)境、語(yǔ)音信道下，能夠?qū)崟r(shí)、準(zhǔn)確地識(shí)別不同方言、口音等特點(diǎn)的說(shuō)話人的語(yǔ)句。
讓機(jī)器聽(tīng)懂人類的語(yǔ)音，這是人們長(zhǎng)期以來(lái)夢(mèng)寐以求的事情。語(yǔ)音識(shí)別是一門(mén)交叉學(xué)科，關(guān)系到多學(xué)科的研究領(lǐng)域，不同領(lǐng)域上的研究成果都對(duì)語(yǔ)音識(shí)別的發(fā)展作了貢獻(xiàn)。語(yǔ)音識(shí)別技術(shù)就是讓機(jī)器通過(guò)識(shí)別和理解過(guò)程把語(yǔ)音信號(hào)轉(zhuǎn)變?yōu)橄鄳?yīng)的文本或命令的技術(shù)。
ISP
iFLY Speech Platform，訊飛語(yǔ)音應(yīng)用平臺(tái)，針對(duì)電信級(jí)應(yīng)用場(chǎng)合開(kāi)發(fā)的一個(gè)升級(jí)擴(kuò)容方便、能提供高性能、高質(zhì)量的負(fù)載均衡、方便部署、易于維護(hù)而且可以進(jìn)行實(shí)時(shí)監(jiān)控和維護(hù)的語(yǔ)音應(yīng)用平臺(tái)。
IMS
iFLY MRCP Server，訊飛MRCP服務(wù)器，支持國(guó)際標(biāo)準(zhǔn)協(xié)議MRCP 1.0/2.0的語(yǔ)音服務(wù)平臺(tái)，該平臺(tái)基于ISP架構(gòu)，提供對(duì)國(guó)際標(biāo)準(zhǔn)的支持。
MSP
iFLY Mobile Speech Platform，或稱為IMSP，訊飛移動(dòng)語(yǔ)音平臺(tái)的縮寫(xiě)，是訊飛面向移動(dòng)互聯(lián)網(wǎng)領(lǐng)域開(kāi)發(fā)的語(yǔ)音服務(wù)平臺(tái)，本項(xiàng)目是該產(chǎn)品的第二個(gè)版本。
MSSP
Mobile Speech Service Protocol，移動(dòng)語(yǔ)音服務(wù)協(xié)議，基于HTTP1.1協(xié)議擴(kuò)展的語(yǔ)音應(yīng)用協(xié)議。
1.3 文檔說(shuō)明
本文針對(duì)的讀者是具有Win32或者Android、iPhone、Windows Mobile等嵌入式平臺(tái)編程經(jīng)驗(yàn)的C/C++程序員。
文檔中使用的符號(hào)約定：
符號(hào) 含義
[in] 表明該參數(shù)是調(diào)用時(shí)賦值的參數(shù)——輸入?yún)?shù)
[out] 該參數(shù)在函數(shù)返回時(shí)被賦值——輸出參數(shù)
[in/out] 該參數(shù)在函數(shù)調(diào)用時(shí)作為輸入、函數(shù)返回時(shí)作為輸出參數(shù)
第2章 QTTS開(kāi)發(fā)接口說(shuō)明
2.1 QTTS接口簡(jiǎn)介
2.1.1 QTTS接口函數(shù)列表
在MSP2.0客戶端子系統(tǒng)中關(guān)于TTS提供如下函數(shù)調(diào)用：
函數(shù)名稱 功能簡(jiǎn)介
QTTSInit 初始化MSC的TTS部分
QTTSSessionBegin 開(kāi)始一個(gè)TTS會(huì)話
QTTSTextPut 輸入要合成的文本
QTTSAudioGet 獲取合成語(yǔ)音
QTTSAudioInfo 獲取音頻相關(guān)信息
QTTSSessionEnd 結(jié)束一路會(huì)話
QTTSGetParam 獲取合成參數(shù)
QTTSLogEvent 將用戶發(fā)送的時(shí)間信息記入服務(wù)器端日志
QTTSFini 逆初始化MSC的TTS部分
對(duì)應(yīng)的寬字符接口如下：
函數(shù)名稱 功能簡(jiǎn)介
QTTSInitW 初始化MSC的TTS部分
QTTSSessionBeginW 開(kāi)始一個(gè)TTS會(huì)話
QTTSTextPutW 輸入要合成的文本
QTTSAudioGetW 獲取合成語(yǔ)音
QTTSAudioInfoW 獲取音頻相關(guān)信息
QTTSSessionEndW 結(jié)束一路會(huì)話
QTTSGetParamW 獲取合成參數(shù)
QTTSLogEventW 將用戶發(fā)送的時(shí)間信息記入服務(wù)器端日志
QTTSFini 逆初始化MSC的TTS部分
寬字符接口的使用和窄字符并沒(méi)有本質(zhì)的不同，只是char型的數(shù)據(jù)換成了wchar_t，所以后面對(duì)各個(gè)函數(shù)的說(shuō)明將以窄字符接口為例。
2.1.2 返回值說(shuō)明
對(duì)于開(kāi)發(fā)接口，如果調(diào)用成功，返回值為int型的接口都會(huì)返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h；對(duì)于返回值為指針類型的，函數(shù)執(zhí)行成功返回非0指針，否則返回空指針0，錯(cuò)誤代碼可以通過(guò)相關(guān)的回傳參數(shù)查看。具體的錯(cuò)誤原因可以結(jié)合MSC日志進(jìn)行分析。
對(duì)于出現(xiàn)在參數(shù)列表中用于返回錯(cuò)誤碼的回傳參數(shù)，如QTTSSessionBegin中的errorCode參數(shù)，用戶可以傳入NULL，此時(shí)MSC會(huì)忽略這個(gè)參數(shù)，此種情況下將不會(huì)有錯(cuò)誤碼返回，用戶可以通過(guò)查看MSC的日志來(lái)了解程序執(zhí)行中的一些信息。
2.1.3 開(kāi)發(fā)包組件
Windows平臺(tái)
開(kāi)發(fā)組件 組件組成 說(shuō)明
頭文件 qtts.h, qisr.h 接口函數(shù)的聲明
動(dòng)態(tài)引入庫(kù) msc.lib 包含接口函數(shù)的引入
運(yùn)行時(shí)刻庫(kù) msc.dll 接口函數(shù)的具體實(shí)現(xiàn)
客戶端配置文件 msc.cfg 運(yùn)行庫(kù)的相關(guān)配置項(xiàng)
Mobile平臺(tái)
開(kāi)發(fā)組件 組件組成 說(shuō)明
頭文件 qtts.h, qisr.h 接口函數(shù)的聲明
動(dòng)態(tài)引入庫(kù) msc.lib 包含接口函數(shù)的引入
運(yùn)行時(shí)刻庫(kù) msc.dll 接口函數(shù)的具體實(shí)現(xiàn)
客戶端配置文件 msc.cfg 運(yùn)行庫(kù)的相關(guān)配置項(xiàng)
iPhone平臺(tái)
開(kāi)發(fā)組件 組件組成 說(shuō)明
頭文件 qtts.h, qisr.h 接口函數(shù)的聲明
靜態(tài)庫(kù) libmsc.a 接口函數(shù)的具體實(shí)現(xiàn)
2.1.4 開(kāi)發(fā)包支持情況
開(kāi)發(fā)包類型 Windows Windows Mobile
本地開(kāi)發(fā) 支持 支持
2.2 函數(shù)調(diào)用
2.2.1 QTTSInit
函數(shù)原型
int TTSLIBAPI QTTSInit(const char* configs)
功能
對(duì)MSC在合成過(guò)程中用到的全局配置項(xiàng)參數(shù)進(jìn)行初始化，如服務(wù)器地址、訪問(wèn)超時(shí)設(shè)置等。
參數(shù)
configs[in]
初始化時(shí)傳入的字符串，以指定合成用到的一些配置參數(shù)，各個(gè)參數(shù)以“參數(shù)名=參數(shù)值”的形式出現(xiàn)，大小寫(xiě)不敏感，不同的參數(shù)之間以“,”或“\n”隔開(kāi)，可以設(shè)置的參數(shù)列表如下（不設(shè)置任何值時(shí)可以傳入NULL或空串）：
返回值 意義
server_url MSP服務(wù)器URL，格式：域名:端口號(hào)/資源名，如dev.voicecloud.cn:80/index.htm。
默認(rèn)值為：dev.voicecloud.cn:80/index.htm。
timeout 與服務(wù)器交互超時(shí)間隔，單位毫秒，缺省值為30000。
coding_libs 合成時(shí)所用編解碼庫(kù)的名字，可用的有amr.dll、amr_fx.dl、 amr_wb.dll、amr_wb_fx.dll和speex.dll，默認(rèn)值為speex.dll。同時(shí)加載多個(gè)編解碼庫(kù)時(shí)各個(gè)編解碼庫(kù)用“;”隔開(kāi)，如：coding_libs=speex.dll; amr-wb.dll。
max_text_size 最大合成文本長(zhǎng)度，0-4096，不在此范圍內(nèi)的值無(wú)效，MSC將使用默認(rèn)值1024。
返回值
如果函數(shù)調(diào)用成功返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h。主要的值如下：
返回值 意義
MSP_ERROR_CONFIG_INITIALIZE 初始化TTS的config實(shí)例時(shí)出現(xiàn)錯(cuò)誤。
說(shuō)明
本函數(shù)在進(jìn)行語(yǔ)音合成時(shí)必須第一個(gè)被調(diào)用。configs參數(shù)字符串中的參數(shù)對(duì)TTS有重要影響，如合成文本最大字節(jié)數(shù)這一參數(shù)，如果用戶實(shí)際發(fā)送的合成文本長(zhǎng)度大于設(shè)定的最大字節(jié)數(shù)，則QTTSTextPut接口會(huì)直接返回錯(cuò)誤。
configs可設(shè)置的參數(shù)在MSC的配置文件中也有對(duì)應(yīng)的配置項(xiàng)，優(yōu)先級(jí)是configs字符串中的值高于配置文件中指定的值。
實(shí)際應(yīng)用時(shí)，QTTSInit應(yīng)當(dāng)在應(yīng)用程序初始化時(shí)僅調(diào)用一次，多次調(diào)用本函數(shù)（中間沒(méi)有調(diào)QTTSFini）時(shí)只有第一次調(diào)用此函數(shù)會(huì)進(jìn)行實(shí)際的初始化工作，configs字符串中的內(nèi)容會(huì)被配置到關(guān)于TTS的配置項(xiàng)中，后面的調(diào)用會(huì)返回成功，但不會(huì)完成實(shí)際的初始化工作。同樣QTTSFini也應(yīng)當(dāng)在應(yīng)用程序退出時(shí)僅調(diào)用一次。
用法示例
const char* configs=“server_url=dev.voicecloud.cn, coding_libs=amr_wb.dll;speex.dll”;
int ret = QTTSInit( configs );
if( 0 != ret )
{
printf( “QTTSInit failed, error code is: %d”, ret );
}
參見(jiàn)
QTTSFini。
2.2.2 QTTSSessionBegin
函數(shù)原型
TTSLIBAPI const char* QTTSSessionBegin(const char* params, int* errorCode)
功能
開(kāi)始一路TTS會(huì)話，并在參數(shù)中指明本路會(huì)話用到的參數(shù)。
參數(shù)
params[in]
本路TTS會(huì)話使用的參數(shù)?？梢栽O(shè)置的參數(shù)及其取值范圍請(qǐng)參考《可設(shè)置參數(shù)列表_MSP20.xls》；各個(gè)參數(shù)以“參數(shù)名=參數(shù)值”的形式出現(xiàn)，不同的參數(shù)之間以“,”或者“\n”隔開(kāi)。
errorCode [out]
如果函數(shù)調(diào)用成功返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h，幾個(gè)主要的返回值如下：
返回值 意義
MSP_ERROR_NOT_INIT 未初始化
MSP_ERROR_INVALID_PARA 無(wú)效的參數(shù)
MSP_ERROR_NO_LICENSE 開(kāi)始一路會(huì)話失敗
返回值
MSC為本路會(huì)話建立的ID，用來(lái)唯一的標(biāo)識(shí)本路會(huì)話，供以后調(diào)用其他函數(shù)時(shí)使用。函數(shù)調(diào)用失敗則會(huì)返回NULL。
說(shuō)明
此處設(shè)定的參數(shù)在本路會(huì)話中一直有效。此函數(shù)需要和接口QTTSSessionEnd()配對(duì)使用，在這兩個(gè)接口之間可以調(diào)用實(shí)際完成合成功能的接口如寫(xiě)入合成文本和取音頻數(shù)據(jù)等。沒(méi)有調(diào)用此函數(shù)則后續(xù)的函數(shù)調(diào)用會(huì)因?yàn)闆](méi)有合法的會(huì)話ID而無(wú)法完成對(duì)應(yīng)的功能。
用戶調(diào)用此函數(shù)時(shí)，可以使用參數(shù)ssm=1或0來(lái)指定是否使用會(huì)話模式。在會(huì)話模式下，用戶和服務(wù)器之間的多次交互都被相互關(guān)聯(lián)起來(lái)，所以會(huì)話模式可以完成一些較為復(fù)雜的功能，比如，將合成音頻分段返回，返回當(dāng)前音頻對(duì)應(yīng)的文本位置等信息。非會(huì)話模式下，MSC發(fā)往服務(wù)器的請(qǐng)求響應(yīng)中攜帶合成參數(shù)和文本，服務(wù)器在應(yīng)答響應(yīng)中返回全部合成音頻，多次請(qǐng)求之間彼此獨(dú)立，互不干擾。默認(rèn)為非會(huì)話模式。
用法示例
/* 可設(shè)置的參數(shù)及含義請(qǐng)參考《可設(shè)置參數(shù)列表_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 );
}
參見(jiàn)
QTTSSessionEnd。
2.2.3 QTTSTextPut
函數(shù)原型
int TTSLIBAPI QTTSTextPut(const char* sessionID, const char* textString,
unsigned int textLen, const char* params)
功能
寫(xiě)入要合成的文本。
參數(shù)
sessionID [in]
由QTTSSessionBegin返回過(guò)來(lái)的會(huì)話ID。
textString [in]
用戶將要進(jìn)行合成的文本。
textLen [in]
合成文本的長(zhǎng)度，該長(zhǎng)度為合成文本的字節(jié)數(shù)，來(lái)明確指定。
params [in]
本次合成所用的參數(shù)，只對(duì)本次合成的文本有效。對(duì)于那些既可以出現(xiàn)在本接口中又可以出現(xiàn)在QTTSSessionBegin中的參數(shù)，此處的優(yōu)先級(jí)要高于QTTSSessionBegin中指定的值?？梢栽O(shè)置的參數(shù)有：發(fā)音人、 語(yǔ)速、音量、音頻格式、文本編碼等，這些參數(shù)的具體名稱和含義請(qǐng)參考《可設(shè)置參數(shù)列表_MSP20.xls》。
返回值
如果函數(shù)調(diào)用成功返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h。幾個(gè)主要的值如下：
返回值 意義
MSP_ERROR_NOT_INIT 未初始化
MSP_ERROR_INVALID_HANDLE 無(wú)效的會(huì)話ID
MSP_ERROR_INVALID_PARA 無(wú)效的參數(shù)
MSP_ERROR_INVALID_PARA_VALUE 無(wú)效的參數(shù)值
MSP_ERROR_NO_ENOUGH_BUFFER 發(fā)送的文本長(zhǎng)度超過(guò)最大允許長(zhǎng)度
說(shuō)明
在非會(huì)話模式下，MSC會(huì)將文本暫時(shí)保存，等到用戶調(diào)用QTTSAudioGet()時(shí)，將文本發(fā)送到服務(wù)器端進(jìn)行合成，如果連續(xù)多次調(diào)用本接口，則后面的文本會(huì)覆蓋前面的文本。在會(huì)話模式下，MSC會(huì)將本次傳入的全部文本發(fā)送到服務(wù)器端，用戶以后可以反復(fù)調(diào)用QTTSAudioGet()來(lái)獲取音頻。會(huì)話模式。
用法示例
const char* text_str = “安徽科大訊飛信息科技股份有限公司”;
unsigned int text_len = strlen( textString ); //textLen參數(shù)為合成文本所占字節(jié)數(shù)
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 );
}
參見(jiàn)
QTTSAudioGet。
2.2.4 QTTSAudioGet
函數(shù)原型
const void* TTSLIBAPI QTTSAudioGet(const char* sessionID, unsigned int* audioLen, int* synthStatus, int*
errorCode)
功能
獲取合成的音頻。
參數(shù)
sessionID [in]
由QTTSSessionBegin返回過(guò)來(lái)的會(huì)話ID。
audioLen [out]
合成音頻長(zhǎng)度。
synthStatus [out]
合成音頻狀態(tài)，可能的值如下：
枚舉常量 簡(jiǎn)介
TTS_FLAG_STILL_HAVE_DATA = 1 音頻還沒(méi)取完，還有后繼的音頻
TTS_FLAG_DATA_END = 2 音頻已經(jīng)取完
TTS_FLAG_CMD_CANCELED = 3 保留
errorCode [out]
如果函數(shù)調(diào)用成功返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h，幾個(gè)主要的值如下：
返回值 意義
MSP_ERROR_NOT_INIT 未初始化
MSP_ERROR_INVALID_HANDLE 無(wú)效的會(huì)話ID
MSP_ERROR_INVALID_PARA 無(wú)效的參數(shù)
MSP_ERROR_NO_MORE_DATA 沒(méi)有更多的數(shù)據(jù)（音頻已經(jīng)取完）
返回值
如果函數(shù)調(diào)用成功返回合成音頻的起始地址，否則返回空指針。
說(shuō)明
用戶需要反復(fù)調(diào)用此接口，在errorCode返回值為0的情況下直到synthStatus返回TTS_FLAG_DATA_END（音頻已經(jīng)取完）為止。
在非會(huì)話模式下，調(diào)用本函數(shù)時(shí)，MSC會(huì)將用戶傳入的文本和本次會(huì)話的參數(shù)打包成消息發(fā)送至服務(wù)器并阻塞當(dāng)前線程等待服務(wù)器的響應(yīng)，如果在此期間響應(yīng)消息到來(lái)，則本函數(shù)會(huì)成功得到合成的音頻數(shù)據(jù)；在預(yù)定的時(shí)間內(nèi)沒(méi)有響應(yīng)消息到來(lái)，errorCode會(huì)被設(shè)置為一個(gè)關(guān)于等待超時(shí)的錯(cuò)誤碼。
在會(huì)話模式下，調(diào)用本函數(shù)時(shí)，MSC會(huì)向服務(wù)器發(fā)送一個(gè)獲取音頻的命令，服務(wù)器返回一定數(shù)量的音頻，并返回音頻對(duì)應(yīng)的文本位置以及音頻是否取完等信息。音頻對(duì)應(yīng)的文本信息可以通過(guò)調(diào)用QTTSAudioInfo獲取到，由于服務(wù)器每次返回給MSC的只是部分音頻，所以會(huì)話模式的響應(yīng)速度可以達(dá)到很快。
用法示例
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 )
{
/* 用戶可以用其他的方式保存音頻，如寫(xiě)入文件等 */
memcpy( synth_speech + speech_len, audio_data, audio_len );
speech_len += audio_len;
}
}
參見(jiàn)
無(wú)。
2.2.5 QTTSAudioInfo
函數(shù)原型
const char* TTSLIBAPI QTTSAudioInfo(const char* sessionID)
功能
獲取關(guān)于合成音頻的某些信息如合成音頻對(duì)應(yīng)的當(dāng)前文本位置等。
參數(shù)
sessionID [in]
由QTTSSessionBegin返回過(guò)來(lái)的會(huì)話ID。
返回值
如果函數(shù)調(diào)用成功返回字符串指針，否則返回NULL。
說(shuō)明
本接口用于在調(diào)用QTTSAudioGet后，獲取關(guān)于此段音頻的描述信息，目前支持的信息有：此次合成音頻對(duì)應(yīng)文本結(jié)束位置，用戶可以利用此信息來(lái)做實(shí)時(shí)高亮度顯示合成的文本等應(yīng)用，格式為”ced=xxx”。
用法示例
const char* audio_info = QTTSAudioInfo( session_id );
if( NULL == audio_info )
{
printf( “QTTSAudioInfo failed” );
}
參見(jiàn)
QTTSSAudioGet。
2.2.6 QTTSSessionEnd
函數(shù)原型
int TTSLIBAPI QTTSSessionEnd(const char* sessionID, const char* hints)
功能
結(jié)束一路TTS會(huì)話。
參數(shù)
sessionID [in]
由QTTSSessionBegin返回過(guò)來(lái)的會(huì)話ID。
hints [in]
結(jié)束本次會(huì)話的原因描述，用于記錄日志，便于用戶查閱或者跟蹤某些問(wèn)題。
返回值
如果函數(shù)調(diào)用成功返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h。幾個(gè)主要的返回值如下：
返回值 意義
MSP_ERROR_NOT_INIT 未初始化
MSP_ERROR_INVALID_HANDLE 無(wú)效的會(huì)話ID
說(shuō)明
本接口對(duì)應(yīng)于QTTSSessionBegin()接口，用來(lái)結(jié)束一路TTS會(huì)話。如果用戶在完成一路TTS會(huì)話后，不調(diào)用本函數(shù)而直接調(diào)用QTTSFini()，則會(huì)返回錯(cuò)誤碼提示“仍有活躍的實(shí)例”。
調(diào)用本函數(shù)后，關(guān)于當(dāng)前會(huì)話的所有資源（參數(shù)，合成文本，會(huì)話實(shí)例等）都會(huì)被釋放，所以用戶不應(yīng)該再針對(duì)該實(shí)例做任何操作（比如使用其會(huì)話ID等）。ed=xxx”。
用法示例
int ret = QTTSSessionEnd ( session_id, “normal end” );
if( 0 != ret )
{
printf( “QTTSSessionEnd failed, error code is: %d”, ret );
}
參見(jiàn)
QTTSSessionBegin
QTTSFini。
2.2.7 QTTSGetParam
函數(shù)原型
int TTSLIBAPI QTTSGetParam(const char* sessionID, const char* paramName,
char* paramValue, unsigned int* valueLen)
功能
查詢MSC記錄下來(lái)的一些信息如數(shù)據(jù)上傳或下載的數(shù)據(jù)量等。
參數(shù)
sessionID [in]
由QISRSessionBegin返回過(guò)來(lái)的會(huì)話ID。
paramName [in]
要獲取的參數(shù)名稱；支持同時(shí)查詢多個(gè)參數(shù)，查詢多個(gè)參數(shù)時(shí)，參數(shù)名稱按“,” 或“\n”分隔開(kāi)來(lái)。
paraValue [out]
獲取的參數(shù)值，以字符串形式返回；查詢多個(gè)參數(shù)時(shí)，參數(shù)值之間按“;”分隔開(kāi)來(lái)，不支持的參數(shù)將返回空的值。
valueLen [in/out]
輸入的是存放參數(shù)值字符串paraValue緩沖區(qū)的長(zhǎng)度，輸出為參數(shù)值字符串的長(zhǎng)度。
返回值
如果函數(shù)調(diào)用成功返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h。幾個(gè)主要的返回值如下：
返回值 意義
MSP_ERROR_NOT_INIT 未初始化
MSP_ERROR_INVALID_HANDLE 無(wú)效的會(huì)話ID
MSP_ERROR_INVALID_PARA 無(wú)效的參數(shù)
說(shuō)明
目前支持的參數(shù)如下：
參數(shù)名稱 意義
upflow 上傳數(shù)據(jù)量，單位：Byte。如果函數(shù)調(diào)用發(fā)生在會(huì)話結(jié)束之后（QTTSSessionEnd之后），獲取到的是從QTTSInit開(kāi)始上行的數(shù)據(jù)總量；如果是在會(huì)話中間調(diào)用，獲取到的是當(dāng)前會(huì)話此刻的上行數(shù)據(jù)量。
downflow 下載數(shù)據(jù)量，單位：Byte。如果函數(shù)調(diào)用發(fā)生在會(huì)話結(jié)束之后（QTTSSessionEnd之后），獲取到的是從QTTSInit開(kāi)始下行的數(shù)據(jù)總量；如果是在會(huì)話中間調(diào)用，獲取到的是當(dāng)前會(huì)話此刻的下行數(shù)據(jù)量。
用法示例
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 );
}
參見(jiàn)
無(wú)。
2.2.8 QTTSFini
函數(shù)原型
int TTSLIBAPI QTTSFini(void)
功能
對(duì)MSC進(jìn)行逆初始化。
參數(shù)
無(wú)。
返回值
如果函數(shù)調(diào)用成功返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h。主要的返回值如下：
返回值 意義
MSP_ERR_STILL_EXIST_ACTIVE_INSTANCE 仍然有活躍的Session實(shí)例
說(shuō)明
本接口對(duì)應(yīng)于QTTSInit接口，在使用TTS功能時(shí)最后一個(gè)被調(diào)用，用來(lái)對(duì)MSC的TTS部分進(jìn)行逆初始化。沒(méi)有調(diào)用QTTSInit()直接調(diào)用本接口，則不會(huì)有任何效果，調(diào)用了QTTSInit()不調(diào)用本接口而直接結(jié)束線程，則MSC會(huì)產(chǎn)生資源泄漏。
本函數(shù)正常的調(diào)用場(chǎng)景是當(dāng)前活躍的TTS實(shí)例數(shù)為0（釋放一個(gè)活躍的實(shí)例使用QTTSSessionEnd()函數(shù)）。如果當(dāng)前活躍的TTS實(shí)例數(shù)不為0，則說(shuō)明用戶在使用函數(shù)時(shí)的時(shí)序有問(wèn)題，這種情況將會(huì)返回關(guān)于“活躍的實(shí)例數(shù)不為空”的錯(cuò)誤碼。
用法示例
int ret = QTTSFini();
if( 0 != ret )
{
printf( “QTTSFini failed, error code is: %d”, ret );
}
參見(jiàn)
QTTSInit
QTTSSessionEnd。。
第3章 QISR開(kāi)發(fā)接口說(shuō)明
3.1 QISR接口簡(jiǎn)介
3.1.1 QISR接口函數(shù)列表
在MSP2.0客戶端子系統(tǒng)中關(guān)于ISR提供如下函數(shù)調(diào)用：
函數(shù)名稱 功能簡(jiǎn)介
QISRInit 初始化MSC的ISR部分
QISRSessionBegin 開(kāi)始一個(gè)ISR會(huì)話
QISRGrammarActivate 傳入語(yǔ)法
QISRAudioWrite 寫(xiě)入用來(lái)識(shí)別的語(yǔ)音
QISRGetResult 獲取識(shí)別結(jié)果
QISRUploadData 上傳用戶自定義數(shù)據(jù)
QISRSessionEnd 結(jié)束一路會(huì)話
QISRGetParam 獲取與識(shí)別交互相關(guān)的參數(shù)
QISRFini 逆初始化MSC的ISR部分
對(duì)應(yīng)的寬字符接口如下：
函數(shù)名稱 功能簡(jiǎn)介
QISRInitW 初始化MSC的ISR部分
QISRSessionBeginW 開(kāi)始一個(gè)ISR會(huì)話
QISRGrammarActivateW 傳入語(yǔ)法
QISRAudioWriteW 寫(xiě)入用來(lái)識(shí)別的語(yǔ)音
QISRGetResultW 獲取識(shí)別結(jié)果
QISRSessionEndW 結(jié)束一路會(huì)話
QISRGetParamW 獲取與識(shí)別交互相關(guān)的參數(shù)
QISRFini 逆初始化MSC的ISR部分
寬字符接口的使用和窄字符并沒(méi)有什么不同，只是char型的數(shù)據(jù)換成了wchar_t，所以后面對(duì)各個(gè)函數(shù)的說(shuō)明將以窄字符接口為例。
本組接口不是線程安全的，用戶需要自行保證某些數(shù)據(jù)的線程安全性，如sessionID。
3.1.2 返回值說(shuō)明
對(duì)于開(kāi)發(fā)接口，如果調(diào)用成功，返回值為int型的接口都會(huì)返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h；對(duì)于返回值為指針類型的，函數(shù)執(zhí)行成功返回非0指針，否則返回空指針0，錯(cuò)誤代碼可以通過(guò)相關(guān)的回傳參數(shù)查看。具體的錯(cuò)誤原因可以結(jié)合MSC日志進(jìn)行分析。
對(duì)于出現(xiàn)在參數(shù)列表中用于返回錯(cuò)誤碼的回傳參數(shù)，如QISRSessionBegin中的errorCode參數(shù)，用戶可以傳入NULL，此時(shí)MSC會(huì)忽略這個(gè)參數(shù)，此種情況下將不會(huì)有錯(cuò)誤碼返回，用戶可以通過(guò)查看MSC的日志來(lái)了解程序執(zhí)行中的一些信息。
3.1.3 開(kāi)發(fā)包組件
Windows平臺(tái)
開(kāi)發(fā)組件 組件組成 說(shuō)明
頭文件 qtts.h, qisr.h 接口函數(shù)的聲明
動(dòng)態(tài)引入庫(kù) msc.lib 包含接口函數(shù)的引入
運(yùn)行時(shí)刻庫(kù) msc.dll 接口函數(shù)的具體實(shí)現(xiàn)
客戶端配置文件 msc.cfg 運(yùn)行庫(kù)的相關(guān)配置項(xiàng)
Mobile平臺(tái)
開(kāi)發(fā)組件 組件組成 說(shuō)明
頭文件 qtts.h, qisr.h 接口函數(shù)的聲明
動(dòng)態(tài)引入庫(kù) msc.lib 包含接口函數(shù)的引入
運(yùn)行時(shí)刻庫(kù) msc.dll 接口函數(shù)的具體實(shí)現(xiàn)
客戶端配置文件 msc.cfg 運(yùn)行庫(kù)的相關(guān)配置項(xiàng)
iPhone平臺(tái)
開(kāi)發(fā)組件 組件組成 說(shuō)明
頭文件 qtts.h, qisr.h 接口函數(shù)的聲明
靜態(tài)庫(kù) libmsc.a 接口函數(shù)的具體實(shí)現(xiàn)
3.1.4 開(kāi)發(fā)包支持情況
開(kāi)發(fā)包類型 Windows Windows Mobile
本地開(kāi)發(fā) 支持 支持
3.2 函數(shù)調(diào)用
3.2.1 QISRInit
函數(shù)原型
int ISRAPI QISRInit(const char* configs)
功能
對(duì)MSC在識(shí)別過(guò)程中用到的全局配置項(xiàng)參數(shù)進(jìn)行初始化，如服務(wù)器地址、訪問(wèn)超時(shí)設(shè)置等。
參數(shù)
configs[in]
初始化時(shí)傳入的字符串，以指定識(shí)別或聽(tīng)寫(xiě)用到的一些配置參數(shù)，各個(gè)參數(shù)以“參數(shù)名=參數(shù)值”的形式出現(xiàn)，大小寫(xiě)不敏感，不同的參數(shù)之間以“,”或“\n”隔開(kāi)，可以設(shè)置的參數(shù)列表如下：
返回值 意義
server_url MSP服務(wù)器URL，格式：域名:端口號(hào)/資源名，如dev.voicecloud.cn:80/index.htm。
默認(rèn)值為：dev.voicecloud.cn:80/index.htm。
appid 應(yīng)用程序ID，服務(wù)端根據(jù)此參數(shù)跟蹤應(yīng)用程序信息，需從http://dev.voicecloud.cn/myapp_reg.php?v_t=1 頁(yè)面申請(qǐng)。
timeout 超時(shí)間隔，單位毫秒，缺省值為30000。
coding_libs 音頻壓縮所用編解碼庫(kù)的名字，可用的有amr.dll、amr_fx.dl、 amr_wb.dll、amr_wb_fx.dll和speex.dll，默認(rèn)值為speex.dll。同時(shí)加載多個(gè)編解碼庫(kù)時(shí)各個(gè)編解碼庫(kù)用“;”隔開(kāi)，如：coding_libs=speex.dll; amr-wb.dll。
max_audio_size 最大音頻長(zhǎng)度，單位為Byte，最大值為1MB，缺省值為262144（256KB）。
coding_chunk_size MSC壓縮音頻時(shí)（在用戶還沒(méi)有將音頻發(fā)送完畢時(shí)）每次寫(xiě)入編解碼庫(kù)的音頻大小，單位為Byte，最大值為max_audio_size，默認(rèn)值為5120。
vad_enable 打開(kāi)或關(guān)閉MSC內(nèi)部集成的VAD功能。此配置項(xiàng)取值為true或false（1或0），默認(rèn)為true（1）。
MSC集成的VAD主要功能有本地語(yǔ)音前后端點(diǎn)檢測(cè)、靜音去除、降噪和語(yǔ)音特征提取等，這些功能只有在VAD功能被打開(kāi)時(shí)才能使用。相對(duì)于使用服務(wù)器端的此類功能，本地前后端點(diǎn)檢測(cè)更靈敏（服務(wù)器響應(yīng)有延遲），靜音去除和降噪可以減少發(fā)往服務(wù)器的數(shù)據(jù)量，語(yǔ)音特征提取相對(duì)于語(yǔ)音編碼可以節(jié)省本地CPU資源。
audio_coding 編解碼算法，可取的值為speex、speex-wb、amr、amr-fx、amr-wb、amr-wb-fx、raw，默認(rèn)值為speex-wb。
使用某一種編解碼算法時(shí)必須在coding_libs配置項(xiàng)中加載了對(duì)應(yīng)的編解碼庫(kù)，編解碼算法和編解碼庫(kù)的對(duì)應(yīng)關(guān)系是：
speex-wb & speex: speex.dll
amr: amr.dll
amr-fx: amr_fx.dll
amr-wb: amr_wb.dll
amr-wb-fx: amr_wb_fx.dll
raw：不需要加載動(dòng)態(tài)庫(kù)
conding_level 音頻壓縮編碼等級(jí)。amr系列算法取值范圍為0-7，speex系列為0-10。默認(rèn)值為7。
返回值
如果函數(shù)調(diào)用成功返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h。主要的返回值如下：
返回值 意義
MSP_ERROR_CONFIG_INITIALIZE 初始化ISR的config實(shí)例時(shí)出現(xiàn)錯(cuò)誤。
說(shuō)明
configs參數(shù)字符串中的參數(shù)對(duì)ISR有重要影響，如音頻數(shù)據(jù)的最大長(zhǎng)度這一參數(shù)，如果用戶實(shí)際發(fā)送的音頻數(shù)據(jù)量大于設(shè)定的最大字節(jié)數(shù)，則QISRAudioWrite接口會(huì)直接返回錯(cuò)誤。
configs可設(shè)置的參數(shù)在MSC的配置文件中也有對(duì)應(yīng)的配置項(xiàng)，優(yōu)先級(jí)是configs字符串中的值高于配置文件中指定的值。
實(shí)際應(yīng)用時(shí)，QISRInit應(yīng)當(dāng)在應(yīng)用程序初始化時(shí)僅調(diào)用一次，多次調(diào)用本函數(shù)（中間沒(méi)有調(diào)QISRFini）時(shí)只有第一次調(diào)用此函數(shù)會(huì)進(jìn)行實(shí)際的初始化工作，configs字符串中的內(nèi)容會(huì)被配置到關(guān)于ISR的配置項(xiàng)中，后面的調(diào)用會(huì)返回成功，但不會(huì)完成實(shí)際的初始化工作。同樣QISRFini也應(yīng)當(dāng)在應(yīng)用程序退出時(shí)僅調(diào)用一次。時(shí)僅調(diào)用一次。
用法示例
const char* configs=“server_url=dev.voicecloud.cn, timeout=10000, vad_enable=true”;
int ret = QISRInit( configs );
if( 0 != ret )
{
printf( “QISRInit failed, error code is: %d”, ret );
}
參見(jiàn)
QISRFini。
3.2.2 QISRSessionBegin
函數(shù)原型
const char* ISRAPI QISRSessionBegin(const char* grammarList, const char*
params, int *errorCode);
功能
本接口用來(lái)開(kāi)始一路ISR會(huì)話，并在參數(shù)中指定本路ISR會(huì)話用到的語(yǔ)法列表，本次會(huì)話所用的參數(shù)等。
參數(shù)
grammarList[in]
uri-list格式的語(yǔ)法，可以是一個(gè)語(yǔ)法文件的URL或者一個(gè)引擎內(nèi)置語(yǔ)法列表?？梢酝瑫r(shí)指定多個(gè)語(yǔ)法，不同的語(yǔ)法之間以“,”隔開(kāi)。進(jìn)行語(yǔ)音聽(tīng)寫(xiě)時(shí)不需要語(yǔ)法，此參數(shù)設(shè)定為NULL或空串即可；進(jìn)行語(yǔ)音識(shí)別時(shí)則需要語(yǔ)法，語(yǔ)法可以在此參數(shù)中指定，也可以隨后調(diào)用QISRGrammarActivate指定識(shí)別所用的語(yǔ)法。
params[in]
本路ISR會(huì)話使用的參數(shù)，可設(shè)置的參數(shù)及其取值范圍請(qǐng)參考《可設(shè)置參數(shù)列表_MSP20.xls》，各個(gè)參數(shù)以“參數(shù)名=參數(shù)值”的形式出現(xiàn)，不同的參數(shù)之間以“,”或者“\n”隔開(kāi)。
errorCode[out]
如果函數(shù)調(diào)用成功則其值為0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h。幾個(gè)主要的返回值如下：
返回值 意義
MSP_ERROR_NOT_INIT 未初始化
MSP_ERROR_INVALID_PARA 無(wú)效的參數(shù)
MSP_ERROR_NO_LICENSE 開(kāi)始一路會(huì)話失敗
返回值
MSC為本路會(huì)話建立的ID，用來(lái)唯一的標(biāo)識(shí)本路會(huì)話，供以后調(diào)用其他函數(shù)時(shí)使用。函數(shù)調(diào)用失敗則會(huì)返回NULL。
說(shuō)明
此處設(shè)定的參數(shù)在本路會(huì)話中一直有效。此函數(shù)需要和接口QISRSessionEnd()配對(duì)使用，在這兩個(gè)接口之間可以調(diào)用實(shí)際完成識(shí)別功能的接口如激活語(yǔ)法、寫(xiě)入音頻和獲取結(jié)果等。沒(méi)有調(diào)用此函數(shù)則MSC不會(huì)建立和當(dāng)前線程有關(guān)的會(huì)話實(shí)例，后續(xù)的函數(shù)調(diào)用會(huì)因?yàn)闆](méi)有合法的會(huì)話ID而無(wú)法完成對(duì)應(yīng)的功能。
用戶調(diào)用此函數(shù)時(shí)，可以使用參數(shù)ssm=1或0來(lái)指定是否在本次會(huì)話中使用會(huì)話模式。在會(huì)話模式下，用戶和服務(wù)器之間的多次交互都被相互關(guān)聯(lián)，所以會(huì)話模式可以完成一些較為復(fù)雜的功能，比如，當(dāng)識(shí)別或轉(zhuǎn)寫(xiě)音頻數(shù)據(jù)量比較大時(shí)，可以把數(shù)據(jù)分段發(fā)往服務(wù)器端，這種工作方式可以使得用戶邊采集音頻邊發(fā)送，另一方面也提高了服務(wù)器的響應(yīng)速度。非會(huì)話模式下，MSC發(fā)往服務(wù)器的請(qǐng)求響應(yīng)中攜帶識(shí)別參數(shù)和音頻數(shù)據(jù)，服務(wù)器在應(yīng)答響應(yīng)中返回全部識(shí)別結(jié)果，多次請(qǐng)求之間彼此獨(dú)立，互不干擾。程序默認(rèn)為非會(huì)話模式。
語(yǔ)音聽(tīng)寫(xiě)可以將用戶輸入的語(yǔ)音轉(zhuǎn)換成與之對(duì)應(yīng)的文字并返回給用戶，同普通的識(shí)別相比，它不需要語(yǔ)法。用戶需要在參數(shù)中使用sub=iat來(lái)指明本次會(huì)話為語(yǔ)音聽(tīng)寫(xiě)會(huì)話。程序默認(rèn)的sub=asr即普通的識(shí)別會(huì)話。
對(duì)于那些可以出現(xiàn)在QISRInit函數(shù)的 configs字符串中又可以出現(xiàn)在本函數(shù)的params中的參數(shù)，比如音頻編碼格式“aue”，在本次會(huì)話中，這些參數(shù)的優(yōu)先級(jí)次序是：params指定的值>configs指定的值>配置文件中指定的值。本路會(huì)話params中指定的值不會(huì)影響到其他的會(huì)話。
用法示例
/* vad_timeout和vad_speech_tail兩個(gè)參數(shù)只有在打開(kāi)VAD功能時(shí)才生效 */
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 );
}
參見(jiàn)
QISRSessionEnd。
3.2.3 QISRGrammarActivate
函數(shù)原型
int ISRAPI QISRGrammarActivate(const char* sessionID, const char* grammar,
const char* type, int weight);
功能
本函數(shù)用來(lái)激活一個(gè)指定的語(yǔ)法，語(yǔ)法類型可以是任何一種合法的語(yǔ)法。
參數(shù)
sessionID [in]
由QISRSessionBegin返回過(guò)來(lái)的會(huì)話ID。
grammar [in]
語(yǔ)法字符串。
type [in]
語(yǔ)法類型，可以是uri-list、abnf、xml等。
weight [in]
本次傳入語(yǔ)法的權(quán)重，本參數(shù)在MSP 2.0中會(huì)被忽略。
返回值
如果函數(shù)調(diào)用成功返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h。幾個(gè)主要的返回值如下：
返回值 意義
MSP_ERROR_NOT_INIT 未初始化
MSP_ERROR_INVALID_HANDLE 無(wú)效的會(huì)話ID
MSP_ERROR_INVALID_PARA 無(wú)效的參數(shù)
MSP_ERROR_NO_DATA 沒(méi)有（語(yǔ)法）數(shù)據(jù)
說(shuō)明
在一路會(huì)話中，用戶可以調(diào)用此接口定義一個(gè)或多個(gè)語(yǔ)法，多個(gè)語(yǔ)法之間以“,”隔開(kāi)，此接口定義的語(yǔ)法和QISRSessionBegin () 指定的語(yǔ)法彼此之間相互獨(dú)立，地位平等，互不干擾，用戶可以通過(guò)查看識(shí)別結(jié)果中的grammar字段來(lái)了解識(shí)別結(jié)果對(duì)應(yīng)的語(yǔ)法。定義的語(yǔ)法從定義成功時(shí)刻到會(huì)話結(jié)束時(shí)一直有效。具體的識(shí)別語(yǔ)法編寫(xiě)規(guī)范可以參閱：
Speech Recognition Grammar Specification Version 1.0用法示例
/* 激活引擎內(nèi)置的歌曲搜索的語(yǔ)法 */
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 );
}
參見(jiàn)
無(wú)。
3.2.4 QISRAudioWrite
函數(shù)原型
int ISRAPI QISRAudioWrite(const char* sessionID, const void* waveData, unsigned
int waveLen, int audioStatus, int* epStatus, int* recogStatus );
功能
寫(xiě)入本次識(shí)別的音頻，音頻可以一次性寫(xiě)入，也可以多次調(diào)用此接口分批寫(xiě)入。
參數(shù)
sessionID [in]
由QISRSessionBegin返回過(guò)來(lái)的會(huì)話ID。
waveData [in]
音頻數(shù)據(jù)緩沖區(qū)起始地址。
waveLen [in]
音頻數(shù)據(jù)長(zhǎng)度，其大小不能超過(guò)設(shè)定的max_audio_size。
audioStatus [in]
用來(lái)指明用戶本次識(shí)別的音頻是否發(fā)送完畢，可能的值如下：
枚舉常量 簡(jiǎn)介
ISR_AUDIO_SAMPLE_FIRST = 1 第一塊音頻
ISR_AUDIO_SAMPLE_CONTINUE = 2 還有后繼音頻
ISR_AUDIO_SAMPLE_LAST = 3 最后一塊音頻
在MSP20中，ISR_AUDIO_SAMPLE_LAST（0x04）用來(lái)指明當(dāng)前的音頻已經(jīng)發(fā)送完畢，除此之外的任何值都將被MSC視為還有后繼的音頻。
epStatus [out]
端點(diǎn)檢測(cè)（End-point detected）器所處的狀態(tài)，可能的值如下：
枚舉常量 簡(jiǎn)介
ISR_EP_LOOKING_FOR_SPEECH= 0 還沒(méi)有檢測(cè)到音頻的前端點(diǎn)。
ISR_EP_IN_SPEECH = 1 已經(jīng)檢測(cè)到了音頻前端點(diǎn)，正在進(jìn)行正常的音頻處理。
ISR_EP_AFTER_SPEECH = 3 檢測(cè)到音頻的后端點(diǎn)，后繼的音頻會(huì)被MSC忽略。
ISR_EP_TIMEOUT = 4 超時(shí)。
ISR_EP_ERROR = 5 出現(xiàn)錯(cuò)誤。
ISR_EP_MAX_SPEECH = 6 音頻過(guò)大。
當(dāng)epStatus大于等于3時(shí)，用戶應(yīng)當(dāng)停止寫(xiě)入音頻的操作，否則寫(xiě)入MSC的音頻會(huì)被忽略。
recogStatus [out]
識(shí)別器所處的狀態(tài)，可能的值如下：
枚舉常量 簡(jiǎn)介
ISR_REC_STATUS_SUCCESS = 0 識(shí)別成功，此時(shí)用戶可以調(diào)用QISRGetResult來(lái)獲?。ú糠郑┙Y(jié)果。
ISR_REC_STATUS_NO_MATCH = 1 識(shí)別結(jié)束，沒(méi)有識(shí)別結(jié)果
ISR_REC_STATUS_INCOMPLETE = 2 正在識(shí)別中
ISR_REC_STATUS_NON_SPEECH_DETECTED = 3 保留
ISR_REC_STATUS_SPEECH_DETECTED = 4 發(fā)現(xiàn)有效音頻
ISR_REC_STATUS_SPEECH_COMPLETE = 5 識(shí)別結(jié)束
ISR_REC_STATUS_MAX_CPU_TIME = 6 保留
ISR_REC_STATUS_MAX_SPEECH = 7 保留
ISR_REC_STATUS_STOPPED = 8 保留
ISR_REC_STATUS_REJECTED = 9 保留
ISR_REC_STATUS_NO_SPEECH_FOUND = 10 沒(méi)有發(fā)現(xiàn)音頻
返回值
如果函數(shù)調(diào)用成功返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h。幾個(gè)主要的返回值如下：
返回值 意義
MSP_ERROR_NOT_INIT 未初始化
MSP_ERROR_INVALID_HANDLE 無(wú)效的會(huì)話ID
MSP_ERROR_INVALID_PARA 無(wú)效的參數(shù)
MSP_ERROR_INVALID_PARA_VALUE 無(wú)效的參數(shù)值
MSP_ERROR_NO_LICENSE 會(huì)話模式中此前開(kāi)始一路會(huì)話失敗。
說(shuō)明
在會(huì)話模式下，MSC處理音頻的策略是邊接收、邊壓縮（如果音頻編碼格式不為raw）、邊發(fā)送。由于音頻壓縮速度和網(wǎng)絡(luò)速度的限制，如果音頻發(fā)送太快太急（如20倍于音頻碼率），可能會(huì)造成原始音頻或壓縮音頻在MSC中積累過(guò)多，從而造成緩沖區(qū)無(wú)法再容納更多的數(shù)據(jù)而產(chǎn)生“沒(méi)有足夠緩沖區(qū)”的錯(cuò)誤。在非會(huì)話模式下，當(dāng)用戶發(fā)送音頻的累積長(zhǎng)度超過(guò)了max_audio_size的值，則多余靠后音頻會(huì)被忽略，不會(huì)被識(shí)別。當(dāng)用戶在宣布音頻發(fā)送完畢后又再次調(diào)用本接口發(fā)音頻，則上次發(fā)送的音頻會(huì)被清除，并被替換成新寫(xiě)入的音頻。
無(wú)論是會(huì)話模式還是非會(huì)話模式，推薦用戶在發(fā)送音頻時(shí)采取“邊錄邊發(fā)”的方式，即每隔一小段時(shí)間將采集到的音頻通過(guò)本接口寫(xiě)入MSC。這種“邊錄邊發(fā)”的方式在非會(huì)話模式下可以減少壓縮音頻所用的時(shí)間，而在非會(huì)話模式下可以加快結(jié)果返回的速度：發(fā)送靠后的音頻時(shí)，前面的音頻或許已經(jīng)被服務(wù)器處理過(guò)并將部分結(jié)果返回了。
調(diào)用接口時(shí)請(qǐng)?jiān)O(shè)置好audioStatus的值，并檢查返回型參數(shù)epStatus的值，以便及時(shí)了解音頻的前后端點(diǎn)等信息。如果當(dāng)前寫(xiě)入的不是最后一塊音頻，需要將audioStatus的值設(shè)為2（ISR_AUDIO_SAMPLE_CONTINUE）。如果在音頻發(fā)送過(guò)程中檢測(cè)到epStatus的值為3（ISR_EP_AFTER_SPEECH），說(shuō)明系統(tǒng)已經(jīng)檢測(cè)到音頻的后端點(diǎn)，則應(yīng)該立即結(jié)束音頻發(fā)送；如果用戶要在檢測(cè)到音頻后端點(diǎn)之前結(jié)束音頻的發(fā)送，需要將最后一個(gè)音頻數(shù)據(jù)的audioStatus設(shè)為4（ISR_AUDIO_SAMPLE_LAST）。
在會(huì)話模式下，如果識(shí)別狀態(tài)recogStatus值為0（ISR_REC_STATUS_SUCCESS）表示已經(jīng)有部分或全部識(shí)別結(jié)果緩存在MSC中了，用戶可以調(diào)用QISRGetResult獲取這部分結(jié)果，再繼續(xù)調(diào)用QISRAudioWrite以發(fā)送后續(xù)的音頻數(shù)據(jù)（如果結(jié)果還沒(méi)取完的話），這種兩個(gè)接口混調(diào)的方式，可以很快的獲得（部分）識(shí)別結(jié)果，特別是使用較大音頻進(jìn)行語(yǔ)音聽(tīng)寫(xiě)時(shí)。
用法示例
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 )
{
… // 讀取音頻到緩沖區(qū)audio_data中，設(shè)置音頻長(zhǎng)度audio_len，音頻狀態(tài)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 ) /* 檢測(cè)到音頻后端點(diǎn)，停止發(fā)送音頻 */
{
printf( “end point of speech has been detected!” );
break;
}
/* 如果是實(shí)時(shí)采集音頻，可以省略此操作。5KB大小的16KPCM持續(xù)的時(shí)間是160毫秒 */
Sleep( 160 );
}
參見(jiàn)
QISRGetResult。
3.2.5 QISRGetResult
函數(shù)原型
const char * ISRAPI QISRGetResult(const char* sessionID, int* rsltStatus, int waitTime, int *errorCode);
功能
獲取識(shí)別結(jié)果。
參數(shù)
sessionID [in]
由QISRSessionBegin返回過(guò)來(lái)的會(huì)話ID。
rsltStatus [out]
識(shí)別結(jié)果的狀態(tài)，其取值范圍和含義請(qǐng)參考QISRAudioWrite的參數(shù)recogStatus。
waitTime [in]
與服務(wù)器交互的間隔時(shí)間，可以控制和服務(wù)器的交互頻度。單位為ms，建議取值為5000。
errorCode [out]
如果函數(shù)調(diào)用成功返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h。幾個(gè)主要的返回值如下：
返回值 意義
MSP_ERROR_NOT_INIT 未初始化
MSP_ERROR_INVALID_HANDLE 無(wú)效的會(huì)話ID
MSP_ERROR_INVALID_PARA 無(wú)效的參數(shù)
MSP_ERROR_NO_DATA 沒(méi)有數(shù)據(jù)（如沒(méi)有寫(xiě)入識(shí)別所用的音頻等）
MSP_ERROR_NO_LICENSE 先前開(kāi)始一路會(huì)話沒(méi)有成功。
返回值
函數(shù)執(zhí)行失敗返回NULL。函數(shù)執(zhí)行成功并且獲取到識(shí)別結(jié)果時(shí)返回識(shí)別結(jié)果，函數(shù)執(zhí)行成功沒(méi)有獲取到識(shí)別結(jié)果時(shí)返回NULL。
說(shuō)明
在會(huì)話模式下，調(diào)用此函數(shù)只是獲取緩存在MSC中的（部分）識(shí)別結(jié)果，程序不會(huì)阻塞，所以用戶需要反復(fù)調(diào)用此接口，直到識(shí)別結(jié)果獲取完畢（rlstStatus值為5（ISR_REC_STATUS_SPEECH_COMPLETE））或返回錯(cuò)誤碼。使用此接口時(shí)請(qǐng)注意，如果某此成功調(diào)用后沒(méi)有獲得識(shí)別結(jié)果，請(qǐng)將當(dāng)前線程sleep一段時(shí)間后再次調(diào)用，以防止頻繁調(diào)用浪費(fèi)CPU資源。
在非會(huì)話模式下，調(diào)用本函數(shù)時(shí)，MSC會(huì)將用戶傳入的語(yǔ)法和音頻以及本次會(huì)話所用的參數(shù)打包成消息發(fā)送至服務(wù)器并阻塞當(dāng)前線程等待服務(wù)器的響應(yīng)，如果在此期間響應(yīng)消息到來(lái)，則本函數(shù)會(huì)成功得到識(shí)別結(jié)果；如果在預(yù)定的時(shí)間內(nèi)沒(méi)有響應(yīng)消息到來(lái)，則本函數(shù)會(huì)返回一個(gè)關(guān)于等待超時(shí)的錯(cuò)誤碼。
用法示例
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 )
{
/* 用戶可以用其他的方式保存識(shí)別結(jié)果 */
strcat( rslt_str, rec_result );
continue;
}
/* sleep一下很有必要，防止MSC端無(wú)緩存的識(shí)別結(jié)果時(shí)浪費(fèi)CPU資源 */
Sleep( 200 );
}
參見(jiàn)
QISRAudioWrite。
3.2.6 QISRSessionEnd
函數(shù)原型
int ISRAPI QISRSessionEnd(const char* sessionID, const char* hints)
功能
結(jié)束一路ISR會(huì)話。
參數(shù)
sessionID [in]
由QISRSessionBegin返回過(guò)來(lái)的會(huì)話ID。
hints [in]
結(jié)束本次會(huì)話的原因描述，用于記錄日志，便于用戶查閱或者跟蹤某些問(wèn)題。
返回值
如果函數(shù)調(diào)用成功返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h和msp_error.h。幾個(gè)主要的返回值如下：
返回值 意義
MSP_ERROR_NOT_INIT 未初始化
MSP_ERROR_INVALID_HANDLE 無(wú)效的會(huì)話ID
說(shuō)明
本接口需要和QISRSessionBegin()配合使用，用來(lái)結(jié)束一路ISR會(huì)話。
調(diào)用本函數(shù)后，關(guān)于當(dāng)前會(huì)話的所有資源（參數(shù)，語(yǔ)法，音頻，會(huì)話實(shí)例等）都會(huì)被釋放，所以用戶不應(yīng)該再針對(duì)該實(shí)例做任何操作（比如使用其SessionID等）。
用法示例
int ret = QISRSessionEnd ( session_id, “normal end” );
if( 0 != ret )
{
printf( “QISRSessionEnd failed, error code is: %d”, ret );
}
參見(jiàn)
QISRSessionBegin。
3.2.7 QISRGetParam
函數(shù)原型
int ISRAPI QISRGetParam(const char* sessionID, const char* paramName, char*
paramValue, unsigned int* valueLen)
功能
查詢MSC記錄下來(lái)的一些信息如數(shù)據(jù)上傳或下載的數(shù)據(jù)量等。
參數(shù)
sessionID [in]
由QISRSessionBegin返回過(guò)來(lái)的會(huì)話ID。
paramName [in]
要獲取的參數(shù)名稱；支持同時(shí)查詢多個(gè)參數(shù)，查詢多個(gè)參數(shù)時(shí)，參數(shù)名稱按“,” 或“\n”分隔開(kāi)來(lái)。
paraValue [out]
獲取的參數(shù)值，以字符串形式返回；查詢多個(gè)參數(shù)時(shí)，參數(shù)值之間按“;”分隔開(kāi)來(lái)，不支持的參數(shù)將返回空的值。
valueLen [out]
參數(shù)值的長(zhǎng)度。
返回值
如果函數(shù)調(diào)用成功返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h。幾個(gè)主要的返回值如下：
返回值 意義
MSP_ERROR_NOT_INIT 未初始化
MSP_ERROR_INVALID_HANDLE 無(wú)效的會(huì)話ID
MSP_ERROR_INVALID_PARA 無(wú)效的參數(shù)
說(shuō)明
目前支持的參數(shù)如下：
參數(shù)名稱 意義
upflow 上傳數(shù)據(jù)量，單位：Byte。如果函數(shù)調(diào)用發(fā)生在會(huì)話結(jié)束之后（QISRSessionEnd之后），獲取到的是從QISRInit開(kāi)始上行的數(shù)據(jù)總量；如果是在會(huì)話中間調(diào)用，獲取到的是當(dāng)前會(huì)話此刻的上行數(shù)據(jù)量。
downflow 下載數(shù)據(jù)量，單位：Byte。如果函數(shù)調(diào)用發(fā)生在會(huì)話結(jié)束之后（QISRSessionEnd之后），獲取到的是從QISRInit開(kāi)始下行的數(shù)據(jù)總量；如果是在會(huì)話中間調(diào)用，獲取到的是當(dāng)前會(huì)話此刻的下行數(shù)據(jù)量。
volume 最近一次寫(xiě)入的音頻的音量
用法示例
參見(jiàn)2.2.7節(jié)QTTSGetParam。參見(jiàn)
無(wú)。
3.2.8 QISRFini
函數(shù)原型
int ISRAPI QISRFini(void)；
功能
對(duì)MSC的ISR部分進(jìn)行逆初始化。
參數(shù)
無(wú)。
返回值
如果函數(shù)調(diào)用成功返回0，否則返回錯(cuò)誤代碼，錯(cuò)誤代碼參見(jiàn)msp_errors.h。主要的返回值如下：
返回值 意義
MSP_ERR_STILL_EXIST_ACTIVE_INSTANCE 仍然有活躍的Session實(shí)例
說(shuō)明
本函數(shù)需要和QISRInit()配對(duì)使用，沒(méi)有調(diào)用QISRInit()直接調(diào)用本接口，則不會(huì)有任何效果，調(diào)用了QISRInit()不調(diào)用本接口而直接結(jié)束線程，則MSC會(huì)產(chǎn)生資源泄漏。
本函數(shù)是對(duì)MSC關(guān)于ISR部分進(jìn)行全局逆初始化，所以正常的調(diào)用情況是當(dāng)前活躍的ISR實(shí)例數(shù)為0（釋放一個(gè)活躍的實(shí)例使用QISRSessionEnd()函數(shù)）。如果當(dāng)前活躍的ISR實(shí)例數(shù)不為0，則說(shuō)明用戶在使用函數(shù)時(shí)的時(shí)序有問(wèn)題，程序運(yùn)行日志中將會(huì)出現(xiàn)警告信息。
用法示例
int ret = QISRFini();
if( 0 != ret )
{
printf( “QISRFini failed, error code is: %d”, ret );
}
參見(jiàn)
QISRInit。
QISRSessionEnd。
第4章 錯(cuò)誤碼的定義
MSP2.0 客戶端子系統(tǒng)返回的錯(cuò)誤碼都在msp_errors.h中定義，大致可以分為一般錯(cuò)誤、網(wǎng)絡(luò)錯(cuò)誤、資源錯(cuò)誤和HTTP錯(cuò)誤等。
4.1 宏
和錯(cuò)誤碼有關(guān)的宏定義：
#define MSP_HTTP_ERROR (x) ((x) + MSP_ERROR_HTTP_BASE)
將HTTP錯(cuò)誤碼×××映射為12×××，即關(guān)于HTTP的錯(cuò)誤碼后三位同HTTP協(xié)議中定義的錯(cuò)誤碼是一致的。
4.2 錯(cuò)誤碼列表
錯(cuò)誤碼 錯(cuò)誤值 意義
MSP_SUCCESS 0 函數(shù)執(zhí)行成功
MSP_ERROR_FAIL -1 失敗
MSP_ERROR_EXCEPTION -2 異常
MSP_ERROR_GENERAL 10100 基碼
MSP_ERROR_OUT_OF_MEMORY 10101 內(nèi)存越界
MSP_ERROR_FILE_NOT_FOUND 10102 文件沒(méi)有發(fā)現(xiàn)
MSP_ERROR_NOT_SUPPORT 10103 不支持
MSP_ERROR_NOT_IMPLEMENT 10104 沒(méi)有實(shí)現(xiàn)
MSP_ERROR_ACCESS 10105 沒(méi)有權(quán)限
MSP_ERROR_INVALID_PARA 10106 無(wú)效的參數(shù)
MSP_ERROR_INVALID_PARA_VALUE 10107 無(wú)效的參數(shù)值
MSP_ERROR_INVALID_HANDLE 10108 無(wú)效的句柄
MSP_ERROR_INVALID_DATA 10109 無(wú)效的數(shù)據(jù)
MSP_ERROR_NO_LICENSE 10110 沒(méi)有授權(quán)許可
MSP_ERROR_NOT_INIT 10111 沒(méi)有初始化
MSP_ERROR_NULL_HANDLE 10112 空句柄
MSP_ERROR_OVERFLOW 10113 溢出
MSP_ERROR_TIME_OUT 10114 超時(shí)
MSP_ERROR_OPEN_FILE 10115 打開(kāi)文件出錯(cuò)
MSP_ERROR_NOT_FOUND 10116 沒(méi)有發(fā)現(xiàn)
MSP_ERROR_NO_ENOUGH_BUFFER 10117 沒(méi)有足夠的內(nèi)存
MSP_ERROR_NO_DATA 10118 沒(méi)有數(shù)據(jù)
MSP_ERROR_NO_MORE_DATA 10119 沒(méi)有更多的數(shù)據(jù)
MSP_ERROR_SKIPPED 10120 跳過(guò)
MSP_ERROR_ALREADY_EXIST 10121 已經(jīng)存在
MSP_ERROR_LOAD_MODULE 10122 加載模塊失敗
MSP_ERROR_BUSY 10123 忙碌
MSP_ERROR_INVALID_CONFIG 10124 無(wú)效的配置項(xiàng)
MSP_ERROR_VERSION_CHECK 10125 版本錯(cuò)誤
MSP_ERROR_CANCELED 10126 取消
MSP_ERROR_INVALID_MEDIA_TYPE 10127 無(wú)效的媒體類型
MSP_ERROR_CONFIG_INITIALIZE 10128 初始化Config實(shí)例
MSP_ERROR_CREATE_HANDLE 10129 建立句柄
MSP_ERROR_CODING_LIB_NOT_LOAD 10130 編解碼庫(kù)未加載
MSP_ERROR_NET_GENERAL 10200 網(wǎng)絡(luò)一般錯(cuò)誤
MSP_ERROR_NET_OPENSOCK 10201 打開(kāi)套接字
MSP_ERROR_NET_CONNECTSOCK 10202 套接字連接
MSP_ERROR_NET_ACCEPTSOCK 10203 套接字接收
MSP_ERROR_NET_SENDSOCK 10204 發(fā)送
MSP_ERROR_NET_RECVSOCK 10205 接收
MSP_ERROR_NET_INVALIDSOCK 10206 無(wú)效的套接字
MSP_ERROR_NET_BADADDRESS 10207 無(wú)效的地址
MSP_ERROR_NET_BINDSEQUENCE 10208 綁定次序
MSP_ERROR_NET_NOTOPENSOCK 10209 套接字沒(méi)有打開(kāi)
MSP_ERROR_NET_NOTBIND 10210 沒(méi)有綁定
MSP_ERROR_NET_NOTLISTEN 10211 沒(méi)有監(jiān)聽(tīng)
MSP_ERROR_NET_CONNECTCLOSE 10212 連接關(guān)閉
MSP_ERROR_NET_NOTDGRAMSOCK 10213 非數(shù)據(jù)報(bào)套接字
MSP_ERROR_NET_DNS 10214 DNS解析錯(cuò)誤
MSP_ERROR_MSG_GENERAL 10300 消息一般錯(cuò)誤
MSP_ERROR_MSG_PARSE_ERROR 10301 解析
MSP_ERROR_MSG_BUILD_ERROR 10302 構(gòu)建
MSP_ERROR_MSG_PARAM_ERROR 10303 參數(shù)出錯(cuò)
MSP_ERROR_MSG_CONTENT_EMPTY 10304 Content為空
MSP_ERROR_MSG_INVALID_CONTENT_TYPE 10305 Content類型無(wú)效
MSP_ERROR_MSG_INVALID_CONTENT_LENGTH 10306 Content長(zhǎng)度無(wú)效
MSP_ERROR_MSG_INVALID_CONTENT_ENCODE 10307 Content編碼無(wú)效
MSP_ERROR_MSG_INVALID_KEY 10308 Key無(wú)效
MSP_ERROR_MSG_KEY_EMPTY 10309 Key為空
MSP_ERROR_MSG_SESSION_ID_EMPTY 10310 會(huì)話ID為空
MSP_ERROR_MSG_LOGIN_ID_EMPTY 10311 登錄ID為空
MSP_ERROR_MSG_SYNC_ID_EMPTY 10312 同步ID為空
MSP_ERROR_MSG_APP_ID_EMPTY 10313 應(yīng)用ID為空
MSP_ERROR_MSG_EXTERN_ID_EMPTY 10314 擴(kuò)展ID為空
MSP_ERROR_MSG_INVALID_CMD 10315 無(wú)效的命令
MSP_ERROR_MSG_INVALID_SUBJECT 10316 無(wú)效的主題
MSP_ERROR_MSG_INVALID_VERSION 10317 無(wú)效的版本
MSP_ERROR_MSG_NO_CMD 10318 沒(méi)有命令
MSP_ERROR_MSG_NO_SUBJECT 10319 沒(méi)有主題
MSP_ERROR_MSG_NO_VERSION 10320 沒(méi)有版本號(hào)
MSP_ERROR_MSG_MSSP_EMPTY 10321 消息為空
MSP_ERROR_MSG_NEW_RESPONSE 10322 新建響應(yīng)消息失敗
MSP_ERROR_MSG_NEW_CONTENT 10323 新建Content失敗
MSP_ERROR_MSG_INVALID_SESSION_ID 10324 無(wú)效的會(huì)話ID
MSP_ERROR_DB_GENERAL 10400 數(shù)據(jù)庫(kù)一般錯(cuò)誤
MSP_ERROR_DB_EXCEPTION 10401 異常
MSP_ERROR_DB_NO_RESULT 10402 沒(méi)有結(jié)果
MSP_ERROR_DB_INVALID_USER 10403 無(wú)效的用戶
MSP_ERROR_DB_INVALID_PWD 10404 無(wú)效的密碼
MSP_ERROR_DB_CONNECT 10405 連接出錯(cuò)
MSP_ERROR_DB_INVALID_SQL 10406 無(wú)效的SQL
MSP_ERROR_RES_GENERAL 10500 資源一般錯(cuò)誤
MSP_ERROR_RES_LOAD 10501 沒(méi)有加載
MSP_ERROR_RES_FREE 10502 空閑
MSP_ERROR_RES_MISSING 10503 缺失
MSP_ERROR_RES_INVALID_NAME 10504 無(wú)效的名稱
MSP_ERROR_RES_INVALID_ID 10505 無(wú)效的ID
MSP_ERROR_RES_INVALID_IMG 10506 無(wú)效的映像
MSP_ERROR_RES_WRITE 10507 寫(xiě)操作
MSP_ERROR_RES_LEAK 10508 泄露
MSP_ERROR_RES_HEAD 10509 資源頭部錯(cuò)誤
MSP_ERROR_RES_DATA 10510 數(shù)據(jù)出錯(cuò)
MSP_ERROR_RES_SKIP 10511 跳過(guò)
MSP_ERROR_TTS_GENERAL 10600 合成一般錯(cuò)誤
MSP_ERROR_TTS_TEXTEND 10601 文本結(jié)束
MSP_ERROR_TTS_TEXT_EMPTY 10602 文本為空
MSP_ERROR_REC_GENERAL 10700 一般錯(cuò)誤
MSP_ERROR_REC_INACTIVE 10701 處于不活躍狀態(tài)
MSP_ERROR_REC_GRAMMAR_ERROR 10702 語(yǔ)法錯(cuò)誤
MSP_ERROR_REC_NO_ACTIVE_GRAMMARS 10703 沒(méi)有活躍的語(yǔ)法
MSP_ERROR_REC_DUPLICATE_GRAMMAR 10704 語(yǔ)法重復(fù)
MSP_ERROR_REC_INVALID_MEDIA_TYPE 10705 無(wú)效的媒體類型
MSP_ERROR_REC_INVALID_LANGUAGE 10706 無(wú)效的語(yǔ)言
MSP_ERROR_REC_URI_NOT_FOUND 10707 沒(méi)有對(duì)應(yīng)的URI
MSP_ERROR_REC_URI_TIMEOUT 10708 獲取URI內(nèi)容超時(shí)
MSP_ERROR_REC_URI_FETCH_ERROR 10709 獲取URI內(nèi)容時(shí)出錯(cuò)
MSP_ERROR_EP_GENERAL 10800 （EP）一般錯(cuò)誤
MSP_ERROR_EP_NO_SESSION_NAME 10801 （EP）鏈接沒(méi)有名字
MSP_ERROR_EP_INACTIVE 10802 （EP）不活躍
MSP_ERROR_EP_INITIALIZED 10803 （EP）初始化出錯(cuò)
MSP_ERROR_LOGIN_SUCCESS 11000 登錄成功
MSP_ERROR_LOGIN_NO_LICENSE 11001 無(wú)授權(quán)
MSP_ERROR_LOGIN_SESSIONID_INVALID 11002 無(wú)效的SessionID
MSP_ERROR_LOGIN_SESSIONID_ERROR 11003 錯(cuò)誤的SessionID
MSP_ERROR_LOGIN_UNLOGIN 11004 未登錄
MSP_ERROR_LOGIN_INVALID_USER 11005 無(wú)效的用戶
MSP_ERROR_LOGIN_INVALID_PWD 11006 無(wú)效的密碼
MSP_ERROR_LOGIN_SYSTEM_ERROR 11099 系統(tǒng)錯(cuò)誤
MSP_ERROR_HTTP_BASE 12000 HTTP錯(cuò)誤基碼
