核心内容摘要
mysql报错1267 - Illegal mix of collations解决方法
本文系统性整理 FreeSWITCH Media Bug 的设计理念、核心数据结构、API 使用方式以及典型应用场景适合FreeSWITCH / VoIP / 媒体处理方向的开发者作为参考文档或源码导读。
目录
概述
核心数据结构
标志位说明
回调类型
核心 API
工作流程
使用示例
最佳实践附录
概述
什么是 Media BugMedia Bug是 FreeSWITCH 内部提供的一套媒体流拦截Hook与处理框架。
开发者可以在通话会话switch_core_session_t中动态挂载一个或多个 Media Bug用于捕获、分析、修改音频 / 视频 / 文本流。
它的核心思想是在编解码之后、媒体送达应用之前提供一个可插拔的处理点。
支持的能力包括 音频录制读 / 写流 实时音频替换与注入 语音分析VAD / DTMF / Tone / ASR 视频捕获、处理、监控 通话监听Spy / Whisper 文本流Text / RTCP / Data channel处理
典型应用场景通话录音单声道 / 立体声实时语音识别ASR语音信箱 / 应答机检测VMD / AVMD回声消除、降噪、语音增强视频录制、截图、水印、转码通话质量监控MOS / RTP通话注入提示音、混音
核心数据结构
switch_media_bug_tMedia Bug 的核心结构体定义于src/include/private/switch_core_pvt.hstruct switch_media_bug { /* 音频缓冲区 */ switch_buffer_t *raw_write_buffer; // 写入流缓冲 switch_buffer_t *raw_read_buffer; // 读取流缓冲 /* 帧替换REPLACE 模式 */ switch_frame_t *read_replace_frame_in; switch_frame_t *read_replace_frame_out; switch_frame_t *write_replace_frame_in; switch_frame_t *write_replace_frame_out; /* 原生帧 */ switch_frame_t *native_read_frame; switch_frame_t *native_write_frame; /* 回调与上下文 */ switch_media_bug_callback_t callback; void *user_data; /* 线程安全 */ switch_mutex_t *read_mutex; switch_mutex_t *write_mutex; /* 会话信息 */ switch_core_session_t *session; uint32_t flags; uint8_t ready; time_t stop_time; switch_thread_id_t thread_id; /* 标识 */ char *function; char *target; /* 编解码信息 */ switch_codec_implementation_t read_impl; switch_codec_implementation_t write_impl; /* 录制相关 */ uint32_t record_frame_size; uint32_t record_pre_buffer_count; uint32_t record_pre_buffer_max; /* 视频相关 */ switch_frame_t *video_ping_frame; switch_queue_t *read_video_queue; switch_queue_t *write_video_queue; switch_queue_t *spy_video_queue[2]; switch_image_t *spy_img[2]; switch_vid_spy_fmt_t spy_fmt; switch_thread_t *video_bug_thread; /* 文本流 */ switch_buffer_t *text_buffer; char *text_framedata; uint32_t text_framesize; /* 链表 */ switch_mm_t mm; struct switch_media_bug *next; /* 临时缓冲 */ uint8_t data[SWITCH_RECOMMENDED_BUFFER_SIZE]; int16_t tmp[SWITCH_RECOMMENDED_BUFFER_SIZE]; }; 一个会话可以同时挂载多个 Media Bug它们以链表形式存在。
回调函数类型typedef switch_bool_t (*switch_media_bug_callback_t)( switch_media_bug_t *bug, void *user_data, switch_abc_type_t type );bug当前 Media Bug 实例user_data创建时传入的用户上下文type当前触发的回调类型
标志位说明
switch_media_bug_flag_t标志位定义在src/include/switch_types.h标志位说明SMBF_READ_STREAM捕获 incoming audioSMBF_WRITE_STREAM捕获 outgoing audioSMBF_READ_REPLACE替换读取流SMBF_WRITE_REPLACE替换写入流SMBF_STEREO立体声录制SMBF_ANSWER_REQ应答后才开始SMBF_BRIDGE_REQ桥接后才开始SMBF_ONE_ONLY同 function 只允许一个SMBF_TAP_NATIVE_READ原生读取帧SMBF_TAP_NATIVE_WRITE原生写入帧SMBF_READ_VIDEO_STREAM读取视频流SMBF_VIDEO_PATCH视频补丁SMBF_READ_TEXT_STREAM文本流
标志位组合示例// 双向立体声录音 flags SMBF_READ_STREAM | SMBF_WRITE_STREAM | SMBF_STEREO; // 仅应答后录制 incoming audio flags SMBF_READ_STREAM | SMBF_ANSWER_REQ; // 替换 outgoing audio flags SMBF_WRITE_REPLACE;
回调类型switch_abc_type_t类型触发时机SWITCH_ABC_TYPE_INITBug 创建成功SWITCH_ABC_TYPE_CLOSEBug 移除SWITCH_ABC_TYPE_READ读取流数据SWITCH_ABC_TYPE_WRITE写入流数据SWITCH_ABC_TYPE_READ_REPLACE读取替换SWITCH_ABC_TYPE_WRITE_REPLACE写入替换SWITCH_ABC_TYPE_READ_VIDEO_PING视频心跳SWITCH_ABC_TYPE_READ_TEXT文本数据返回值说明SWITCH_TRUE继续执行SWITCH_FALSE停止并移除该 Media Bug
核心 API
添加 Media Bugswitch_core_media_bug_add( session, record, filename, callback, user_data, 0, flags, bug );
移除 Media Bugswitch_core_media_bug_remove(session, bug); switch_core_media_bug_remove_all_function(session, record);
读取混合音频switch_core_media_bug_read(bug, frame, SWITCH_TRUE);
工作流程
音频处理流程简化Codec Decode → Media Bug → 应用处理 → Codec Encode
生命周期switch_core_media_bug_addINIT 回调READ / WRITE 回调switch_core_media_bug_removeCLOSE 回调
使用示例示例双向立体声录音flags SMBF_READ_STREAM | SMBF_WRITE_STREAM | SMBF_STEREO;
最佳实践
线程安全回调运行在媒体线程共享资源务必加锁
内存管理使用switch_core_session_alloc不要使用malloc / free
性能建议回调中避免阻塞使用异步队列仅订阅必要的流附录A. 关键源码switch_core_media_bug.cswitch_core_pvt.hB. 常见模块mod_vmdmod_avmdmod_spymod_snapshot
总结Media Bug 是 FreeSWITCH 媒体处理的基石能力之一。
通过合理使用 Media Bug可以实现高性能录音实时音频 / 视频处理通话监控与分析ASR / TTS / AI 媒体接入如果你在做语音平台、呼叫中心、AI 语音、VoIP 内核开发Media Bug 是绕不开的一块核心能力。
FreeSWITCH
1.