Administrator
发布于 2026-11-21 / 3 阅读
0
0

系列 1:mod_taering_stream 媒体协议详解

本文是《从零搭建 AI + 人工呼叫中心》的补充篇。主篇讲"怎么跑通",这一篇讲"为什么这样跑":模块在通话里做了什么、WebSocket 上传输的每一种消息、四种控制方式、事件、全部配置参数,以及自己写后端时必须遵守的规则。

适合:要自己实现 AI 后端、要对接其他 ASR/TTS 厂商、或者要把模块集成进现有呼叫系统的开发者。

本文基于 mod_taering_stream 0.55 版本。


目录


1. 模块做什么、不做什么

mod_taering_stream 只做一件事:在一通已经存在的通话上,把音频双向桥接到 WebSocket。

做 不做
把通话音频实时推给后端(PCM16LE 二进制) 拨号、应答、桥接、转接、挂机
把后端返回的 PCM 实时注入通话 ASR、TTS、VAD、大模型
打断:清空播放队列并报告已播放进度 重采样、编解码转换
断线重连、多后端轮询 断线期间的音频补发
推送连接、错误、播放、后端 JSON 等事件 维护呼叫状态或业务状态

呼叫控制交给拨号计划、ESL 程序或 FCC 这样的控制模块;语音能力由你的后端实现。

不需要为机器人创建坐席或分机。 推流模块只挂在通话上,不关心通话是谁发起的、对方是谁,也不需要 SIP 注册或 mod_callcenter 坐席。主篇里的"AI 分机 8000"只是一段拨号计划,不是一个注册用户。

↑ 回到目录


2. 工作原理:媒体钩子与方向

2.1 媒体钩子(media bug)

start 时,模块在通道上挂一个 FreeSWITCH media bug,名字是 mod_taering_stream。之后这个通道每读、写一帧音频,模块都会拿到:

  • 在采集方向拿到的帧 → 复制一份,按声道模式打包,放进上行队列,由网络线程发给后端;
  • 在注入方向拿到的帧 → 从下行队列取出等长的后端 PCM,**叠加(混音)**到这一帧上,再交还给 FreeSWITCH。

网络收发在独立的 worker 线程里完成,不会阻塞媒体线程。

2.2 两个方向

FreeSWITCH 的通道有两个方向:

  • 读方向(read):从对端流进 FreeSWITCH 的声音。对一通来电来说,就是来电者在说什么。
  • 写方向(write):FreeSWITCH 发给对端的声音。对一通来电来说,就是来电者听到了什么。

默认情况下:

方向
采集 读方向(来电者的声音)
注入 写方向(让来电者听到 AI)

2.3 loopback 感知

用 loopback/ endpoint 发起的呼叫(比如 FCC 的 route_mode=dialplan 外呼)会产生 A、B 两条腿,两条腿的读写方向是镜像的。模块会读取通道变量 loopback_leg:

loopback_leg 采集方向 注入方向
未设置(普通通道) 读 写
B 读 写
A 写 读

所以在 loopback A 腿上推流时,模块会自动反转方向,保证采集的始终是"对方的声音",注入的始终是"让对方听到的声音"。开启 log_debug 后,日志里的 media route: ... capture_dir=... inject_dir=... 会打印实际使用的方向。AI 外呼的完整场景放在系列第 3 篇讲。

↑ 回到目录


3. 一个推流会话的生命周期

            start(拨号计划 / API)
                    │  检查授权并发 → 挂 media bug → 安排连接
                    ▼
            ┌── connecting ──┐
            │                │ 连接成功,发送 start 帧
            │                ▼
            │           streaming ◄────────────┐
            │                │ 连接断开         │ 重连成功,重新发送 start 帧
            │                ▼                  │
            └──────► reconnecting ─────────────┘
                             │ 超过 reconnect_max_attempts
                             ▼
     stop / 挂机 ──────► stopping ──► 释放会话和授权名额
状态 含义 上行音频 下行注入
connecting 首次连接中 丢弃(不缓存) 无
streaming 已连接 正常发送 正常
reconnecting 断线后等待重连 丢弃 继续播放缓冲里剩下的音频
stopping 正在停止 停止 停止

