Add documentation explaining PLC in Asterisk.
[asterisk/asterisk.git] / doc / tex / plc.tex
1 \section{What is PLC?}
2
3         PLC stands for Packet Loss Concealment. PLC describes any method of generating
4 new audio data when packet loss is detected. In Asterisk, there are two main flavors
5 of PLC, generic and native. Generic PLC is a method of generating audio data on
6 signed linear audio streams. Signed linear audio, often abbreviated "slin," is required
7 since it is a raw format that has no companding, compression, or other transformations
8 applied. Native PLC is used by specific codec implementations, such as
9 iLBC and Speex, which generates the new audio in the codec's native format. Native
10 PLC happens automatically when using a codec that supports native PLC. Generic PLC
11 requires specific configuration options to be used and will be the focus of this
12 document.
13
14 \section{How does Asterisk detect packet loss?}
15
16         Oddly, Asterisk does not detect packet loss when reading audio in. In order to
17 detect packet loss, one must have a jitter buffer in use on the channel on which
18 Asterisk is going to write missing audio using PLC. When a jitter buffer is in use,
19 audio that is to be written to the channel is fed into the jitterbuffer. When the
20 time comes to write audio to the channel, a bridge will request that the jitter
21 buffer gives a frame of audio to the bridge so that the audio may be written. If
22 audio is requested from the jitter buffer but the jitter buffer is unable to give
23 enough audio to the bridge, then the jitter buffer will return an interpolation
24 frame. This frame contains no actual audio data and indicates the number of samples
25 of audio that should be inserted into the frame.
26
27 \section{A bit of background on translation}
28
29         As stated in the introduction, generic PLC can only be used on slin audio.
30 The majority of audio communication is not done in slin, but rather using lower
31 bandwidth codecs. This means that for PLC to be used, there must be a translation
32 step involving slin on the write path of a channel. This means that PLC cannot
33 be used if the codecs on either side of the bridge are the same or do not require
34 a translation to slin in order to translate between them. For instance, a
35 ulaw $<$-$>$ ulaw call will not use PLC since no translation is required. In addition,
36 a ulaw $<$-$>$ alaw call will also not use PLC since the translation path does not
37 include any step involving slin.
38         One item of note is that slin must be present on the write path of a channel
39 since that is the path where PLC is applied. Consider that Asterisk is bridging
40 channels A and B. A uses ulaw for audio and B uses GSM. This translation involves
41 slin, so things are shaping up well for PLC. Consider, however if Asterisk sets
42 up the translation paths like so:
43 \begin{verbatim}
44
45                     Fig. 1
46
47 A                      +------------+       B
48 <---ulaw<---slin<---GSM|            |GSM--->
49                        |  Asterisk  |
50 ulaw--->slin--->GSM--->|            |<---GSM
51                        +------------+
52
53 \end{verbatim}
54         The arrows indicate the direction of audio flow. Each channel has a write
55 path (the top arrow) and a read path (the bottom arrow). In this setup, PLC
56 can be used when sending audio to A, but it cannot be used when sending audio
57 to B. The reason is simple, the write path to A's channel contains a slin
58 step, but the write path to B contains no slin step. Such a translation setup
59 is perfectly valid, and Asterisk can potentially set up such a path depending
60 on circumstances. When we use PLC, however, we want slin audio to be present
61 on the write paths of both A and B. A visual representation of what we want
62 is the following:
63 \begin{verbatim}
64
65                     Fig. 2
66
67 A               +------------+               B
68 <---ulaw<---slin|            |slin--->GSM--->
69                 |  Asterisk  |
70 ulaw--->slin--->|            |<---slin<---GSM
71                 +------------+
72
73 \end{verbatim}
74         In this scenario, the write paths for both A and B begin with slin,
75 and so PLC may be applied to either channel. This translation behavior has,
76 in the past been doable with the \texttt{transcode\_via\_sln} option in \path{asterisk.conf}.
77 Recent changes to the PLC code have also made the \texttt{genericplc} option in
78 \path{codecs.conf} imply the \texttt{transcode\_via\_sln} option. The result is that by
79 enabling \texttt{genericplc} in \path{codecs.conf}, the translation path set up in
80 Fig. 2 should automatically be used.
81
82 \section{Additional restrictions and caveats}
83
84         One restriction that has not been spelled out so far but that has been
85 hinted at is the presence of a bridge. The term bridge in this sense means
86 two channels exchanging audio with one another. A bridge is required because
87 use of a jitter buffer is a prerequisite for using PLC, and a jitter buffer
88 is only used when bridging two channels. This means that one-legged calls,
89 (e.g. calls to voicemail, to an IVR, to an extension that just plays back
90 audio) will not use PLC. In addition, MeetMe and ConfBridge calls will not
91 use PLC.
92         It should be obvious, but it bears mentioning, that PLC cannot be used
93 when using a technology's native bridging functionality. For instance, if
94 two SIP channels can exchange RTP directly, then Asterisk will never be
95 able to process the audio in the first place. Since translation of audio
96 is a requirement for using PLC, and translation will not allow for a
97 native bridge to be created, this is something that is not likely to be
98 an issue, though.
99         Since a jitter buffer is a requirement in order to use PLC, it should
100 be noted that simply enabling the jitter buffer via the \texttt{jbenable} option
101 may not be enough. For instance, if bridging two SIP channels together,
102 the default behavior will not be to enable jitter buffers on either channel.
103 The rationale is that the jitter will be handled at the endpoints to which
104 Asterisk is sending the audio. In order to ensure that a jitter buffer is
105 used in all cases, one must enable the \texttt{jbforce} option for channel types
106 on which PLC is desired.
107
108 \section{Summary}
109         The following are all required for PLC to be used:
110 \begin{itemize}
111 \item Enable \texttt{genericplc} in the \texttt{plc} section of \path{codecs.conf}
112 \item Enable (and potentially force) jitter buffers on channels
113 \item Two channels must be bridged together for PLC to be used
114 (no Meetme or one-legged calls)
115 \item The audio must be translated between the two channels
116 and must have slin as a step in the translation process.
117 \end{itemize}
118
119 \section{Protip}
120
121         One of the restrictions mentioned is that PLC will only
122 be used when two audio channels are bridged together. Through the
123 use of Local channels, you can create a bridge even if the call
124 is, for all intents and purposes, one-legged. By using a combination
125 of the /n and /j suffixes for a Local channel, one can ensure
126 that the Local channel is not optimized out of the talk path
127 and that a jitter buffer is applied to the Local channel as well.
128 Consider the following simple dialplan:
129 \begin{verbatim}
130
131 [example]
132 exten => 1,1,Playback(tt-weasels)
133 exten => 2,1,Dial(Local/1@example/nj)
134
135 \end{verbatim}
136 When dialing extension 1, PLC cannot be used because there
137 will be only a single channel involved. When dialing extension
138 2, however, Asterisk will create a bridge between the incoming
139 channel and the Local channel, thus allowing PLC to be used.