Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Mixing Bridges

In a mixing bridge, Asterisk shares media between all the channels in the bridge. Depending on the attributes the bridge was created with and the types of channels in the bridge, a mixing bridge may attempt to share the media in a variety of ways. They are, in order of best performance to lowest performance:

  • Direct packet sharing between devices - when there are two channels in a mixing bridge of similar types, it may be possible to have the media bypass Asterisk completely. In this type of bridge, the channels will pass media directly between each other, and Asterisk will simply monitor the state of the channels. However, because the media is not going through Asterisk, most features - such as recording, speech detection, DTMF, etc. - are not available. The proxy_media attribute or the dtmf_events attribute will prevent this mixing type from being used.
  • Native packet sharing through Asterisk - when there are two channels in a mixing bridge of similar types, but the media cannot flow directly between the devices, Asterisk will attempt to mix the media between the channels by directly passing media from one channel to the other, and vice versa. The media itself is not decoded, and so - much like when the media is directly shared between the devices - Asterisk cannot use many features. The proxy_media attribute or the dtmf_events attribute will prevent this mixing type from being used.
Panel
titleOn This Page

Table of Contents

  • Two party mixing - when there are two channels in a mixing bridge, regardless of the channel type, Asterisk will decode the media from each channel and pass it to the other participant. This mixing technology allows for all the various features of Asterisk to be used on the channels while they are in the bridge, but does not necessarily incur any penalties from transcoding.
  • Multi-party mixing - when there are more than two channels in a mixing bridge, Asterisk will transcode the media from each participant into signed linear, mix the media from all participants together into a new media frame, then write the media back out to all participants.

At all times, the bridge will attempt to mix the media in the most performant manner possible. As the situation in the bridge changes, Asterisk will switch the mixing technology to the best mixing technology available.

What Can Happen in a Mixing Bridge

ActionBridge Response
A bridge is created using POST /bridges, and Alice's channel - which supports having media be directly sent to another device - is added to the bridge using POST /bridges/{bridge_id}/addChannel.Asterisk picks the basic two-party mixing technology. We don't know yet what other channel is going to join the bridge - it could be anything! - and so Asterisk picks the best one based on the information it currently has.
Bob's channel - which also supports having media be directly sent to another device - also joins the bridge via POST /bridges/{bridge_id}/addChannel.

We have two channels in the bridge now, so Asterisk re-evaluates how the media is mixed. Since both channels support having their media be sent directly to each other, and mixing media that way is more performant than the current mixing technology, Asterisk picks the direct media mixing technology and instructs the channels to tell their devices to send the media to each other.

Carol's channel - which is a DAHDI channel (poor Carol, calling from the PSTN) - is also added to the bridge via POST /bridges/{bridge_id}/addChannel.Since we now have three channels in the bridge, Asterisk switches the mixing technology to multi-mix. Alice and Bob's media is sent back to Asterisk, and Asterisk mixes the media from Alice, Bob, and Carol together and then sends the new media to each channel.
Eventually, Alice hangs up, leaving only Bob and Carol in the bridge.Since Alice left, Asterisk switches back to the basic two-party mixing technology. We can't use a native mixing technology, as Bob and Carol's channels are incompatible, but we can use a mixing technology that is less expensive than the multi-mix technology.

Example: Implementing a basic dial

Dialing can be implemented by using the POST - /channels operation and putting both the resulting channel and the original Stasis channel in a mixing bridge to allow media to flow between them. An endpoint should be specified along with the originate operation as well as a Stasis application name. This will cause the dialed channel to enter Stasis, where it can be added to a mixing bridge. It's also a good idea to use Stasis application arguments to flag that the dialed channel was dialed using originate in order to handle it differently from the original channel once it enters into the Stasis application.

This example ARI application will do the following:

  1. When a channel enters into the Stasis application, a call will be originated to the endpoint specified by the first command line argument to the script.
  2. When that channel enters into the Stasis application, a mixing bridge will be created and the two channels will be put in it so that media can flow between them.
  3. If either channel hangs up, the other channel will also be hung up.
  4. Once the dialed channel exists the Stasis application, the mixing bridge will be destroyed.

