Mumble 网络协议深度解析：TCP 控制通道与 UDP 语音通道的通信机制全解

音视频即时通讯【免费下载链接】mumbleMumble is an open-source, low-latency, high quality voice chat software.项目地址https://gitcode.com/gh_mirrors/mu/mumble点击查看免费下载Mumble 是一款开源、低延迟、高质量语音聊天软件其客户端与服务器之间的通信建立在双通道模型之上一条可靠的 TCP 连接负责控制信令一条低延迟的 UDP 连接承载语音数据。本文以仓库 docs/dev/network-protocol 下的协议文档为核心结合src/Mumble.proto、src/MumbleUDP.proto与src/PacketDataStream.h等源码系统讲解数据包封装格式、连接建立流程、语音帧编码与加密机制读完即可掌握 Mumble 1.2.x 时代协议的全貌并了解其在现代版本中的演进方向。协议总体架构双通道模型与强制加密Mumble 采用标准的服务器-客户端通信模型通信被拆分为两条互不相同的通道TCP 控制通道可靠地传输控制数据认证、频道/用户状态、文本消息、ACL 等是客户端连接服务器的必要条件UDP 语音通道用于低延迟传输语音数据传输层不可靠但通过序列号等手段维持有序性。两条通道都被强加密保护且加密是强制的、不可关闭的TCP 控制通道使用 TLSv1 AES256-SHA语音通道使用 OCB-AES128。需要特别指出的是虽然 TCP 连接是必需的但 UDP 通道并非必需——当 UDP 不可用时语音包可以通过 TCP 连接隧道传输详见后文Tunneling audio over TCP一节。TCP 控制通道协议栈前缀 Protobuf 的浅层封装Mumble 的协议栈非常浅易于理解它本质上是Google Protocol Buffers编码的消息加上一个简单的二进制前缀用于区分消息类型与长度所有数据再经由 TLSv1 加密传输。这种设计使协议非常容易扩展。数据包前缀格式每个 TCP 控制消息的前缀由两部分构成字段长度说明消息类型2 字节标识负载payload的类型负载长度4 字节负载的字节数前缀之后紧跟负载本体。除UDPTunnel外所有消息类型都是简单的 protobuf 消息除非特别说明protobuf 编码之外的所有字段均为**大端big-endian**字节序。消息类型表1.2.x 协议当前协议中定义了以下 26 种消息类型Type 0–25Type负载消息0Version1UDPTunnel2Authenticate3Ping4Reject5ServerSync6ChannelRemove7ChannelState8UserRemove9UserState10BanList11TextMessage12PermissionDenied13ACL14QueryUsers15CryptSetup16ContextActionModify17ContextAction18UserList19VoiceTarget20PermissionQuery21CodecVersion22UserStats23RequestBlob24ServerConfig25SuggestConfig每种消息类型的原始定义见仓库中的 src/Mumble.protoTCP 消息与 src/MumbleUDP.protoUDP 消息两个 protobuf 定义文件。值得注意的是MumbleUDP.proto目前使用proto3语法而Mumble.proto仍为proto2src/Mumble.proto顶部注释明确标注了Not used. Not even for tunneling UDP through TCP说明UDPTunnel消息在代码层面已不再使用。建立连接从 TLS 握手到状态同步的完整时序本节描述连接建立阶段客户端与服务器之间的通信过程。注意客户端只要建立 TCP 连接即视为已连接此后即对其他客户端可见并能发送各类消息UDP 通道并非必需。连接与 TLS 握手客户端首先与服务器建立 TCP 连接并完成一次标准的 TLSv1 握手。为了使用 Mumble 协议的完整功能集建议但不强制客户端向服务器提供一张强证书无证书也可以连接。反过来服务器必须向客户端提供自己的证书且建议客户端对其进行校验。版本交换Version 消息TLS 握手完成后双方应使用Version消息交换各自版本信息。1.2.x 文档中记录的消息结构如下字段类型versionuint32releasestringosstringos_versionstringversion字段是主版本号、次版本号、补丁版本号的组合如 1.2.0主版本占 2 字节次版本与补丁版本各占 1 字节主版本次版本补丁版本2 字节1 字节1 字节release、os、os_version为携带附加信息的普通字符串目前协议不对其做任何解释。版本信息会被用于SuggestConfig检查通常针对标准客户端版本。1.2.x 系列的主要版本变化如下版本主要变化1.2.0CELT 0.7.0 编解码器支持1.2.2CELT 0.7.1 编解码器支持1.2.3CELT 0.11.0 编解码器1.2.4Opus 编解码器支持、引入 SuggestConfig 消息注意原文档特别标注这段 Version 结构说明已过时应以后续 proto 定义为准。在当前的 src/Mumble.proto 中可以看到演进痕迹Version消息同时定义了旧版optional uint32 version_v1 1与新格式optional uint64 version_v2 5新格式是为了支持补丁版本号超过 255 的情况而引入。认证Authenticate 消息客户端发送完版本消息后紧接着应发送Authenticate消息。该消息可以在发送版本消息后立即发出无需等待服务器返回版本消息。1.2.x 文档中的结构如下字段类型usernamestringpasswordstringtokensstringusername与password是 UTF-8 编码字符串。客户端可以接受用户输入的任何用户名但服务器有权施加进一步限制若客户端证书已在服务器上注册则客户端主要以其注册证书时的用户名被识别。password仅在以下情况必须提供服务器设有密码、客户端未提供证书但要认证到设有密码的账户、或要访问 SuperUser 账户。tokens是零个或多个 token 字符串组成的列表作为密码使用可让客户端无需成为 ACL 组的注册成员即可访问某些 ACL 组。在当前 src/Mumble.proto 中Authenticate消息还扩展了更多字段包括repeated int32 celt_versions客户端支持的 CELT 比特流版本常量列表、optional bool opus是否支持 Opus、以及optional int32 client_type0 REGULAR1 BOT这些字段用于客户端向服务器声明自身的编解码能力。加密设置CryptSetup 消息版本包交换完成后服务器会向客户端发送一个CryptSetup包其中包含 UDP 语音通道 OCB-AES128 加密所需的全部密钥材料字段类型keybytesclient_noncebytesserver_noncebytes加密算法的具体实现可参考仓库 src/crypto/CryptStateOCB2.cpp 与 src/crypto/CryptStateOCB2.h该实现基于 OCB-AES128 模式。频道状态同步ChannelState 消息客户端认证成功后服务器开始逐个频道发送部分ChannelState消息为每个频道建立基础信息。这些初始消息不含频道链接links信息因为此时客户端还没有看到全部频道当所有频道的初始ChannelState发送完毕后服务器再通过新的数据包补发链接信息。完整结构如下字段类型channel_iduint32parentuint32namestringlinksrepeateduint32descriptionstringlinks_addrepeateduint32links_removerepeateduint32temporaryoptionalboolpositionoptionalint32服务器必须为 ID 为 0 的根频道root channel发送一个 ChannelState 消息。在 src/Mumble.proto 中ChannelState还包含description_hash描述超过 128 字节时使用 SHA1 哈希传输、max_users频道最大用户数0 表示使用服务器usersperchannel设置、is_enter_restricted、can_enter等扩展字段。用户状态同步UserState 消息频道同步完成后服务器继续逐个列出当前在线的用户为每个用户包括正在连接的客户端自己发送一条UserState消息。1.2.x 文档中的字段如下字段类型sessionuint32actoruint32namestringuser_iduint32channel_iduint32mutebooldeafboolsuppressboolself_muteboolself_deafbooltexturebytesplugin_contextbytesplugin_identitystringcommentstringhashstringcomment_hashbytestexture_hashbytespriority_speakerboolrecordingbool在 src/Mumble.proto 中UserState还扩展了temporary_access_tokens、listening_channel_add/listening_channel_remove频道监听、listening_volume_adjustment针对收听者的音量调整等字段并内嵌了VolumeAdjustment子消息。服务器同步ServerSync 消息此时客户端已获得服务器状态中其需要知道的部分。为完成同步服务器最后发送一条ServerSync消息包含客户端会话session的 ID、服务器允许的最大带宽、服务器欢迎文本welcome text以及客户端最终所在频道的权限。在 src/Mumble.proto 中ServerSync的权限字段是optional uint64 permissions其注释说明权限数据类型通常是 uint32如 PermissionQuery 与 PermissionDenied 消息中此处因历史疏漏使用 uint64但值不应超过 uint32 范围。Ping 保活机制若客户端希望维持与服务器的连接就必须持续向服务器发送 Ping。若服务器在 30 秒内未收到任何 Ping将断开该客户端的连接。客户端也可通过 Ping 消息向服务器上报网络质量统计good/late/lost/resync、UDP/TCP 丢包与延迟数据详见 src/Mumble.proto 中Ping消息的丰富字段。语音数据通道UDP自定义编码的音频包与 TCP 控制通道不同音频通道使用自定义编码传输音频包。音频通道与传输层解耦——诸如加密之类的特性由传输层实现超过 8 位的整数一律使用变长整数编码Variable length integer encodingvarint。音频包格式音频通道的包是变长的以一个 8 位头部字段开头最高 3 位bit 7–5定义包类型type其余 5 位bit 4–0定义目标target其后紧跟负载。整个音频数据包的最大长度为1020 字节这使得应用可以使用 1024 字节的缓冲区接收 UDP 数据报多出的 4 字节用于加密头开销。------------------------------- | Audio packet structure | | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | ------------------------ | type | target | ------------------------------ | Payload... | -------------------------------音频包类型type音频通道上传输的包要么是用于诊断传输层连通性的 Ping 包要么是不同编解码器编码的音频包Type位域Bitfield说明0000xxxxxCELT Alpha 编码语音数据1001xxxxxPing 包2010xxxxxSpeex 编码语音数据3011xxxxxCELT Beta 编码语音数据4100xxxxxOpus 编码语音数据5-7—未使用音频目标targettarget 部分定义音频数据的接收者。两个恒定目标为Normal talking0与Server Loopback31范围 1–30 保留给耳语whisper目标这些目标通过控制通道中的VoiceTarget包单独注册。当客户端在服务器上注册一个 VoiceTarget 时会为其分配一个 ID该 ID 即可作为语音包中的 target 使用将音频定向发送到特定用户或频道。接收耳语音频时服务器使用target 1表示向频道的耳语产生的音频使用target 2表示直接向用户的耳语产生的音频。Target说明0正常说话Normal talking1–30耳语目标Whisper target客户端发送耳语时使用 VoiceTarget ID接收向频道的耳语时为 1接收直接向用户的耳语时为 231服务器回环Server loopbackPing 包音频通道的 Ping 包用于音频传输层的连通性检查仅包含一个 varint 编码的时间戳作为数据字段类型说明Headerbyte00100000b0x20Datavarint时间戳Header通用音频包头Ping 包应固定为 0x20。Data时间戳。该包应被原样回显echo back因此时间戳格式由原始发送方自行决定——唯一限制是它必须能放进 varint 编码的 64 位整数。在现代版本中UDP Ping 已升级为 protobuf 消息src/MumbleUDP.proto 中的Ping消息包含timestamp客户端自定义格式、request_extended_information请求服务器附加信息、server_version_v2、user_count、max_user_count、max_bandwidth_per_user等字段。编码音频数据包编码音频包承载实际语音数据。**传入incoming服务器发给客户端**的音频数据包结构字段类型说明Headerbyte编解码器类型/音频目标Session IDvarint源用户的会话 IDSequence Numbervarint第一个音频数据segment的序列号Payloadbyte[]音频负载Position Infofloat[3]位置音频信息**传出outgoing客户端发给服务器**的音频数据包结构字段类型说明Headerbyte编解码器类型/音频目标Sequence Numbervarint第一个音频数据segment的序列号Payloadbyte[]音频负载Position Infofloat[3]位置音频信息要点说明Session ID音频包归属用户的会话 ID。传出包不携带它服务器根据传输层信息将其匹配到正确的会话。Sequence Number音频数据序列号用于在 UDP 这种不可靠传输上维持包顺序。当音频包包含多个音频 segment 时序列号在相邻包之间可能一次增加不止 1这使丢包隐藏packet loss concealment算法能计算出两次收到包之间丢失的音频帧数。Payload音频负载格式取决于 Header 中定义的编解码器。负载必须能自定界self-delimiting以便判断包尾是否存在位置信息。Position Info音频源的 XYZ 坐标。发送位置信息的同时用户必须在使用UserState消息中定义的某个位置音频插件positional plugin。插件可能定义不同的 context阻止不同 context 下的用户之间进行语音通信。Speex 与 CELT 音频帧Speex 与 CELT 编码的音频以独立编码帧的形式传输每帧前面有一个 1 字节的长度/续传continuation头字段类型说明Headerbyte长度/续传头Databyte[]编码语音帧HeaderData 字段的长度。最高位0x80是续传位负载中除最后一帧外的所有帧都要置位其余 7 位是 Data 帧的实际长度。注意长度可以是 0——这用于发出语音传输结束信号此时音频数据是单个零字节可正常解读为长度为 0 且未置续传位。Data单个编码音频帧编码方式取决于整个音频包的type头。Opus 音频帧Opus 编码的音频作为单个 Opus 音频帧传输前面是一个变长字节头字段类型说明Headervarint长度/终止terminator头Databyte[]编码语音帧HeaderData 字段的长度采用 16 位变长整数编码并含终止位。varint 编码方式与 64 位值相同但只允许 16 位未编码值。最大语音帧大小为 81910x1FFF字节占头部的 13 个最低有效位第 14 位掩码0x2000是终止位指示该包是否为当前语音传输的最后一包。对比说明CELT 中头部的续传位定义当前包是否还有更多音频帧每个包可含多帧Opus 每包只含一帧。CELT 用零字节包表示语音结束而 Opus 在头部有专门的终止位。编解码器CodecsMumble 支持三种不同编解码器早期版本用 Speex 承载低码率音频、用 CELT 承载更高质量的音频而较新的版本在所有场景下都优先使用 Opus。当多个能力不同的客户端互相通信时由服务器负责裁决使用哪种编解码器有能力的客户端应遵守服务器裁决。若服务器裁决的编解码器客户端不支持该客户端可以自由使用任何它偏好的编解码器——通常这意味着它无法解码收到的音频但仍然可以向外发送编码音频。CELT 的比特流从未冻结导致大多数 CELT 版本互不兼容。Mumble 支持的两种 CELT 比特流是**CELT 0.7.0CELT Alpha**与CELT 0.11.0CELT Beta。虽然 CELT 0.7.0 在技术上应被大多数 Mumble 实现支持但部分服务器可能被配置为强制用户使用 Opus。Mumble 自1.2.42013 年 6 月起支持 Opus可以合理假设如今大多数客户端都已支持它。耳语Whispering正常说话可以被当前频道及所有链接频道的用户听到前提是说话者对这些频道拥有 Talk 权限。若说话者想将声音定向广播给特定用户或频道可以使用耳语通过VoiceTarget消息注册一个语音目标然后在 UDP 包的首字节中把该目标 ID 作为 target 使用。UDP 连通性检查UDP 是无连接协议受网络拓扑如 NAT 配置影响严重在连通性被确认之前不应使用 UDP 传输音频。检查流程如下客户端向服务器发送一个Ping 包服务器收到后将其回显到收到的源地址客户端收到服务器响应后即可开始使用 UDP 传输音频数据服务器一旦通过 UDP 收到音频数据也会把出站音频切换到 UDP 传输。如果客户端某时刻不再收到 UDP Ping 的回复它应开始通过 TCP 隧道传输语音见下节。服务器收到 TCP 上的隧道包后也必须停止使用 UDP进行通信。同时客户端仍应继续通过 UDP 发送音频 Ping 包以便 UDP 连接恢复后通信可以切回。通过 TCP 隧道传输音频Tunneling audio over TCP当 UDP 通道不可用时语音包可以通过控制通道所用的 TCP 传输。这些消息使用标准 TCP 前缀16 位消息类型 32 位消息长度见前文TCP 控制通道协议栈一节。但与其它 TCP 消息不同音频包不是protobuf 编码的消息而是将上文Packet format描述的原始音频包原样写入 TCP socket。收到包时可安全地按常规解析类型与长度字段若类型匹配音频隧道UDPTunnel则消息其余部分应作为 UDP 包处理不要尝试进行 protobuf 解码。实现建议Implementation note实现协议时可以先忽略 UDP 传输层、仅通过 TCP 隧道传输 UDP 数据。TCP 层无论如何都必须实现认证需要它。在实现 UDP 协议之前先确保语音传输可用能极大简化调试过程。加密所有包在传输期间只加密一次。实际加密方式取决于所用的传输层若包经 TCP 隧道传输则使用加密整条控制通道连接的 TLS若直接通过 UDP 发送则必须使用 OCB-AES128 加密实现见 src/crypto/CryptStateOCB2.cpp。变长整数编码Varint64 位整数的紧凑表示varint 用于编码长64 位整数使短值不必占用完整的 8 字节。基本思想是给值加上长度前缀然后去掉值的高位零。正数始终右对齐——即编码表示中的最低有效位与解码表示中的最低有效位一一对应。编码过程是在解码表中查找第一个能容纳该数的描述将其截断为所需字节数再与定义的编码前缀合并。各前缀定义如下编码表示解码结果0xxxxxxx7 位正数10xxxxxx 1 字节14 位正数110xxxxx 2 字节21 位正数1110xxxx 3 字节28 位正数111100__int32 位32 位正数111101__long64 位64 位数111110__varint负数递归 varint111111xx字节反转的负数两位~xx表中x位是解码数字的组成部分_表示未使用位。参考实现位于 src/PacketDataStream.h其quint64相关的移位运算符实现了完整的编解码逻辑——例如operator(const quint64 value)#L142负责编码、decode_next_int(std::size_t recursionLevel 0)#L202负责解码内部通过next()读取字节并依据前缀位模式逐级还原数值如(v 0x0F) 24、(v 0x1F) 16等移位操作。这份头文件同时被客户端与服务端复用是理解 varint 细节的最佳源码入口。现代演进proto3 时代的新语音协议需要说明的是本文所依据的协议文档反映的是Mumble 1.2.8 客户端所实现的协议状态读者阅读时可能已经过时。两个 protobuf 定义文件才是消息类型与消息结构的最新权威来源src/Mumble.protoTCP 控制消息定义当前为 proto2含version_v1/version_v2双版本号格式等演进痕迹src/MumbleUDP.protoUDP 消息定义当前为 proto3其Audio消息展示了语音通道的新面貌——用oneof区分target客户端发送时的目标与context服务器发送时的上下文0 正常说话 / 1 向频道喊话 / 2 向用户耳语 / 3 经由频道监听收到、sender_session、frame_number、opus_data、positional_data、volume_adjustment与is_terminator等字段。该文件注释还解释了字段索引为何跳过 1–15索引 ≤ 15 的字段在 protobuf 编码中只需 1 字节开销为高频字段预留。对于希望实现 Mumble 协议的开发者建议始终以这两个.proto文件为准本文档可作为理解协议设计思想与历史演进脉络的补充参考。赞分享音视频即时通讯【免费下载链接】mumbleMumble is an open-source, low-latency, high quality voice chat software.项目地址https://gitcode.com/gh_mirrors/mu/mumble点击查看免费下载相关推荐Mumble 网络协议全解析TCP 控制通道、UDP 语音通道与双通道加密机制Mumble 网络协议全解析TCP 控制通道、UDP 语音通道与双通道加密机制 Mumble 是一款开源、低延迟、高质量语音通信软件其网络协议采用经典的服务音视频即时通讯xiaozhi-esp32 MQTT UDP 混合通信协议深度解析控制通道与实时音频通道的分工协作xiaozhi esp32 MQTT UDP 混合通信协议深度解析控制通道与实时音频通道的分工协作 导读 本文档以 xiaozhi esp32 项目中基于人工智能大模型语音交互助手嵌入式物联网智能硬件MCP 服务Mumble 协议栈TCP 控制通道深度解析前缀封装、消息类型与加密传输机制Mumble 协议栈TCP 控制通道深度解析前缀封装、消息类型与加密传输机制 Mumble 的 TCP 控制通道采用简洁、易扩展的设计以 Googl音视频即时通讯上一篇Bitnami Containers配置管理ConfigMapSecret配置注入下一篇Firecrawl MCP Server 结构化数据提取LLM 驱动的智能信息抽取终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考