# [speech]()
Speech模块管理语音输入功能，提供语音识别功能，可支持用户通过麦克风设备进行语音输入内容。通过plus.speech可获取语音输入管理对象。
### 方法：
- [startRecognize](http://www.dcloud.io/docs/api/zh_cn/speech.shtml#plus.speech.startRecognize): 启动语音识别
- [stopRecognize](http://www.dcloud.io/docs/api/zh_cn/speech.shtml#plus.speech.stopRecognize): 停止语音识别
### 对象：
- [SpeechRecognizeOption](http://www.dcloud.io/docs/api/zh_cn/speech.shtml#plus.speech.SpeechRecognizeOption): JSON对象，语音识别参数
### 回调方法：
- [RecognitionSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/speech.shtml#plus.speech.RecognitionSuccessCallback): 语音识别成功回调
- [RecognitionErrorCallback ](http://www.dcloud.io/docs/api/zh_cn/speech.shtml#plus.speech.RecognitionErrorCallback%20): 语音识别失败回调
### 权限：
permissions
~~~
"Speech": {
"description": "访问语音插件"
}
~~~
# [startRecognize]()
启动语音识别
~~~
void plus.speech.startRecognize( options, successCB, errorCB );
~~~
### 说明：
启动语音识别时调用，当语音识别成功后通过successCallback回调返回识别出文本内容，调用语音识别失败则通过errorCallback回调返回。
### 参数：
- options: *( [SpeechRecognizeOption](http://www.dcloud.io/docs/api/zh_cn/speech.shtml#plus.speech.SpeechRecognizeOption) ) 必选 *语音识别参数，用于控制语音引擎的各种技术参数
- successCB: *( [RecognitionSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/speech.shtml#plus.speech.RecognitionSuccessCallback) ) 可选 *语音识别成功回调
当语音识别引擎识别数据成功时的回调函数，并返回识别出的文本内容。
- errorCB: *( [RecognitionErrorCallback](http://www.dcloud.io/docs/api/zh_cn/speech.shtml#plus.speech.RecognitionErrorCallback) ) 可选 *语音识别失败时的回调函数
当语音识别引擎识别数据失败时的回调函数，并返回失败的错误信息。
### 返回值：
void : 无
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>Speech Example</title>
<script type="text/javascript">
// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕，现在可以正常调用扩展API
// ...
}, false );
var text=null;
function startRecognize () {
var options = {};
options.engine = 'iFly';
text = "";
alert( "开始语音识别：" );
plus.speech.startRecognize( options, function ( s ) {
text += s;
}, function ( e ) {
alert( "语音识别失败："+e.message );
} );
}
</script>
</head>
<body>
<button onclick="startRecognize">开始识别</button><br/>
<button onclick="alert(text);">识别内容</button>
</body>
</html>
~~~
# [stopRecognize]()
停止语音识别
~~~
void plus.speech.stopRecognize();
~~~
### 说明：
当语音识别完成时或用户取消语音识别时调用，调用此方法将导致errorCallback回调函数的调用。
### 参数：
无
### 返回值：
void : 无
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>Speech Example</title>
<script type="text/javascript">
// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕，现在可以正常调用扩展API
// ...
}, false );
var text=null;
function startRecognize () {
var options = {};
options.engine = 'iFly';
text = "";
alert( "开始语音识别：" );
plus.speech.startRecognize( options, function ( s ) {
text += s;
}, function ( e ) {
alert( "语音识别失败："+e.message );
} );
setTimeout( stopRecognize, 10000 );
}
function stopRecognize(){
plus.speech.stopRecognize();
}
</script>
</head>
<body>
<button onclick="startRecognize">开始识别(10s后自动关闭)</button><br/>
<button onclick="alert(text);">识别内容</button>
</body>
</html>
~~~
# [SpeechRecognizeOption]()
JSON对象，语音识别参数
~~~
interface plus.speech.SpeechRecognizeOption {
attribute DOMString engine;
attribute DOMString service;
attribute Number timeout;
attribute DOMString lang;
attribute Boolean continue;
attribute Number nbest;
attribute Boolean userInterface;
attribute EventHandler onstart;
attribute EventHandler onend;
attribute EventHandler onaudiostart;
attribute EventHandler onaudioend;
attribute EventHandler onrecognizestart;
attribute EventHandler onrecognizeend;
}
~~~
### 说明：
控制语音识别引擎内部参数，在JS中为JSON对象，在启动语音识别时使用。
### 属性：
- engine: *(DOMString 类型)*语音识别引擎标识
用于兼容多语音识别引擎的浏览器，建议使用语音识别厂商的产品名称，如未设置或设置不正确则使用浏览器默认的语音识别引擎。
- service: *(DOMString 类型)*语音识别引擎服务器地址
可使用url地址或ip地址，如service:192.168.1.99指定定制的语音识别引擎服务器。默认值为浏览器内置服务器地址。
- timeout: *(Number 类型)*语音识别超时时间
语音识别超时的时间，单位为ms，如timeout:60000，默认值为10s。
- lang: *(DOMString 类型)*语音识别引擎的语言
用于定义语音识别引擎的语言，其取值需符合W3C的Language codes规范。默认值为浏览器的默认语言。
- continue: *(Boolean 类型)*语音识别是否采用持续模式
设置为true表示语音引擎不会根据语音输入自动结束，识别到文本内容将多次调用successCallback函数返回，如果需要结束语音识别则必须调用stopRecognize接口，默认值为false。
- nbest: *(Number 类型)*指定识别结果识别包括多候选结果
用于指定识别结果识别包括多候选结果。如nbest:3，识别返回3个候选结果，默认值为1。
- userInterface: *(Boolean 类型)*识别时是否显示用户界面
用于指定识别时是否显示用户界面，设置为true表示显示浏览器内置语音识别界面；设置为false表示不显示浏览器内置语音识别界面。默认值为true。
- onstart: *(EventHandler 类型)*语音识别开始事件
事件函数，语音识别开始启动，在调用startRecognize方法后触发，与onend事件成对触发。
- onend: *(EventHandler 类型)*语音识别结束事件
事件函数，语音识别结束，在调用stopRecognize方法后触发，或者在引擎内部自动完成语音识别后触发，与onstart事件成对触发。
- onaudiostart: *(EventHandler 类型)*录音开始事件
事件函数，录音开始事件，启动语音识别后，调用设备麦克风设备开始一段语音录音时触发，与onaudioend事件成对触发。
- onaudioend: *(EventHandler 类型)*录音结束事件
事件函数，录音结束事件，调用麦克风完成一段语音录音时触发，与onaudiostart事件成对触发。
- onrecognizestart: *(EventHandler 类型)*录音识别开始事件
事件函数，录音识别开始事件，开始对语音录音数据分析识别，与onrecognizeend事件成对触发。
- onrecognizeend: *(EventHandler 类型)*录音识别结束事件
事件函数，录音识别结束事件，开始对语音录音数据分析识别完成，与onrecognizestart事件成对触发。
# [RecognitionSuccessCallback]()
语音识别成功回调
~~~
void RecognitionSuccessCallback ( results ) {
// Recognition success code
}
~~~
### 说明：
当语音识别成功时的回调函数，用于返回语音识别出的文本内容。
### 参数：
- results: *( DOMString[] ) 必选 *语音识别出的文本内容数组
语音识别出的候选文本内容，区配度高的在数组的前面，通过其length属性可获取总的候选内容的长度
### 返回值：
void : 无
# [RecognitionErrorCallback ]()
语音识别失败回调
~~~
void RecognitionErrorCallback ( error ) {
// Recognition error code
}
~~~
### 说明：
当语音识别失败时的回调函数，用于返回语音识别失败的错误信息。
### 参数：
- error: *( DOMException ) 必选 *语音识别失败的错误信息
### 返回值：
void : 无
- API参考
- Accelerometer
- Audio
- Camera
- Contacts
- Device
- Downloader
- Events
- Gallery
- Geolocation
- IO
- Key
- Messaging
- NativeUI
- Navigator
- Orientation
- Proximity
- SplashScreen
- Storage
- UI
- Uploader
- InterfaceOrientation
- Runtime
- WebView
- XMLHttpRequest
- Zip
- Plugins
- Barcode
- Maps
- Payment
- Push
- Share
- Speech
- Statistic
- Native.js
- Android
- iOS