几个要点:

  • start 立即返回,连接是异步建立的。start 返回成功只表示会话已创建、media bug 已挂上,不代表后端已经连上。
  • 一个通道同时只能有一个推流会话。重复 start 会返回"已存在"(拨号计划应用里是 +OK already started)。
  • 授权在 start 时检查。超过授权并发(试用版 1 路)时,start 直接失败。会话结束后名额释放。
  • 状态可以通过 JSON API 的 get 查询,字段名是 state。

↑ 回到目录


4. WebSocket 协议

4.1 连接

  • 模块是客户端,你的后端是服务端。每个推流会话一条独立连接。

  • 支持 ws:// 和 wss://。

  • URL 的来源,按优先级:

    1. start 时显式传入的 URL;
    2. 配置里的 default_ws_urls(逗号或分号分隔多个地址,每次新建会话按轮询选一个);
    3. 配置里的 default_ws_url。

    三者都没有时,start 失败。

  • 一条连接上的消息分两类:二进制帧 = 音频,文本帧 = JSON 控制消息。

4.2 start 帧

连接建立后,模块发出的第一条消息一定是 start 帧(文本):

{
  "type": "start",
  "uuid": "5f1c9a2e-1111-2222-3333-444455556666",
  "stream_id": "…",
  "external_id": "order-20261120-001",
  "sample_rate": 16000,
  "mix_type": "mono",
  "metadata": {"service": "ai_hotline", "caller": "1001"}
}
字段 说明
type 固定为 start
uuid FreeSWITCH 通道 UUID。后端调用 FCC 或 ESL 控制这通电话时用它
stream_id 模块为本次推流会话生成的 ID,HTTP / JSON API 用它定位会话
external_id 业务关联 ID,通过 JSON / HTTP API 启动时传入;没有则为空字符串
sample_rate 实际采样率,以通话编码为准,见第 5 章
mix_type mono / mixed / stereo
metadata 可选。通过拨号计划应用或命令行 API 启动时传入的 JSON,原样嵌入;没有传入时不出现这个字段

后端必须以 start 帧里的 sample_rate 和 mix_type 为准来解析音频,不要用自己的配置去假设。

4.3 上行音频:三种声道模式

上行音频是二进制帧,格式是 PCM16LE(16 位有符号整数、小端序),采样率等于 start 帧里的 sample_rate。

单声道每 20ms 的字节数:

字节数 = 采样率 × 2(字节/采样)× 0.02(秒)
8000 Hz  → 320 字节
16000 Hz → 640 字节
48000 Hz → 1920 字节

帧长一般是 20ms,但取决于通话的打包时长(ptime)。后端请把上行音频当作连续的字节流处理,不要假设每条消息的长度固定。

三种模式的区别:

mix_type 声道 内容 适用场景
mono 1 只有采集方向(来电者的声音) 实时 ASR、AI 对话(推荐)
mixed 1 采集方向 + 写方向混成一路 整通录音、整体情绪分析
stereo 2 左声道 = 采集方向,右声道 = 写方向,按采样点交织 质检、坐席辅助,需要区分说话人

stereo 的字节排列(每个采样点 2 字节):

| L0 | R0 | L1 | R1 | L2 | R2 | ...
  └─ 采集方向(如客户)  └─ 写方向(如坐席)

所以 stereo 下每帧字节数是单声道的 2 倍:16000 Hz、20ms 时是 1280 字节。后端拆分声道的示例:

import array

def split_stereo(frame: bytes) -> tuple[bytes, bytes]:
    pcm = array.array("h", frame)          # 机器字节序需为小端(x86/ARM 均是)
    return pcm[0::2].tobytes(), pcm[1::2].tobytes()   # (左=采集方向, 右=写方向)

注意事项:

  • AI 对话一定要用 mono。用 mixed 或 stereo 时,ASR 会听到 AI 自己的声音,导致自己打断自己。
  • 在 loopback A 腿上(采集方向是写方向),mixed 和 stereo 不生效,模块按单声道发送采集方向的声音。
  • stereo 模式下,写方向这一帧如果还没准备好,右声道会填 0(静音)。
  • 未连接或重连期间,采集到的音频会直接丢弃,不会缓存后补发。
  • 配置里 default_mix_type 的内置默认值是 stereo。如果你希望默认推单声道,记得在配置里显式改成 mono。

4.4 下行音频:注入规则

后端发给模块的二进制帧会被当作要播放的音频:

  • 格式:单声道 PCM16LE;
  • 采样率:必须等于 start 帧的 sample_rate,模块不做重采样;
  • 注入方式:叠加(混音)到注入方向的帧上,而不是替换。

