语音评测(Evaluator)

这里介绍的是Android API关于语音评测(Evaluator)的相关说明，点击右侧目录可快速找到相应文件。

#类SpeechEvaluator

com.iflytek.cloud

java.lang.Object
com.iflytek.cloud.msc.module.SpeechInterface
com.iflytek.cloud.SpeechEvaluator

public class SpeechEvaluator extends com.iflytek.cloud.msc.module.SpeechInterface

#语音评测类

语音评测是通过智能语音技术自动对发音水平进行评价、发音错误、缺陷定位和问题分析的软件系统。评音评测提供汉语、英语两种语言的评测，支持单字（汉语专有）、词语、句子和篇章（需开权限）朗读四种题型，请参考SpeechConstant.ISE_CATEGORY 。
本类使用单例，调用者使用本类的对象，只需要通过createEvaluator(android.content.Context, com.iflytek.cloud.InitListener)创建 一次对象后，便可一直使用该对象，直到通过调用destroy()进行单例对象销毁。调用者可通过createEvaluator(android.content.Context, com.iflytek.cloud.InitListener)获取当前已经创建的单例。在销毁本类的单例对象后， 需要先通过createEvaluator(android.content.Context, com.iflytek.cloud.InitListener)再次创建单例对象，方可再使用。

在当前应用生命周期第一次使用本类的任何函数前，须先调用 SpeechUtility.createUtility(android.content.Context, java.lang.String) 进行SDK初始化。

#嵌套类概要

从类继承的嵌套类/接口 com.iflytek.cloud.msc.module.SpeechInterface
com.iflytek.cloud.msc.module.SpeechInterface.ENGINE_MODE

#方法概要

限定符和类型	字段和说明
void	cancel() 取消会话 通过此函数取消当前的会话。
static SpeechEvaluator	createEvaluator(android.content.Context context, InitListener listener) 创建单例对象 使用此函数创建一个本类单例对象。
boolean	destroy() 销毁单例对象 通过本函数，销毁由createEvaluator(android.content.Context, com.iflytek.cloud.InitListener)创建的单例对象。
static SpeechEvaluator	getEvaluator() 获取单例对象 通过函数获取已创建的单例对象。
java.lang.String	getParameter(java.lang.String key) 获取参数 获取指定的参数的当前值。
boolean	isEvaluating() 是否在会话中 通过此函数，获取当前SDK是否正在进行会话。
boolean	setParameter(java.lang.String key, java.lang.String value) 设置参数 设置评测会话参数。
int	startEvaluating(byte[] text, java.lang.String textParams, EvaluatorListener listener) 开始评测 传入byte[]类型的评测文本，开始评测会话。
int	startEvaluating(java.lang.String text, java.lang.String textParams, EvaluatorListener listener) 开始评测 调用此函数，开始评测。
void	stopEvaluating() 停止录音 调用本函数告知SDK，当前会话音频已全部录入。
boolean	writeAudio(byte[] buffer, int offset, int length) 写入录音数据 通过调用此函数，把音频数据传给SDK。

从类继承的方法 com.iflytek.cloud.msc.module.SpeechInterface
setParameter

从类继承的方法 java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

#方法详细资料

#createEvaluator

public static SpeechEvaluator createEvaluator(android.content.Context context,
                                              InitListener listener)

创建单例对象

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

返回：
评测对象

另请参阅: destroy(), getEvaluator()

#getEvaluator

public static SpeechEvaluator getEvaluator()

获取单例对象

通过函数获取已创建的单例对象。当单例对象未创建时，将返回null，此时应先通过 createEvaluator(android.content.Context, com.iflytek.cloud.InitListener)创建单例对象。

返回:
评测对象

另请参阅:
createEvaluator(android.content.Context, com.iflytek.cloud.InitListener), destroy()

#startEvaluating(传入String)

public int startEvaluating(java.lang.String text,
                           java.lang.String textParams,
                           EvaluatorListener listener)

开始评测 调用此函数，开始评测。

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

在调用本函数开始评测前，通过setParameter(java.lang.String, java.lang.String)设置相 应的参数。

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

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

参数:
text - 评测文本
textParams - 当前会话参数，见setParameter(java.lang.String, java.lang.String)支持的参数， 仅在当次会话生效，如无特殊要求，传入null即可。
listener - 监听器，获取状态和结果。

返回:
是否成功写入数据，ErrorCode.SUCCESS表示成功，其他值表示有错误， 具体错误码，请参考ErrorCode。

另请参阅:
writeAudio(byte[], int, int), createEvaluator(android.content.Context, com.iflytek.cloud.InitListener), getEvaluator(), stopEvaluating(), setParameter(java.lang.String, java.lang.String), cancel(),startEvaluating(byte[], String, EvaluatorListener)

#startEvaluating(传入byte)

