[asterisk-dev] jitterbuffer documentation

[David Chappell]

Yesterday, I started experiencing bad jitter on a transatlantic IAX2 
trunk.  I again attempted to enable the IAX2 jitterbuffer, with the 
usual result that it made the problem much worse (continuous 
stuttering).  I then tried to enable the generic jitterbuffer in 
sip.conf peer entry for the phone.  This did nothing.  So, I started 
searching with Google and grepping the code in an attempt to get to the 
bottom of the matter.  After comparing the example in sip.conf.sample, 
the code in main/abstract_jb.c, some postings by Slav Klenov (the author 
of the aforementioned code), I have concluded that the comments in 
sip.conf.sample are misleading.

Here are Slav Klenov's key postings:
http://lists.digium.com/pipermail/asterisk-dev/2006-October/024225.html
http://lists.digium.com/pipermail/asterisk-dev/2006-October/024226.html

If you were to read the whole thread, you would see many users find his 
explanation surprising.  The users expect to be able to enable the 
jitterbuffer on the VoIP channel which receives jittery audio from the 
packet network so that the jitter is removed on the way in.  He tells 
them that it does not work that way, rather the jitterbuffer is enabled 
on non-VoIP channels so that the jitter will be removed on the way out.  
He explains that this scheme avoids the creation of unnecessary multiple 
jitterbuffers which would increase latency.  The users express 
frustration with what they see as a backwards scheme and with the fact 
that voicemail messages arriving over SIP will not be dejittered as they 
had expected.

The users' expectations were likely based on the following comment in 
sip.conf.sample:

> ; jbenable = yes              ; Enables the use of a jitterbuffer on 
> the receiving side of a
>                               ; SIP channel. Defaults to "no". An 
> enabled jitterbuffer will
>                               ; be used only if the sending side can 
> create and the receiving
>                               ; side can not accept jitter. The SIP 
> channel can accept jitter,
>                               ; thus a jitterbuffer on the receive SIP 
> side will be used only
>                               ; if it is forced and enabled.
>
Ask yourself, how will the user interpret the phrase "receiving side of 
a SIP channel"?  If he is editing sip.conf, he is mentally looking 
outward into the IP network, toward Asterisk's SIP peer.  He will 
interpret this explanation to mean that the stream of packets which the 
Asterisk SIP channel is receiving from the IP network will pass through 
a jitterbuffer.

I believe the person who wrote the above description was mentally 
looking _inward_ toward the bridge.  By "receiving side of a SIP 
channel" he meant the stream of packets which the Asterisk channel 
_receives_ from its bridge peer and which it _transmits_ to its SIP 
peer.  (It is likely that the problem is that this wording was 
transplanted from another context, such as an explanation of the 
jitterbuffer addressed to the writers of channel drivers.)

Dispite what the author really meant, the user has every reason to 
believe that he has interpreted the description of jbenable correctly.  
Suppose the peer definition is for a SIP telephone.  He has enabled the 
jitterbuffer on the phone.  This allows the person with the handset to 
his ear to hear dejittered audio.  If he then enables the jitter buffer 
on the Asterisk end of the SIP connection, presumably it will have an 
analogous effect: voicemail will hear dejittered audio.  Since there is 
next to no chance that the reader will adopt the author's perspective, 
the explanation should be considered incorrect.

I would be happy to submit a patch to correct the explanation of 
jbenable.  I am writing to the dev mailing list to ask whether my 
understanding is correct or not.  With that purpose in mind, could 
developers with actual knowledge of the code look over the following 
conclusions?

1) In sip.conf, jbenable=yes and jbforce=yes enable dejittering of the 
packet stream which Asterisk _transmits_ to its SIP peer.
2) In sip.conf, jbenable=yes will never _never_ actually enable a 
jitterbuffer unless jbforce=yes is also present. (A confusing result of 
the jitterbuffer being generic.)
3) In sip.conf, even jbforce=yes is not powerful enough to the guarantee 
the creation of a jitterbuffer.  For example, no
jitterbuffer will be created if the SIP channel is bridged with a Dahdi 
channel.  (I know such a jitterbuffer would be useless, but one would 
expect that forcing its creation would result in its creation.)
4) In sip.conf, even jbforce=yes will only succeed in forcing the 
creation of a jitterbuffer if the SIP channel is bridged with another 
VoIP channel (since VoIP channels may receive jittery audio).
5) As an exception to point 4, even jbforce=yes in sip.conf will not 
result in the creation of a jitterbuffer if the SIP channel is bridged 
with an IAX2 channel.  The superficial reason for this is that the IAX2 
channel claims that it never feeds jittery audio into the bridge.
6) In iax.conf, jitterbuffer=yes works in the opposite manner: it 
dejitters the audio _received_ from the IP network.

Having written this, I have an idea.  Jbenable=yes is confusing because 
it does not always enable the jitterbuffer.  Jbforce=yes is confusing 
too because it doesn't force the jitterbuffer into existence.  Instead, 
we should say _when_ to enable the jitterbuffer.  How about these settings:

jbenable = never (jbenable=no)
jbenable = ifneeded (jbenable=yes, jbforce=no)
jbenable = ifpossible (jbenable=yes, jbforce=yes)