Dialplan

For this example, we'll use a Stasis application that species not only the application - bridge-dial - but also:

  • Whether or not the channel is inbound or a dialed channel.
  • If the channel is inbound, the endpoint to dial.

As an example, here is a dialplan that dials the PJSIP/bob endpoint:

Code Block
titleextensions.conf
exten => 1000,1,NoOp()
 same =>      n,Stasis(bridge-dial,inbound,PJSIP/bob)
 same =>      n,Hangup()

Python

 

Code Block
titlebasic-dial.py
linenumberstrue
languagepy
#!/usr/bin/env python

import logging
import requests
import ari

logging.basicConfig(level=logging.ERROR)

client = ari.connect('http://localhost:8088', 'asterisk', 'asterisk')


def safe_hangup(channel):
    """Safely hang up the specified channel"""
    try:
        print "Hanging up %s" % channel.json.get('name')
        channel.hangup()
    except requests.HTTPError as e:
        if e.response.status_code != requests.codes.not_found:
            raise e


def safe_bridge_destroy(bridge):
    """Safely destroy the specified bridge"""
    try:
        bridge.destroy()
    except requests.HTTPError as e:
        if e.response.status_code != requests.codes.not_found:
            raise e


def stasis_start_cb(channel_obj, ev):
    """Handler for StasisStart"""

    channel = channel_obj.get('channel')
    channel_name = channel.json.get('name')
    args = ev.get('args')

    if not args:
        print "Error: {} didn't provide any arguments!".format(channel_name)
        return

    if args and args[0] != 'inbound':
        # Only handle inbound channels here
        return

    if len(args) != 2:
        print "Error: {} didn't tell us who to dial".format(channel_name)
        channel.hangup()
        return

    channel.ring()

    try:
        outgoing = client.channels.originate(endpoint=args[1],
                                             app='bridge-dial',
                                             appArgs='dialed')
    except requests.HTTPError:
        print "Whoops, pretty sure %s wasn't valid" % args[1]
        channel.hangup()
        return

    channel.on_event('StasisEnd', lambda *args: safe_hangup(outgoing))
    outgoing.on_event('StasisEnd', lambda *args: safe_hangup(channel))

    def outgoing_start_cb(channel_obj, ev):
        """StasisStart handler for our dialed channel"""

        print "{} answered; bridging with {}".format(outgoing.json.get('name'),
                                                     channel.json.get('name'))
        channel.answer()

        bridge = client.bridges.create(type='mixing')
        bridge.addChannel(channel=[channel.id, outgoing.id])

        # Clean up the bridge when done
        channel.on_event('StasisEnd', lambda *args:
                         safe_bridge_destroy(bridge))
        outgoing.on_event('StasisEnd', lambda *args:
                          safe_bridge_destroy(bridge))

    outgoing.on_event('StasisStart', outgoing_start_cb)


client.on_channel_event('StasisStart', stasis_start_cb)

client.run(apps='bridge-dial')

 

JavaScript (Node.js)

This example shows how to use anonymous functions to call functions with extra parameters that would otherwise require a closer. This can be done to reduce the number of nested callbacks required to implement the flow of an application. First, we look for an application argument in our StasisStart event callback to ensure that we will only originate a call if the channel entering Stasis is a channel that dialed our application extension we defined in the extensions.conf file above. We then play a sound on the channel asking the caller to wait while they are being connected and call the originate() function to process down the application flow:

Code Block
linenumberstrue
languagejs
firstline22
function stasisStart(event, channel) {
  // ensure the channel is not a dialed channel
  var dialed = event.args[0] === 'dialed';

  if (!dialed) {
    channel.answer(function(err) {
      if (err) {
        throw err;
      }

      console.log('Channel %s has entered our application', channel.name);

      var playback = client.Playback();
      channel.play({media: 'sound:pls-wait-connect-call'},
        playback, function(err, playback) {
          if (err) {
            throw err;
          }
      });

      originate(channel);
    });
  }
}