这几条规则直接决定后端怎么写:

① 模块内部按帧切分,尾部不足一帧会补零

帧长 = 采样率 × 2 × packet_ms / 1000。模块把收到的每条二进制消息切成整帧,最后不足一帧的部分补零凑成整帧。如果后端把 TTS 分片原样转发,每个分片结尾都会插入一小段静音,听起来是连续的"咔哒"声。

规则:每条下行消息的长度都应该是帧长的整数倍。 一句话说完时,最后一帧可以由后端自己补零。

② 下行缓冲是一个固定大小的环,满了丢最旧的帧

环的容量 = rx_buffer_ms / packet_ms 帧,同时不超过 rx_queue_limit 字节。默认值是 80 / 20 = 4 帧(80ms)。环满时再写入,会丢弃最旧的一帧,并把 rx_drop_frames 加一。

TTS 合成速度往往比实时快好几倍。如果一次性把整句话塞给模块,绝大部分音频会被丢掉,听起来就是"吞字"。

规则:后端按实时节奏发送,只领先一小段(比如 200ms),并把 rx_buffer_ms 调到明显大于这个领先量(比如 1000)。 主篇配套代码 bot/player.py 就是这么做的。

③ 叠加而不是替换

注入的音频会和这一帧原有的声音混在一起。

  • 通道在 park 时,原有的声音基本是静音,对方听到的就是纯粹的 AI 声音;
  • 通道在 bridge 时,对方会同时听到桥接另一端的声音和 AI 的声音。坐席辅助这类场景就可以利用这一点,对坐席"耳语"提示。

④ 播放可以暂停

pause_playback 后,模块停止从环里取音频,已排队的音频保留;resume_playback 后继续播放。配置项 default_autoplay=false 会让每个新会话一开始就处于播放暂停状态。

4.5 下行文本消息

后端发给模块的文本帧必须是 JSON。模块按以下顺序处理:

顺序 条件 处理
1 长度超过 max_text_payload 丢弃,发出 error 事件 backend text too large
2 带有 uuid 字段,但和本会话不一致 丢弃,发出 error 事件 uuid mismatch in websocket response
3 type 是 clear 或 interrupt_play 清空播放队列(打断)
4 带有 audio_b64 字段 按 Base64 音频处理(见下文)
5 其他任何 JSON 原样作为 taering_stream::json 事件抛出

打断:clear

{"type": "clear"}
  • 需要配置 enable_barge_in=true,否则清空失败,并发出 error 事件 failed to clear playback queue;
  • 清空下行环里还没播放的 PCM,以及兼容模式下排队中的文件(正在播放的那个文件不会被中断);
  • 发出 taering_stream::play 事件,Play-State=interrupted,并带上本轮已经播放的进度(见第 7 章)。

Base64 音频(兼容模式,一般不推荐)

{"audio_b64": "<base64>", "format": "pcm"}
format 处理方式 前提条件
pcm、pcm16、pcm16le、raw、base64、b64,或不填 解码后按 PCM 注入,规则同二进制下行 allow_text_audio=true,否则报错 text/base64 audio disabled, use binary pcm
wav、mp3、ogg 解码后写入 temp_dir 下的临时文件,排进文件播放队列,用 FreeSWITCH 的播放器播放,播完删除 enable_file_playback=true(默认开启)

文件播放适合后端只能产出整段 wav/mp3 的场景,但延迟高、无法流式,并且会产生 queued / start / done 等播放事件。实时对话请使用二进制 PCM。

自定义 JSON:给业务系统传话

除上面几类以外的 JSON,会作为 taering_stream::json 事件发出,事件正文就是这段 JSON。比如后端识别到"转人工"意图时,可以发:

{"type": "intent", "name": "transfer_human", "reason": "客户要求人工"}

订阅了这个事件的 ESL 程序就能收到,然后执行转接。这是一条"AI 后端 → 呼叫控制系统"的通道,好处是后端不需要知道控制系统的地址。主篇的做法是后端直接调用 FCC 接口,两种方式都可以。

4.6 结束:stop 帧与连接关闭

推流会话有两种结束方式,后端看到的情况不一样:

