# 语音识别器

消息类型	名称	必须实现
request	audio_in	是
	text_in	否
response	intermediate_text	是
	stop_capture	否
	expect_reply	否
	evaluate_result	否

# context

"iflyos_context": {
  ...
  "recognizer": {
    "version": "1.1",
  },
  ...
}

参数	类型	说明	必填
version	String	模块版本，现在是1.1	是

版本说明

版本	说明	更新日期
1.0	基础实现	2019-07-01
1.1	新增`expect_reply`的`background_recognize`字段	2019-08-28
1.1	`audio_in`新增`profile` `EVALUATE` ，`response`新增`evaluate_result`	2019-12-16

# request

# 语音请求

语音请求分两部分：

构建语音处理的 iflyos_request
发送语音数据

# 构建语音处理的 iflyos_request

请求示例

{
  "iflyos_header": {...},
  "iflyos_context": {...},
  "iflyos_request": {
    "header": {
      "name": "recognizer.audio_in",
      "request_id": "xxxxxxxx"
    },
    "payload": {
      "reply_key": "xxxxxx",
      "enable_vad": true,
      "vad_eos": 300,
      "profile": "CLOSE_TALK",
      "format": "AUDIO_L16_RATE_16000_CHANNELS_1",
      "iflyos_wake_up": {
        "score": 666,
        "start_index_in_samples": 50,
        "end_index_in_samples": 150,
        "word": "蓝小飞",
        "prompt": "我在"
      },
      "evaluate": {
        "language": "en_us",
        "category": "read_word",
        "text": "welcome"
      }
    }
  }
}

参数	类型	说明	必填
iflyos_header	Object	构建的通用 iflyos_header	是
iflyos_context	Object	构建的通用 iflyos_context	是
reply_key	String	如果接收到 name 为 recognizer.expect_reply 的响应的话，重新打开麦克风识别的时候，需要填入响应中返回的 reply_key 中的取值	否
enable_vad	Bool	是否使用云端VAD，默认为true; 当该参数为true时，设备会收到 recognizer.stop_capture 指令。评测类型为read_chapter时，不建议开启云端VAD。	否
vad_eos	Int	VAD后端点时长，单位为毫秒。若该字段不出现，则视为使用EVS默认配置；该字段仅支持大于800ms的时间。建议取值见下表	否
profile	String	音频输入的处理引擎。取值见下表。	是
format	String	音频编码类型，取值见下表	是
iflyos_wake_up	Object	语音唤醒信息。若使用讯飞的麦克风阵列，必须填写；若使用其他厂商提供的阵列，可不填	否
iflyos_wake_up.word	String	唤醒词	是
iflyos_wake_up.score	Int	唤醒得分	是
iflyos_wake_up. start_index_in_samples	Int	唤醒音频开始时间（iFLYOS提供专属引擎提供）	否
iflyos_wake_up. end_index_in_samples	Int	唤醒音频结束时间（iFLYOS提供专属引擎提供）	否
iflyos_wake_up.prompt	String	如果播放真人录音的提示音，请把播放出来的提示音的对应文本进行上传，比如：我在，怎么了	否
evaluate	Object	语音评测信息。当`profile`取值为`EVALUATE`时，该项才需要出现。若该项出现，以下信息均必填	否
evaluate.language	String	评测语言，取值：en_us（美式英文）,zh_cn（中文）	是
evaluate.category	String	评测题型，取值见下表。	是
evaluate.text	String	评测题目文本，使用utf-8编码，中文长度不超过180字节，英文长度不超过300字节。写法样例请点击	是

profile取值

`profile` 取值	说明	`vad_eos`取值建议
CLOSE_TALK	近场识别，适合3米内的使用场景	建议使用800ms
FAR_FIELD	远场识别，适合10米内的使用场景	建议使用800ms
EVALUATE	语音评测，适合中英文评测场景	`read_syllable` ， `read_word` ， `read_sentence` 建议使用300ms。 `read_chapter` 建议使用1000ms。

format 取值

iFLYOS 支持识别 16-bit 位深度、16000Hz 采样率、单声道的音频。具体支持的编码如下：

format	说明	建议帧大小
AUDIO_L16_RATE_16000_CHANNELS_1	PCM，Little-Endian	640字节
OPUS	OPUS 压缩，32000bps 固定比特率 (CBR)，VOIP 模式	96字节
SPEEX_WB_QUALITY_9	SPEEX 压缩，宽带 (wideband)，Quality 9	86字节

evaluate.category 取值

`category` 取值	含义	备注
read_chapter	篇章朗读	仅英文可用
read_sentence	句子朗读	中英文可用
read_word	词语朗读	中英文可用
read_syllable	单字朗读	仅中文

# 发送语音数据

