外观
FreeSWITCH 核心模块与实时 AI 语音集成专题
本文全面盘点 WSL /data/docker_fs_server/freeswitch-install/lib/freeswitch/mod/ 目录下预置编译的 80+ 个核心扩展模块，介绍各模块的核心功能、应用场景及其在 AI Voice 语音平台中的具体用途。
1. AI 语音核心链路架构
在 AI Voice Platform 中，FreeSWITCH 充当高并发音频管道与分流核心：
2. 80+ 个核心扩展模块功能详解
2.1 实时 AI 语音与多媒体流核心模块（AI Voice Platform 关键链路 ⭐️）
模块名称 (.so) | 功能说明与核心用途 |
|---|---|
mod_audio_fork | 平台自研核心 AI 音频交互模块。提供高性能 WebSocket 流式识别分流与 FreeSWITCH 官方标准 SWITCH_FILE_INTERFACE 原生流式驱动。上行通过 uuid_audio_fork 指令将 16kHz PCM 单声道音频实时推送到 sherpa-asr-server (10096)、funasr-asr-server (10099) 或前置代理 stream-vad-proxy (10093) 实现流式 ASR 与开嗓打断；下行支持通过 playback audio_fork://${uuid} 进行防崩加固的低延迟流式播放，全面剔除 Boost 依赖。 |
mod_shout | 流式 TTS 播放核心模块。集成 libshout/libmp3lame/libmpg123（由底层 Debian 系统 APT 运行时库驱动），支持通过 shout://<tts-host>:9080/tts-stream/<id>.mp3 协议边合成边流式解码播放 TTS 音频，大幅降低首包播放延迟（注：在多方会议 mod_conference 中为避免阻塞混音线程，会议播放统一回退为标准 WAV 文件）。 |
mod_local_stream | 本地连续流媒体发生器（AI 通话背景音混音核心）。支持从内存预加载音频文件循环广播（如 local_stream://ambient/office/16000 或 8000），在 AI 外呼或会议通话中无缝注入真实办公室环境白噪音，消除纯静音尴尬且无磁盘 I/O 开销（素材可由工程 data/ 目录按需装配到 sounds/ambient/office/）。 |
mod_tts_commandline | 命令行外部 TTS 工具调用接口，允许通过外部脚本或独立可执行文件生成语音。 |
mod_vmd | 基础留言音/蜂鸣音检测（Voicemail Beep Detection），用于外呼机器人识别被叫是否已进入语音信箱蜂鸣阶段。 |
mod_avmd | 高级答录机检测（Advanced Voicemail Detection），基于快速幅值/频率方差算法精确判定对端是真人还是智能答录机。 |
mod_soundtouch | 音频音调与速率实时调整模块，支持在呼叫中进行变声、升降调与变速播放。 |
2.2 通信协议栈与终端端点模块 (Endpoints)
模块名称 (.so) | 功能说明与核心用途 |
|---|---|
mod_sofia | 核心 SIP 协议栈。基于 Sofia-SIP 实现 SIP/TLS/WebRTC 注册、呼叫控制、NAT 穿透与 SIP Trunk 网关管理。 |
mod_rtc | WebRTC 核心媒体引擎。处理 RTCP、ICE 候选协商与 DTLS-SRTP 媒体流加密。 |
mod_verto | FreeSWITCH 原生 WebRTC JSON-RPC 信令通道，用于 Verto 协议软电话与音视频通信。 |
mod_loopback | 本地回环端点（loopback/<ext>），用于内部会话测试、桥接以及复杂多腿呼叫控制。 |
mod_skinny | 思科 SCCP（Skinny Client Control Protocol）终端接入支持，兼容 Cisco IP 话机。 |
mod_rtmp | RTMP 实时流媒体协议端点，支持与 Flash 或流媒体直播服务对接。 |
mod_alsa | Linux ALSA 声卡驱动端点，用于服务器物理声卡直连麦克风/扬声器测试。 |
2.3 事件驱动与管理控制模块 (Event & Socket)
模块名称 (.so) | 功能说明与核心用途 |
|---|---|
mod_event_socket | ESL 管理核心。对外开放 8021 TCP 端口，驱动 apps/callflow-esl 业务服务对 FreeSWITCH 的全生命周期出入站编排控制。 |
mod_esl | ESL 客户端 C 库封装模块，供本地扩展调用 ESL 接口。 |
mod_event_multicast | 局域网 UDP 组播事件广播模块，用于跨机器多节点事件同步。 |
mod_erlang_event | 与 Erlang 节点进行 C-Node 级事件直连互通，适用于 Erlang 高并发调度系统。 |
mod_amqp | RabbitMQ / AMQP 消息队列集成，支持将呼叫事件直接投递到消息中间件。 |
2.4 拨号计划与呼叫路由模块 (Dialplans & Routing)
模块名称 (.so) | 功能说明与核心用途 |
|---|---|
mod_dialplan_xml | 核心 XML 拨号计划引擎。解析 etc/freeswitch/dialplan/ 下的全部 XML 呼叫路由规则。 |
mod_dialplan_asterisk | Asterisk 风格 extensions.conf 拨号方案解析器，方便从 Asterisk 迁移老旧配置。 |
mod_dialplan_directory | 从分机目录中直接查找路由的拨号计划接口。 |
mod_enum | ENUM（E.164 电话号码到 DNS NAPTR/SIP URI）路由解析，支持全球电信号码解析。 |
mod_easyroute | 基于数据库的简单动态路由模块，支持按前缀查表分流。 |
mod_lcr | 动态最少成本路由（Least Cost Routing）计算与分流引擎，用于运营商多线路比价外呼。 |
2.5 呼叫控制与业务应用组件 (Applications & Call Center)
模块名称 (.so) | 功能说明与核心用途 |
|---|---|
mod_commands | CLI / ESL 基础指令集。提供 originate, uuid_kill, status, show channels, eval 等数百个核心 API。 |
mod_dptools | 拨号方案核心动作库。提供 bridge, answer, hangup, playback, record, socket, export, set, sleep 等核心应用。 |
mod_conference | 高并发多方音视频会议室。支持音视频混音、画中画混画面、静音控制与成员角色管理。 |
mod_fifo | 先进先出呼叫排队等待队列，适用于简易排队业务。 |
mod_valet_parking | 呼叫代客泊车与提取（Call Parking），支持话机将呼叫暂存指定车位并换机接听。 |
mod_callcenter | 呼叫中心座席队列调度系统（ACD），支持座席签入/签出、技能组排队与多策略振铃分配。 |
mod_voicemail | 语音信箱留言录制与检索播放系统。 |
mod_voicemail_ivr | 语音信箱 IVR 交互导航菜单。 |
mod_fsv | 原生视频流录制与回放（.fsv 格式）。 |
mod_expr | 拨号方案逻辑表达式求值计算器，用于 Dialplan 条件判断。 |
mod_hash | 内存级全局 Hash 键值表与速率限制器（Limit 并发频控机制）。 |
mod_db | 基于 SQLite 的简单键值数据持久化与计数器。 |
mod_blacklist | 呼叫黑名单阻断拦截。 |
mod_cidlookup | 来电号码归属地与姓名反查。 |
mod_distributor | 呼叫按权重随机轮询分发器，用于多网关分流。 |
mod_nibblebill | 通话实时计费与扣费结算模块。 |
mod_spy | 坐席密语监听与插话（Eavesdrop / Whisper），用于班长座席质检与指导。 |
2.6 音视频编解码器模块 (Codecs)
模块名称 (.so) | 功能说明与核心用途 |
|---|---|
mod_opus | Opus 高清自适应语音编解码器。支持 8k~48k 动态采样率，WebRTC 与现代软电话首选。 |
mod_spandsp | DSP 信号处理核心。支持 T.38 传真、DTMF 双音多频生成与检测、G.726/G.711 等协议。 |
mod_g729 | 电信级 G.729 窄带高压缩语音（8kbps），广泛用于 PSTN 运营商中继与专线。 |
mod_g723_1 | G.723.1 语音编解码（5.3k / 6.3k），传统 PSTN 常见格式。 |
mod_amr / mod_amrwb | 移动蜂窝网络（3G/VoLTE/4G HD）标准窄带与宽带语音编解码。 |
mod_codec2 | 超低码率（700~3200 bps）开源语音编解码，适用于极低带宽卫星/无线电通信。 |
mod_b64 | Base64 数据编解码支持。 |
mod_vpx | VP8 / VP9 视频编解码器（WebRTC 视频通信主流格式）。 |
mod_png | PNG 图片渲染与视频占位头像支持。 |
mod_video_filter | 视频图像滤镜与画面缩放处理。 |
2.7 媒体文件格式与流通道 (Formats & Media Streams)
模块名称 (.so) | 功能说明与核心用途 |
|---|---|
mod_sndfile | 基于 libsndfile 的标准音频文件（WAV、AIFF、FLAC 等）读写解析。 |
mod_native_file | 原生裸音频文件快速流式回放（无需经过重采样与转码）。 |
mod_tone_stream | 多国拨号音、回铃音、忙音与 TGML 信号发生器。 |
mod_local_stream | 本地连续流媒体发生器（MOH 等待音乐、广播轮播，以及会议背景音 ambient/office/*）。 |
mod_av | 基于 FFmpeg / LibAV 的音视频容器封装与流格式转换。 |
mod_http_cache | 远端 HTTP 音频资源自动下载与本地缓存加速播放。 |
mod_snapshot | 视频通话实时抓拍截图。 |
2.8 数据库、话单与日志系统 (Databases, CDR & Observability)
模块名称 (.so) | 功能说明与核心用途 |
|---|---|
mod_hiredis | 高性能 Redis 客户端模块，支持分布式锁、跨节点状态共享与频控。 |
mod_pgsql | 原生 PostgreSQL 数据库连接器，支持 FreeSWITCH 核心数据库直接连入 Postgres。 |
mod_mariadb | 原生 MariaDB / MySQL 数据库连接器。 |
mod_cdr_csv | 标准 CSV 格式通话记录（CDR）本地文件持久化。 |
mod_cdr_sqlite | SQLite 格式 CDR 话单存储。 |
mod_cdr_pg_csv | 直接将 CDR 话单入库至 PostgreSQL。 |
mod_xml_cdr / mod_json_cdr | 将完整通话信令与指标按 XML / JSON 格式通过 HTTP POST 推送到第三方计费/质检中台。 |
mod_logfile | freeswitch.log 本地日志文件写入与轮转。 |
mod_console | 控制台彩色日志实时打印。 |
mod_syslog | Linux 系统 syslog 日志导出。 |
mod_graylog2 | GELF 格式日志直接投递至 Graylog / ELK 日志收集中心。 |
2.9 脚本语言与动态 Web 接口 (Languages & Web APIs)
模块名称 (.so) | 功能说明与核心用途 |
|---|---|
mod_lua | Lua 5.2 嵌入式脚本引擎。支持通过 Lua 编写复杂的通话控制逻辑与离线 IVR 脚本。 |
mod_httapi | HTTP RESTful 交互式语音响应协议（由远程 Web 服务返回 XML 驱动通话）。 |
mod_xml_curl | 动态 XML 配置拉取。支持从外部 Web 接口实时拉取 Directory 分机、Dialplan 规则与配置。 |
mod_xml_rpc | XML-RPC Web 管理接口（默认 8080 端口）。 |
mod_xml_scgi | SCGI 协议后端连接器。 |
2.10 多语种语音朗读引擎 (Say Localization)
模块名称 (.so) | 支持语种与功能用途 |
|---|---|
mod_say_en | 英语数字、日期、货币与时间自然朗读引擎 |
mod_say_zh | 中文汉字、数字、金额与时间自然朗读引擎 |
mod_say_ja | 日语数字与时间自然朗读引擎 |
mod_say_de / mod_say_fr / mod_say_es / mod_say_ru 等 | 德语、法语、西班牙语、俄语、葡萄牙语、意大利语、波兰语、泰语等多国语言朗读引擎 |
3. 模块配置与管理方式
3.1 静态配置 (modules.conf.xml)
在 freeswitch-install/etc/freeswitch/autoload_configs/modules.conf.xml 中配置随服务自启的模块：
xml
<modules>
<!-- 添加需要加载的模块 -->
<load module="mod_shout"/>
<load module="mod_pgsql"/>
<!-- 移除或注释不需要的模块 -->
<!-- <load module="mod_cdr_csv"/> -->
</modules>3.2 运行时动态管理指令
bash
# 检查模块状态
docker exec -it fs-app fs_cli -x "module_exists mod_audio_fork"
# 动态加载模块（无需重启容器）
docker exec -it fs-app fs_cli -x "load mod_shout"
# 动态卸载模块
docker exec -it fs-app fs_cli -x "unload mod_shout"
# 重新加载模块
docker exec -it fs-app fs_cli -x "reload mod_audio_fork"3.3 底层依赖库分层说明
为了实现运行时的极致轻量与高稳定，镜像构建采用了“系统 APT 依赖”与“专有核心共享库”双层解耦设计：
- Debian APT 官方系统库：如
libwebsockets（驱动mod_audio_fork的 WebSocket 通信）、libshout、libmp3lame、libmpg123（驱动mod_shout的 MP3 编解码播放）等，在构建 Docker 镜像时直接通过 APT 安装； - 专有核心底层 C/C++ 共享库 (
deps-lib/)：针对 Debian 官方源中缺乏对应版本的 4 个编译依赖（libks2,libsignalwire_client2,libsofia-sip-ua,libspandsp），打包在宿主机deps-lib/目录下，在构建时通过COPY deps-lib/ /usr/lib/注入镜像并执行ldconfig建立系统链接。