结束方式 后端收到什么
显式停止:拨号计划 taering_stream stop、命令行 <uuid> stop、JSON/HTTP 的 stop 先收到一条 stop 帧,然后连接关闭
直接挂机 不发 stop 帧,连接直接关闭

stop 帧和 start 帧的字段一样,只是 type 为 stop。拨号计划应用和命令行 API 可以附带 metadata:

taering_stream stop {"reason":"transfer_to_human"}
{"type":"stop","uuid":"…","stream_id":"…","external_id":"","sample_rate":16000,"mix_type":"mono","metadata":{"reason":"transfer_to_human"}}

规则:后端要把"收到 stop"和"连接关闭"都当作通话结束,在两种情况下都释放 ASR/TTS 连接等资源。

4.7 断线重连

连接意外断开后(后端重启、网络抖动),模块会自动重连:

  • 退避时间:第 n 次重连的等待时间 = reconnect_base_ms × 2^(n−1),指数最多到 2⁶,并且不超过 reconnect_max_ms。默认值下依次是 300、600、1200、2400、4800、5000、5000 … 毫秒。
  • 次数上限:reconnect_max_attempts,默认 0 表示无限重连;超过上限后,会话进入 stopping 状态。
  • 地址:重连使用原来的 URL,不会切换到 default_ws_urls 里的其他地址。
  • 重新握手:重连成功后,模块会再发一次 start 帧,uuid 和 stream_id 都不变。
  • 不补发:断线期间采集到的音频已经丢弃,不会补发。

规则:后端要能处理"同一个 uuid 的第二次 start"。比如把它当作一次续接:恢复对话上下文,并重新建立 ASR 会话。

↑ 回到目录


5. 采样率与编码

start 时请求的采样率(拨号计划里的 16k、API 里的 sample_rate)只是期望值。模块会读取通道当前读方向编码的实际采样率;只要能读到,就以实际值为准:

通话编码 start 帧里的 sample_rate
PCMA / PCMU(G.711) 8000
G722 16000
OPUS 48000

模块不做重采样。所以:

  • ASR 要按 sample_rate 配置输入采样率;
  • TTS 要按 sample_rate 合成输出,或者后端自己重采样后再发给模块;
  • 想要 16k 宽带音质,就在软电话、网关或 FreeSWITCH 的编码偏好里把 G722 排在前面;
  • 运营商线路通常是 PCMA(8k),记得用 8k 下的识别效果做评估。

编码协商发生在 answer 之前。一定要在 answer 之后再 start,否则读到的可能不是最终的编码。

↑ 回到目录


6. 四种控制方式

6.1 拨号计划应用

