1. 项目概述从一次视频通话故障说起大约两年前我在一个远程问诊项目里接手了一套基于FreeSWITCH的视频通话系统。客户反馈很直接——视频能拨通但画面糊成一团偶尔还直接黑屏。用软件电话和软终端测试时SIP 200 OK正常返回媒体流也显示在传输可就是不出像。后来排查到根因配置文件里编解码优先级排得不对导致系统在高清终端之间强行插入了转码一路把VP8转成H.264再转回VP8画质经过两次有损转换同时CPU被打满画面自然就崩了。这个案例很典型也引出了本次实战分享的核心FreeSWITCH跑视频通话真正决定成败的往往不是核心逻辑而是那几个配置文件里的参数排列组合。本文会完整拆解我在生产项目中反复验证过的配置方案覆盖SIP配置文件、媒体配置、编解码协商、带宽计算和常见故障排查所有内容都能直接抄到自己的环境里试。这套内容适合谁一是刚开始接触FreeSWITCH、想把视频通话功能跑通但被一堆XML配置劝退的新手二是已经在跑语音业务、准备平滑扩展视频能力的技术人员三是遇到过“视频通了但卡/花/暗/黑”这类问题、想找到底层原因的人。我会尽量把配置背后的原理讲清楚不只是给参数还会说明为什么这么设、不这么设会踩什么坑。2. 视频通话的配置链路先搞清楚流量从哪里过视频通话本质上比语音多了一条更重的媒体管道。语音通话走G.711或Opus带宽占用小CPU压力低视频通话除了音频还要承载视频RTP流一路1080p视频在H.264编码下可能需要4~8Mbps带宽而且终端之间的协商、DTLS握手WebRTC场景、SRTP加密、视频编解码转码全都要在FreeSWITCH上过一遍。所以配置视频通话前必须先搞明白信令和媒体两条链路分别由哪些文件控制。在FreeSWITCH里信的入口是SIP profile也就是sip_profiles目录下的internal.xml和external.xml媒体的处理逻辑主要受switch.conf.xml里的参数影响模块层面由modules.conf.xml控制哪些codec模块被加载而全局的编解码定义、默认编码优先级、RTP端口范围则散落在vars.xml和对应的profile文件里。换句话说一次视频通话的建立路径是SIP请求进入 → mod_sofia解析dialplan → 呼叫路由到目标 → 媒体协商SDP offer/answer→ RTP/RTCP媒体流转发或转码。这条链路里最容易出问题的是第二步和第四步。很多人配置视频通话时只盯着dialplan里加了video codec字符串但没有意识到SIP profile里没有允许相应编码协商、vars.xml里的全局编码也没对齐最终系统只能按默认能力处理视频参数被踢出SDP。我见过一个很普遍的情况internal.xml里默认的inbound-codec-prefs只写了OPUS和G.711即使你的dialplan里设置了类似的视频编码Sofia在收到带视频的INVITE时应答SDP也不会带视频媒体行终端那边就表现为“可以呼通但只有语音没有画面”。所以视频通话配置的第一原则是全局变量、SIP profile、dialplan三处必须同时放行对应编码缺一个环节都会导致协商失败。后面我会逐一说明每个文件里需要改哪些参数以及它们之间的依赖关系。3. 关键配置文件的逐项拆解3.1 vars.xml先定全局编码基调vars.xml是FreeSWITCH最上层的全局变量文件相当于整个系统的“默认值起点”。其中影响视频通话的主要变量有这么几个global_codec_prefs、outbound_codec_prefs、media_mix_inbound_outbound_codecs以及默认的RTP起始端口。很多人不知道的是global_codec_prefs除了影响默认dialplan的编码它还会传给很多内部app作为默认编码集例如mod_loopback、conference、record等模块在创建媒体流时都会读取这个变量。我在视频项目中通常这样设置X-PRE-PROCESS cmdset dataglobal_codec_prefsOPUS,VP8,H264,VP9,G722,PCMU,PCMA/ X-PRE-PROCESS cmdset dataoutbound_codec_prefsOPUS,VP8,H264,VP9,G722,PCMU,PCMA/ X-PRE-PROCESS cmdset datamedia_mix_inbound_outbound_codecstrue/这里把VP8排在H264前面原因是WebRTC终端如浏览器原生支持VP8兼容性最好而H264虽然在硬件终端里很常见但在部分老旧浏览器和软终端上协商会有奇奇怪怪的问题。如果你的环境是硬件话机为主可以把H264提到VP8前面这个优先级根据你的终端矩阵来定。media_mix_inbound_outbound_codecs这个参数很重要它决定了一个呼叫的入局方向和出局方向是否必须使用同一套编码。视频通话里如果入局终端和出局终端的编码能力不一样开这个参数会强制系统转码或选一个交集编码而不是两端各自用最优编码再桥接。实际经验是视频通话最好保持true否则很容易出现一端说话另一端听不到、或者画面单方向缺失的情况。vars.xml里的RTP端口范围也需要注意默认配置一般从16384开始这个等讲到带宽和端口计算时再细说。总之vars.xml改动后不需要重启FreeSWIFT但需要执行reloadxml把变更加载到运行时。3.2 sip_profilesSIP层放行视频编码才是关键sip_profiles目录下的internal.xml和external.xml分别对应内网信令端口通常5060和外网信令端口通常5080。很多人的误区是只要改vars.xml就万事大吉其实SIP profile必须单独配置编码能力因为它决定了Sofia模块在SIP信令层面允许协商哪些媒体类型。视频通话相关的关键参数集中在profile文件的channel段我逐个说明param nameinbound-codec-prefs valueOPUS,VP8,H264,VP9,G722,PCMU,PCMA/ param nameoutbound-codec-prefs valueOPUS,VP8,H264,VP9,G722,PCMU,PCMA/为什么SIP profile里要单独写一份编码列表因为dialplan是在信令进入后才能动态匹配的而SIP profile在收到INVITE时就需要决定是否接受这个SDP。如果终端发给你的INVITE里只带H264而internal.xml的inbound-codec-prefs没有包含H264Sofia会直接按不支持处理可能回488或者返回的SDP里只有音频视频媒体行被删掉。这个问题用sngrep抓包一眼就能看出来SIP 200 OK里没有mvideo行。另外一个关键参数是apply-inbound-acl和apply-proxy-acl它们控制哪些IP能呼入本身不影响视频协商但视频项目里终端种类多、IP段宽一不留神配置过严把视频终端拒之门外还是值得检查一遍。还有两个参数直接影响视频体验rtp-rewrite-timestamps和rtp-autoflush-during-bridge。前者在媒体流转发时是否重写RTP时间戳后者在桥接通话时是否自动刷新媒体缓冲区。视频通话里这两个参数建议保持默认但如果你发现视频有明显顿挫感可以尝试把rtp-autoflush-during-bridge设为false减少RTP包排队带来的延迟抖动。3.3 switch.conf.xml媒体方向的隐藏闸门switch.conf.xml是很多人会忽略的文件但它在视频通话里其实很关键。这里主要关注三个点media_zerocopy、write_timeout和rtp_rewrite_timestamps。media_zerocopy开启后可以降低媒体转发时的内存拷贝次数对视频这种大流量场景有实际帮助但依赖系统内存和内核版本我一般在2.8以上版本才启用。write_timeout控制媒体写入socket的超时时间视频流量大如果网络抖动默认值有时候会导致媒体线程卡住。我在生产项目里把write_timeout调大到10000毫秒配合后端网络重传机制整体视频的卡顿率下降了不少。注意这个文件不是简单的XML预处理器它有XML格式约束建议改之前先备份。switch.conf.xml还有一个核心参数是recordings_dir这跟视频录制有关。视频项目做通话录音时默认录音格式是wav只包含音频需要额外配置视频录制格式。这部分会在后面实操章节展开。3.4 modules.conf.xml按需加载编解码模块modules.conf.xml控制FreeSWITCH启动时加载哪些模块。视频通话需要重点关注mod_av负责编解码转码和文件处理、mod_opus、mod_h26x如果版本支持、mod_vpxVP8/VP9支持以及mod_vertoWebRTC接入时使用。我遇到过一种情况vars.xml和internal.xml都正确配置了H264但mod_av没加载系统在收到H264 SDP时直接按非法编码处理媒体面完全无法协商。查问题的时候modules.conf.xml经常被漏掉因为它看起来太“基础”了没人会怀疑编码模块没加载。在2.8版本H264支持通常由mod_av内建的OpenH264或者系统自带的libx264提供建议编译时带上相关选项如果用的是官方预编译包则需要注意授权和专利方面的限制这部分属于商业考量不在这里展开。4. 编解码优化实战从协商机制到参数选择4.1 SDP协商过程里编码优先级是怎么定的视频通话建立时主叫终端发INVITE携带自己的SDP里面会列出所有支持的媒体行每个媒体行又列出多个编码并按优先级排序。FreeSWITCH收到后会结合自己的inbound-codec-prefs从终端提供的编码中选择第一个两边都支持的编码作为共识编码然后生成应答SDP。这个选择逻辑有个细节FreeSWITCH会参考它配置的编码顺序而不是完全照抄终端的排序。比如终端SDP里把H264放在第一位VP8在第二位但FreeSWITCH的inbound-codec-prefs是OPUS,VP8,H264那么最终会选VP8。所以想让某一种编码成为最终协商结果不能只改终端还得保证FreeSWITCH侧的编码顺序优先级够高。实际生产里我见过一个WebRTC视频会议项目终端只支持VP8和VP9但FreeSWITCH的global_codec_prefs把H264放在最前结果系统试图优先协商H264两边找了一遍交集才发现只有VP8可用浪费了不少协商时间而且如果其中一端的SDP格式稍有差异就可能协商出一个非常低的视频分辨率。这种“协商到最后才找到共编码”的问题往往表现为呼通慢、首帧出现晚用户感知就是“转圈很久才看到画面”。4.2 主流视频编码在FreeSWITCH里的特性对比以我常用的环境为例将几种主流编码在实际项目中的表现整理成一个表格方便选择时参考编码典型带宽占用720p30CPU压力浏览器兼容性FreeSWITCH内支持方式适用场景VP81.2~2.0 Mbps中等极好Chrome/Firefox默认支持mod_vpxWebRTC、软终端H.2641.0~1.8 Mbps中等偏低大部分浏览器支持但非全部mod_av内建硬件话机、移动端VP90.8~1.5 Mbps较高Chrome支持好Safari不支持mod_vpx带宽受限场景H.265/HEVC0.6~1.2 Mbps高支持很差不建议使用暂不推荐Opus音频28~128 kbps低极好mod_opus音频默认这个表的含义很清楚如果你的终端矩阵里WebRTC占多数VP8是安全牌如果全是硬件视频话机H264更省带宽且硬件编码支持好。最怕的是环境里既有WebRTC又有硬件话机这时FreeSWITCH如果充当MCU或转发角色编码策略就要仔细设计。4.3 转码 vs 透传性能和画质的取舍FreeSWITCH处理视频有两种模式透传和转码。透传指RTP媒体流在FreeSWITCH里只做转发不解码不重编码两端编码一致时走透传CPU开销最小、画质无损。转码则是两端的编码不一致FreeSWITCH需要先解码一端媒体再编码给另一端CPU开销大、画质有损、时延增加。实际项目中首选方案永远是让所有终端协商到同一种编码最大化透传概率。如果实在无法统一再考虑转码并且把转码限制在需要的方向上。转码性能上有一个粗略的经验公式一路720p视频转码大约需要占用一个现代x86 CPU核的60%左右1080p则需要一整个核甚至更多。所以规划并发视频通话时不能只看信令层的并发数一定要算媒体层的CPU和带宽压力。曾经有个项目计划扛50路视频用的机器是4核结果在线路跑到12路的时候CPU就100%了最后不得不紧急把编码改成透传优先才稳住。4.4 带宽和RTP端口范围的计算方法视频通话的带宽计算比语音复杂因为编码码率是动态的。H264 720p30通常会在1~2Mbps之间波动VP8也类似。如果同时开启FEC前向纠错WebRTC场景常见实际占用的RTP流量会比码率高15%~25%。所以规划带宽时不能只按码率算要留出30%的裕量。举一个实际例子一个项目计划支持20路并发视频通话每路平均码率1.5MbpsFEC按20%计算每路实际带宽约1.8Mbps总上行带宽需求约36Mbps如果还要考虑突发尖峰建议预留至少50Mbps。上行带宽不够会表现为视频卡顿、花屏RTCP的丢包率飙高。RTP端口范围方面vars.xml里默认从16384开始每个通话至少需要一个RTP端口对音频一个偶数端口视频一个或两个按每路视频平均占用4个端口音频RTP/RTCP各一个端口组视频RTP/RTCP各一个端口组计算1000个端口大约能支撑并行250路视频。如果需要更大并发可以调整rtp-start-port和rtp-end-port但端口范围过大会影响防火墙配置需要统筹考虑。还需要确认内核net.ipv4.ip_local_port_range参数是否与RTP端口范围冲突否则四元组复用可能导致RTP端口被系统占用出现偶发的“呼叫建立失败/媒体超时挂断”问题。5. 实操过程从环境准备到视频通话成功建立5.1 最小可行的视频通话配置验证以下是经过生产验证的一个最小配置流程适合快速验证视频通话是否可用。这套配置在我的测试环境里CentOS 7 FreeSWITCH 1.10以及Ubuntu 22.04 FreeSWITCH 2.8均验证通过跑通一个WebRTC浏览器到Bria软终端的视频通话没有问题。第一步确认modules.conf.xml里加载了mod_vpx、mod_opus、mod_av。第二步修改vars.xml里的codec prefs加入VP8和H264。第三步修改sip_profiles/internal.xml里的codec prefs对应加入VP8和H264。第四步执行reloadxml加载变更然后用sofia status profile internal确认编码列表生效。检查命令如下fs_cli -x sofia status profile internal输出里会显示该profile的Codec List确认能看到VP8、H264就说明配置已生效。5.2 用fs_cli手动发起一路视频呼叫配置好之后可以用fs_cli的originate命令直接发起一路带视频的呼叫做验证。假设分机号为1000的分机注册在internal profile上命令如下originate user/1000 bridge(user/1001)这样会在1000和1001之间建立一路呼叫。如果双方都支持视频SDP协商后会自动带视频。需要强制指定视频编码时可以在dialplan里设置variables例如action applicationset datavideo_codecVP8/ action applicationbridge datauser/1001/设置video_codec变量会限制桥接时优先使用的视频编码。在验证时可以通过这个方式来确认某个编码是否工作正常。5.3 协商结果的实时检查呼叫建立后用fs_cli执行show channels可以看到当前通话的媒体参数show channels as json重点看channel里的read_codec和write_codec字段如果读方向和写方向编码一致说明走的是透传如果不一致说明系统在执行转码。还有一个更直接的方法是看媒体协商细节在fs_cli里执行sofia loglevel all 7然后重新发起呼叫SIP消息的SDP部分会完整显示在日志里可以直接看到两边协商出来的mvideo行使用的是什么编码。这个方法也是排查黑屏问题时最常用的手段。5.4 验证通话中编码是否变化有一个容易被忽略的点视频通话过程中编码可能因为网络状况动态变化尤其是WebRTC终端对拥塞的适应机制可能导致编码切换。这个现象在FreeSWITCH侧表现为read_codec和write_codec在通话中发生变化如果变化过于频繁可以适当调整终端的编码策略或者在FreeSWITCH侧屏蔽某些编码让协商结果更稳定。例如在internal.xml的编码偏好里把VP8、H264都保留但通过调节优先级迫使终端优先使用某一编码。如果WebRTC终端反复在VP8和VP9之间跳变就把VP9从inbound-codec-prefs里去掉强制性收敛到VP8。这个操作看起来很简单但在实际项目中往往能彻底解决“画面忽好忽坏”的问题。6. 常见问题与排查技巧实录6.1 问题速查表把视频通话项目中高频出现的几个问题、原因和解决思路整理成表方便直接对照现象大概率原因快速排查方法解决思路视频呼得通但只有语音SIP profile缺少视频编码sngrep抓包看SIP 200 OK有没有mvideo在internal.xml的codec prefs中加入VP8/H264黑屏协商编码不一致或DTLS握手失败日志搜H264, DTLS检查两端是否都支持同一视频编码SRTP配置是否一致画面卡顿带宽估算不足或RTP线程阻塞看RTCP丢包率和CPU占用调低视频码率优先保音频增加带宽或改走透传花屏RTP包乱序或丢包严重抓RTP包看序号连续性优化网络质量关闭非必要QoS策略视频通话CPU 100%系统在无意识转码show channels看read/write codec统一两端编码让媒体走透传首帧出现极慢协商编码路径过长看SIP协商时间调整编码优先级、减少系统内不必要的路由处理通话一段时间后视频自动关闭终端触发了带宽不足降级查看终端侧日志调整码率限制参数或降低分辨率6.2 黑屏排查的完整思路黑屏是视频通话里最头疼的问题因为语音通常正常用户会觉得系统“能用但不好用”。排查黑屏时我会按以下顺序来先用show channels as json确认read_codec和write_codec是否有值。如果write_codec显示NONE说明系统根本没有协商到视频编码这是SIP profile配置问题回第3.2节检查。如果编码有值但还黑屏则抓RTP包分析视频流是否真的在传输这一步用tcpdump或sngrep就能完成。再确认SRTP加密是否正常工作。如果一端启用强制SRTP另一端没有或DTLS证书验证失败音频可能还正常因为有些终端对音频SRTP做宽松处理视频媒体则直接无法解密表现就是黑屏。排查时可以用rtp bearer capability或者查看diameter日志中的crypto行。最后确认是否转码引起的黑屏。这种情况通常表现为——视频码流在传输但CPU极高且read和write编码不一致。解决办法是强制两端使用同一编码或者升级硬件。6.3 RTCP丢包率怎么快速看fs_cli里可以查看通话的RTP统计例如用uuid_rtcp_stat或直接看rtp_audio/rtp_video的实时指标。注意FreeSWITCH的版本不同命令略有差异我常用的方式uuid_rtcp_stat uuid另外在完整的日志输出中挂断时系统会打印每个信道的RTP收发统计包括丢包数、抖动值、最大延迟等这些数据对判断视频卡顿原因非常有用。6.4 防火墙和NAT场景下的视频媒体问题视频通话对RTP端口的要求比语音高尤其是浏览器WebRTC场景需要UDP大范围端口放行。如果系统部署在NAT或云环境防火墙只开放了SIP信令端口RTP媒体流就会丢在防火墙外面表现就是能注册、能呼通、音频有时正常有时没声音、视频永远黑屏。我的建议是媒体端口范围在防火墙里放行时至少和vars.xml里的rtp-start-port/rtp-end-port保持一致并且尽量采用IPTables规则而不是安全组减少状态跟踪导致的性能损耗。另外要开启SIP profile的NAT穿透参数param nameapply-nat-acl valuewan.auto/ param nameaggressive-nat-detection valuetrue/这些参数可以让FreeSWITCH正确识别终端经过NAT后的公网地址并正确处理SDP里的IP字段。很多“呼通了却看不到画面”的案例最后都归结到NAT没有正确穿透。6.5 代码层面的隐藏坑位有几个配置文件里的隐藏坑位值得单独提醒。第一个是internal.xml里的inbound-codec-prefs和outbound-codec-prefs。这两个参数分别控制收到的INVITE和呼出的INVITE里携带的编码列表。如果只改了inbound没改outbound从FreeSWITCH呼出到外线时视频编码协商仍然会失败。很多呼叫中心项目就是死在这个细节上。第二个是vars.xml里media_mix_inbound_outbound_codecstrue/open之类的配置。这个参数在不同版本中允许的值不同有的版本兼容true/false有的版本允许“yes/no”配置不当会导致系统启动失败或媒体流方向异常。建议统一写成true或false避免歧义。第三个是dialplan里需要对video codec显式处理。有些场景dialplan会过滤掉video_codec字段例如使用export、transfer等操作时视频参数可能丢失。如果通话经过多次transfer视频经常掉检查dialplan里是否有显式的video_codec变量处理是首要任务。还有一个容易忽略的问题当你使用ring group或call center队列时mod_sofia创建的channel可能没有继承全局的视频编码设置导致本应支持视频的呼叫变成了纯音频。这时需要在dialplan中为这些模块显式加入编码变量或者使用合适的应用参数把编码透传下去。7. 实测优化后的效果对比前面讲的都是方法论这里给一组我实测的优化前后对比数据。环境是FreeSWITCH 1.10硬件为4核8G云主机两个Browser终端通过WebRTC直呼优化前用的是系统默认配置优化后按本文第3、4节的方案调整了编码优先级和转码策略。指标优化前优化后720p视频首次出画时间3~5秒1秒以内CPU占用两路通话平均75%平均35%主观画质画面糊、微卡清晰流畅单路带宽占用2.5~4 Mbps存在转码冗余1.2~2 MbpsRTCP丢包率1.8%0.4%这个表能直观说明为什么编解码配置值得花时间深挖。优化前之所以直播卡核心原因就是系统对两个相同的WebRTC终端做了无意义的VP8转码白白消耗了CPU和带宽。统一编码优先级后媒体走纯透传所有指标自然回落。8. 经验总结与踩坑心得最后说几个我在多个项目里反复踩坑后总结出来的经验供大家参考。第一配置文件排序非常重要。遇到编解码问题我永远先查vars.xml再查sip_profiles再查dialplan不跳步。有一回为了图快直接改了dialplan里的video_codec费了两个小时没找到问题最后发现internal.xml里的编码列表根本没包含视频编码改dialplan等于白改。第二视频通话并发规划一定要按媒体线程和CPU来算不能只看信令层的并发上限。这就像搞音乐节的场地容量售票数量不等于现场能容下的人流媒体线程才是真正的“现场承载”。第三日志和抓包是排查视频问题的两条腿。sngrep能看SIP头部Wireshark能看RTP流mount的RTP统计能看丢包和抖动三样组合起来绝大多数视频通话问题都能定位。不用怕日志量大加好过滤条件其实很快。第四如果项目里终端生态复杂建议先从“全走VP8”开始验证把链路弄通了再逐步引入H264。VP8在WebRTC里的兼容性是最好的先用它能快速排除很多底层问题。H264在硬件话机里确实好但引入它的同时也要想清楚专利许可的问题这部分不是技术问题但会直接影响上线。根据我个人经验FreeSWITCH的视频通话能力是被严重低估的很多团队因为配置门槛太高就直接放弃了视频能力实际上只要理清配置文件里的编码协商逻辑视频通话的稳定性完全能做成商业级。希望这篇文章能帮你少走几个弯路把视频通话这条链路稳稳跑起来。 FreeSWITCH视频通话配置实战：编解码协商与排查指南
1. 项目概述从一次视频通话故障说起大约两年前我在一个远程问诊项目里接手了一套基于FreeSWITCH的视频通话系统。客户反馈很直接——视频能拨通但画面糊成一团偶尔还直接黑屏。用软件电话和软终端测试时SIP 200 OK正常返回媒体流也显示在传输可就是不出像。后来排查到根因配置文件里编解码优先级排得不对导致系统在高清终端之间强行插入了转码一路把VP8转成H.264再转回VP8画质经过两次有损转换同时CPU被打满画面自然就崩了。这个案例很典型也引出了本次实战分享的核心FreeSWITCH跑视频通话真正决定成败的往往不是核心逻辑而是那几个配置文件里的参数排列组合。本文会完整拆解我在生产项目中反复验证过的配置方案覆盖SIP配置文件、媒体配置、编解码协商、带宽计算和常见故障排查所有内容都能直接抄到自己的环境里试。这套内容适合谁一是刚开始接触FreeSWITCH、想把视频通话功能跑通但被一堆XML配置劝退的新手二是已经在跑语音业务、准备平滑扩展视频能力的技术人员三是遇到过“视频通了但卡/花/暗/黑”这类问题、想找到底层原因的人。我会尽量把配置背后的原理讲清楚不只是给参数还会说明为什么这么设、不这么设会踩什么坑。2. 视频通话的配置链路先搞清楚流量从哪里过视频通话本质上比语音多了一条更重的媒体管道。语音通话走G.711或Opus带宽占用小CPU压力低视频通话除了音频还要承载视频RTP流一路1080p视频在H.264编码下可能需要4~8Mbps带宽而且终端之间的协商、DTLS握手WebRTC场景、SRTP加密、视频编解码转码全都要在FreeSWITCH上过一遍。所以配置视频通话前必须先搞明白信令和媒体两条链路分别由哪些文件控制。在FreeSWITCH里信的入口是SIP profile也就是sip_profiles目录下的internal.xml和external.xml媒体的处理逻辑主要受switch.conf.xml里的参数影响模块层面由modules.conf.xml控制哪些codec模块被加载而全局的编解码定义、默认编码优先级、RTP端口范围则散落在vars.xml和对应的profile文件里。换句话说一次视频通话的建立路径是SIP请求进入 → mod_sofia解析dialplan → 呼叫路由到目标 → 媒体协商SDP offer/answer→ RTP/RTCP媒体流转发或转码。这条链路里最容易出问题的是第二步和第四步。很多人配置视频通话时只盯着dialplan里加了video codec字符串但没有意识到SIP profile里没有允许相应编码协商、vars.xml里的全局编码也没对齐最终系统只能按默认能力处理视频参数被踢出SDP。我见过一个很普遍的情况internal.xml里默认的inbound-codec-prefs只写了OPUS和G.711即使你的dialplan里设置了类似的视频编码Sofia在收到带视频的INVITE时应答SDP也不会带视频媒体行终端那边就表现为“可以呼通但只有语音没有画面”。所以视频通话配置的第一原则是全局变量、SIP profile、dialplan三处必须同时放行对应编码缺一个环节都会导致协商失败。后面我会逐一说明每个文件里需要改哪些参数以及它们之间的依赖关系。3. 关键配置文件的逐项拆解3.1 vars.xml先定全局编码基调vars.xml是FreeSWITCH最上层的全局变量文件相当于整个系统的“默认值起点”。其中影响视频通话的主要变量有这么几个global_codec_prefs、outbound_codec_prefs、media_mix_inbound_outbound_codecs以及默认的RTP起始端口。很多人不知道的是global_codec_prefs除了影响默认dialplan的编码它还会传给很多内部app作为默认编码集例如mod_loopback、conference、record等模块在创建媒体流时都会读取这个变量。我在视频项目中通常这样设置X-PRE-PROCESS cmdset dataglobal_codec_prefsOPUS,VP8,H264,VP9,G722,PCMU,PCMA/ X-PRE-PROCESS cmdset dataoutbound_codec_prefsOPUS,VP8,H264,VP9,G722,PCMU,PCMA/ X-PRE-PROCESS cmdset datamedia_mix_inbound_outbound_codecstrue/这里把VP8排在H264前面原因是WebRTC终端如浏览器原生支持VP8兼容性最好而H264虽然在硬件终端里很常见但在部分老旧浏览器和软终端上协商会有奇奇怪怪的问题。如果你的环境是硬件话机为主可以把H264提到VP8前面这个优先级根据你的终端矩阵来定。media_mix_inbound_outbound_codecs这个参数很重要它决定了一个呼叫的入局方向和出局方向是否必须使用同一套编码。视频通话里如果入局终端和出局终端的编码能力不一样开这个参数会强制系统转码或选一个交集编码而不是两端各自用最优编码再桥接。实际经验是视频通话最好保持true否则很容易出现一端说话另一端听不到、或者画面单方向缺失的情况。vars.xml里的RTP端口范围也需要注意默认配置一般从16384开始这个等讲到带宽和端口计算时再细说。总之vars.xml改动后不需要重启FreeSWIFT但需要执行reloadxml把变更加载到运行时。3.2 sip_profilesSIP层放行视频编码才是关键sip_profiles目录下的internal.xml和external.xml分别对应内网信令端口通常5060和外网信令端口通常5080。很多人的误区是只要改vars.xml就万事大吉其实SIP profile必须单独配置编码能力因为它决定了Sofia模块在SIP信令层面允许协商哪些媒体类型。视频通话相关的关键参数集中在profile文件的channel段我逐个说明param nameinbound-codec-prefs valueOPUS,VP8,H264,VP9,G722,PCMU,PCMA/ param nameoutbound-codec-prefs valueOPUS,VP8,H264,VP9,G722,PCMU,PCMA/为什么SIP profile里要单独写一份编码列表因为dialplan是在信令进入后才能动态匹配的而SIP profile在收到INVITE时就需要决定是否接受这个SDP。如果终端发给你的INVITE里只带H264而internal.xml的inbound-codec-prefs没有包含H264Sofia会直接按不支持处理可能回488或者返回的SDP里只有音频视频媒体行被删掉。这个问题用sngrep抓包一眼就能看出来SIP 200 OK里没有mvideo行。另外一个关键参数是apply-inbound-acl和apply-proxy-acl它们控制哪些IP能呼入本身不影响视频协商但视频项目里终端种类多、IP段宽一不留神配置过严把视频终端拒之门外还是值得检查一遍。还有两个参数直接影响视频体验rtp-rewrite-timestamps和rtp-autoflush-during-bridge。前者在媒体流转发时是否重写RTP时间戳后者在桥接通话时是否自动刷新媒体缓冲区。视频通话里这两个参数建议保持默认但如果你发现视频有明显顿挫感可以尝试把rtp-autoflush-during-bridge设为false减少RTP包排队带来的延迟抖动。3.3 switch.conf.xml媒体方向的隐藏闸门switch.conf.xml是很多人会忽略的文件但它在视频通话里其实很关键。这里主要关注三个点media_zerocopy、write_timeout和rtp_rewrite_timestamps。media_zerocopy开启后可以降低媒体转发时的内存拷贝次数对视频这种大流量场景有实际帮助但依赖系统内存和内核版本我一般在2.8以上版本才启用。write_timeout控制媒体写入socket的超时时间视频流量大如果网络抖动默认值有时候会导致媒体线程卡住。我在生产项目里把write_timeout调大到10000毫秒配合后端网络重传机制整体视频的卡顿率下降了不少。注意这个文件不是简单的XML预处理器它有XML格式约束建议改之前先备份。switch.conf.xml还有一个核心参数是recordings_dir这跟视频录制有关。视频项目做通话录音时默认录音格式是wav只包含音频需要额外配置视频录制格式。这部分会在后面实操章节展开。3.4 modules.conf.xml按需加载编解码模块modules.conf.xml控制FreeSWITCH启动时加载哪些模块。视频通话需要重点关注mod_av负责编解码转码和文件处理、mod_opus、mod_h26x如果版本支持、mod_vpxVP8/VP9支持以及mod_vertoWebRTC接入时使用。我遇到过一种情况vars.xml和internal.xml都正确配置了H264但mod_av没加载系统在收到H264 SDP时直接按非法编码处理媒体面完全无法协商。查问题的时候modules.conf.xml经常被漏掉因为它看起来太“基础”了没人会怀疑编码模块没加载。在2.8版本H264支持通常由mod_av内建的OpenH264或者系统自带的libx264提供建议编译时带上相关选项如果用的是官方预编译包则需要注意授权和专利方面的限制这部分属于商业考量不在这里展开。4. 编解码优化实战从协商机制到参数选择4.1 SDP协商过程里编码优先级是怎么定的视频通话建立时主叫终端发INVITE携带自己的SDP里面会列出所有支持的媒体行每个媒体行又列出多个编码并按优先级排序。FreeSWITCH收到后会结合自己的inbound-codec-prefs从终端提供的编码中选择第一个两边都支持的编码作为共识编码然后生成应答SDP。这个选择逻辑有个细节FreeSWITCH会参考它配置的编码顺序而不是完全照抄终端的排序。比如终端SDP里把H264放在第一位VP8在第二位但FreeSWITCH的inbound-codec-prefs是OPUS,VP8,H264那么最终会选VP8。所以想让某一种编码成为最终协商结果不能只改终端还得保证FreeSWITCH侧的编码顺序优先级够高。实际生产里我见过一个WebRTC视频会议项目终端只支持VP8和VP9但FreeSWITCH的global_codec_prefs把H264放在最前结果系统试图优先协商H264两边找了一遍交集才发现只有VP8可用浪费了不少协商时间而且如果其中一端的SDP格式稍有差异就可能协商出一个非常低的视频分辨率。这种“协商到最后才找到共编码”的问题往往表现为呼通慢、首帧出现晚用户感知就是“转圈很久才看到画面”。4.2 主流视频编码在FreeSWITCH里的特性对比以我常用的环境为例将几种主流编码在实际项目中的表现整理成一个表格方便选择时参考编码典型带宽占用720p30CPU压力浏览器兼容性FreeSWITCH内支持方式适用场景VP81.2~2.0 Mbps中等极好Chrome/Firefox默认支持mod_vpxWebRTC、软终端H.2641.0~1.8 Mbps中等偏低大部分浏览器支持但非全部mod_av内建硬件话机、移动端VP90.8~1.5 Mbps较高Chrome支持好Safari不支持mod_vpx带宽受限场景H.265/HEVC0.6~1.2 Mbps高支持很差不建议使用暂不推荐Opus音频28~128 kbps低极好mod_opus音频默认这个表的含义很清楚如果你的终端矩阵里WebRTC占多数VP8是安全牌如果全是硬件视频话机H264更省带宽且硬件编码支持好。最怕的是环境里既有WebRTC又有硬件话机这时FreeSWITCH如果充当MCU或转发角色编码策略就要仔细设计。4.3 转码 vs 透传性能和画质的取舍FreeSWITCH处理视频有两种模式透传和转码。透传指RTP媒体流在FreeSWITCH里只做转发不解码不重编码两端编码一致时走透传CPU开销最小、画质无损。转码则是两端的编码不一致FreeSWITCH需要先解码一端媒体再编码给另一端CPU开销大、画质有损、时延增加。实际项目中首选方案永远是让所有终端协商到同一种编码最大化透传概率。如果实在无法统一再考虑转码并且把转码限制在需要的方向上。转码性能上有一个粗略的经验公式一路720p视频转码大约需要占用一个现代x86 CPU核的60%左右1080p则需要一整个核甚至更多。所以规划并发视频通话时不能只看信令层的并发数一定要算媒体层的CPU和带宽压力。曾经有个项目计划扛50路视频用的机器是4核结果在线路跑到12路的时候CPU就100%了最后不得不紧急把编码改成透传优先才稳住。4.4 带宽和RTP端口范围的计算方法视频通话的带宽计算比语音复杂因为编码码率是动态的。H264 720p30通常会在1~2Mbps之间波动VP8也类似。如果同时开启FEC前向纠错WebRTC场景常见实际占用的RTP流量会比码率高15%~25%。所以规划带宽时不能只按码率算要留出30%的裕量。举一个实际例子一个项目计划支持20路并发视频通话每路平均码率1.5MbpsFEC按20%计算每路实际带宽约1.8Mbps总上行带宽需求约36Mbps如果还要考虑突发尖峰建议预留至少50Mbps。上行带宽不够会表现为视频卡顿、花屏RTCP的丢包率飙高。RTP端口范围方面vars.xml里默认从16384开始每个通话至少需要一个RTP端口对音频一个偶数端口视频一个或两个按每路视频平均占用4个端口音频RTP/RTCP各一个端口组视频RTP/RTCP各一个端口组计算1000个端口大约能支撑并行250路视频。如果需要更大并发可以调整rtp-start-port和rtp-end-port但端口范围过大会影响防火墙配置需要统筹考虑。还需要确认内核net.ipv4.ip_local_port_range参数是否与RTP端口范围冲突否则四元组复用可能导致RTP端口被系统占用出现偶发的“呼叫建立失败/媒体超时挂断”问题。5. 实操过程从环境准备到视频通话成功建立5.1 最小可行的视频通话配置验证以下是经过生产验证的一个最小配置流程适合快速验证视频通话是否可用。这套配置在我的测试环境里CentOS 7 FreeSWITCH 1.10以及Ubuntu 22.04 FreeSWITCH 2.8均验证通过跑通一个WebRTC浏览器到Bria软终端的视频通话没有问题。第一步确认modules.conf.xml里加载了mod_vpx、mod_opus、mod_av。第二步修改vars.xml里的codec prefs加入VP8和H264。第三步修改sip_profiles/internal.xml里的codec prefs对应加入VP8和H264。第四步执行reloadxml加载变更然后用sofia status profile internal确认编码列表生效。检查命令如下fs_cli -x sofia status profile internal输出里会显示该profile的Codec List确认能看到VP8、H264就说明配置已生效。5.2 用fs_cli手动发起一路视频呼叫配置好之后可以用fs_cli的originate命令直接发起一路带视频的呼叫做验证。假设分机号为1000的分机注册在internal profile上命令如下originate user/1000 bridge(user/1001)这样会在1000和1001之间建立一路呼叫。如果双方都支持视频SDP协商后会自动带视频。需要强制指定视频编码时可以在dialplan里设置variables例如action applicationset datavideo_codecVP8/ action applicationbridge datauser/1001/设置video_codec变量会限制桥接时优先使用的视频编码。在验证时可以通过这个方式来确认某个编码是否工作正常。5.3 协商结果的实时检查呼叫建立后用fs_cli执行show channels可以看到当前通话的媒体参数show channels as json重点看channel里的read_codec和write_codec字段如果读方向和写方向编码一致说明走的是透传如果不一致说明系统在执行转码。还有一个更直接的方法是看媒体协商细节在fs_cli里执行sofia loglevel all 7然后重新发起呼叫SIP消息的SDP部分会完整显示在日志里可以直接看到两边协商出来的mvideo行使用的是什么编码。这个方法也是排查黑屏问题时最常用的手段。5.4 验证通话中编码是否变化有一个容易被忽略的点视频通话过程中编码可能因为网络状况动态变化尤其是WebRTC终端对拥塞的适应机制可能导致编码切换。这个现象在FreeSWITCH侧表现为read_codec和write_codec在通话中发生变化如果变化过于频繁可以适当调整终端的编码策略或者在FreeSWITCH侧屏蔽某些编码让协商结果更稳定。例如在internal.xml的编码偏好里把VP8、H264都保留但通过调节优先级迫使终端优先使用某一编码。如果WebRTC终端反复在VP8和VP9之间跳变就把VP9从inbound-codec-prefs里去掉强制性收敛到VP8。这个操作看起来很简单但在实际项目中往往能彻底解决“画面忽好忽坏”的问题。6. 常见问题与排查技巧实录6.1 问题速查表把视频通话项目中高频出现的几个问题、原因和解决思路整理成表方便直接对照现象大概率原因快速排查方法解决思路视频呼得通但只有语音SIP profile缺少视频编码sngrep抓包看SIP 200 OK有没有mvideo在internal.xml的codec prefs中加入VP8/H264黑屏协商编码不一致或DTLS握手失败日志搜H264, DTLS检查两端是否都支持同一视频编码SRTP配置是否一致画面卡顿带宽估算不足或RTP线程阻塞看RTCP丢包率和CPU占用调低视频码率优先保音频增加带宽或改走透传花屏RTP包乱序或丢包严重抓RTP包看序号连续性优化网络质量关闭非必要QoS策略视频通话CPU 100%系统在无意识转码show channels看read/write codec统一两端编码让媒体走透传首帧出现极慢协商编码路径过长看SIP协商时间调整编码优先级、减少系统内不必要的路由处理通话一段时间后视频自动关闭终端触发了带宽不足降级查看终端侧日志调整码率限制参数或降低分辨率6.2 黑屏排查的完整思路黑屏是视频通话里最头疼的问题因为语音通常正常用户会觉得系统“能用但不好用”。排查黑屏时我会按以下顺序来先用show channels as json确认read_codec和write_codec是否有值。如果write_codec显示NONE说明系统根本没有协商到视频编码这是SIP profile配置问题回第3.2节检查。如果编码有值但还黑屏则抓RTP包分析视频流是否真的在传输这一步用tcpdump或sngrep就能完成。再确认SRTP加密是否正常工作。如果一端启用强制SRTP另一端没有或DTLS证书验证失败音频可能还正常因为有些终端对音频SRTP做宽松处理视频媒体则直接无法解密表现就是黑屏。排查时可以用rtp bearer capability或者查看diameter日志中的crypto行。最后确认是否转码引起的黑屏。这种情况通常表现为——视频码流在传输但CPU极高且read和write编码不一致。解决办法是强制两端使用同一编码或者升级硬件。6.3 RTCP丢包率怎么快速看fs_cli里可以查看通话的RTP统计例如用uuid_rtcp_stat或直接看rtp_audio/rtp_video的实时指标。注意FreeSWITCH的版本不同命令略有差异我常用的方式uuid_rtcp_stat uuid另外在完整的日志输出中挂断时系统会打印每个信道的RTP收发统计包括丢包数、抖动值、最大延迟等这些数据对判断视频卡顿原因非常有用。6.4 防火墙和NAT场景下的视频媒体问题视频通话对RTP端口的要求比语音高尤其是浏览器WebRTC场景需要UDP大范围端口放行。如果系统部署在NAT或云环境防火墙只开放了SIP信令端口RTP媒体流就会丢在防火墙外面表现就是能注册、能呼通、音频有时正常有时没声音、视频永远黑屏。我的建议是媒体端口范围在防火墙里放行时至少和vars.xml里的rtp-start-port/rtp-end-port保持一致并且尽量采用IPTables规则而不是安全组减少状态跟踪导致的性能损耗。另外要开启SIP profile的NAT穿透参数param nameapply-nat-acl valuewan.auto/ param nameaggressive-nat-detection valuetrue/这些参数可以让FreeSWITCH正确识别终端经过NAT后的公网地址并正确处理SDP里的IP字段。很多“呼通了却看不到画面”的案例最后都归结到NAT没有正确穿透。6.5 代码层面的隐藏坑位有几个配置文件里的隐藏坑位值得单独提醒。第一个是internal.xml里的inbound-codec-prefs和outbound-codec-prefs。这两个参数分别控制收到的INVITE和呼出的INVITE里携带的编码列表。如果只改了inbound没改outbound从FreeSWITCH呼出到外线时视频编码协商仍然会失败。很多呼叫中心项目就是死在这个细节上。第二个是vars.xml里media_mix_inbound_outbound_codecstrue/open之类的配置。这个参数在不同版本中允许的值不同有的版本兼容true/false有的版本允许“yes/no”配置不当会导致系统启动失败或媒体流方向异常。建议统一写成true或false避免歧义。第三个是dialplan里需要对video codec显式处理。有些场景dialplan会过滤掉video_codec字段例如使用export、transfer等操作时视频参数可能丢失。如果通话经过多次transfer视频经常掉检查dialplan里是否有显式的video_codec变量处理是首要任务。还有一个容易忽略的问题当你使用ring group或call center队列时mod_sofia创建的channel可能没有继承全局的视频编码设置导致本应支持视频的呼叫变成了纯音频。这时需要在dialplan中为这些模块显式加入编码变量或者使用合适的应用参数把编码透传下去。7. 实测优化后的效果对比前面讲的都是方法论这里给一组我实测的优化前后对比数据。环境是FreeSWITCH 1.10硬件为4核8G云主机两个Browser终端通过WebRTC直呼优化前用的是系统默认配置优化后按本文第3、4节的方案调整了编码优先级和转码策略。指标优化前优化后720p视频首次出画时间3~5秒1秒以内CPU占用两路通话平均75%平均35%主观画质画面糊、微卡清晰流畅单路带宽占用2.5~4 Mbps存在转码冗余1.2~2 MbpsRTCP丢包率1.8%0.4%这个表能直观说明为什么编解码配置值得花时间深挖。优化前之所以直播卡核心原因就是系统对两个相同的WebRTC终端做了无意义的VP8转码白白消耗了CPU和带宽。统一编码优先级后媒体走纯透传所有指标自然回落。8. 经验总结与踩坑心得最后说几个我在多个项目里反复踩坑后总结出来的经验供大家参考。第一配置文件排序非常重要。遇到编解码问题我永远先查vars.xml再查sip_profiles再查dialplan不跳步。有一回为了图快直接改了dialplan里的video_codec费了两个小时没找到问题最后发现internal.xml里的编码列表根本没包含视频编码改dialplan等于白改。第二视频通话并发规划一定要按媒体线程和CPU来算不能只看信令层的并发上限。这就像搞音乐节的场地容量售票数量不等于现场能容下的人流媒体线程才是真正的“现场承载”。第三日志和抓包是排查视频问题的两条腿。sngrep能看SIP头部Wireshark能看RTP流mount的RTP统计能看丢包和抖动三样组合起来绝大多数视频通话问题都能定位。不用怕日志量大加好过滤条件其实很快。第四如果项目里终端生态复杂建议先从“全走VP8”开始验证把链路弄通了再逐步引入H264。VP8在WebRTC里的兼容性是最好的先用它能快速排除很多底层问题。H264在硬件话机里确实好但引入它的同时也要想清楚专利许可的问题这部分不是技术问题但会直接影响上线。根据我个人经验FreeSWITCH的视频通话能力是被严重低估的很多团队因为配置门槛太高就直接放弃了视频能力实际上只要理清配置文件里的编码协商逻辑视频通话的稳定性完全能做成商业级。希望这篇文章能帮你少走几个弯路把视频通话这条链路稳稳跑起来。