# speech

Speech模块管理语音输入功能，提供语音识别功能，可支持用户通过麦克风设备进行语音输入内容。通过plus.speech可获取语音输入管理对象。

## 方法：

- startRecognize: 启动语音识别
- stopRecognize: 停止语音识别
- addEventListener: 监听语音识别事件

## 对象：

- SpeechRecognizeOptions: JSON对象，语音识别参数
- SpeechRecoginzeEvents: 语音识别事件类型

## 回调方法：

- RecognitionEventCallback: 语音识别事件回调函数
- RecognitionSuccessCallback: 语音识别成功回调
- RecognitionErrorCallback : 语音识别失败回调

## 权限：

permissions

    {
    // ...
    "permissions":{
    	// ...
    	"Speech": {
    		"description": "语音输入"
    	}
    }
    }

# SpeechRecognizeOptions

JSON对象，语音识别参数

    interface plus.speech.SpeechRecognizeOptions {
    	attribute Boolean continue;
    	attribute String engine;
    	attribute String lang;
    	attribute Number nbest;
    	attribute String punctuation;
    	attribute Number timeout;
    	attribute Boolean userInterface;
    	attribute EventHandler onstart;
    	attribute EventHandler onend;
    }

## 说明：

控制语音识别引擎内部参数，在JS中为JSON对象，在启动语音识别时使用。

## 属性：

- continue: (Boolean 类型 )语音识别是否采用持续模式

  设置为true表示语音引擎不会根据语音输入自动结束，识别到文本内容将多次调用successCallback函数返回，如果需要结束语音识别则必须调用stopRecognize接口，默认值为false。

- engine: (String 类型 )语音识别引擎标识

  用于兼容多语音识别引擎的浏览器，使用语音识别厂商的产品名称，如未设置或设置不正确则使用运行环境默认的语音识别引擎。 支持以下语音识别引擎： "baidu"-百度语音识别； "iFly"-讯飞语音识别。

- lang: (String 类型 )语音识别引擎的语言

  用于定义语音识别引擎的语言，其取值需符合W3C的Language codes规范。 目前讯飞语音支持以下语言： "zh-cn"-中文，普通话； "en-us"-英语； "zh-cantonese"-中文，粤语； "zh-henanese"-中文，河南话（百度语音识别不支持此语言）。 默认值为"zh-cn"。

- nbest: (Number 类型 )指定识别结果识别包括多候选结果

  用于指定识别结果识别包括多候选结果。如nbest:3，识别返回3个候选结果，默认值为1。

- punctuation: (Boolean 类型 )识别结果中是否包含标点符号

  true表示识别结果文本中包含标点符号，false表示识别结果文本中不包含标点符号。 默认值为true。

- timeout: (Number 类型 )语音识别超时时间

  语音识别超时的时间，单位为ms，默认值为1000（即10秒）。 注：百度语音识别不支持此参数。

- userInterface: (Boolean 类型 )识别时是否显示用户界面

  用于指定识别时是否显示用户界面，设置为true表示显示浏览器内置语音识别界面；设置为false表示不显示浏览器内置语音识别界面。默认值为true。

- onstart: (EventHandler 类型 )语音识别开始事件（已废弃，使用start事件）

  事件函数，语音识别开始启动，在调用startRecognize方法后触发，与onend事件成对触发。 注：iOS平台未支持

- onend: (EventHandler 类型 )语音识别结束事件（已废弃，使用end事件）

  事件函数，语音识别结束，在调用stopRecognize方法后触发，或者在引擎内部自动完成语音识别后触发，与onstart事件成对触发。 注：iOS平台未支持

# SpeechRecoginzeEvents

语音识别事件类型

## 说明：

描述语音过程的触发事件列表，可以通过调用plus.sppech.addEventListener方法进行注册监听。

## 常量：

- start: (String 类型 )开始语音识别

  调用plus.speech.startRecognize方法开始语音识别时触发。 无回调函数参数。

- volumeChange: (String 类型 )音量变化

  开始语音识别后，麦克风录制到的语音音量变化时触发。 回调函数参数event={volume:"Number类型，取值范围0-1"}。

- recognizing: (String 类型 )临时语音识别结果

  返回临时语音识别结果时触发。 回调函数参数event={partialResult:"String类型，临时识别结果"}。

- recognition: (String 类型 )最终语音识别

  返回最终语音识别结果。 回调函数参数event={result:"String类型，最佳识别结果",results:"String数组类型，所有候选结果"}。

- end: (String 类型 )结束语音识别

  调用plus.speech.stopRecognize方法结束语音识别或语音识别完成后自动结束时触发。 无回调函数参数。

- error: (String 类型 )语音识别错误

  语音识别发生错误时触发。 回调函数参数event={code:"Number类型，错误编码",message:"String类型，错误描述信息"}。

# RecognitionEventCallback

语音识别事件回调函数

    void onEvent(event){
    	// Event code
    }

## 说明：

调用plus.speech.addEventListener方法监听语音识别事件的回调函数。

## 参数：

- event: ( JSON ) 可选
  不同事件返回的参数不一样，详情参考SpeechRecoginzeEvents事件说明。

## 返回值：

void : 无

# RecognitionSuccessCallback

语音识别成功回调

    void onSuccess(result){
    	// Recognition success code
    }

## 说明：

语音识别成功时的回调函数，用于返回语音识别出的文本内容。

## 参数：

- result: ( String ) 必选 语音识别出的文本内容

## 返回值：

void : 无

# RecognitionErrorCallback

语音识别失败回调

    void onError(error){
    	// Recognition error code
    }

## 说明：

当语音识别失败时的回调函数，用于返回语音识别失败的错误信息。

## 参数：

- error: ( Exception ) 必选 语音识别失败的错误信息
  可通过error.code（Number类型）获取错误编码； 可通过error.message（String类型）获取错误描述信息。 详细错误描述信息可参考：http://ask.dcloud.net.cn/article/282。

## 返回值：

void : 无