public int startEvaluating(byte[] text,
                           java.lang.String textParams,
                           EvaluatorListener listener)

开始评测
传入byte[]类型的评测文本，开始评测会话。其他介绍请参考startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener)。

另请参阅:
startEvaluating(String, String, EvaluatorListener)

#writeAudio

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

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

仅在SpeechConstant.AUDIO_SOURCE值为-1时，需要通过调用本函数，把 音频数据传给SDK。在写入音频数据前，应先通过startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener) 开启会话。在结束录音数据写入后，调用stopEvaluating()告知应用层，当前会话 音频数据已全部写入。

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

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

参数:
buffer - 要写入的录音数据缓存
offset - 实际音频在传入缓存的起始点
length - 音频数据长度

返回:
是否成功写入数据，true 表示成功，false 表示有错误。发生错误时，通过EvaluatorListener.onError(com.iflytek.cloud.SpeechError)获取错误信息。
另请参阅:
startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener), stopEvaluating(), EvaluatorListener

#isEvaluating

public boolean isEvaluating()

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

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

返回:
会话状态，true：正在会话中；false：不在会话中。

另请参阅:
startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener), stopEvaluating(),cancel()

#stopEvaluating

public void stopEvaluating()

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

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

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

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

另请参阅:
startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener), writeAudio(byte[], int, int),EvaluatorListener.onEndOfSpeech(), cancel()

#cancel

public void cancel()

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

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

另请参阅:
startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener), stopEvaluating()

#setParameter

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

设置参数<>br> 设置评测会话参数。

可设置参数有：
SpeechConstant.ISE_AUDIO_PATH 音频保存路径
SpeechConstant.ISE_CATEGORY 题型
SpeechConstant.LANGUAGE 语言
SpeechConstant.ISE_INTERRUPT_ERROR 中断报错
SpeechConstant.ISE_PARSED 是否已标注
SpeechConstant.ISE_SOURCE_PATH 音频源文件路径
SpeechConstant.ISE_USER_MODEL_ID 用户模型ID
SpeechConstant.KEY_REQUEST_FOCUS 音频焦点
SpeechConstant.NET_TIMEOUT 网络超时
SpeechConstant.RESULT_LEVEL 结果等级
SpeechConstant.SAMPLE_RATE 音频采样率
SpeechConstant.TEXT_BOM 文本字节顺序
SpeechConstant.TEXT_ENCODING 文本编码格式
SpeechConstant.VAD_ENABLE 启用VAD
SpeechConstant.VAD_BOS VAD 前端点
SpeechConstant.VAD_EOS VAD 后端点
SpeechConstant.AUDIO_SOURCE: 音频源
SpeechConstant.BLUETOOTH: 蓝牙录音
SpeechConstant.ENGINE_TYPE: 引擎类型（目前评测仅支持在线模式）

当前评测支持未压缩的16位，单声道，采样率为16000或8000，字节 顺序为Little-Endian的Windows PCM音频。

覆盖:
setParameter 在类中 com.iflytek.cloud.msc.module.SpeechInterface

参数:
key - 参数名称
value - 参数值

返回:
true 设置成功，false 设置失败

#getParameter

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

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

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

覆盖:
getParameter 在类中 com.iflytek.cloud.msc.module.SpeechInterface

参数:
key - 参数名称，所有支持参数，参考setParameter(String, String)

返回:
参数值，值意义，参考SpeechConstant对各参数的说明。

另请参阅:
setParameter(String, String)

#destroy

public boolean destroy()

销毁单例对象
通过本函数，销毁由createEvaluator(android.content.Context, com.iflytek.cloud.InitListener)创建的单例对象。

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

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

覆盖:
destroy 在类中 com.iflytek.cloud.msc.module.SpeechInterface

返回:
销毁成功：true；销毁失败：false。

另请参阅:
createEvaluator(android.content.Context, com.iflytek.cloud.InitListener),cancel()

#类EvaluatorResult

java.lang.Object
com.iflytek.cloud.EvaluatorResult

所有已实现的接口:

android.os.Parcelable
public class EvaluatorResult
extends java.lang.Object
implements android.os.Parcelable

#评测结果类

关于评测结果的各键值说明，请参考《Speech Evaluation API Documents》。

另请参阅:
EvaluatorListener.onResult(EvaluatorResult, boolean), SpeechEvaluator

#嵌套类概要

从接口继承的嵌套类/接口 android.os.Parcelable

android.os.Parcelable.ClassLoaderCreator<T>, android.os.Parcelable.Creator<T>

###字段概要
字段

限定符和类型	字段和说明
static android.os.Parcelable.Creator<EvaluatorResult>	CREATOR

从接口继承的字段 android.os.Parcelable

CONTENTS_FILE_DESCRIPTOR, PARCELABLE_WRITE_RETURN_VALUE

