For the complete documentation index, see llms.txt. This page is also available as Markdown.

音频数据(通过数据通道)

此页面说明通过 WebRTC 数据通道发送给客户端的指标。


1. 在 Connect API 请求中启用音频数据

要通过 WebRTC 数据通道而不是标准音频轨道接收音频,请在调用 audio_config 时进行配置。

注意: 通过数据通道传输的音频数据仅支持 LiveKit 传输(默认)。

HTTP 请求:

POST https://live.convai.com/connect
X-Api-Key: <X-Api-Key>
Content-Type: application/json

请求体:

{
  "character_id": "<your character_id>",
  "audio_config": {
    "output": {
      "audio_routing": "data_only",
      "max_chunk_duration_ms": 100,
      "add_wav_header": false
    }
  }
}

配置字段:

字段
范围/选项
描述

audio_routing(字符串)

"data_only"

"audio_only" (默认)

"both"

控制音频传输方式: • "data_only" - 通过数据通道接收音频数据消息 • "audio_only" - 标准 WebRTC 音频轨道(无音频数据消息) • "both" - 同时通过音频轨道和数据通道接收

max_chunk_duration_ms(整数)

10-1000,默认(100)

每个音频块的最大持续时间(毫秒)。会向上取整到最接近的 10 毫秒(例如,95ms → 100ms)

add_wav_header(布尔值)

false(默认)/ true

是否在每个音频块中包含 44 字节的 WAV 头(仅影响数据通道音频)


2. 在客户端接收音频数据

audio_routing 被设置为 "data_only""both".

过滤传入消息:

  • label === "rtvi-ai"

  • type === "server-message"

  • data.type === "audio-data"


3. 音频数据信息结构

字段说明:

字段
类型
值/描述

label

字符串

Always "rtvi-ai" (RTVI 协议标识符)

type

字符串

Always "server-message" (RTVI 消息类型)

data.type

字符串

Always "audio-data" (特定消息子类型)

data.sample_rate

整数

音频采样率(Hz)(例如:16000、24000、48000)

data.channels

整数

音频声道数(1=单声道,2=立体声)

data.audio

字符串

Base64 编码的音频数据(原始 PCM 或带头部的 WAV)

data.includes_wav_header

布尔值

true 如果音频包含 44 字节的 WAV 头, false 适用于原始 PCM

注意:

  • 每条消息包含一个音频块

  • 块持续时间由 max_chunk_duration_ms 控制(默认:100ms)

  • 由于向上取整到最接近的 10ms,实际持续时间可能会略高

  • 音频数据是以 base64 编码的 16 位有符号 PCM


4. 音频数据格式与解码

字段
说明

格式

16 位有符号 PCM(小端序)

标准 PCM 音频格式

编码

Base64

用于数据通道上的 JSON 传输

采样率

不同(通常为 16000、24000 或 48000)

在以下字段中指定 sample_rate 字段

声道

1(单声道)或 2(立体声)

在以下字段中指定 channels 字段

WAV 头(可选)

44 字节

当以下情况包含时 add_wav_header: true 在配置中

块大小

由以下控制 max_chunk_duration_ms

默认 100ms,向上取整到最接近的 10ms

解码步骤:

  1. audio 字段进行 Base64 解码以获取原始字节

  2. 如果 includes_wav_headertrue:

    • 前 44 个字节是 WAV 头(可直接保存为 .wav)

    • 剩余字节是 PCM 音频数据

  3. 如果 includes_wav_headerfalse:

    • 所有字节都是原始 16 位有符号 PCM

    • 使用 sample_ratechannels 用于配置音频上下文的字段

5. 接收并解码音频数据的示例代码


6. 使用说明

当你需要以下功能时,通过数据通道传输音频数据会很有用:

  • 自定义音频处理 在播放前(例如:滤波器、效果、归一化)

  • 自定义缓冲策略 用于不稳定的网络条件

  • 音频录制/保存 为 WAV 文件(带 add_wav_header: true)

  • 不支持浏览器的客户端 那些不支持 WebRTC 音频轨道

对于标准的基于浏览器的音频播放,建议使用默认的 audio_routing: "audio_only" (标准 WebRTC 音频轨道),因为它具有最低延迟,并且由浏览器自动处理。


代理说明:查询本文档

如果你需要本页未直接提供的更多信息,可以通过提问动态查询文档。

在当前页面 URL 上执行 HTTP GET 请求,并使用 ask 查询参数:

问题应具体、自包含,并使用自然语言编写。响应将包含该问题的直接答案,以及文档中的相关摘录和来源。

当答案未在当前页面中明确给出、你需要澄清或更多上下文,或者你想检索相关文档章节时,请使用此机制。

最后更新于

这有帮助吗?