taering_stream start [ws://url | wss://url | -] [mono | mixed | stereo | -] [8k | 16k | … | -] [metadata_json]
taering_stream start [mono | mixed | stereo | -] [8k | 16k | … | -] [metadata_json]     ← 省略 URL 的简写
taering_stream stop  [metadata_json]
taering_stream clear                                                                   ← 等同 interrupt_play
  • - 表示使用配置里的默认值;
  • 参数按空格切分,所以 metadata JSON 里不能有空格。写在 XML 里时,双引号要写成 &quot;;
  • 应用会立即返回,拨号计划继续往下执行。所以 start 之后需要 park 或 bridge 之类的应用让通道保持住;
  • 执行结果写入通道变量 taering_stream_result:
值 含义
+OK 成功
+OK already started 这个通道已经在推流(仅 start)
-ERR 失败:授权不足或并发已满、没有可用 URL、通道异常、clear 时未开启打断、stop 时没有会话

完整示例:

<extension name="ai_bot">
  <condition field="destination_number" expression="^8000$">
    <action application="answer"/>
    <action application="taering_stream" data="start - mono 16k {&quot;scene&quot;:&quot;hotline&quot;}"/>
    <action application="park"/>
  </condition>
</extension>

<extension name="human_queue">
  <condition field="destination_number" expression="^7000$">
    <action application="taering_stream" data="stop {&quot;reason&quot;:&quot;to_human&quot;}"/>
    <action application="callcenter" data="support@default"/>
  </condition>
</extension>

6.2 命令行 API:taering_stream

在 fs_cli 里执行,或者通过 ESL 发送 api / bgapi 命令:

命令 返回 说明
taering_stream version +OK module=… version=… build_id=… barge_in=… capture_route=loopback-aware license=… 版本与能力
taering_stream stats 见第 9 章 运行指标
taering_stream license 见第 9 章 授权状态
taering_stream <uuid> start [url|-] [mix|-] [rate|-] [metadata] +OK stream started / -ERR stream already exists / -ERR failed to start / -ERR <授权原因> 启动
taering_stream <uuid> stop [metadata] +OK stopping 停止,会发送 stop 帧
taering_stream <uuid> pause / resume +OK paused stream+playback 同时暂停/恢复采集和播放
taering_stream <uuid> pause_stream / resume_stream +OK stream paused 只暂停/恢复上行采集
taering_stream <uuid> pause_play / resume_play +OK playback paused 只暂停/恢复下行播放
taering_stream <uuid> interrupt_play +OK playback queue cleared 打断,需要 enable_barge_in=true
taering_stream <uuid> send_text <text> +OK text queued 给后端发一条文本帧

注意:

  • 对一个不存在的会话执行操作时返回 -ERR stream not found。另外,interrupt_play 在未开启 enable_barge_in 时也返回同样的提示,排查时别被误导。
  • send_text 只取第一个空格前的内容,发送带空格的文本请改用 JSON API。

6.3 JSON API:taering_stream_json

面向程序的稳定接口,参数和返回都是 JSON。通过 ESL 调用:

api taering_stream_json {"action":"start","channel_id":"<uuid>","mix_type":"mono","external_id":"order-001","request_id":"req-001"}

其他 FreeSWITCH 模块也可以在进程内通过 switch_api_execute("taering_stream_json", …) 调用。

start

字段 必填 说明
action ✅ start
channel_id ✅ 通道 UUID
ws_url 不填则使用配置里的默认地址
mix_type 不填则使用 default_mix_type
sample_rate 数字或字符串(16000 / "16k"),不填则使用 default_sample_rate
external_id 业务关联 ID,会出现在 start 帧和所有事件头里
request_id 幂等键(见下文)

JSON API 和 HTTP API 启动时不支持 metadata;需要传 metadata 的话,用拨号计划应用或命令行 API。反过来,external_id 和 request_id 只能通过 JSON API 和 HTTP API 设置。

成功时返回会话信息:

{"ok":true,"stream_id":"…","channel_id":"…","external_id":"order-001","request_id":"req-001","state":"connecting","connected":false,"capture_paused":false,"playback_paused":false,"tx_drop_frames":0,"rx_drop_frames":0,"idempotent":false}

幂等:当 request_id 非空、并且有一个仍在运行的会话使用了同一个 request_id 时:

  • 如果是同一个 channel_id,直接返回那个会话,"idempotent":true;
  • 如果是不同的 channel_id,返回 IDEMPOTENCY_CONFLICT。

幂等记录只在会话运行期间有效,会话结束后同一个 request_id 可以再次使用。

其他动作:用 stream_id 或 channel_id 定位会话。

action 说明
get 查询会话,返回上面的会话信息
stop 停止,会发送 stop 帧
pause_capture / resume_capture 暂停/恢复上行采集
pause_playback / resume_playback 暂停/恢复下行播放
interrupt_playback 打断,需要 enable_barge_in=true
send_text 必须带 text 字段,作为文本帧发给后端
api taering_stream_json {"action":"get","channel_id":"<uuid>"}
api taering_stream_json {"action":"send_text","stream_id":"<stream_id>","text":"{\"type\":\"hint\",\"content\":\"客户是 VIP\"}"}

动作成功时返回:

{"ok":true,"stream_id":"…","action":"pause_capture","accepted":true}

错误码:

code 含义
INVALID_REQUEST 缺少 action;start 缺少 channel_id;send_text 缺少 text
BACKEND_NOT_CONFIGURED 既没传 ws_url,配置里也没有默认地址
STREAM_ALREADY_EXISTS 这个通道已经在推流
IDEMPOTENCY_CONFLICT request_id 正被另一个通道使用
START_FAILED 通道不存在、挂载失败,或授权并发已满
STREAM_NOT_FOUND stream_id / channel_id 找不到运行中的会话
UNKNOWN_ACTION 不支持的动作
ACTION_FAILED 动作被拒绝(比如未开启打断时执行 interrupt_playback)
INTERNAL_ERROR 内部错误

6.4 HTTP REST API

HTTP API 是 JSON API 的 HTTP 外壳,默认关闭。开启方式:

<param name="api_enabled" value="true"/>
<param name="api_listen_host" value="127.0.0.1"/>
<param name="api_listen_port" value="18081"/>
<param name="api_token" value="用 openssl rand -hex 32 生成"/>

开启 HTTP API 时 api_token 不能为空,否则模块会加载失败。 改完配置要执行 reload mod_taering_stream。这个接口是明文 HTTP,建议只监听 127.0.0.1;需要跨机器访问时,前面加 TLS 反向代理。

所有请求都要带 Authorization: Bearer <api_token>。请求体最大 64KB。

方法 路径 对应 JSON 动作 成功状态码
GET /api/v1/health — 200
POST /api/v1/streams start(请求体字段同 6.3,不用写 action) 202
GET /api/v1/streams/{stream_id} get 200
POST /api/v1/streams/{stream_id}/actions 请求体里的 action 200
DELETE /api/v1/streams/{stream_id} stop 200

失败时的状态码:401 鉴权失败;404 会话或路由不存在;409 冲突(IDEMPOTENCY_CONFLICT、STREAM_ALREADY_EXISTS);400 其他错误。

TOKEN=你的api_token; API=http://127.0.0.1:18081/api/v1

curl -sS -H "Authorization: Bearer $TOKEN" $API/health

curl -sS -X POST $API/streams -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"channel_id":"<uuid>","mix_type":"mono","sample_rate":16000,"external_id":"order-001","request_id":"req-001"}'

