Improve voice protocol documentation

[dexgs]

Context

I'm writing a very minimal client library for writing bots. I've had no trouble using the protocol docs to establish a connection and send messages on the control channel. The docs aren't as clear when it comes to voice messages.

Description

Could the documentation of the voice protocol be expanded?

The questions I currently can't find answers to are:

• How are voice messages encoded? Is it the same as messages in the control channel?
• How are voice messages tunneled over TCP?
• What is the encryption scheme for voice messages? The docs say 128-bit OCB AES, but I can't find more details.

Just answering these questions on this issue would be enough for me. I'd be willing to contribute to the docs once I figure this out.

Mumble component

Both

OS-specific?

No

Additional information

No response

[Krzmbrzl]

Since Mumble 1.5, we're using Protobuf for audio packets as well, which I think simplifies that part a lot. See https://github.com/mumble-voip/mumble/blob/master/src/MumbleUDP.proto

As for encryption, I think the best source of documentation for that at this point is the source code: https://github.com/mumble-voip/mumble/blob/master/src/crypto/CryptStateOCB2.cpp#L7

And tunneling audio is done by encoding the audio packet normally but then sending it through the TCP connection and prepending the header for the UDPTunnel Protobuf message. See also https://github.com/mumble-voip/mumble/blob/master/src/mumble/ServerHandler.cpp#L305

You might also be interested in https://github.com/mumble-voip/mumble/blob/master/src/MumbleProtocol.cpp

Finally, there is https://github.com/mumble-voip/mumble/tree/master/docs/dev/network-protocol which contains the description of the legacy voice data format.

[TheStaticTurtle]

Having read most of the codebase and implemented part of the protocol for a prototype,
I'll add that the CryptStateOCB2 was so finicky to get working in java for me that I ended up using JNI which worked great!

It's probably less of an issue for a bot that only sends music, but I had two issues while trying to understand mumble:

• The packet/data flow (for both control and audio) is sometimes challenging to follow inside the codebase
  • The main files I needed to look at are MumbleProtocol.cpp (packet en/decoding) and mumble/ServerHandler.cpp+mumble/Messages.cpp for packet handling
• The files in /docs/dev/network-protocol are wonderful at explaining how to establish a connection. But I found that while the theoretical function of the rest of the packets, is very well documented in the .proto(s) , the actual usage/handling of said packets and their repercussions are sometimes unclear.
  • The mumble/Messages.cpp file cleared up a bunch of things for me, but it was still a staring contest sometimes

This is in no way a dig, mumble is awesome. My issues probably stem from the fact that the protocol is very tightly integrated into the app. IIRC, there was (is?) some talk about splitting mumble into UI logic and an API logic, but I might be wrong.

[Krzmbrzl]

there was (is?) some talk about splitting mumble into UI logic and an API logic, but I might be wrong.

Yes, we still plan to make the split. That's what we want to achieve with libmumble in the long run.