# Java SDK 语音识别(Recognizer)

这里介绍的是Java SDK API关于语音识别(Recognizer)的相关说明，点击右侧目录可快速找到相应文件。

# 类SpeechRecognizer

java.lang.Object
com.iflytek.cloud.msc.module.SpeechModule
com.iflytek.cloud.speech.SpeechRecognizer

# 语音识别类

语音识别，包括听写功能。语音识别技术(Auto Speech Recognize， 简称ASR)即把人的自然语言音频数据转换成文本数据。关于文本数据转语音的 功能，请参考语音合成类 SpeechSynthesizer
听写，基于自然语言处理技术，将自然语言转换为文本输出的技术。语音听写不需要基于某个具体的语法文件，其识别 范围是整个语种内的词条。在听写时，应用还可以上传个性化的词表，如联系人 列表等，提高列表中词语的匹配率。关于个性化词表上传，请参考updateLexicon(String, String, LexiconListener)。
本类使用单例，调用者使用本类的对象，只需要通过createRecognizer()创建 一次对象后，便可一直使用该对象，直到通过调用destroy()进行单例对象销毁。调 用者可通过getRecognizer()获取当前已经创建的单例。在销毁本类的单例对象后， 需要先通过createRecognizer()再次创建单例对象，方可再使用。

# 构造器概要

# 构造器和说明

SpeechRecognizer()

# 方法概要

# 从类继承的方法 com.iflytek.cloud.msc.module.SpeechModule

getStaticSync, getSync, setParameter

# 从类继承的方法 java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

# 构造器详细资料

# SpeechRecognizer

public SpeechRecognizer()

# 方法详细资料

# createRecognizer

public static SpeechRecognizer createRecognizer()

# 创建单例对象

使用此函数创建一个本类单例对象。当成功创建一次单例对象后，可一直使用此对象， 直到调用destroy()销毁已创建的单例对象为止。若在当前应用生命周期内调用 destroy()前再次调用本函数，则直接返回已创建的单例对象。可通过 getRecognizer()获取已创建的单例对象。

返回:
识别对象
另请参阅:
destroy(), getRecognizer()

# getRecognizer

public static SpeechRecognizer getRecognizer()

# 获取单例对象

通过函数获取已创建的单例对象。当单例对象未创建时，将返回null，此时应先通过 createRecognizer()创建单例对象。

返回:识别对象
另请参阅:
destroy(), createRecognizer()

# startListening

public abstract void startListening(RecognizerListener listener)

开始录音 调用此函数，开始听写。

目前SDK不支持多线程，所以在调用本函数开始一次会话后，直到结束前(结果返回 完毕，或出现错误)，不能再调用本函数开始新的会话。一次会话，即从会话开始，到结 束为止。

在调用本函数开始听写前，通过setParameter(String, String)设置相 应的参数。

调用本函数开始识别后，通过SDK的录音机录取用户通过麦克风读入的音频（当 SpeechConstant.AUDIO_SOURCE 值>=0时），或由应用层调用 writeAudio(byte[], int, int)写入音频流，获取用于识别的音频。在完成音频 录入（包括麦克风或写音频流方式）后，通过调用stopListening()告知SDK已完 成音频录入，或由SDK自带的VAD（Voice Activity Detection,静音抑制）自动结束音频录 入，见RecognizerListener.onEndOfSpeech()。（关于写入音流方式的SDK自动结束 录入应注意的地方，请参考writeAudio(byte[], int, int)；VAD端点长度设置，请 参考setParameter(String, String)

可通过cancel()取消当前的会话。

参数:
listener - 识别状态和结果监听器 听写的结果，将通过回调此接口的函数返回，应用 需要实现此接口，并把实例通过此参数传给SDK。关于接口回调的相关知识，请自行查阅 Java 的相关资料。当录音完毕，或应用层完成音频写入后，由于网络 的延迟等原因，识别结果可能无法即时的返回。同时，SDK为了不阻塞应用层的调用线程， 使用了独立的线程来交互数据。故为了在应用层不在等待结果时，由于主线程结束，而在没 有获取得结果时，就退出了应用，应用层需要在主线程中，考虑等待监听返回结果或其他状 态的情况。 另请参阅:
createRecognizer(), getRecognizer(), stopListening(), setParameter(String, String), cancel()