curl -sS -X POST $API/streams/<stream_id>/actions -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"action":"interrupt_playback"}'

curl -sS -X DELETE -H "Authorization: Bearer $TOKEN" $API/streams/<stream_id>

202 的意思是"会话已创建、正在连接",不代表后端已经连上。确认连接状态请用 GET /streams/{stream_id} 查 state,或者订阅 taering_stream::connect 事件。

6.5 怎么选

场景 推荐
固定流程:某个号码一接通就开 AI 拨号计划应用
手工调试、排障 命令行 API
已有 ESL 程序控制呼叫 JSON API(通过 ESL 的 api 命令)
业务系统不想接 ESL,只想调 HTTP HTTP API
需要传 metadata 拨号计划应用或命令行 API
需要 external_id / 幂等 JSON API 或 HTTP API

↑ 回到目录


7. 事件

模块会发出 5 种 CUSTOM 事件。所有事件都带有:

事件头 说明
Unique-ID 通道 UUID
Stream-ID 会话 ID(会话仍存在时才有)
External-ID 业务关联 ID(会话仍存在时才有)
子类 何时发出 事件正文
taering_stream::connect 会话创建、连接成功、开始重连 stream started、initial websocket connect scheduled、websocket connected、reconnect requested
taering_stream::disconnect 连接断开 断开原因
taering_stream::error 各类错误 例如 invalid websocket url、reconnect failed、tx queue overflow、pcm payload too large、backend text too large、uuid mismatch in websocket response、failed to clear playback queue、text/base64 audio disabled, use binary pcm、invalid audio_b64、file playback disabled、play queue overflow
taering_stream::json 后端发来无法识别的 JSON 后端发来的原文
taering_stream::play 打断、文件播放状态变化 无,信息在事件头里

play 事件的额外事件头:

事件头 说明
Play-State queued、start、done、interrupted、error_no_session、error_playback
Track-ID 文件播放的轨道号;PCM 打断时为空
Audio-Format pcm、wav、mp3、ogg
Played-Ms / Played-Samples 打断时本轮 PCM 已经实际播放的时长和采样数
Playback-Generation 播放批次号。下行环从空变为非空时、以及每次打断时都会加一,可用来区分打断前后的不同回复

PCM 流式播放不会发出 start / done 事件,也不会逐块报告进度。只有被打断时,才会发出一条带进度的 interrupted 事件。文件播放会发出 queued / start / done 或 error 系列事件。

用 Played-Ms 截断对话历史:打断发生时,用 Played-Ms 结合 TTS 的语速(或者 TTS 返回的字级时间戳),就能算出客户实际听到了哪几个字。把机器人的上一轮回复截断到这里再写进对话历史,大模型就不会以为客户听完了整段话。

订阅事件:

在 fs_cli 里:

/event plain CUSTOM taering_stream::connect taering_stream::disconnect taering_stream::error taering_stream::json taering_stream::play

ESL 程序(不依赖第三方库的 Python 示例):

