[asterisk-dev] Configuring multistream in chan_pjsip

[Mark Michelson]

Hi folks,

For those of you following along at home, I recently published review 
https://gerrit.asterisk.org/#/c/5760/ , which is step one towards making 
chan_pjsip multistream, i.e. supporting more than one stream of a given 
media type. This initial review does not actually introduce multistream 
support so much as it just makes use of multistream structures under the 
hood to ease the transition.

Continuing on, one of the next steps we need to determine is how a user 
of chan_pjsip should configure a channel that supports multiple streams 
of a particular type.

To refresh everyone on how things currently work in pjsip.conf, you set 
an "allow" option in order to determine what codecs a particular 
endpoint supports.

[Alice]
type = endpoint
allow = ulaw,opus,h264

In the above example, the endpoint "Alice" supports the ulaw and opus 
audio codecs and the H.264 video codec. Given that information, when 
Asterisk creates an offer to Alice, Asterisk may offer at most one audio 
stream and one video stream. Most commonly, the determination of what to 
offer is based on whatever incoming call results in the call to Alice. 
So if Bob called in and only offered audio, then Asterisk would offer 
one audio stream to Alice and no video (even though Alice is configured 
to allow video). If Carol called in and offered both audio and video, 
then Asterisk would offer one audio stream and one video stream on the 
resulting outgoing call to Alice.

Consider now that Alice is an endpoint that is capable of supporting 
more than one audio or video stream. For instance, Alice may be a 
browser that can support multiple video streams being displayed at once. 
The above configuration does not convey Alice's capabilities clearly. 
Asterisk has no way of knowing how many streams Alice would prefer to 
have offered to her, and Asterisk has no idea what Alice's limitations 
are with regards to number of streams.


I propose the following configuration options to move forward.

offered_audio_streams = 1
offered_video_streams = 2

The offered_audio_streams and offered_video_streams options will 
determine how many streams Asterisk will offer to Alice when no other 
hints are available to dictate how many streams to offer. This would be 
used most commonly when originating a call to Alice from Asterisk. With 
the options specified above, Asterisk would offer one audio stream and 
two video streams when originating a call to Alice. This option would 
not be consulted if the outgoing call to Alice were the result of an 
incoming call from someone else. For instance, an incoming call from 
Carol might offer only one audio and one video stream. In that case, 
Asterisk would mirror Carol's capabilities by only offering one audio 
and one video stream in the outgoing call to Alice. To maintain behavior 
of previous versions of Asterisk, the default value for both options 
would be 1.


max_audio_streams = 1
max_video_streams = 5

The max_audio_streams and max_video_streams options will determine the 
maximum number of streams Asterisk may offer to Alice. This option would 
come into play most commonly because an application (such as ConfBridge) 
may wish to expand the number of video streams configured on an endpoint 
further and further. The option would also come into play on basic 
one-to-one calls. These options would make it so that Asterisk would not 
attempt to offer an "unreasonable" number of streams to a particular 
endpoint. Say that Bob calls into Asterisk on some crazy device that 
offers three audio streams and six video streams. Given the options 
specified above, Asterisk would only offer one audio stream and five 
video streams to Alice. The rest of Bob's offered streams would be 
rejected. To maintain behavior of previous Asterisk versions, the 
default value for both options would be 1.


minimum_audio_streams = 1
minimum_video_streams = 0

This determines the minimum number of audio and video streams that must 
be present before Asterisk will attempt a call to Alice. Let's say that 
Bob calls Alice and offers one audio and one video stream. The audio 
stream is compatible with Alice's audio codecs, but the video codecs 
offered are not compatible with Alice's video. The result is that 
Asterisk is only capable of offering one audio stream to Alice and no 
video. Should Asterisk attempt to call Alice? According to the 
configuration above, yes. If Alice had configured the 
minimum_video_streams to be 1 instead of 0, though, Asterisk would have 
rejected the incoming call from Bob instead. To maintain compatibility 
with previous versions of Asterisk, the default values for these options 
would be 1 for minimum_audio_streams and 0 for minimum_video_streams.


With these options, Asterisk can reasonably have multistream support for 
PJSIP channels. Configuration from previous Asterisk versions would 
continue to work and behave the same after an upgrade. The only 
potential downside I see is that if you wanted to be able to configure 
separate capabilities for different streams, then that is not possible 
with this configuration scheme.

What are people's thoughts on this? Got better configuration ideas? Can 
you think of something I'm not thinking of? For the time being, I'd like 
to focus on the configuration file/realtime options moreso than dialplan 
functions that would pertain to a single call. We can get to that 
discussion after this part gets settled.

Thanks,
Mark Michelson