# writeAudio

public abstract int writeAudio(byte[] buffer,int offset,int length)

写入录音数据
通过调用此函数，把音频数据传给SDK。

仅在SpeechConstant.AUDIO_SOURCE值为-1时，需要通过调用本函数，把 音频数据传给SDK。在写入音频数据前，应先通过startListening(RecognizerListener)开启会话。在结束录音数据写入后，调用stopListening()告知应用层，当前会话 音频数据已全部写入。

当SDK回调RecognizerListener.onEndOfSpeech()时，说明SDK已经通过VAD检测 到了静音末端点，应该立即停止写入音频数据。当SDK回调 RecognizerListener.onResult(com.iflytek.cloud.speech.RecognizerResult, boolean)返回完结果，或回调 RecognizerListener.onError(SpeechError)返回错误时，也应该停止当次会话的音频写 入。

支持的音频格式，请参考setParameter(String, String)的参数说明。

参数:
buffer - 要写入的录音数据缓存
offset - 实际音频在传入缓存的起始点
length - 音频数据长度
返回:
是否成功写入数据，ErrorCode.SUCCESS表示成功，其他值表示有错误， 具体错误码，请参考ErrorCode。 另请参阅:
startListening(RecognizerListener), stopListening(), RecognizerListener

# stopListening

public abstract void stopListening()

停止录音
调用本函数告知SDK，当前会话音频已全部录入。

在调用本函数后，已录入的音频还在继续上传到服务器，结果不会马上就返回，当前会 话还在继续，直到结果返回完毕，或出现错误。

要取消会话，请参考cancel()函数。

当应用调用本函数结束停止录音时，SDK不会再回调 RecognizerListener.onEndOfSpeech()。相反的，当SDK回调RecognizerListener.onEndOfSpeech()应用层可不必再调用本函数通知SDK停止录音。

另请参阅:
startListening(RecognizerListener), writeAudio(byte[], int, int), RecognizerListener.onEndOfSpeech(), cancel()

# isListening

public abstract boolean isListening()

是否在会话中
通过此函数，获取当前SDK是否正在进行会话。应用层可通过此函数，查询能否 开始一路新的会话等。

调用了stopListening()停止录音后，如果会话未出现错误或返回最后的结果， 当前状态依然处于会话中，即本函数会返回true。如果调用cancel()取消了会话， 则当前状态处于不在会话中。

返回:
会话状态，true：正在会话中；false：不在会话中。 另请参阅:
startListening(RecognizerListener), stopListening(), cancel()

# cancel

public void cancel()

取消会话
通过此函数取消当前的会话。

在会话被取消后，当前会话结束，未返回的结果将不再返回。

覆盖:
cancel 在类中 com.iflytek.cloud.msc.module.SpeechModule
另请参阅:
startListening(RecognizerListener), stopListening()

# setParameter

public boolean setParameter(java.lang.String key,
                            java.lang.String value)

参数设置

可设置的参数有：
SpeechConstant.NET_TIMEOUT： 网络连接超时时间
SpeechConstant.KEY_SPEECH_TIMEOUT：语音输入超时时间
SpeechConstant.LANGUAGE：语言
SpeechConstant.ACCENT：语言区域
SpeechConstant.DOMAIN：应用领域
SpeechConstant.AUDIO_SOURCE：音频源
SpeechConstant.VAD_BOS：前端点超时
SpeechConstant.VAD_EOS：后端点超时
SpeechConstant.SAMPLE_RATE：识别采样率
SpeechConstant.ASR_NBEST：句子级多候选
SpeechConstant.ASR_WBEST：词级多候选
SpeechConstant.ASR_PTT：设置是否有标点符号
SpeechConstant.RESULT_TYPE：识别结果类型
SpeechConstant.ASR_AUDIO_PATH：识别录音保存路径

SpeechConstant请点击这里

当前识别支持未压缩的16位，单声道，采样率为16000或8000，字节顺序为 Little-Endian的Windows PCM音频。本地识别时，需要有相应的资源文件才 支持对应的采样率的音频识别。

