# 语音识别器

消息类型 名称 必须实现
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_replybackground_recognize字段 2019-08-28
1.1 audio_in新增profile EVALUATEresponse新增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_syllableread_wordread_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 来进行回复。

注意

  1. 如果同时打开recognizer.audio_in和recognizer.text_in的情况下,用户通过屏幕进行点击操作的时候,应该发送 __CANCEL__ 来通知云端取消语音输入。
  2. 如果设备进入了持续交互模式,此时设备想要退出本轮持续交互(如打开了一个不应该继续和用户交互的音乐播放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 语音评测请求的结果,语音评测结果说明请点击