Permalink
Browse files

Documentation: Added a note concerning the codec requirements and cla…

…rified UDP tunneling. Also some minor float/margin tweaks.
  • Loading branch information...
1 parent ca23daf commit 2131364b88c9ae5cc6a1bde018f36962be0edfbe @Rantanen Rantanen committed with hacst Nov 8, 2010
Showing with 24 additions and 19 deletions.
  1. BIN doc/mumble-protocol.pdf
  2. +24 −19 doc/mumble-protocol.tex
View
Binary file not shown.
View
@@ -4,8 +4,6 @@
% This is a simple template for a LaTeX document using the "article" class.
% See "book", "report", "letter" for other types of document.
-% Rantanen: Might prefer 'report' document type. Mainly for the use of Chapters.
-
\documentclass[11pt]{article} % use larger type; default would be 10pt
\usepackage[utf8]{inputenc} % set input encoding (not needed with XeLaTeX)
@@ -17,7 +15,7 @@
%%% PAGE DIMENSIONS
\usepackage{geometry} % to change the page dimensions
\geometry{a4paper} % or letterpaper (US) or a5paper or....
-% \geometry{margins}{2cm} % for example, change the margins to 2 inches all round
+\geometry{top=2.5cm, bottom=2.5cm} % for example, change the margins to 2 inches all round
% \geometry{landscape} % set up the page for landscape
% read geometry.pdf for detailed page layout information
@@ -41,6 +39,8 @@
\usepackage{mathtools}
\usepackage{amssymb}
+\usepackage{float}
+
\DeclareMathOperator{\bit}{bit}
\DeclareMathOperator{\band}{and}
\DeclareMathOperator{\lshift}{<<}
@@ -200,7 +200,7 @@ \subsection{Connect}
\subsection{Version exchange}
Once the TLS handshake is completed both sides should transmit their version information using the Version message. The message structure is described below.
-\begin{figure}[htp]\begin{center}
+\begin{figure}[H]\begin{center}
\begin{mumbleMessage}{Version}
version & uint32 \\
@@ -214,7 +214,7 @@ \subsection{Version exchange}
The version field is a combination of major, minor and patch version numbers (e.g. 1.2.0) so that major number takes two bytes and minor and patch numbers take one byte each. The structure is shown in figure \ref{fig:versionEncoding}. The release, os and os\_version fields are common strings containing additional information. This information is not interpreted in any way at the moment.
-\begin{figure}[htp]\begin{center}\begin{tabular}{|@{\hspace{0.5cm}}c@{\hspace{0.5cm}}|c|c|}
+\begin{figure}[H]\begin{center}\begin{tabular}{|@{\hspace{0.5cm}}c@{\hspace{0.5cm}}|c|c|}
\hline
Major & Minor & Patch \\
@@ -230,7 +230,7 @@ \subsection{Version exchange}
\subsection{Authenticate}
Once the client has sent the version it should follow this with the Authenticate message. The message structure is described below in figure \ref{msg:conn:authenticate}. This message may be sent immediately after sending the version message. The client does not need to wait for the server version message.
-\begin{figure}[htp]\begin{center}
+\begin{figure}[H]\begin{center}
\begin{mumbleMessage}{Authenticate}
username & string \\
password & string \\
@@ -248,7 +248,7 @@ \subsection{Authenticate}
\subsection{Crypt setup}
Once the Version packets are exchanged the server will send a CryptSetup packet to the client. It contains the necessary cryptographic information for the OCB-AES128 encryption used in the UDP Voice channel. The packet is described in figure \label{msg:conn:cryptSetup}. The encryption itself is described later in section \ref{sect:udpEncryption}.
-\begin{figure}[htp]\begin{center}
+\begin{figure}[H]\begin{center}
\begin{mumbleMessage}{CryptSetup}
key & bytes \\
client\_nonce & bytes \\
@@ -263,7 +263,7 @@ \subsection{Channel states}
After the client has successfully authenticated the server starts listing the channels by transmitting partial ChannelState message for every channel on this server. These messages lack the channel link information as the client does not yet have full picture of all the channels. Once the initial ChannelState has been transmitted for all channels the server updates the linked channels by sending new packets for these. The full structure of these ChanneLState messages is shown in \ref{msg:conn:channelState}.
-\begin{figure}[htp]\begin{center}
+\begin{figure}[H]\begin{center}
\begin{mumbleMessage}{ChannelState}
channel\_id & uint32 \\
parent & uint32 \\
@@ -285,7 +285,7 @@ \subsection{User states}
After the channels have been synchronized the server continues by listing the connected users. This is done by sending a UserState message for each user currently on the server, including the user that is currently connecting. The message structure is shown in figure \ref{msg:conn:userState}.
-\begin{figure}[htp]\begin{center}
+\begin{figure}[H]\begin{center}
\begin{mumbleMessage}{ChannelState}
session & uint32 \\
actor & uint32 \\
@@ -332,7 +332,7 @@ \subsection{Enabling the UDP channel}
In practice these requirements are filled with UDP ping. When the server receives a UDP ping packet (See figure \ref{fig:udpping}) from the client it echoes the packet back. When the client receives this packet it can ascertain that the UDP channel works for two-way communication.
-\begin{figure}[htp]\begin{center}\begin{tabular}{|rcl|p{0.3\textwidth}}
+\begin{figure}[H]\begin{center}\begin{tabular}{|rcl|p{0.3\textwidth}}
\cline{1-3}
byte &:& type/flags & \texttt{0010 0000} for Ping \\
@@ -350,7 +350,7 @@ \subsection{Data}
The voice data is transmitted in variable length packets that consist of header portion, followed by repeated data segments and an optional position part. The full packet structure is shown in figure \ref{fig:udpvoice}. The decrypted data should never be longer than 1020 bytes, this allows the use of 1024 byte UDP buffer even after the 4-byte encryption header is added to the packet during the encryption. The protocol transfers 64-bit integers using variable length encoding. This encoding is specified in section \ref{sect:varint}.
-\begin{figure}[htp]\begin{center}\begin{tabular}{l|rcl|p{0.5\textwidth}}
+\begin{figure}[H]\begin{center}\begin{tabular}{l|rcl|p{0.5\textwidth}}
\cline{2-4}
\textbf{Header} & byte &:& type/target & Bit 1-3: Type, Bit 4-8: Target \\
@@ -381,7 +381,7 @@ \subsection{Data}
The first byte of the header contains the packet type and additional target specifier. The type is stored in the first three bits and specifies the type and encoding of the packet. Current types are listed in table \ref{tbl:udptypes}. The remaining 5 bits specify additional packet-wide options. For voice packets the values specify the voice target as listed in table \ref{tbl:udptargets}.
-\begin{table}[htp]\begin{center}
+\begin{table}[H]\begin{center}
\caption{UDP Types}\label{tbl:udptypes}
\begin{tabular}{ll}
@@ -395,7 +395,7 @@ \subsection{Data}
\end{tabular}
\end{center}\end{table}
-\begin{table}[htp]\begin{center}
+\begin{table}[H]\begin{center}
\caption{UDP targets}\label{tbl:udptargets}
\begin{tabular}{ll}
@@ -411,6 +411,11 @@ \subsection{Data}
The audio frames consist of one byte long header and up to 127 bytes long data portion. The first bit in the header is the \texttt{Terminator bit} which informs the receiver whether there are more audio frames after this one. This bit is turned on (value \texttt{1}) for all but the last frame in the current UDP packet. Rest of the seven bits in the header specify the length of the data portion. The data portion is encoded using one of the supported codecs. The exact codec is specified in the type portion of the whole packet (See table \ref{tbl:udptypes}). \emph{The data in each frame is encoded separately.}
+\subsection{Codecs}
+\label{sect:codecs}
+
+Mumble supports two distinct codecs; Low bit rate audio uses Speex and higher quality audio is encoded with CELT. Both of these codecs must be supported for full support of the Mumble protocol. Furthermore, as the CELT bitstream has not been frozen yet which places requirements for the exact CELT version: The clients must support CELT 0.7.1 bitstream. The protocol includes codec negotiation which allows clients to support other codec versions as well, in which case the server should attempt to negotiate a version that all clients support. The clients must respect the server resolution.
+
\subsubsection{Whispering}
\label{sect:whispering}
@@ -421,7 +426,7 @@ \subsubsection{Whispering}
The variable length integer encoding is used to encode long, 64-bit, integers so that short values do not need the full 8 bytes to be transferred. The basic idea behind the encoding is prefixing the value with a length prefix and then removing the leading zeroes from the value. The positive numbers are always right justified. That is to say that the least significant bit in the encoded presentation matches the least significant bit in the decoded presentation. Table \ref{tbl:varint} contains the definitions of the different length prefixes. The encoded \texttt{x} bits are part of the decoded number while the \texttt{\_} signifies a unused bit. Encoding should be done by searching the first decoded description that fits the number that should be decoded, truncating it to the required bytes and combining it with the defined encoding prefix.
-\begin{table}[htp]\begin{center}
+\begin{table}[H]\begin{center}
\caption{\texttt{varint} prefixes}\label{tbl:varint}
\begin{tabular}{ll}
@@ -484,9 +489,9 @@ \subsubsection{Whispering}
\subsection{TCP tunnel}
\label{sect:udptunnel}
-When the UDP packets are tunneled through the TCP tunnel they are prefixed with the TCP protocol header that contains the packet type and length and sent through the connection. (Figure \ref{fig:udptunnel})
+When the UDP packets are tunneled through the TCP tunnel they are prefixed with the TCP protocol header that contains the packet type and length and sent through the connection. (Figure \ref{fig:udptunnel}) These packets do not use protocol buffer messages.
-\begin{figure}[htp]\begin{center}\begin{tabular}{|c|@{\hspace{0.5cm}}c@{\hspace{0.5cm}}|@{\hspace{3cm}}c@{\hspace{3cm}}|}
+\begin{figure}[H]\begin{center}\begin{tabular}{|c|@{\hspace{0.5cm}}c@{\hspace{0.5cm}}|@{\hspace{3cm}}c@{\hspace{3cm}}|}
\hline
Type & Length & UDP Packet \\
@@ -804,10 +809,10 @@ \subsection{TextMessage}
\subsection{UDPTunnel}
\label{msg:udpTunnel}
-Used to tunnel the UDP packets through the TCP channel. See section \ref{sect:udptunnel} for more information.
+Not used. Not even for tunneling UDP through TCP. See section \ref{sect:udptunnel} for more information.
\begin{mumbleMessageEx}
-\mumbleMessageExItem{packet}{bytes}{Req.}{The data from the UDP packet}
+\mumbleMessageExItem{packet}{bytes}{Req.}{Not used}
\end{mumbleMessageEx}
\subsection{UserList}
@@ -939,7 +944,7 @@ \subsubsection{VoiceTarget\_Target}
% Right place?
-\section {This document is WIP}
+\section*{This document is WIP}
SORRY BUT THIS DOCUMENT IS WORK IN PROGRESS. AT THE MOMENT IT LACKS A LOT OF IMPORTANT INFORMATION BUT WE HOPE TO BE ABLE TO FINISH THIS DOCUMENT SOMEDAY :-)
\appendix

0 comments on commit 2131364

Please sign in to comment.