覆盖:
setParameter 在类中 com.iflytek.cloud.msc.module.SpeechModule
参数:
key - 参数名称
value - 参数值
返回:
是否设置成功
另请参阅:
getParameter(String), startListening(RecognizerListener)

# getParameter

public java.lang.String getParameter(java.lang.String key)

获取参数
获取指定的参数的当前值。

某些有默认的值的参数，如SpeechConstant.SAMPLE_RATE，在应用层未 调用setParameter(String, String)来设置参数值前，可能获取到的是null值， 但在实际会话会始时，SDK会使用默认值传给服务器。

覆盖:
getParameter 在类中 com.iflytek.cloud.msc.module.SpeechModule
参数:
key - 参数名称，所有支持参数，参考setParameter(String, String)
返回:
参数值，值意义，参考SpeechConstant对各参数的说明。
另请参阅:
setParameter(String, String)

# destroy

public abstract boolean destroy()

销毁单例对象
通过本函数，销毁由createRecognizer()创建的单例对象。

在调用本函数进行销毁前，应先保证当前不在会话中，否则，本函数将尝试取消当前 会话，并返回false，此时销毁失败。关于当前是否在会话中，请参考函数 isListening()。若销毁失败，请在取消当前会话后，再次调用本函数重试。

当本函数返回true时，销毁成功。此时，之前创建的单例对象已不能再使用，否则， 将会报错。此时需要再使用，应先通过createRecognizer()创建一个新的单例 对象。

指定者:
destroy 在类中 com.iflytek.cloud.msc.module.SpeechModule
返回:
销毁成功：true；销毁失败：false。
另请参阅:
createRecognizer(), cancel()

# updateLexicon

public abstract int updateLexicon(java.lang.String lexiconName,
                                  java.lang.String lexiconContent,
                                  LexiconListener lexiconListener)

更新词典
更新应用个性化的词典，如联系人列表等。热词更新后，在5~10分钟内生效。

参数:
lexiconName - 词典名称，{ "userword", "contact" }。
lexiconContent - 词典内容，联系人列表：以换行符"\n"分隔的词语字符串，如"张三，李四，王五"; 用户热词：满足一定格式的json字符串，格式如下：
{"userword":
[
{ "name":"default",
"words":
["默认词条1",
"默认词条2"]
},
{ "name":"词表名称1",
"words":
["词条1的第一个词",
"词条1的第二个词"]
},
{ "name":"词表名称2",
"words":
["词条2的第一个词",
"词条2的第二个词"]
}
]
}
同时请参考相关DEMO的示例, 或UserWords类。
lexiconListener - 词典更新回调接口
返回:
错误码 若更新成功，则返回0。

# 类RecognizerResult

ava.lang.Object<br/>
com.iflytek.cloud.speech.RecognizerResult<br/>

public class RecognizerResult<br/>
extends java.lang.Object<br/>

# 识别结果

识别结果为文本内容，格式包括自然语言文本(plain)、xml结构化文本(xml)、json结构化文本(json)3种。

当使用听写时，结果文本格式支持：plain、json（默认）。

关于json和xml格式的各关键字说明，请参考新手指南文档。

# 构造器概要

# 构造器和说明

RecognizerResult(java.lang.String result)
构造函数 应用层只通过RecognizerListener.onResult(com.iflytek.cloud.speech.RecognizerResult, boolean)得到结果，可忽略此类的构造函数。

# 方法概要

# 从类继承的方法 java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

# 构造器详细资料

# RecognizerResult

public RecognizerResult(java.lang.String result)

# 构造函数

应用层只通过RecognizerListener.onResult(com.iflytek.cloud.speech.RecognizerResult, boolean)得到结果，可忽略此类的构造函数。

参数:
result - 文本结果

# 方法详细资料

# getResultString

public java.lang.String getResultString()

获取识别结果
返回:
String类型识别结果文本。返回的结果文本有可能为空字符串。

# 类UserWords

java.lang.Object<br/>
com.iflytek.cloud.speech.UserWords<br/>

public class UserWords<br/>
extends java.lang.Object<br/>

# 用户词表类

