CAF: Working With Cmc Mixers

Revision as of 12:13, 17 January 2012

Audio Mixers Definition

Audio mixers are used to mix audio from multiple call legs and provide mixed output to each call leg. At any time during a call flow the application can join call legs to one (or multiple) audio mixer.

An audio mixer is represented by an instance of the CTBCMCMixer class. Call legs ([CTBCMCLeg]) can be joined to this audio mixer as talkers, listeners, or both.

In addition to call legs joining/unjoining, the CTBCMCMixer class allows some media functions such as playing audio files or tones to all listeners of the mixer, or recording all active talkers of the mixer.

Other member functions are available to retrieve (and change in some cases) the mixer attributes, and the way different call legs are joined to the mixer (talker/listener)

It is important to note that this class is protocol-agnostic and can handle any type of supported call legs (e.g. SIP/VOIP, ISDN, SS7, Media only, etc).

todo

- Max size of mixers

Caveats

• Do not confuse the base class CTBCMCMixer with the class CTBCAFMixer. The later is an implementation class specialized to be used by the ITBCAFCallFlow interface when dealing with multiple legs and mixers.

Command Flow for Mixer Actions in CAF

All actions requested on a mixer are executed asynchronously. For each action DoSomething() on a mixer, a corresponding OnDoSomethingResponse() event will be received on the mixer once Toolpack starts processing the command. If the OnSomethingResponse() function does not handle the response (the default implementation is empty) and the result of the action was a failure, the default error handling function OnMixerError() will be called. In some cases, when the action is completed, an event will be received on the mixer (OnSomethingDone() for example).

For example, to play a digit sequence, one would call MixerPlayDigit(). It would then almost immediately receive the OnMixerPlayDigitResponse() event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start playing the digits on the mixer. Once the digits play is completed, the user will receive an OnMixerDigitPlayingDone() event.

Mixer Creation

Creating a mixer is always done through the definition of a mixer attribute. The values entered in the mixer attribute will define how the mixer behaves, and will influence resource reservation.

Preparing Mixer Attributes

The class CTBCMC_MIXER_ATTRIBUTE defines available attributes to configure an audio mixer. Default parameters are provided for standard usage, though parameters may be changed to control the behavior more precisely. Example mixer attributes are:

• Reserve IVR resource (else add it dynamically when needed)
• Reserve talker slots (else add talker slots dynamically when needed)
• Maximum number of active "loudest" speakers

Once a mixer is created, Toolpack will manage reservation of DSP resources on a TMedia, and will manage connecting legs to the mixer (listeners, or talkers). When call legs are joined or unjoined from the mixer, Toolpack will automatically re-size the DSP resource if appropriate (unless reserved talker resources have been requested, for example). And thus, the application does not have to deal with resource management distribution among TMedia units, but only make sure that the total number of talkers (or reserved talker slots) does not exceed the DSP capacity of the TMedia units.

The following code snippet shows how to build the attributes.

 PTRCTBCMC_MIXER_ATTRIBUTE ptrMixerAttribute;

 ptrMixerAttribute = tbnew CTBCMC_MIXER_ATTRIBUTE();

 ptrMixerAttribute->mfReserveIvr                  = TBX_TRUE;
 ptrMixerAttribute->mun32NbReservedActiveMembers  = 10;

Creating the Mixer

Once the mixer attributes have been filled, creating the mixer in Toolpack is only a matter of creating a CTBCMCMixer object and calling MixerCreate on it. At that moment a message is sent to Toolpack system to allocate the mixer on the hardware.

 pCallMixer = new CTBCMCMixer( 0 /* or MixerId from OnMixerSync() */, ptrMixerAttribute, this, &mLegMutex );
 pCallMixer ->MixerCreate();

Once the mixer has finished being allocated on hardware, the function OnMixerCreated() will be called.

Interaction with Mixers

Play Digit

/* this will play the sequence of digit 5551234 to all call legs listening to this mixer */
ptrMixer->MixerPlayDigit( "5551234" );

Play Event (Tone) with Signal Id String

/* this will play dtmf 7 */
CTBCMC_EVENT_ATTRIBUTE			Event;
Event.AddToneString( "dg/d7" );
ptrMixer->MixerPlayEvent( Event );

Tones can also be described in detail with frequencies, durations and repats, as described in the documentation for ([CTBCMCLeg])