完整FreeSWITCH语音处理模块mod_audio_stream技术实现细节分享

FreeSWITCH模块mod_audio_stream技术实现细节

目的和范围

本文档涵盖 mod_audio_stream，这是一个 FreeSWITCH 模块，用于从活动通话信道捕获音频，并通过 WebSocket 或 TCP 连接将其流式传输到外部服务。该模块支持实时音频处理用例，如语音识别、AI 驱动的语音助手和自定义音频分析。

有关构建和安装说明，请参阅FreeSWITCH开源社区的快速入门指南文档和有关关于FreeSWITCH的详细的 API 命令参考，请参阅 API 参考。有关架构深入分析，请参阅架构。

什么是 mod_audio_stream？

mod_audio_stream 是一个 FreeSWITCH 可加载模块，它与 FreeSWITCH 媒体 bug 框架集成，以便在通话期间接入实时音频流。它捕获音频帧，通过可配置的管道（重采样、缓冲、编码）处理它们，并将音频传输到外部端点进行实时处理。

该模块支持双向通信：它将音频流式传输到外部服务，并从这些服务接收响应（JSON 消息或用于播放的音频），从而实现交互式语音应用程序。

主要功能

高层架构

该模块组织为五个不同的架构层，具有清晰的关注点分离：

第 5 层：外部依赖

第 4 层：音频处理

第 3 层：传输接口

第 2 层：流式传输抽象

第 1 层：FreeSWITCH 集成

mod_audio_stream.c模块注册

stream_function()API 命令处理程序

capture_callback()媒体 Bug 回调

responseHandler()事件生成器

stream_session_init()

stream_session_cleanup()

stream_frame()

private_t会话状态

BaseStreamer抽象接口

AudioStreamerWebSocket 实现

TcpStreamerTCP 实现

RingBuffer环形缓冲区

SpeexResampler采样率转换

base64_encode/decode编码

IXWebSocket静态库

组件层映射：

系统架构概述

下图显示了模块组件如何与 FreeSWITCH 核心和外部服务交互：

加载模块

uuid_audio_stream API

音频帧

stream_session_init()

capture_callback()

new AudioStreamer()new TcpStreamer()

writeBinary()

L16 音频块

JSON 响应streamAudio 命令

eventCallback()

responseHandler()

switch_event_fire()

FreeSWITCH 核心

mod_audio_stream.c模块入口

audio_streamer_glue.cpp会话逻辑

AudioStreamer /TcpStreamer

外部服务WebSocket/TCP

音频数据流管道

音频通过以下阶段在系统中流动，从捕获到传输：

stream_frame()

音频帧

重采样数据

20-500ms 块

L16 PCM

base64 二进制

媒体 Bug 捕获capture_callback()

switch_core_media_bug_read()

环形缓冲区ringBufferAppendMultiple()

Speex 重采样器speex_resampler_init()

块组装ringBufferGetMultiple()

Base64 编码base64_encode()

传输层writeBinary()

管道阶段：

1. 1. 捕获：mod_audio_stream.c:26-52 - capture_callback 从 FreeSWITCH 媒体 bug 接收音频帧
2. 2. 帧读取：audio_streamer_glue.cpp:1088 - switch_core_media_bug_read 提取音频数据
3. 3. 重采样：audio_streamer_glue.cpp:705-718 - 如果需要，Speex 转换采样率
4. 4. 缓冲：audio_streamer_glue.cpp:1095-1111 - 环形缓冲区将音频累积到可配置的块大小
5. 5. 编码：base64.cpp - 用于传输的 Base64 编码
6. 6. 传输：audio_streamer_glue.cpp:287-292 (WebSocket) 或 audio_streamer_glue.cpp:555-584 (TCP)

传输策略模式

该模块使用策略模式来抽象传输协议，允许在运行时在 WebSocket 和 TCP 之间进行选择，而无需更改核心流式传输逻辑：

implements

implements

owns (via pAudioStreamer)

«interface»

BaseStreamer

+disconnect() : void

+isConnected() : bool

+writeBinary(buffer, len) : void

+writeText(text) : void

+eventCallback(event, message) : void

+processMessage(session, message) : bool

+deleteFiles() : void

AudioStreamer

-m_sessionId string

-webSocket ix::WebSocket

-m_notify responseHandler_t

-m_Files unordered_set

+AudioStreamer(uuid, wsUri, callback, ...)

+writeBinary(buffer, len) : void

+writeText(text) : void

+disconnect() : void

+isConnected() : bool

TcpStreamer

-m_sessionId string

-m_socket int

-m_address string

-m_port int

-m_notify responseHandler_t

+TcpStreamer(uuid, address, port, ...)

+writeBinary(buffer, len) : void

+disconnect() : void

+isConnected() : bool

private_t

+sessionId char[256]

+ws_uri char[512]

+pAudioStreamer void

+buffer RingBuffer

+resampler SpeexResamplerState

+mutex switch_mutex_t

+audio_paused int

编译时传输选择：

传输类型由 mod_audio_stream.h 中定义的 STREAM_TYPE 宏在编译时确定：

• • STREAM_TYPE = "WS"：使用带有 WebSocket 协议的 AudioStreamer
• • STREAM_TYPE = "TCP"：使用带有原始 TCP 套接字的 TcpStreamer

运行时多态：

private_t 结构将流式传输器实例存储为 void* pAudioStreameraudio_streamer_glue.cpp:646-681，代码根据 STREAM_TYPE 分支以转换和调用适当的实现 audio_streamer_glue.cpp:1076-1080。

会话生命周期

每个流式传输会话经历以下状态：

uuid_audio_stream start

stream_session_init()

CONNECT_SUCCESS 事件

uuid_audio_stream pause

uuid_audio_stream resume

uuid_audio_stream stop

连接失败

stream_session_cleanup()

清理完成

初始化中

已连接

流式传输中

已暂停

断开连接中

错误

- 验证参数 - 创建 AudioStreamer/TcpStreamer - 初始化环形缓冲区 - 如果需要，设置重采样器

- capture_callback 接收帧 - stream_frame 处理音频 - writeBinary 发送到端点 - 消息触发事件

- 发送最终文本（可选） - 关闭连接 - 删除临时文件 - 销毁资源

关键函数：

事件系统集成

该模块通过回调机制将外部服务响应桥接到 FreeSWITCH 的事件系统：

"FreeSWITCH 核心""responseHandler()""audio_streamer_glue""AudioStreamer /TcpStreamer""外部服务""FreeSWITCH 核心""responseHandler()""audio_streamer_glue""AudioStreamer /TcpStreamer""外部服务"alt[streamAudio 命令][JSON 响应]WebSocket 消息eventCallback(MESSAGE, json)processMessage()解码 base64 音频保存到临时文件responseHandler(EVENT_PLAY, data)responseHandler(EVENT_JSON, json)switch_event_create_subclass()switch_event_add_body()switch_event_fire()分发到监听器

事件类型：

事件注册：mod_audio_stream.c文件 事件处理程序：mod_audio_stream.c文件 事件回调：audio_streamer_glue.cpp文件， (AudioStreamer)，audio_streamer_glue.cpp:文件 (TcpStreamer)

参考资料

https://github.com/sptmru/freeswitch_mod_audio_stream https://xswitch.cn/ https://freeswitch.org.cn/

更多IPPBX接入，PBX/AI机器人接入，CRM对接，企业通信电话系统扩容升级，酒店场景，物联网、SIP对接，API接口开发，语音连接其他业务场景的解决方案信息，访问：https://xswitch.cn/