import socket
from urllib.parse import unquote

def esl_events(host="127.0.0.1", port=8021, password="ClueCon"):
    s = socket.create_connection((host, port))
    f = s.makefile("rb")

    def read_msg():
        headers = {}
        while (line := f.readline().decode().rstrip("\n")):
            k, _, v = line.partition(": ")
            headers[k] = v
        body = f.read(int(headers["Content-Length"])).decode() if "Content-Length" in headers else ""
        return headers, body

    read_msg()                                             # auth/request
    s.sendall(f"auth {password}\n\n".encode()); read_msg()
    s.sendall(b"event plain CUSTOM taering_stream::connect taering_stream::disconnect "
              b"taering_stream::error taering_stream::json taering_stream::play\n\n"); read_msg()
    while True:
        _, body = read_msg()                               # 事件以 text/event-plain 形式放在正文里
        ev, _, ev_body = body.partition("\n\n")
        h = {k: unquote(v) for k, v in (l.split(": ", 1) for l in ev.splitlines() if ": " in l)}
        yield h.get("Event-Subclass"), h, ev_body

for subclass, h, body in esl_events():
    print(subclass, h.get("Unique-ID"), h.get("Play-State", ""), h.get("Played-Ms", ""), body)

event plain 格式下事件头的值经过 URL 编码(比如 taering_stream%3A%3Aplay),示例里已用 unquote 解码。生产环境建议使用成熟的 ESL 库,并处理断线重连。

↑ 回到目录


8. 配置参数全表

文件:autoload_configs/mod_taering_stream.conf.xml。修改后必须执行 reload mod_taering_stream(会断开当前所有推流);只执行 reloadxml 不会生效。超出范围的值会回落到默认值。

8.1 后端与媒体

参数 默认 范围 说明
default_ws_url 空 — 默认后端地址
default_ws_urls 空 逗号或分号分隔 多个后端,每个新会话轮询选择一个,优先级高于 default_ws_url
default_mix_type stereo mono / mixed / stereo AI 对话请改为 mono
default_sample_rate 16000 8000–192000 期望采样率,实际以通话编码为准
default_autoplay true 布尔 false 时新会话的下行播放默认处于暂停状态
packet_ms 20 10–60 下行切帧和缓冲的帧时长;后端对齐帧长时使用

8.2 缓冲与限额

参数 默认 范围 说明
tx_buffer_ms 80 20–10000 上行缓冲时长(帧数 = 本值 ÷ packet_ms)
rx_buffer_ms 80 20–10000 下行缓冲时长,满了丢最旧的帧。后端领先发送时请调大,比如 1000
tx_queue_limit 1 MiB 64 KiB–256 MiB 上行队列字节上限,同时限制上行缓冲帧数
rx_queue_limit 1 MiB 64 KiB–256 MiB 下行字节上限,同时限制下行缓冲帧数
play_queue_limit 32 1–10000 文件播放队列最多排多少个文件
max_text_payload 2 MiB 1 KiB–64 MiB 单条文本消息的上限
max_audio_payload 8 MiB 1 KiB–256 MiB 单条音频消息的上限(含 Base64 解码后的大小)

8.3 连接与重连

参数 默认 范围 说明
reconnect_base_ms 300 10–60000 首次重连等待时间
reconnect_max_ms 5000 10–600000 重连等待时间上限
reconnect_max_attempts 0 0–1000000 0 = 无限重连
network_workers 0 0–8 网络线程数。0 = 自动:CPU ≤4 核时等于核数,5–8 核时为 6,更多时为 8

8.4 功能开关

参数 默认 说明
enable_barge_in false 打断开关。关闭时 clear / interrupt_play / interrupt_playback 全部失败
allow_text_audio false 是否接受 Base64 编码的 PCM
enable_file_playback true 是否接受 Base64 编码的 wav/mp3/ogg 文件播放
temp_dir /tmp/mod_taering_stream 文件播放的临时目录
log_debug false 调试日志,会打印媒体方向和注入细节,日志量很大,只在排障时开

8.5 HTTP API

参数 默认 说明
api_enabled false 是否开启 HTTP API
api_listen_host 127.0.0.1 监听地址(IPv4)
api_listen_port 18081 监听端口
api_token 空 Bearer Token。开启 API 时必须设置,否则模块加载失败

8.6 推荐配置:AI 对话