发送完音频上传指令之后，客户端应尽快开始发送二进制语音数据。除非平台硬件有特殊限制，请使用 20ms 采样（对PCM格式来说即640个字节语音数据，其余格式见上表）封装到一个 websocket binary 消息中发送。如果打开了服务端 vad ，那么在收到服务端recognizer.stop_capture时，应该结束本地录音；如果没有打开服务端 vad，那么客户端可以根据本地 vad 或者按键请求等，自己确定什么时候结束录音。

注意

无论通过哪种方式结束录音，结束本地录音，关闭设备麦克风后，客户端都应该统一发送音频结束标志：

__END__ 代表发送的音频流结束，请求云端进行后续操作（如语义理解等）。
__CANCEL__ 代表发送的音频流结束，取消之前发送的语音请求，云端无需进行后续操作。

# 文本请求

iFLYOS 不单单支持语音的请求，还支持文本请求，这让多模态交互成为可能。在以下场景，我们建议你使用text_in。

当用户点击设备的GUI按键或实体按键时，设备可以将某些动作绑定转化为text_in请求，请求云端语义处理。
支持用户在设备上进行文本输入。

请求示例


{
  "iflyos_header": {...},
  "iflyos_context": {...},
  "iflyos_request": {
    "header": {
      "name": "recognizer.text_in",
      "request_id": "xxxxxxxx"
    },
    "payload": {
      "query": "请求的文本",
      "with_tts": true,
      "reply_key": "xxxxxx"
    }
  }
}

参数	类型	说明	必填
iflyos_header	Object	构建的通用 iflyos_header	是
iflyos_context	Object	构建的通用 iflyos_context	是
query	String	需要请求的文本	是
with_tts	Bool	是否需要语音回复，如果你希望用户点击按钮的时候，不要出现提示音，那么可以设置为 false，默认为：true	否
reply_key	String	如果接收到 name 为 recognizer.expect_reply 的响应的话，重新打开麦克风识别的时候，需要填入响应中返回的 reply_key 中的取值	否

# response

# 识别结果

当你需要实时显示用户说话时，你可以使用recognizer.intermediate_text来获得用户实时的转写结果，这个是一个可选项，按需实现即可；

回复示例


{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "recognizer.intermediate_text"
      },
      "payload": {
        "text": "明天的天气怎么样",
        "is_last": false
      }
    }
  ]
}

参数	类型	说明	必有
text	String	当前应该显示的文本	是
is_last	Bool	是否为最终结果，true表示当前文本为最终结果，false表示当前文本不是最终状态	是

# 结束录音

当设备端收到recognizer.stop_capture的消息的时候，你需要在设备上执行关闭麦克风的操作，关闭后发送 __END__来结束音频上传。

在收到recognizer.stop_capture前，你可以随时通过__END__来主动结束语音音频流并等待云端返回结果；当然你也可以通过 __CANCEL__来取消本次语音请求。

回复示例

{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "recognizer.stop_capture"
      },
      "payload": {}
    }
  ]
}

# 追问

追问是iflyos的一种响应，当你接收到 name 为 recognizer.expect_reply 的时候，应该使用recognizer.audio_in并且将接收到的reply_key中的值附带进去。当然你也可以使用recognizer.text_in 来进行回复。

注意

如果同时打开recognizer.audio_in和recognizer.text_in的情况下，用户通过屏幕进行点击操作的时候，应该发送 __CANCEL__ 来通知云端取消语音输入。
如果设备进入了持续交互模式，此时设备想要退出本轮持续交互（如打开了一个不应该继续和用户交互的音乐播放app），你可以发送__CANCEL__并在设备端自行关闭麦克风。

回复示例


{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "recognizer.expect_reply"
      },
      "payload": {
        "reply_key": "xxxx",
        "background_recognize": true,
        "timeout": 8000//单位为毫秒
      }
    }
  ]
}

参数	类型	说明	必有
reply_key	String	接下来发起的recognizer request时需要放入里面。	是
background_ recognize	Bool	是否为背景录音，默认为flase，代表为前景录音。如果取值为`true`，则设备在处理录音时，显示背景录音的状态（不影响用户当前的使用的情况下的录音）。你只有在设备支持持续交互的情况下才会收到这个字段。	否
timeout	Long	追问等待的超时时间，单位为毫秒	是

# 语音评测结果

设备发起语音评测后，云端会回复语音评测的结果。设备收到评测结果后，需要将评测结果友好的反馈给用户，并适当地引导用户进行下一步操作。

{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "recognizer.evaluate_result"
      },
      "payload": {
        "code": 0,
        "description": "success",
        "sid": "xxxxxxx",
        "data": {...}
      }
    }
  ]
}

参数	类型	说明	必有
code	Int	请求结果代码，0代表成功。错误码查询 (opens new window)	是
description	String	请求结果说明	是
sid	String	语音评测请求的唯一标识	是
data	Object	语音评测请求的结果，语音评测结果说明请点击	是