本文是《从零搭建 AI + 人工呼叫中心》的补充篇。主篇讲"怎么跑通",这一篇讲"为什么这样跑":模块在通话里做了什么、WebSocket 上传输的每一种消息、四种控制方式、事件、全部配置参数,以及自己写后端时必须遵守的规则。
适合:要自己实现 AI 后端、要对接其他 ASR/TTS 厂商、或者要把模块集成进现有呼叫系统的开发者。
本文基于 mod_taering_stream 0.55 版本。
目录
- 1. 模块做什么、不做什么
- 2. 工作原理:媒体钩子与方向
- 3. 一个推流会话的生命周期
- 4. WebSocket 协议
- 5. 采样率与编码
- 6. 四种控制方式
- 7. 事件
- 8. 配置参数全表
- 9. 运维命令:version / stats / license
- 10. 自己写后端的检查清单
- 11. 常见问题
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 的来源,按优先级:
start时显式传入的 URL;- 配置里的
default_ws_urls(逗号或分号分隔多个地址,每次新建会话按轮询选一个); - 配置里的
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 里时,双引号要写成
"; - 应用会立即返回,拨号计划继续往下执行。所以
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 {"scene":"hotline"}"/>
<action application="park"/>
</condition>
</extension>
<extension name="human_queue">
<condition field="destination_number" expression="^7000$">
<action application="taering_stream" data="stop {"reason":"to_human"}"/>
<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::playESL 程序(不依赖第三方库的 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=enabledbarge_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 推给一个后端,在后端内部分发。
相关链接
- 主篇:《从零搭建 AI + 人工呼叫中心》:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-from-scratch
- freeswitch_stream_mod:https://github.com/taering365/freeswitch_stream_mod
- mod_fcc:https://github.com/taering365/mod_fcc
- 配套代码:https://www.liaoxinghui.com/upload/ai-callcenter-demo.zip
- 商业授权:taering@vip.qq.com
系列文章
- 主篇:从零搭建 AI + 人工呼叫中心:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-from-scratch
- 系列 1:mod_taering_stream 媒体协议详解:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-01-stream-protocol
- 系列 2:FCC 控制面深入:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-02-fcc
- 系列 3:AI 外呼:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-03-outbound
- 系列 4:实时质检与坐席辅助:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-04-qa-assist
- 系列 5:延迟优化:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-05-latency
- 系列 6:接入运营商线路:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-06-carrier
- 系列 7:生产化:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-07-production
- 系列 8:排障手册:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-08-troubleshooting