用户个性化词表类，解析、生成json格式数据。用于在听写着上传个性化数据，以提高匹配率， 关于个性化数据上传，参考com.iflytek.cloud.SpeechRecognizer#updatelexicon。

格式示例如下： {
"userword":
[
{ "name" : "default" , "words" : [ "默认词条1", "默认词条2" ] },
{ "name" : "词表名称1", "words": [ "词条1的第一个词", "词条1的第二个词"] },
{ "name" : "词表名称2", "words": [ "词条2的第一个词", "词条2的第二个词"] }
]
}

# 构造器概要

# 构造器和说明

UserWords()
默认构造函数
UserWords(java.lang.String json)
构造函数 通过传入JSON格式字符串来初始化用户词表

# 方法概要

# 从类继承的方法 java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

# 构造器详细资料

# UserWords

public UserWords()

默认构造函数

# UserWords

public UserWords(java.lang.String json)

构造函数
通过传入JSON格式字符串来初始化用户词表

参数:
json - 格式化的用户词表字符串。

# 方法详细资料

# hasKey

public boolean hasKey(java.lang.String key)

是否包含某个键
是否包含名称为key的词表。

参数:
key - 键名
返回:
false：否; true：是。

# putWord

public boolean putWord(java.lang.String value)

添加词
向默认词组中增加一个value，key值为default。

参数:
value - 需要插入的词条内容
返回:
true表示插入成功，false表示失败

# putWord

public boolean putWord(java.lang.String key,
                       java.lang.String value)

添加词
向key词组中增加一个value。

参数:
key - 需要插入的词组名称
value - 需要插入的词条内容
返回:
是否成功添加

# putWords

public boolean putWords(java.util.ArrayList<java.lang.String> words)

添加多个词
向默认词组中增加多个value，key值为default。

参数:
words - 需要插入的词条列表
返回:
true表示插入成功，false表示失败

# putWords

public boolean putWords(java.lang.String key,
                        java.util.ArrayList<java.lang.String> words)

添加多个词
向key词组中增加多个value。

参数:
key - 需要插入的词组名称。
words - 需要插入的词条内容。
返回:
true表示插入成功，false表示失败

# getWords

public java.util.ArrayList<java.lang.String> getWords()

获取词条
获取默认词组下的所有词条。

返回:
默认词组的词条列表

# getKeys

public java.util.ArrayList<java.lang.String> getKeys()

获取键值
获取词表下的所有键值。

返回:
词表下的所有键值

# getWords

public java.util.ArrayList<java.lang.String> getWords(java.lang.String key)

获取词条
获取键名key下，对应所有用户词表。

参数:
key - 需要获取的词组名称。
返回:
词条列表

# toString

public java.lang.String toString()

转为String
同toJson()

覆盖:
toString 在类中 java.lang.Object
另请参阅:
toJson()

# 接口LexiconListener

public interface LexiconListener

# 词典更新回调接口

通过实现此接口，获取词典更新状态

# 方法概要

# 方法详细资料

# onLexiconUpdated

void onLexiconUpdated(java.lang.String lexiconId,
                      SpeechError error)

词典更新结束回调
参数:
lexiconId - 词典ID。目前即使上传成功，此值也是null，只要上传成功，个性化词表便可生效，可忽略此参数值。
error - 错误信息。值为null时表示成功，其他值时表示有错误。 获取错误码信息请查看SpeechError,详细错误码请看ErrorCode 另请参阅:
SpeechError, ErrorCode

# 接口RecognizerListener

public interface RecognizerListener

# 识别监听器

通过实现此接口，获取当前识别的状态和结果

合成监听器，请参考SynthesizerListener

# 方法概要

# 方法详细资料

# onVolumeChanged

void onVolumeChanged(int volume)

音量变化
当开始识别，到停止录音（停止写入音频流）或SDK返回最后一个结果自动结束识别为止， SDK检测到音频数据（正在录音或写入音频流）的音量变化时，会多次通过此函数回调，告 知应用层当前的音量值。应用层可通过此函数传入的值变化，改变自定义UI的画面等。

参数:
volume - 当前音量值，范围[0-30]
另请参阅:
SpeechRecognizer.startListening(com.iflytek.cloud.speech.RecognizerListener), onBeginOfSpeech(), onEndOfSpeech(), SpeechRecognizer.stopListening()