We then prepare an object with a locally generate Id for the dialed channel and register event callbacks either channels hanging up and the dialed channel entering into the Stasis application. We then originate a call to the endpoint specified by the first command line argument to the script passing in a Stasis application argument of dialed so we can skip the dialed channel when the original StasisStart event callback fires for it:

Code Block
linenumberstrue
languagejs
firstline47
function originate(channel) {
  var dialed = client.Channel();

  channel.on('StasisEnd', function(event, channel) {
    hangupDialed(channel, dialed);
  });

  dialed.on('ChannelDestroyed', function(event, dialed) {
    hangupOriginal(channel, dialed);
  });

  dialed.on('StasisStart', function(event, dialed) {
    joinMixingBridge(channel, dialed);
  });

  dialed.originate(
    {endpoint: process.argv[2], app: 'bridge-dial', appArgs: 'dialed'},
    function(err, dialed) {
      if (err) {
        throw err;
      }
  });
}

We then handle either channel hanging up by hanging up the other channel. Note that we skip any errors that occur on hangup since it is possible that the channel we are attempting to hang up is the one that has already left and would result in an HTTP error as it is no longer a Statis channel:

Code Block
linenumberstrue
languagejs
firstline73
function hangupDialed(channel, dialed) {
  console.log(
    'Channel %s left our application, hanging up dialed channel %s',
    channel.name, dialed.name);

  // hangup the other end
  dialed.hangup(function(err) {
    // ignore error since dialed channel could have hung up, causing the
    // original channel to exit Stasis
  });
}

// handler for the dialed channel hanging up so we can gracefully hangup the
// other end
function hangupOriginal(channel, dialed) {
  console.log('Dialed channel %s has been hung up, hanging up channel %s',
    dialed.name, channel.name);

  // hangup the other end
  channel.hangup(function(err) {
    // ignore error since original channel could have hung up, causing the
    // dialed channel to exit Stasis
  });
}

We then handle the StasisStart event for the dialed channel by registered an event callback for the StasisEnd event on the dialed channel, answer that answer, creating a new mixing bridge, and finally calling a function to add the two channels to the new bridge:

Code Block
linenumberstrue
languagejs
firstline99
function joinMixingBridge(channel, dialed) {
  var bridge = client.Bridge();

  dialed.on('StasisEnd', function(event, dialed) {
    dialedExit(dialed, bridge);
  });

  dialed.answer(function(err) {
    if (err) {
      throw err;
    }
  });

  bridge.create({type: 'mixing'}, function(err, bridge) {
    if (err) {
      throw err;
    }

    console.log('Created bridge %s', bridge.id);

    addChannelsToBridge(channel, dialed, bridge);
  });
}

We then handle the dialed channel exiting the Stasis application by destroying the mixing bridge:

Code Block
linenumberstrue
languagejs
firstline124
function dialedExit(dialed, bridge) {
  console.log(
      'Dialed channel %s has left our application, destroying bridge %s',
      dialed.name, bridge.id);

  bridge.destroy(function(err) {
    if (err) {
      throw err;
    }
  });
}

Finally, the function that was called earlier by the callback handling the StasisStart event for the dialed channel adds the two channels to the mixing bridge which allows media to flow between the two channels:

Code Block
linenumberstrue
languagejs
firstline137
function addChannelsToBridge(channel, dialed, bridge) {
  console.log('Adding channel %s and dialed channel %s to bridge %s',
      channel.name, dialed.name, bridge.id);

  bridge.addChannel({channel: [channel.id, dialed.id]}, function(err) {
    if (err) {
      throw err;
    }
  });
}

bridge-dial.js

The full source code for bridge-dial.js is shown below:

Code Block
titlebridge-dial.js
linenumberstrue
languagejs
/*jshint node:true*/
'use strict';

var ari = require('ari-client');
var util = require('util');

// ensure endpoint was passed in to script
if (!process.argv[2]) {
  console.error('usage: node bridge-dial.js endpoint');
  process.exit(1);
}

ari.connect('http://localhost:8088', 'asterisk', 'asterisk', clientLoaded);