<configuration name="mod_taering_stream.conf" description="Taering bidirectional audio stream">
  <settings>
    <param name="default_ws_urls" value="ws://10.0.0.11:9000/stream,ws://10.0.0.12:9000/stream"/>
    <param name="default_mix_type" value="mono"/>
    <param name="default_sample_rate" value="16000"/>
    <param name="enable_barge_in" value="true"/>
    <param name="packet_ms" value="20"/>
    <param name="tx_buffer_ms" value="200"/>
    <param name="rx_buffer_ms" value="1000"/>
    <param name="reconnect_base_ms" value="300"/>
    <param name="reconnect_max_ms" value="5000"/>
    <param name="allow_text_audio" value="false"/>
  </settings>
</configuration>

↑ 回到目录


9. 运维命令:version / stats / license

version

+OK module=taering_stream version=0.55 build_id=… interrupt_play=enabled play_progress=enabled barge_in=enabled capture_route=loopback-aware license=enabled

barge_in 反映的是当前配置里 enable_barge_in 的值。

stats

module=taering_stream version=0.55 build_id=…
+OK active_sessions=1 workers=4 text_audio=false barge_in=true file_playback=true packet_ms=20 tx_buffer_ms=200 rx_buffer_ms=1000 licensed_active=1 license_status=… license_mode=… license_max=… license_expire_at=…
worker[0] sessions=1 tx_fill=2/10 rx_fill=7/50 tx_drop=0 rx_drop=0 reconnects=0
worker[1] sessions=0 …
字段 看什么
active_sessions / licensed_active 当前推流数 / 占用的授权名额
tx_fill / rx_fill 上行/下行缓冲当前帧数 / 总帧数。rx_fill 长期接近满,说明后端发得太快
tx_drop 上行丢帧。持续增长说明后端读得太慢,或网络拥塞
rx_drop 下行丢帧。持续增长说明后端发送太快,或 rx_buffer_ms 太小,表现为"吞字"
reconnects 累计重连次数

要看某一个会话的数据,用 taering_stream_json {"action":"get","channel_id":"<uuid>"},看返回里的 tx_drop_frames / rx_drop_frames。

license

+OK license_status=… license_mode=… max_concurrency=… active_concurrency=… fingerprint=… … expire_at=… cache_expire_at=… message=…

授权状态为 pending 时推流无法启动。试用版功能完整,限 1 路并发。商业授权(不限并发)请联系 taering@vip.qq.com,完成在线授权后即可使用。

↑ 回到目录


10. 自己写后端的检查清单

不管用什么语言、对接哪家 ASR/TTS,后端都要做到下面这些:

连接

上行

下行

结束

参考实现:主篇配套代码的 bot/server.py(会话管理)和 bot/player.py(帧对齐、节奏、打断)。

↑ 回到目录


11. 常见问题

Q:后端收不到任何音频?

先看 start 帧有没有到。到了但没有音频:检查是否执行了 pause / pause_capture;通道是否已经 answer;log_debug=true 后看 media READ 日志有没有帧。

Q:对方听不到后端发的声音?

依次检查:是否执行了 pause_playback,或配置了 default_autoplay=false;采样率是否一致;start 之后是否有 park 或 bridge 让通道保持住;stats 里的 rx_drop 是否在增长。

Q:声音变调?

下行采样率和 start 帧的 sample_rate 不一致。

Q:有规律的"咔哒"声?

下行消息没有按整帧对齐,模块对每条消息的尾部补了零。

Q:吞字、断断续续?

下行缓冲溢出:后端发得太快,或者 rx_buffer_ms 太小。看 stats 里的 rx_drop。

Q:clear 不起作用?

enable_barge_in 没有开;或者开了但没有执行 reload mod_taering_stream。用 taering_stream version 确认 barge_in=enabled。

Q:AI 自己打断自己?

mix_type 不是 mono。注意配置里 default_mix_type 的内置默认值是 stereo。

Q:重连后对话上下文丢了?

重连会重新发送 start 帧,后端如果把它当成一通新电话,就会丢失上下文。请按 uuid 保存会话状态。

Q:可以同时给一个通道开两路推流吗?

不可以,一个通道同时只能有一个推流会话。需要同时做 AI 对话和质检时,用一路 stereo 推给一个后端,在后端内部分发。


相关链接

系列文章

↑ 回到顶部


评论