CAF: Working With Cmc Mixers - Revision history

Allyntree at 15:08, 6 September 2022

2022-09-06T15:08:55Z

← Older revision		Revision as of 11:08, 6 September 2022
Line 1:		Line 1:
			{{DISPLAYTITLE:CAF: Working With Cmc Mixers}}
	== Audio Mixers Definition ==		== Audio Mixers Definition ==
	Audio mixers are used to mix audio from multiple call legs and provide mixed output to each call leg.		Audio mixers are used to mix audio from multiple call legs and provide a 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~~.		At any time during a call flow the application can join call legs to one (or multiple) audio mixers.

	== TMedia concepts and density ==		== TMedia concepts and density ==
Line 19:		Line 20:

	===== Caveats =====		===== Caveats =====
	* Do not confuse the base class CTBCMCMixer with the class CTBCAFMixer. The ~~later~~ is an implementation class specialized ~~to be used~~ by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs and mixers.		* Do not confuse the base class CTBCMCMixer with the class CTBCAFMixer. The CTBCAFMixer class is an implementation class specialized for use by the [https://docs.telcobridges.com/mediawiki/autodoc/class_t_b_c_a_f_1_1_i_t_b_c_a_f_call_flow.html ITBCAFCallFlow] interface when dealing with multiple legs and mixers.

	== Command Flow for Mixer Actions in CAF ==		== Command Flow for Mixer Actions in CAF ==
Line 25:		Line 26:


	For example, to play an audio file on the mixer (heard by all legs listening to this mixer), ~~one would~~ call '''MixerPlayStream()'''. It ~~would then~~ almost immediately receive the '''OnMixerPlayStreamResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start configuring the resources to play on the mixer. Once the play has started, the user will receive an event '''OnMixerStreamPlayingStarted()''', and when it finished playing (or failed to start), the user will receive an '''OnMixerStreamPlayingDone()''' event.		For example, to play an audio file on the mixer (heard by all legs listening to this mixer), you call '''MixerPlayStream()'''. It will almost immediately receive the '''OnMixerPlayStreamResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start configuring the resources to play on the mixer. Once the play has started, the user will receive an event '''OnMixerStreamPlayingStarted()''', and when it is finished playing (or failed to start), the user will receive an '''OnMixerStreamPlayingDone()''' event.

	== Mixer Creation ==		== Mixer Creation ==
Line 35:		Line 36:
	Example mixer attributes are:		Example mixer attributes are:
	* '''SetReserveListenerSlot''' / '''IsReserveListenerSlot'''		* '''SetReserveListenerSlot''' / '''IsReserveListenerSlot'''
	Choose if a 'listener-only' slot must be reserved on this mixer (allocated even when no call leg is joined as listener-only). If disabled, the listener-only slot is added dynamically upon joining of first 'listener-only' leg (note that only one listener-only slot is required if ~~more~~ there are more than one listener-only legs).<br>		Choose if a 'listener-only' slot must be reserved on this mixer (allocated even when no call leg is joined as listener-only). If disabled, the listener-only slot is added dynamically upon joining of first 'listener-only' leg (note that only one listener-only slot is required if there are more than one listener-only legs).<br>
	Default is TBX_FALSE (no listener-only slot reservation).		Default is TBX_FALSE (no listener-only slot reservation).
	* '''SetNbReservedActiveSpeakerSlots''' / '''GetNbReservedActiveSpeakerSlots'''		* '''SetNbReservedActiveSpeakerSlots''' / '''GetNbReservedActiveSpeakerSlots'''
	Choose the number of speaker slots to reserve on this mixer. The mixer will always have minimum ~~this~~ number of speaker slots ready, though it can be more if joining more than ~~that~~ number of speaker call legs.<br>		Choose the number of speaker slots to reserve on this mixer. The mixer will always have a minimum number of speaker slots ready, though it can be more if joining more than the number of speaker call legs.<br>
	Default is 0 (no reserved active speaker slot).<br>		Default is 0 (no reserved active speaker slot).<br>
	Maximum is 12 active speakers (though there can be unlimited number of "inactive speakers", waiting voice activity detection to take the place of the oldest active speaker among the 12).		Maximum is 12 active speakers (though there can be unlimited number of "inactive speakers", waiting voice activity detection to take the place of the oldest active speaker among the 12).
Line 44:		Line 45:
	Choose the delay before reducing the size of a mixer (removing unnecessary IVR or TDM slots).<br>		Choose the delay before reducing the size of a mixer (removing unnecessary IVR or TDM slots).<br>
	Smaller delay reduces MIPs usage faster, but increases the number of times mixers need to be re-sized, and thus increases CPU usage on the TMedia Unit.<br>		Smaller delay reduces MIPs usage faster, but increases the number of times mixers need to be re-sized, and thus increases CPU usage on the TMedia Unit.<br>
	~~Larger~~ delay allows, for example, ~~re-sizing~~ the mixer only once if multiple users leave the conference (un-joined from the mixer) almost at the same time.<br>		A larger delay allows, for example, resizing the mixer only once if multiple users leave the conference (un-joined from the mixer) almost at the same time.<br>
	Default is 15,000 (15 seconds).		Default is 15,000 (15 seconds).
	* '''SetNbDominantSpeakers''' / '''GetNbDominantSpeakers'''		* '''SetNbDominantSpeakers''' / '''GetNbDominantSpeakers'''
Line 67:		Line 68:
	* '''SetRecordPlayback''' / '''IsRecordPlayback'''		* '''SetRecordPlayback''' / '''IsRecordPlayback'''
	Choose if mixer recording will "hear" the mixer audio playback or not.<br>		Choose if mixer recording will "hear" the mixer audio playback or not.<br>
	Enabling this options will cause mixer to use 2 IVR slots.<br>		Enabling this options will cause the mixer to use 2 IVR slots.<br>
	Disabling this option will cause mixer to use 1 IVR slot for both play and record, but record won't include playback audio.<br>		Disabling this option will cause the mixer to use 1 IVR slot for both play and record, but record won't include playback audio.<br>
	Default is TBX_FALSE (record don't include playback, use only 1 IVR slot)		Default is TBX_FALSE (record don't include playback, use only 1 IVR slot)
	<br>		<br>
Line 76:		Line 77:
	<br>		<br>
	<br>		<br>
	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 speakers). When call legs are joined or unjoined from the mixer, Toolpack will automatically ~~re-size~~ the DSP resource if appropriate (with a minimum size determined by the 'reserve' mixer attributes).<br>		Once a mixer is created, Toolpack will manage tge reservation of DSP resources on a TMedia, and will manage connecting legs to the mixer (listeners, or speakers). When call legs are joined or unjoined from the mixer, Toolpack will automatically resize the DSP resource if appropriate (with a minimum size determined by the 'reserve' mixer attributes); the application does not have to deal with resource management distribution among TMedia units.<br>
	<br>		<br>
	~~And thus, the application does not have to deal with resource management distribution among TMedia units.<br>~~
	<br>		<br>
			For more information about the capacity of TMedia units (in regard to the number of conference "slots"), please refer to this page: [[AudioMixers#Resource_usage_of_mixers\|Audio Mixers -> Resource usage]]
	<br>		<br>
	~~For more information about capacity of TMedia units (in number of conference "slots"), please refer to this page: [[AudioMixers#Resource_usage_of_mixers\|Audio Mixers -> Resource usage]]~~
	<br>		<br>
	~~<br>~~		The following code snippet demonstrates how to build the attributes.
	The following code snippet ~~shows~~ how to build the attributes.
	PTRCTBCMC_MIXER_ATTRIBUTE ptrMixerAttribute;		PTRCTBCMC_MIXER_ATTRIBUTE ptrMixerAttribute;

Line 97:		Line 96:

	=== Creating the Mixer ===		=== 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.		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 to allocate the mixer on the hardware.

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

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


	== Mixer Termination ==		== Mixer Termination ==

	Terminating a mixer is a 2 ~~steps~~ process:		Terminating a mixer is a 2-step process:
	# Call '''MixerTerminate()'''		# Call '''MixerTerminate()'''
	# Ask for mixer object free upon '''OnMixerTerminated()''' callback function		# Ask for mixer object free upon '''OnMixerTerminated()''' callback function
Line 114:		Line 113:


	In some ~~situation~~, it is possible that mixer termination be initiated by Toolpack. This can happen in the event of sudden media resource unavailability on hardware, or if the application gets disconnected from Toolpack engine. In that cases, the callback '''OnMixerTerminated()''' is called. On reception of this event, the application should also acknowledge termination by calling '''FreeMixer()'''.		In some situations, it is possible that mixer termination be initiated by Toolpack. This can happen in the event of sudden media resource unavailability on hardware, or if the application gets disconnected from the Toolpack engine. In that cases, the callback '''OnMixerTerminated()''' is called. On reception of this event, the application should also acknowledge termination by calling '''FreeMixer()'''.

	== Mixer Synchronization on Failover ==		== Mixer Synchronization on Failover ==
Line 125:		Line 124:
	The course of action to take when receiving a leg or mixer synchronization event depends on the ability of the application to resynchronize or rebuild its own states.		The course of action to take when receiving a leg or mixer synchronization event depends on the ability of the application to resynchronize or rebuild its own states.

	A typical ~~re-synchronization~~ scenario would be similar to:		A typical resynchronization scenario would be similar to:
	* Application receives all '''OnCallLegSync()''' callbacks, for each a new object of type CTBCMCLeg is created		* Application receives all '''OnCallLegSync()''' callbacks, for each a new object of type CTBCMCLeg is created
	* Application receives all '''OnMixerSync()''' callbacks, and for each a new object of type CTBCMCMixer is created.		* Application receives all '''OnMixerSync()''' callbacks, and for each a new object of type CTBCMCMixer is created.

Abrassard: /* Preparing Mixer Attributes */

2014-04-03T14:15:06Z

Preparing Mixer Attributes

← Older revision		Revision as of 10:15, 3 April 2014
Line 34:		Line 34:
	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.		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:		Example mixer attributes are:
	* '''SetReserveIvrSlot''' / '''IsReserveIvrSlot'''
	~~Choose if a IVR slot must be reserved on this mixer (allocated even when not playing/recording). If disabled, IVR slot is add it dynamically when needed.<br>~~
	~~Default is TBX_FALSE (disabled)~~
	* '''SetReserveListenerSlot''' / '''IsReserveListenerSlot'''		* '''SetReserveListenerSlot''' / '''IsReserveListenerSlot'''
	Choose if a 'listener-only' slot must be reserved on this mixer (allocated even when no call leg is joined as listener-only). If disabled, the listener-only slot is added dynamically upon joining of first 'listener-only' leg (note that only one listener-only slot is required if more there are more than one listener-only legs).		Choose if a 'listener-only' slot must be reserved on this mixer (allocated even when no call leg is joined as listener-only). If disabled, the listener-only slot is added dynamically upon joining of first 'listener-only' leg (note that only one listener-only slot is required if more there are more than one listener-only legs).<br>
			Default is TBX_FALSE (no listener-only slot reservation).
	* '''SetNbReservedActiveSpeakerSlots''' / '''GetNbReservedActiveSpeakerSlots'''		* '''SetNbReservedActiveSpeakerSlots''' / '''GetNbReservedActiveSpeakerSlots'''
	Choose the number of speaker slots to reserve on this mixer. The mixer will always have minimum this number of speaker slots ready, though it can be more if joining more than that number of speaker call legs.		Choose the number of speaker slots to reserve on this mixer. The mixer will always have minimum this number of speaker slots ready, though it can be more if joining more than that number of speaker call legs.<br>
			Default is 0 (no reserved active speaker slot).<br>
			Maximum is 12 active speakers (though there can be unlimited number of "inactive speakers", waiting voice activity detection to take the place of the oldest active speaker among the 12).
	* '''SetResizeDownTimer''' / '''GetResizeDownTimer'''		* '''SetResizeDownTimer''' / '''GetResizeDownTimer'''
	Choose the delay before reducing the size of a mixer (removing unnecessary IVR or TDM slots).<br>		Choose the delay before reducing the size of a mixer (removing unnecessary IVR or TDM slots).<br>
	Smaller delay reduces MIPs usage faster, but increases the number of times mixers need to be re-sized, and thus increases CPU usage on the TMedia Unit.<br>		Smaller delay reduces MIPs usage faster, but increases the number of times mixers need to be re-sized, and thus increases CPU usage on the TMedia Unit.<br>
	Larger delay allows, for example, re-sizing the mixer only once if multiple users leave the conference (un-joined from the mixer) almost at the same time.		Larger delay allows, for example, re-sizing the mixer only once if multiple users leave the conference (un-joined from the mixer) almost at the same time.<br>
			Default is 15,000 (15 seconds).
	* '''SetNbDominantSpeakers''' / '''GetNbDominantSpeakers'''		* '''SetNbDominantSpeakers''' / '''GetNbDominantSpeakers'''
	Choose the maximum number of active "dominant" speakers (maximum number of audio sources mixed together at a given time, based on loudest speakers)		Choose the maximum number of active "dominant" speakers (maximum number of audio sources mixed together at a given time, based on loudest speakers).<br>
	* ~~Noise~~ floor (for ~~considering~~ inactive ~~speaker as now talking~~)		Default is 3. Max is 12.
	* ~~Noise~~ suppression limit (for removal of background noise from active speakers)		* '''SetNoiseFloor''' / '''GetNoiseFloor'''
	* ~~Target~~ power for conference output		Choose the noise floor (for voice activity of inactive speakers, before they are considered active speakers).<br>
	* ~~Loss~~ limit / ~~Gain~~ limit (limiting the audio level adjustments allowed from speaker legs to reach the target power)		Default is -30dbm. Min / max is -94dbm / 0dbm.
			* '''SetNoiseSuppressionLimit''' / '''GetNoiseSuppressionLimit'''
			Choose the noise suppression limit (for removal of background noise from active speakers).<br>
			Default is 30dbm. Min / max is 0dbm / 95dbm.
			* '''SetTargetPower''' / '''GetTargetPower'''
			Choose the target power for conference output. Conference output level will be adjusted (amplified up to GetGainLimit, dampened up to GetLossLimit) to match the target power.<br>
			Default is -5dbm. Min / max is -50dbm / 0dbm.
			* '''SetLossLimit''' / '''GetLossLimit''', and '''SetGainLimit''' / '''GetGainLimit'''
			Choose the loss limit / gain limit (limiting the audio level adjustments allowed from speaker legs to reach the target power)<br>
			Default loss limit is -10dbm. Min / max loss limit is -23dbm / 0dbm.<br>
			Default gain limit is 5dbm. Min / max gain limit is 0dbm / 23dbm.
			* '''SetReserveIvrSlot''' / '''IsReserveIvrSlot'''
			Choose if a IVR slot must be reserved on this mixer (allocated even when not playing/recording). If disabled, IVR slot is add it dynamically when needed.<br>
			Default is TBX_FALSE (no IVR slot reservation).
			* '''SetRecordPlayback''' / '''IsRecordPlayback'''
			Choose if mixer recording will "hear" the mixer audio playback or not.<br>
			Enabling this options will cause mixer to use 2 IVR slots.<br>
			Disabling this option will cause mixer to use 1 IVR slot for both play and record, but record won't include playback audio.<br>
			Default is TBX_FALSE (record don't include playback, use only 1 IVR slot)
			<br>
			<br>
			<br>
	Note: Please refer to header file '''tbcmc_mixer.hpp''' for a more complete documentation on all available mixer attributes.		Note: Please refer to header file '''tbcmc_mixer.hpp''' for a more complete documentation on all available mixer attributes.
			<br>
	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 speakers). When call legs are joined or unjoined from the mixer, Toolpack will automatically re-size the DSP resource if appropriate (with a minimum size determined by the 'reserve' mixer attributes).		<br>
	And thus, the application does not have to deal with resource management distribution among TMedia units.		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 speakers). When call legs are joined or unjoined from the mixer, Toolpack will automatically re-size the DSP resource if appropriate (with a minimum size determined by the 'reserve' mixer attributes).<br>
			<br>
			And thus, the application does not have to deal with resource management distribution among TMedia units.<br>
			<br>
			<br>
	For more information about capacity of TMedia units (in number of conference "slots"), please refer to this page: [[AudioMixers#Resource_usage_of_mixers\|Audio Mixers -> Resource usage]]		For more information about capacity of TMedia units (in number of conference "slots"), please refer to this page: [[AudioMixers#Resource_usage_of_mixers\|Audio Mixers -> Resource usage]]
			<br>
			<br>
	The following code snippet shows how to build the attributes.		The following code snippet shows how to build the attributes.
	PTRCTBCMC_MIXER_ATTRIBUTE ptrMixerAttribute;		PTRCTBCMC_MIXER_ATTRIBUTE ptrMixerAttribute;

Abrassard: Improving doc

2014-04-03T14:01:52Z

Improving doc

← Older revision		Revision as of 10:01, 3 April 2014
Line 34:		Line 34:
	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.		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:		Example mixer attributes are:
	* ~~Reserve~~ IVR ~~resource~~ (~~else~~ add it dynamically when needed)		* '''SetReserveIvrSlot''' / '''IsReserveIvrSlot'''
	* ~~Reserve~~ 'listener-only' slot (~~else~~ added dynamically upon joining of first 'listener-only' leg)		Choose if a IVR slot must be reserved on this mixer (allocated even when not playing/recording). If disabled, IVR slot is add it dynamically when needed.<br>
	* ~~Reserve~~ speaker slots (~~else add speaker~~ slots ~~dynamically when needed~~)		Default is TBX_FALSE (disabled)
	* ~~Maximum~~ number of active "dominant" speakers (maximum number of audio sources mixed together at a given time, based on loudest speakers)		* '''SetReserveListenerSlot''' / '''IsReserveListenerSlot'''
			Choose if a 'listener-only' slot must be reserved on this mixer (allocated even when no call leg is joined as listener-only). If disabled, the listener-only slot is added dynamically upon joining of first 'listener-only' leg (note that only one listener-only slot is required if more there are more than one listener-only legs).
			* '''SetNbReservedActiveSpeakerSlots''' / '''GetNbReservedActiveSpeakerSlots'''
			Choose the number of speaker slots to reserve on this mixer. The mixer will always have minimum this number of speaker slots ready, though it can be more if joining more than that number of speaker call legs.
			* '''SetResizeDownTimer''' / '''GetResizeDownTimer'''
			Choose the delay before reducing the size of a mixer (removing unnecessary IVR or TDM slots).<br>
			Smaller delay reduces MIPs usage faster, but increases the number of times mixers need to be re-sized, and thus increases CPU usage on the TMedia Unit.<br>
			Larger delay allows, for example, re-sizing the mixer only once if multiple users leave the conference (un-joined from the mixer) almost at the same time.
			* '''SetNbDominantSpeakers''' / '''GetNbDominantSpeakers'''
			Choose the maximum number of active "dominant" speakers (maximum number of audio sources mixed together at a given time, based on loudest speakers)
	* Noise floor (for considering inactive speaker as now talking)		* Noise floor (for considering inactive speaker as now talking)
	* Noise suppression limit (for removal of background noise from active speakers)		* Noise suppression limit (for removal of background noise from active speakers)

Alexandre Lussier: /* Mixer Synchronization on Failover */ change order of mixer sync

2012-08-13T14:50:22Z

Mixer Synchronization on Failover: change order of mixer sync

← Older revision		Revision as of 10:50, 13 August 2012
Line 83:		Line 83:
	When a Toolpack application is restarted, or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs, links and mixers:		When a Toolpack application is restarted, or when a standby application is activated, it goes through a synchronization phase with the Toolpack framework. During this phase, Toolpack informs the application of all the already allocated call legs, links and mixers:
	* Callback '''OnCallLegSync()''' lists all legs that were retrieved from Toolpack		* Callback '''OnCallLegSync()''' lists all legs that were retrieved from Toolpack
			* Callback '''OnMixerSync()''' lists all mixers that were retrieved from Toolpack, along with list of legs joined to each mixer.
	* Callback '''OnLinkSync()''' lists all joined leg pairs that were retrieved from Toolpack		* Callback '''OnLinkSync()''' lists all joined leg pairs that were retrieved from Toolpack
	* Callback '''OnMixerSync()''' lists all mixers that were retrieved from Toolpack, along with list of legs joined to each mixer.
	* Callback '''OnMixerLinkSync()''' lists all legs joined to mixers, and mixers joined to mixers.		* Callback '''OnMixerLinkSync()''' lists all legs joined to mixers, and mixers joined to mixers.

Line 91:		Line 91:
	A typical re-synchronization scenario would be similar to:		A typical re-synchronization scenario would be similar to:
	* Application receives all '''OnCallLegSync()''' callbacks, for each a new object of type CTBCMCLeg is created		* Application receives all '''OnCallLegSync()''' callbacks, for each a new object of type CTBCMCLeg is created
			* Application receives all '''OnMixerSync()''' callbacks, and for each a new object of type CTBCMCMixer is created.
	* Application receives all '''OnLinkSync()''' callbacks, and for each re-builds the association between the CTBCMCLeg by calling function '''SetJoined()''' of one of the legs.		* Application receives all '''OnLinkSync()''' callbacks, and for each re-builds the association between the CTBCMCLeg by calling function '''SetJoined()''' of one of the legs.
	* Application receives all '''OnMixerSync()''' callbacks, and for each a new object of type CTBCMCMixer is created.
	* Application receives all '''OnMixerLinkSync()''' callbacks, and for each re-builds the association between legs and mixers by calling function '''MixerSetJoined()'''.		* Application receives all '''OnMixerLinkSync()''' callbacks, and for each re-builds the association between legs and mixers by calling function '''MixerSetJoined()'''.
	* Any leg, link or mixer that the application does not wish to keep is destroyed ('''RefuseLeg''', '''RefuseLink''', '''RefuseMixer''', or '''RefuseMixerLink''')		* Any leg, link or mixer that the application does not wish to keep is destroyed ('''RefuseLeg''', '''RefuseLink''', '''RefuseMixer''', or '''RefuseMixerLink''')

	When all legs, links and mixers have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. Event '''OnSyncDone()''' is also called on each re-synchronized leg, and '''OnMixerSyncDone()''' on each re-synchronized mixer.		When all legs, links and mixers have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. Event '''OnSyncDone()''' is also called on each re-synchronized leg, and '''OnMixerSyncDone()''' on each re-synchronized mixer.

Abrassard: /* Preparing Mixer Attributes */

2012-06-11T16:13:31Z

Preparing Mixer Attributes

← Older revision		Revision as of 12:13, 11 June 2012
Line 58:		Line 58:
	ptrMixerAttribute->SetNbDominantSpeakers( 3 );		ptrMixerAttribute->SetNbDominantSpeakers( 3 );
	ptrMixerAttribute->SetNoiseFloor( TBCMC_VAD_NOISE_FLOOR_LEVEL_MINUS_30_DBM );		ptrMixerAttribute->SetNoiseFloor( TBCMC_VAD_NOISE_FLOOR_LEVEL_MINUS_30_DBM );
			...

	=== Creating the Mixer ===		=== Creating the Mixer ===

Abrassard: Doc revision after implementation

2012-06-11T16:13:18Z

Doc revision after implementation

← Older revision		Revision as of 12:13, 11 June 2012
Line 11:		Line 11:
	Call legs ([[CAF:_Working_With_Cmc_Call_Legs\|CTBCMCLeg]]) can be joined to this audio mixer as speakers, listeners, or both.		Call legs ([[CAF:_Working_With_Cmc_Call_Legs\|CTBCMCLeg]]) can be joined to this audio mixer as speakers, 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 speakers of the mixer.		In addition to call legs joining/unjoining, the CTBCMCMixer class allows some media functions such as playing audio files to all listeners of the mixer, or recording all active speakers 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 (speaker/listener)		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 (speaker/listener)
Line 25:		Line 25:


	For example, to play ~~a digit sequence to~~ all legs ~~in the~~ mixer, 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.		For example, to play an audio file on the mixer (heard by all legs listening to this mixer), one would call '''MixerPlayStream()'''. It would then almost immediately receive the '''OnMixerPlayStreamResponse()''' event indicating that Toolpack has received the command. At the same time this event is called, Toolpack will start configuring the resources to play on the mixer. Once the play has started, the user will receive an event '''OnMixerStreamPlayingStarted()''', and when it finished playing (or failed to start), the user will receive an '''OnMixerStreamPlayingDone()''' event.

	== Mixer Creation ==		== Mixer Creation ==
Line 35:		Line 35:
	Example mixer attributes are:		Example mixer attributes are:
	* Reserve IVR resource (else add it dynamically when needed)		* Reserve IVR resource (else add it dynamically when needed)
			* Reserve 'listener-only' slot (else added dynamically upon joining of first 'listener-only' leg)
	* Reserve speaker slots (else add speaker slots dynamically when needed)		* Reserve speaker slots (else add speaker slots dynamically when needed)
	* Maximum number of active "dominant" speakers		* Maximum number of active "dominant" speakers (maximum number of audio sources mixed together at a given time, based on loudest speakers)
			* Noise floor (for considering inactive speaker as now talking)
			* Noise suppression limit (for removal of background noise from active speakers)
			* Target power for conference output
			* Loss limit / Gain limit (limiting the audio level adjustments allowed from speaker legs to reach the target power)
	Note: Please refer to header file '''tbcmc_mixer.hpp''' for a more complete documentation on all available mixer attributes.		Note: Please refer to header file '''tbcmc_mixer.hpp''' for a more complete documentation on all available mixer attributes.

	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 speakers). When call legs are joined or unjoined from the mixer, Toolpack will automatically re-size the DSP resource if appropriate (~~unless reserved speaker resources have been requested, for example~~).		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 speakers). When call legs are joined or unjoined from the mixer, Toolpack will automatically re-size the DSP resource if appropriate (with a minimum size determined by the 'reserve' mixer attributes).
	And thus, the application does not have to deal with resource management distribution among TMedia units.		And thus, the application does not have to deal with resource management distribution among TMedia units.
	For more information about capacity of TMedia units (in number of conference "slots"), please refer to this page: [[AudioMixers#Resource_usage_of_mixers\|Audio Mixers -> Resource usage]]		For more information about capacity of TMedia units (in number of conference "slots"), please refer to this page: [[AudioMixers#Resource_usage_of_mixers\|Audio Mixers -> Resource usage]]
Line 48:		Line 53:
	ptrMixerAttribute = tbnew CTBCMC_MIXER_ATTRIBUTE();		ptrMixerAttribute = tbnew CTBCMC_MIXER_ATTRIBUTE();

	ptrMixerAttribute->~~mfReserveIvr =~~ TBX_TRUE;		ptrMixerAttribute->SetReserveIvrSlot( TBX_TRUE );
	ptrMixerAttribute->~~mun32NbReservedActiveMembers = 10~~;		ptrMixerAttribute->->SetReserveListenerSlot( TBX_FALSE );
			ptrMixerAttribute->SetNbReservedActiveSpeakerSlots( 3 );
			ptrMixerAttribute->SetNbDominantSpeakers( 3 );
			ptrMixerAttribute->SetNoiseFloor( TBCMC_VAD_NOISE_FLOOR_LEVEL_MINUS_30_DBM );

	=== Creating the Mixer ===		=== Creating the Mixer ===
Line 69:		Line 77:


	In some situation, it is possible that mixer termination be initiated by Toolpack. This can happen in the event of sudden media resource unavailability on hardware, or if the application gets disconnected from Toolpack engine. In that cases, the callback '''OnMixerTerminated()''' is called. On reception of this event, the application should acknowledge termination by calling '''FreeMixer()'''.		In some situation, it is possible that mixer termination be initiated by Toolpack. This can happen in the event of sudden media resource unavailability on hardware, or if the application gets disconnected from Toolpack engine. In that cases, the callback '''OnMixerTerminated()''' is called. On reception of this event, the application should also acknowledge termination by calling '''FreeMixer()'''.

	== Mixer Synchronization on Failover ==		== Mixer Synchronization on Failover ==
Line 76:		Line 84:
	* Callback '''OnLinkSync()''' lists all joined leg pairs that were retrieved from Toolpack		* Callback '''OnLinkSync()''' lists all joined leg pairs that were retrieved from Toolpack
	* Callback '''OnMixerSync()''' lists all mixers that were retrieved from Toolpack, along with list of legs joined to each mixer.		* Callback '''OnMixerSync()''' lists all mixers that were retrieved from Toolpack, along with list of legs joined to each mixer.
			* Callback '''OnMixerLinkSync()''' lists all legs joined to mixers, and mixers joined to mixers.

	The course of action to take when receiving a leg or mixer synchronization event depends on the ability of the application to resynchronize or rebuild its own states.		The course of action to take when receiving a leg or mixer synchronization event depends on the ability of the application to resynchronize or rebuild its own states.
Line 82:		Line 91:
	* Application receives all '''OnCallLegSync()''' callbacks, for each a new object of type CTBCMCLeg is created		* Application receives all '''OnCallLegSync()''' callbacks, for each a new object of type CTBCMCLeg is created
	* Application receives all '''OnLinkSync()''' callbacks, and for each re-builds the association between the CTBCMCLeg by calling function '''SetJoined()''' of one of the legs.		* Application receives all '''OnLinkSync()''' callbacks, and for each re-builds the association between the CTBCMCLeg by calling function '''SetJoined()''' of one of the legs.
	* Application receives all '''OnMixerSync()''' callbacks, and for each a new object of type CTBCMCMixer is created. ~~Context of each leg joined to this mixer is retrieved~~, and re-~~associated to~~ the ~~mixer using~~ function '''MixerSetJoined()''' ~~of the mixer~~		* Application receives all '''OnMixerSync()''' callbacks, and for each a new object of type CTBCMCMixer is created.
	* Any leg, link or mixer that the application does not wish to keep is destroyed ('''RefuseLeg''', '''RefuseLink''', '''RefuseMixer''')		* Application receives all '''OnMixerLinkSync()''' callbacks, and for each re-builds the association between legs and mixers by calling function '''MixerSetJoined()'''.
			* Any leg, link or mixer that the application does not wish to keep is destroyed ('''RefuseLeg''', '''RefuseLink''', '''RefuseMixer''', or '''RefuseMixerLink''')

	When all legs, links and mixers have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. Event '''OnSyncDone()''' is also called on each re-synchronized leg, and '''OnMixerSyncDone()''' on each re-synchronized mixer.		When all legs, links and mixers have been synchronized, Toolpack sends the '''OnCmcLibReady()''' event indicating that active resources synchronization is complete. Event '''OnSyncDone()''' is also called on each re-synchronized leg, and '''OnMixerSyncDone()''' on each re-synchronized mixer.

Cbilodeau: fix typo

2012-06-08T12:16:34Z

fix typo

← Older revision		Revision as of 08:16, 8 June 2012
Line 41:		Line 41:
	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 speakers). When call legs are joined or unjoined from the mixer, Toolpack will automatically re-size the DSP resource if appropriate (unless reserved speaker resources have been requested, for example).		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 speakers). When call legs are joined or unjoined from the mixer, Toolpack will automatically re-size the DSP resource if appropriate (unless reserved speaker resources have been requested, for example).
	And thus, the application does not have to deal with resource management distribution among TMedia units.		And thus, the application does not have to deal with resource management distribution among TMedia units.
	For more information about capacity of TMedia units (in number of conference "slots"), please refer to this page: [[~~http://docs.telcobridges.com/mediawiki/index.php/~~AudioMixers#Resource_usage_of_mixers Audio Mixers -> Resource usage]]		For more information about capacity of TMedia units (in number of conference "slots"), please refer to this page: [[AudioMixers#Resource_usage_of_mixers\|Audio Mixers -> Resource usage]]

	The following code snippet shows how to build the attributes.		The following code snippet shows how to build the attributes.

Abrassard at 14:34, 20 January 2012

2012-01-20T14:34:48Z

← Older revision		Revision as of 10:34, 20 January 2012
Line 37:		Line 37:
	* Reserve speaker slots (else add speaker slots dynamically when needed)		* Reserve speaker slots (else add speaker slots dynamically when needed)
	* Maximum number of active "dominant" speakers		* Maximum number of active "dominant" speakers
	Note: Please refer to header file ''tbcmc_mixer.hpp'' for a more complete documentation on all available mixer attributes.		Note: Please refer to header file '''tbcmc_mixer.hpp''' for a more complete documentation on all available mixer attributes.

	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 speakers). When call legs are joined or unjoined from the mixer, Toolpack will automatically re-size the DSP resource if appropriate (unless reserved speaker resources have been requested, for example).		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 speakers). When call legs are joined or unjoined from the mixer, Toolpack will automatically re-size the DSP resource if appropriate (unless reserved speaker resources have been requested, for example).

Abrassard at 14:32, 20 January 2012

2012-01-20T14:32:40Z

← Older revision		Revision as of 10:32, 20 January 2012
Line 52:		Line 52:

	=== Creating the Mixer ===		=== 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.		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 = new CTBCMCMixer( 0 /* or MixerId from OnMixerSync() */, ptrMixerAttribute, this, &mLegMutex );
	pCallMixer ->MixerCreate();		pCallMixer ->MixerCreate();

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


Line 63:		Line 63:

	Terminating a mixer is a 2 steps process:		Terminating a mixer is a 2 steps process:
	# Call MixerTerminate()		# Call '''MixerTerminate()'''
	# Ask for mixer object free upon OnMixerTerminated() callback function		# Ask for mixer object free upon '''OnMixerTerminated()''' callback function

	When '''MixerTerminate()''' is called, the Toolpack framework will start destroying the mixer (including unjoining any call leg that was joined to it). Once the mixer hardware resources have been deallocated, Toolpack will call '''OnMixerTerminated()'''. Receiving that event means that the mixer no more exists in Toolpack, and the object can thus be freed. Any time after '''OnMixerTerminated()''' (or within that function), the application is responsible to call method '''FreeMixer()''', which will eventually cause the mixer's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface function '''Free''' to be called. The ITBCMCFreeListener to use can be specified either in the CTBCMCMixer constructor and by calling SetFreeListener(). The mixer can be it's own ''FreeListener'', in which it just 'delete' itself. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the mixer is deleted. An example could be the case where the mixer object was allocated from a pool and it should be returned to that pool instead of being deleted.		When '''MixerTerminate()''' is called, the Toolpack framework will start destroying the mixer (including unjoining any call leg that was joined to it). Once the mixer hardware resources have been deallocated, Toolpack will call '''OnMixerTerminated()'''. Receiving that event means that the mixer no more exists in Toolpack, and the object can thus be freed. Any time after '''OnMixerTerminated()''' (or within that function), the application is responsible to call method '''FreeMixer()''', which will eventually cause the mixer's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface function '''Free''' to be called. The ITBCMCFreeListener to use can be specified either in the CTBCMCMixer constructor and by calling '''SetFreeListener()'''. The mixer can be it's own ''FreeListener'', in which it just 'delete' itself. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the mixer is deleted. An example could be the case where the mixer object was allocated from a pool and it should be returned to that pool instead of being deleted.


	In some situation, it is possible that mixer termination be initiated by Toolpack. This can happen in the event of sudden media resource unavailability on hardware. In that cases, the callback OnMixerTerminated is called. On reception of this event, the application should acknowledge termination by calling '''FreeMixer()'''.		In some situation, it is possible that mixer termination be initiated by Toolpack. This can happen in the event of sudden media resource unavailability on hardware, or if the application gets disconnected from Toolpack engine. In that cases, the callback '''OnMixerTerminated()''' is called. On reception of this event, the application should acknowledge termination by calling '''FreeMixer()'''.

	In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the OnMixerTerminated() event directly without prior call to MixerTerminate from the application. This event indicates that the mixer already no more exist on the Toolpack side and the user should free its object by calling FreeMixer() on it.

	== Mixer Synchronization on Failover ==		== Mixer Synchronization on Failover ==

Abrassard: /* Mixer Termination */

2012-01-20T14:30:13Z

Mixer Termination

← Older revision		Revision as of 10:30, 20 January 2012
Line 66:		Line 66:
	# Ask for mixer object free upon OnMixerTerminated() callback function		# Ask for mixer object free upon OnMixerTerminated() callback function

	When '''MixerTerminate()''' is called, the Toolpack framework will start destroying the mixer (including unjoining any call leg that was joined to it). Once the mixer hardware resources have been deallocated, Toolpack will call '''OnMixerTerminated()'''. Receiving that event means that the mixer no more exists in Toolpack, and the object can thus be freed. Any time after '''OnMixerTerminated()''' (or within that function), the application is responsible to call method FreeMixer, which will eventually cause the mixer's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface function 'Free' to be called. The ITBCMCFreeListener to use can be specified either in the CTBCMCMixer constructor and by calling SetFreeListener(). The mixer can be it's own ''FreeListener'', in which it just 'delete' itself. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the mixer is deleted. An example could be the case where the mixer object was allocated from a pool and it should be returned to that pool instead of being deleted.		When '''MixerTerminate()''' is called, the Toolpack framework will start destroying the mixer (including unjoining any call leg that was joined to it). Once the mixer hardware resources have been deallocated, Toolpack will call '''OnMixerTerminated()'''. Receiving that event means that the mixer no more exists in Toolpack, and the object can thus be freed. Any time after '''OnMixerTerminated()''' (or within that function), the application is responsible to call method '''FreeMixer()''', which will eventually cause the mixer's [https://docs.telcobridges.com/mediawiki/autodoc/class_i_t_b_c_m_c_free_listener.html ITBCMCFreeListener] interface function '''Free''' to be called. The ITBCMCFreeListener to use can be specified either in the CTBCMCMixer constructor and by calling SetFreeListener(). The mixer can be it's own ''FreeListener'', in which it just 'delete' itself. An application specific ''FreeListener'' can be used for cases where other action needs to be taken before the mixer is deleted. An example could be the case where the mixer object was allocated from a pool and it should be returned to that pool instead of being deleted.


	In some situation, it is possible that mixer termination be initiated by Toolpack. This can happen in the event of sudden media resource unavailability on hardware. In that cases, the callback ~~OnMixerTerminating~~ is called. On reception of this event, the application should ~~initiate~~ termination ~~as shown above~~ (~~starting with MixerTerminate, as usual~~).		In some situation, it is possible that mixer termination be initiated by Toolpack. This can happen in the event of sudden media resource unavailability on hardware. In that cases, the callback OnMixerTerminated is called. On reception of this event, the application should acknowledge termination by calling '''FreeMixer()'''.

	In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the OnMixerTerminated() event directly without prior call to MixerTerminate from the application. This event indicates that the mixer already no more exist on the Toolpack side and the user should free its object by calling FreeMixer() on it.		In case of internal system error or major communication lost with the Toolpack engine, Toolpack would send the OnMixerTerminated() event directly without prior call to MixerTerminate from the application. This event indicates that the mixer already no more exist on the Toolpack side and the user should free its object by calling FreeMixer() on it.