// handler for client being loaded
function clientLoaded (err, client) {
  if (err) {
    throw err;
  }

  // handler for StasisStart event
  function stasisStart(event, channel) {
    // ensure the channel is not a dialed channel
    var dialed = event.args[0] === 'dialed';

    if (!dialed) {
      channel.answer(function(err) {
        if (err) {
          throw err;
        }

        console.log('Channel %s has entered our application', channel.name);

        var playback = client.Playback();
        channel.play({media: 'sound:pls-wait-connect-call'},
          playback, function(err, playback) {
            if (err) {
              throw err;
            }
        });

        originate(channel);
      });
    }
  }

  function originate(channel) {
    var dialed = client.Channel();

    channel.on('StasisEnd', function(event, channel) {
      hangupDialed(channel, dialed);
    });

    dialed.on('ChannelDestroyed', function(event, dialed) {
      hangupOriginal(channel, dialed);
    });

    dialed.on('StasisStart', function(event, dialed) {
      joinMixingBridge(channel, dialed);
    });

    dialed.originate(
      {endpoint: process.argv[2], app: 'bridge-dial', appArgs: 'dialed'},
      function(err, dialed) {
        if (err) {
          throw err;
        }
    });
  }

  // handler for original channel hanging up so we can gracefully hangup the
  // other end
  function hangupDialed(channel, dialed) {
    console.log(
      'Channel %s left our application, hanging up dialed channel %s',
      channel.name, dialed.name);

    // hangup the other end
    dialed.hangup(function(err) {
      // ignore error since dialed channel could have hung up, causing the
      // original channel to exit Stasis
    });
  }

  // handler for the dialed channel hanging up so we can gracefully hangup the
  // other end
  function hangupOriginal(channel, dialed) {
    console.log('Dialed channel %s has been hung up, hanging up channel %s',
      dialed.name, channel.name);

    // hangup the other end
    channel.hangup(function(err) {
      // ignore error since original channel could have hung up, causing the
      // dialed channel to exit Stasis
    });
  }

  // handler for dialed channel entering Stasis
  function joinMixingBridge(channel, dialed) {
    var bridge = client.Bridge();

    dialed.on('StasisEnd', function(event, dialed) {
      dialedExit(dialed, bridge);
    });

    dialed.answer(function(err) {
      if (err) {
        throw err;
      }
    });

    bridge.create({type: 'mixing'}, function(err, bridge) {
      if (err) {
        throw err;
      }

      console.log('Created bridge %s', bridge.id);

      addChannelsToBridge(channel, dialed, bridge);
    });
  }

  // handler for the dialed channel leaving Stasis
  function dialedExit(dialed, bridge) {
    console.log(
        'Dialed channel %s has left our application, destroying bridge %s',
        dialed.name, bridge.id);

    bridge.destroy(function(err) {
      if (err) {
        throw err;
      }
    });
  }

  // handler for new mixing bridge ready for channels to be added to it
  function addChannelsToBridge(channel, dialed, bridge) {
    console.log('Adding channel %s and dialed channel %s to bridge %s',
        channel.name, dialed.name, bridge.id);

    bridge.addChannel({channel: [channel.id, dialed.id]}, function(err) {
      if (err) {
        throw err;
      }
    });
  }

  client.on('StasisStart', stasisStart);

  client.start('bridge-dial');
}

bridge-dial.js in action

The following shows the output of the bridge-dial.js script when a PJSIP channel for alice enters the application and dials a PJSIP channel for bob:

Code Block
Channel PJSIP/alice-00000001 has entered our application
Created bridge 30430e82-83ed-4242-9f37-1bc040f70724
Adding channel PJSIP/alice-00000001 and dialed channel PJSIP/bob-00000002 to bridge 30430e82-83ed-4242-9f37-1bc040f70724
Dialed channel PJSIP/bob-00000002 has left our application, destroying bridge 30430e82-83ed-4242-9f37-1bc040f70724
Dialed channel PJSIP/bob-00000002 has been hung up, hanging up channel PJSIP/alice-00000001
Channel PJSIP/alice-00000001 left our application, hanging up dialed channel undefined