Fix escaping and some of the formattting (closes issue #10285)
[asterisk/asterisk.git] / doc / tex / jitterbuffer.tex
1 \subsubsection{The new jitterbuffer}
2
3 You must add "jitterbuffer=yes" to either the [general] part of 
4 iax.conf, or to a peer or a user.  (just like the old jitterbuffer).    
5 Also, you can set "maxjitterbuffer=n", which puts a hard-limit on the size of the 
6 jitterbuffer of "n milliseconds".  It is not necessary to have the new jitterbuffer 
7 on both sides of a call; it works on the receive side only.
8
9 \subsubsection{PLC}
10
11 The new jitterbuffer detects packet loss.  PLC is done to try to recreate these
12 lost packets in the codec decoding stage, as the encoded audio is translated to slinear.  
13 PLC is also used to mask jitterbuffer growth.
14
15 This facility is enabled by default in iLBC and speex, as it has no additional cost.
16 This facility can be enabled in adpcm, alaw, g726, gsm, lpc10, and ulaw by setting 
17 genericplc => true in the [plc] section of codecs.conf.
18
19 \subsubsection{Trunktimestamps}
20
21 To use this, both sides must be using Asterisk v1.2 or later.
22 Setting "trunktimestamps=yes" in iax.conf will cause your box to send 16-bit timestamps 
23 for each trunked frame inside of a trunk frame. This will enable you to use jitterbuffer
24 for an IAX2 trunk, something that was not possible in the old architecture.
25
26 The other side must also support this functionality, or else, well, bad things will happen.  
27 If you don't use trunktimestamps, there's lots of ways the jitterbuffer can get confused because 
28 timestamps aren't necessarily sent through the trunk correctly.
29
30 \subsubsection{Communication with Asterisk v1.0.x systems}
31
32 You can set up communication with v1.0.x systems with the new jitterbuffer, but
33 you can't use trunks with trunktimestamps in this communication.
34
35 If you are connecting to an Asterisk server with earlier versions of the software (1.0.x),
36 do not enable both jitterbuffer and trunking for the involved peers/users 
37 in order to be able  to communicate. Earlier systems will not support trunktimestamps.
38
39 You may also compile chan\_iax2.c without the new jitterbuffer, enabling the old 
40 backwards compatible architecture. Look in the source code for instructions.
41
42
43 \subsubsection{Testing and monitoring}
44
45 You can test the effectiveness of PLC and the new jitterbuffer's detection of loss by using 
46 the new CLI command "iax2 test losspct $<$n$>$".  This will simulate n percent packet loss 
47 coming \_in\_ to chan\_iax2. You should find that with PLC and the new JB, 10 percent packet 
48 loss should lead to just a tiny amount of distortion, while without PLC, it would lead to 
49 silent gaps in your audio.
50
51 "iax2 show netstats" shows you statistics for each iax2 call you have up.  
52 The columns are "RTT" which is the round-trip time for the last PING, and then a bunch of s
53 tats for both the local side (what you're receiving), and the remote side (what the other 
54 end is telling us they are seeing).  The remote stats may not be complete if the remote 
55 end isn't using the new jitterbuffer.
56
57 The stats shown are:
58 \begin{itemize}
59 \item Jit: The jitter we have measured (milliseconds)
60 \item Del: The maximum delay imposed by the jitterbuffer (milliseconds)
61 \item Lost: The number of packets we've detected as lost.
62 \item \%: The percentage of packets we've detected as lost recently.
63 \item Drop: The number of packets we've purposely dropped (to lower latency).
64 \item OOO: The number of packets we've received out-of-order
65 \item Kpkts: The number of packets we've received / 1000.
66 \end{itemize}
67
68 \subsubsection{Reporting problems} 
69
70 There's a couple of things that can make calls sound bad using the jitterbuffer:
71
72 \begin{enumerate}
73 \item The JB and PLC can make your calls sound better, but they can't fix everything.  
74 If you lost 10 frames in a row, it can't possibly fix that.  It really can't help much 
75 more than one or two consecutive frames.
76
77 \item Bad timestamps:  If whatever is generating timestamps to be sent to you generates 
78 nonsensical timestamps, it can confuse the jitterbuffer.  In particular, discontinuities 
79 in timestamps will really upset it:  Things like timestamps sequences which go 0, 20, 40, 
80 60, 80,  34000, 34020, 34040, 34060...   It's going to think you've got about 34 seconds 
81 of jitter in this case, etc..
82 The right solution to this is to find out what's causing the sender to send us such nonsense, 
83 and fix that.  But we should also figure out how to make the receiver more robust in 
84 cases like this.
85
86 chan\_iax2 will actually help fix this a bit if it's more than 3 seconds or so, but at 
87 some point we should try to think of a better way to detect this kind of thing and 
88 resynchronize.
89
90 Different clock rates are handled very gracefully though; it will actually deal with a 
91 sender sending 20\% faster or slower than you expect just fine.
92
93 \item Really strange network delays:  If your network "pauses" for like 5 seconds, and then 
94 when it restarts, you are sent some packets that are 5 seconds old, we are going to see 
95 that as a lot of jitter.   We already throw away up to the worst 20 frames like this, 
96 though, and the "maxjitterbuffer" parameter should put a limit on what we do in this case.
97
98 \end{enumerate}