mod_audio_fork

模块定位

mod_audio_fork 是一个 FreeSWITCH 模块，它在通话上附加一个 media bug（媒体监听器），把通话的实时音频以 L16 编码通过 WebSocket 推送到远端服务器，同时支持远端推回音频做实时播放。是本项目把 FreeSWITCH 与 AI 语音服务串起来的唯一桥梁。

• 仓库来源：Wangijun/mod_audio_fork，fork 自 W1ck3dZA/mod_audio_fork
• 语言：C++（~78%）+ C
• 协议：标准 RFC6455 WebSocket，子协议 audio.drachtio.org

为什么不用 mod_unimrcp

本项目当前版本完全不依赖 mod_unimrcp，识别只走 mod_audio_fork。

核心能力

• 双向音频流：上行通过 WS 上传 PCM16；下行可接收服务端推回的 base64 JSON 或 binary 音频帧
• 音频标记：mark / clearMarks 同步播放节奏
• 混流模式：mono（仅主叫）、mixed（主被叫混音）、stereo（双声道分离）
• 采样率：8000 / 16000 / 24000 / 32000 / 48000 / 64000 Hz，内置 Speex 重采样
• SIMD 优化：AVX2 / SSE2 编译加速
• TLS 支持：wss:// 直连
• 平滑停止：graceful-shutdown 排空缓冲后再关闭
• HTTP Basic Auth：通过 channel variable 注入认证头

构建与安装

模块仓库提供 build.sh 一键脚本：

1
2
3
4

git clone https://github.com/Wangijun/mod_audio_fork.git
cd mod_audio_fork
chmod +x build.sh
sudo ./build.sh all

或分步：

1
2
3

sudo ./build.sh deps      # 装编译依赖
./build.sh build          # 编译
sudo ./build.sh install   # 安装到 FreeSWITCH 的 mod 目录

详细构建说明见仓库 BUILD.md。

在 FreeSWITCH 中加载：

1
2

<!-- conf/autoload_configs/modules.conf.xml -->
<load module="mod_audio_fork"/>

或运行时：

1

fs_cli -x "load mod_audio_fork"

uuid_audio_fork 命令集

通用语法：uuid_audio_fork <uuid> <command> [args...]

示例：

1
2
3
4

fs_cli -x "uuid_audio_fork <uuid> start ws://127.0.0.1:10096/audio mono 16k callflow_asr {}"
fs_cli -x "uuid_audio_fork <uuid> pause callflow_asr"
fs_cli -x "uuid_audio_fork <uuid> resume callflow_asr"
fs_cli -x "uuid_audio_fork <uuid> stop callflow_asr {\"reason\":\"complete\"}"

bugname 在同一通通话里需保持唯一；callflow-esl 默认用 callflow_asr。

关键环境变量

关键 channel variable

可在 dialplan 或 uuid_setvar 中设置：

自定义事件

模块在 FreeSWITCH event bus 上发布以下 CUSTOM event（subclass）：

callflow-esl 主要消费 connect / disconnect / transcription 三种。

上下行消息协议（与服务端约定）

客户端 → 服务端

• 第一帧：text frame，JSON metadata。callflow-esl 默认下发：

  1 2 3 4 5

  { "uuid": "<fs-channel-uuid>", "callerId": "...", "direction": "inbound" }

• 后续帧：binary frame，原始 16kHz / mono / PCM16 little-endian 音频

服务端 → 客户端

服务端可发 text frame，JSON 体按 type 分发：

1
2
3
4
5
6
7
8

{ "type": "transcription", "text": "...", "isFinal": true }
{ "type": "playAudio", "audioContent": "<base64>", "sampleRate": 16000 }
{ "type": "killAudio" }
{ "type": "mark", "name": "..." }
{ "type": "clearMarks" }
{ "type": "transfer", "to": "..." }
{ "type": "disconnect" }
{ "type": "error", "message": "..." }

当通话需要服务端推 TTS 给主叫播放时（双向音频模式），playAudio 携带 base64 音频或 binary 帧。

mark 队列最大 30 项。

在本项目中的使用

callflow-esl 通过配置项 audioFork 调用本模块：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "audioFork": {
    "wsUrl": "ws://192.168.2.246:10096/audio",
    "bugName": "callflow_asr",
    "mixType": "mono",
    "sampleRate": "16k",
    "bidirectionalAudioEnabled": false,
    "bidirectionalAudioStreamEnabled": false,
    "connectTimeoutMs": 5000,
    "eventSubscriptionMode": "all"
  }
}

runtime 在 ctx.hear() 启动时下发 uuid_audio_fork start，并在结束 / 挂机时下发 stop。eventSubscriptionMode 控制 ESL 事件订阅策略，默认 "all" 是当前唯一稳定下发 mod_audio_fork::transcription 的策略。详见 配置参考。

已知坑

参考链接

• 源码仓库：https://github.com/Wangijun/mod_audio_fork
• 上游：https://github.com/W1ck3dZA/mod_audio_fork
• 子协议命名来源：drachtio 项目（audio.drachtio.org 是其约定的 WS 子协议）