1 files changed, 98 insertions, 0 deletions
diff --git a/trunk/doc/tex/jitterbuffer.tex b/trunk/doc/tex/jitterbuffer.tex
new file mode 100644
index 000000000..a29cf811a
--- /dev/null
+++ b/trunk/doc/tex/jitterbuffer.tex
@@ -0,0 +1,98 @@
+\subsubsection{The new jitterbuffer}
+
+You must add "jitterbuffer=yes" to either the [general] part of
+iax.conf, or to a peer or a user.  (just like the old jitterbuffer).
+Also, you can set "maxjitterbuffer=n", which puts a hard-limit on the size of the
+jitterbuffer of "n milliseconds".  It is not necessary to have the new jitterbuffer
+on both sides of a call; it works on the receive side only.
+
+\subsubsection{PLC}
+
+The new jitterbuffer detects packet loss.  PLC is done to try to recreate these
+lost packets in the codec decoding stage, as the encoded audio is translated to slinear.
+PLC is also used to mask jitterbuffer growth.
+
+This facility is enabled by default in iLBC and speex, as it has no additional cost.
+This facility can be enabled in adpcm, alaw, g726, gsm, lpc10, and ulaw by setting
+genericplc =$>$ true in the [plc] section of codecs.conf.
+
+\subsubsection{Trunktimestamps}
+
+To use this, both sides must be using Asterisk v1.2 or later.
+Setting "trunktimestamps=yes" in iax.conf will cause your box to send 16-bit timestamps
+for each trunked frame inside of a trunk frame. This will enable you to use jitterbuffer
+for an IAX2 trunk, something that was not possible in the old architecture.
+
+The other side must also support this functionality, or else, well, bad things will happen.
+If you don't use trunktimestamps, there's lots of ways the jitterbuffer can get confused because
+timestamps aren't necessarily sent through the trunk correctly.
+
+\subsubsection{Communication with Asterisk v1.0.x systems}
+
+You can set up communication with v1.0.x systems with the new jitterbuffer, but
+you can't use trunks with trunktimestamps in this communication.
+
+If you are connecting to an Asterisk server with earlier versions of the software (1.0.x),
+do not enable both jitterbuffer and trunking for the involved peers/users
+in order to be able  to communicate. Earlier systems will not support trunktimestamps.
+
+You may also compile chan\_iax2.c without the new jitterbuffer, enabling the old
+backwards compatible architecture. Look in the source code for instructions.
+
+
+\subsubsection{Testing and monitoring}
+
+You can test the effectiveness of PLC and the new jitterbuffer's detection of loss by using
+the new CLI command "iax2 test losspct $<$n$>$".  This will simulate n percent packet loss
+coming \_in\_ to chan\_iax2. You should find that with PLC and the new JB, 10 percent packet
+loss should lead to just a tiny amount of distortion, while without PLC, it would lead to
+silent gaps in your audio.
+
+"iax2 show netstats" shows you statistics for each iax2 call you have up.
+The columns are "RTT" which is the round-trip time for the last PING, and then a bunch of s
+tats for both the local side (what you're receiving), and the remote side (what the other
+end is telling us they are seeing).  The remote stats may not be complete if the remote
+end isn't using the new jitterbuffer.
+
+The stats shown are:
+\begin{itemize}
+\item Jit: The jitter we have measured (milliseconds)
+\item Del: The maximum delay imposed by the jitterbuffer (milliseconds)
+\item Lost: The number of packets we've detected as lost.
+\item \%: The percentage of packets we've detected as lost recently.
+\item Drop: The number of packets we've purposely dropped (to lower latency).
+\item OOO: The number of packets we've received out-of-order
+\item Kpkts: The number of packets we've received / 1000.
+\end{itemize}
+
+\subsubsection{Reporting problems}
+
+There's a couple of things that can make calls sound bad using the jitterbuffer:
+
+\begin{enumerate}
+\item The JB and PLC can make your calls sound better, but they can't fix everything.
+If you lost 10 frames in a row, it can't possibly fix that.  It really can't help much
+more than one or two consecutive frames.
+
+\item Bad timestamps:  If whatever is generating timestamps to be sent to you generates
+nonsensical timestamps, it can confuse the jitterbuffer.  In particular, discontinuities
+in timestamps will really upset it:  Things like timestamps sequences which go 0, 20, 40,
+60, 80,  34000, 34020, 34040, 34060...   It's going to think you've got about 34 seconds
+of jitter in this case, etc..
+The right solution to this is to find out what's causing the sender to send us such nonsense,
+and fix that.  But we should also figure out how to make the receiver more robust in
+cases like this.
+
+chan\_iax2 will actually help fix this a bit if it's more than 3 seconds or so, but at
+some point we should try to think of a better way to detect this kind of thing and
+resynchronize.
+
+Different clock rates are handled very gracefully though; it will actually deal with a
+sender sending 20\% faster or slower than you expect just fine.
+
+\item Really strange network delays:  If your network "pauses" for like 5 seconds, and then
+when it restarts, you are sent some packets that are 5 seconds old, we are going to see
+that as a lot of jitter.   We already throw away up to the worst 20 frames like this,
+though, and the "maxjitterbuffer" parameter should put a limit on what we do in this case.
+
+\end{enumerate}