#构造器概要

构造器
构造器和说明
EvaluatorResult(java.lang.String result)
构造函数 应用层一般只用到EvaluatorListener.onResult(com.iflytek.cloud.EvaluatorResult, boolean)返回的评测结果对象， 可忽略此构造函数。

#方法概要

所有方法

限定符和类型	方法和说明
int	describeContents()
java.lang.String	getResultString() 获取评测结果 获取xml格式的String字符串，请参考《Speech Evaluation API Documents》。
void	writeToParcel(android.os.Parcel dest, int flags)

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

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

字段详细资料
CREATOR

public static final android.os.Parcelable.Creator<EvaluatorResult> CREATOR

构造器详细资料

#EvaluatorResult

public EvaluatorResult(java.lang.String result)

构造函数
应用层一般只用到EvaluatorListener.onResult(com.iflytek.cloud.EvaluatorResult, boolean)返回的评测结果对象， 可忽略此构造函数。

方法详细资料

#getResultString

public java.lang.String getResultString()

获取评测结果
获取xml格式的String字符串，请参考《Speech Evaluation API Documents》。

返回:
评测结果

#describeContents

public int describeContents()

指定者:
describeContents 在接口中 android.os.Parcelable

#writeToParcel

public void writeToParcel(android.os.Parcel dest,
                          int flags)

指定者:
writeToParcel 在接口中 android.os.Parcelable

#接口EvaluatorListener

public interface EvaluatorListener

#评测回调接口

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

识别监听器，请参考RecognizerListener

合成监听器，请参考SynthesizerListener

#方法概要

限定符和类型	方法和说明
void	onBeginOfSpeech() 开始说话 在录音模式(音频源参数设为 > -1时 )下， 调用开始录音函数后，会自动开启系统的录音 机，并在录音机开启后，会回调此函数（这中间的过程应该在几毫秒内，可以忽略，除非系 统响应很慢）。
void	onEndOfSpeech() 结束说话 在SDK检测到音频的静音端点时，回调此函数（在录音模式或写音频模式下都会回调， 应用层主动调用SpeechEvaluator.stopEvaluating()则不会回调此函数， 在识别出错时，可能不会回调此函数）。
void	onError(SpeechError error) 错误回调 当此函数回调时，说明当次会话出现错误，会话自动结束，录音也会停止。
void	onEvent(int eventType, int arg1, int arg2, android.os.Bundle obj) 事件 扩展用接口，由具体业务进行约定。
void	onResult(EvaluatorResult result, boolean islast) 返回结果 返回的结果可能为null，请增加判断处理。
void	[onVolumeChanged(int volume, byte] data) 音量变化 当开始识别，到停止录音（停止写入音频流）或SDK返回最后一个结果自动结束识别为止， SDK检测到音频数据（正在录音或写入音频流）的音量变化时，会多次通过此函数回调，告 知应用层当前的音量值。

方法详细资料

#onVolumeChanged

void onVolumeChanged(int volume,
                     byte[] data)

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

参数:
volume - 当前音量值，范围[0-30]
data - 录音数据，格式请参考SpeechConstant.SAMPLE_RATE , SpeechConstant.AUDIO_FORMAT。此参数返回的数据，即使 SpeechConstant.NOTIFY_RECORD_DATA为false，也会返回。

另请参阅: SpeechEvaluator.startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener), onBeginOfSpeech(), onEndOfSpeech(), SpeechEvaluator.stopEvaluating(), SpeechConstant.NOTIFY_RECORD_DATA

#onBeginOfSpeech

void onBeginOfSpeech()

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

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

另请参阅:
SpeechEvaluator.startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener), onEndOfSpeech()

#onEndOfSpeech

void onEndOfSpeech()

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

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

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

另请参阅:
onBeginOfSpeech(), onResult(com.iflytek.cloud.EvaluatorResult, boolean), onError(com.iflytek.cloud.SpeechError), [SpeechEvaluator.writeAudio(byte], int, int), SpeechEvaluator.stopEvaluating()

#onResult

void onResult(EvaluatorResult result,
              boolean islast)

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

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

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

参数:
result - 结果数据
islast - 是否最后一次结果标记

另请参阅:
onError(com.iflytek.cloud.SpeechError), SpeechEvaluator.cancel(), EvaluatorResult

#onError

void onError(SpeechError error)

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

参数:
error - 错误类型

另请参阅: SpeechError , onResult(com.iflytek.cloud.EvaluatorResult, boolean), SpeechEvaluator.startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener)

#onEvent

void onEvent(int eventType,
             int arg1,
             int arg2,
             android.os.Bundle obj)

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

参数:
eventType - 消息类型
arg1 - 参数1
arg2 - 参数2
obj - 消息内容

另请参阅: SpeechEvent