# onBeginOfSpeech

void onBeginOfSpeech()

开始说话
在录音模式(音频源参数设为 > -1 时 )下， 调用开始录音函数后，会自动开启系统的录音 机，并在录音机开启后，会回调此函数（这中间的过程应该在几毫秒内，可以忽略，除非系 统响应很慢）。

应用层可通过此函数回调，告知用户，当前可开始说话。若应用层使用的是声音提示， 则应该在调用开始录音函数前，提放提示音， 并在提示音非静音数据播放结束时，调用 开始录音函数，开始录音。若太早调用，则 可能会把提示音录进要识别的音频中，若太晚，则可能会漏掉部分用户说话的音频。

另请参阅:
SpeechRecognizer.startListening(com.iflytek.cloud.speech.RecognizerListener), onEndOfSpeech()

# onEndOfSpeech

void onEndOfSpeech()

结束说话
在SDK检测到音频的静音端点时，回调此函数（在录音模式或写音频模式下都会回调， 应用层主动调用SpeechRecognizer.stopListening()则不会回调此函数， 在识别出错时，可能不会回调此函数）。在此函数回调后，当前识别会话可能并没有结束， 识别结果可能还要等待一定的时间才会返回。

此函数回调后，应用层应立即停止调用SpeechRecognizer.writeAudio(byte[], int, int)写入音 频数据，(当音频源设置为音频流时（SpeechConstant.AUDIO_SOURCE为-1时) 否则，再通过SpeechRecognizer.writeAudio(byte[], int, int)写入的音频也会被忽略。

应用层可以通过此函数回调，告知用户，当次说话已结束，正在等待识别结果（若结果 未返回）等。

另请参阅:
onBeginOfSpeech(), onResult(com.iflytek.cloud.speech.RecognizerResult, boolean), onError(com.iflytek.cloud.speech.SpeechError), SpeechRecognizer.writeAudio(byte[], int, int), SpeechRecognizer.stopListening()

# onResult

void onResult(RecognizerResult result,
              boolean islast)

返回结果
返回的结果可能为null，请增加判断处理。

一次识别会话的结果可能会多次返回（即多次回调此函数），通过参数2,判断是否是最后 一个结果，true时为最后一个结果，否则不是。当最后一个结果返回时，本次会话结束，录 音也会停止，在重新调用 SpeechRecognizer.startListening(com.iflytek.cloud.speech.RecognizerListener)开启新的识别会话前， 停止调用SpeechRecognizer.writeAudio(byte[], int, int)写入音频(当音频源设置为音频流时 （SpeechConstant.AUDIO_SOURCE为-1时)。 当出现错误，或应用层调用SpeechRecognizer.cancel()取消当次识别时，在当次识 别会话过程可能不会回调此函数。

识别采用边录边上传的分次上传音频数据方式，可能在结束录音前，就有结果返回。

参数:
result - 结果数据
islast - 是否最后一次结果标记
另请参阅:
onError(com.iflytek.cloud.speech.SpeechError), SpeechRecognizer.cancel(), RecognizerResult

# onError

void onError(SpeechError error)

错误回调
当此函数回调时，说明当次会话出现错误，会话自动结束，录音也会停止。应在再次调用 SpeechRecognizer.startListening(com.iflytek.cloud.speech.RecognizerListener)开启新的识别会话前， 停止调用SpeechRecognizer.writeAudio(byte[], int, int)写入音频(当音频源设置为音频流时 （SpeechConstant.AUDIO_SOURCE为-1时)。

参数:
error - 错误类型
另请参阅:
SpeechError, onResult(com.iflytek.cloud.speech.RecognizerResult, boolean), SpeechRecognizer.startListening(com.iflytek.cloud.speech.RecognizerListener)

# onEvent

void onEvent(int eventType,
             int arg1,
             int arg2,
             java.lang.String msg)

事件
扩展用接口，由具体业务进行约定。例如eventType为0显示网络状态，agr1为网络连接值。

参数:
eventType - 消息类型
arg1 - 参数1
arg2 - 参数2
msg - 消息内容
另请参阅:
SpeechEvent