Mod conference

From FreeSWITCH Wiki

The mod_conference module provides multi-user conference features. You can create as many conferences as you like, as long as there still are free system resources (i.e. memory, cpu power) left.

The configuration is done in conference.conf.xml (if you are using the standard configuration with mod_dialplan_xml). The conference configuration defines how conferences behave, while the dialplan configuration defines how conferences are created.

Contents 1 Conference configuration 1.1 <advertise> 1.1.1 Example configuration 1.2 Example 'advertise' Event via mod_event_multicast 1.3 <caller-controls> 1.3.1 actions 1.3.2 Example configurations 1.4 <chat-permissions> 1.5 <profiles> 2 Dialplan configuration 2.1 Syntax 2.2 Examples 3 Sound files 4 CUSTOM events 5 Application Reference 6 API Reference 6.1 deaf 6.2 dial 6.3 energy 6.4 record 6.5 norecord 6.6 kick 6.7 list 6.8 lock 6.9 mute 6.10 play 6.11 relate 6.12 say 6.13 saymember 6.14 stop 6.15 transfer 6.16 undeaf 6.17 unlock 6.18 unmute 6.19 volume_in 6.20 volume_out 6.21 pin 6.22 nopin 7 FAQ 7.1 Q: are out-of-band DTMF's propogated to callers? 7.2 Q: Does it require hardware, kernel modules, ztdumshit, etc.?

Conference configuration

The configuration has the following structure, each "[... config here ...]" should be replaced with a configuration.

<configuration name="conference.conf" description="Audio Conference">
  <advertise>
    	[... config here ...]
  </advertise>

  <caller-controls>
    <group name="default">
    	[... config here ...]
    </group>
  </caller-controls>

  <profiles>
    <profile name="default">
    	[... config here ...]
    </profile>
  </profiles>
  <chat-permissions>
    <profile name="default>
    	[... config here ...]
    </profile>
  </chat-permissions>    
</configuration>

<advertise>

Specifies whether changes in the conference (as leaving and entering) should be advertised in the conference. The following information will be advertised to a Jabber/XMPP server.

(someone please complete this list)

• Enter - Someone entered the conference.
• Leave - someone left the conference.
• Mute - Someone muted/unmuted the conference.

Example configuration

  <advertise>
    <room name="888@$${subdomain}" status="FreeSWITCH"/>
  </advertise>

The name (888 in this case) should be the profile name that you specified in <profiles> section, $${subdomain} will be replaced with the subdomain that you specified in FreeSwitch.xml.

"status" is advertised as whatever you pass to it (identifier) or "Available" if none is passed.

Example 'advertise' Event via mod_event_multicast

proto: conf
login: 888@example.com
from: 888@example.com
status: FreeSWITCH
rpid: idle
event_type: presence
Event-Name: PRESENCE_IN
Core-UUID: c76e2d7d-39d7-dc11-93bf-0090fb0792c6
FreeSWITCH-Hostname: example.com
FreeSWITCH-IPv4: 192.168.1.5
FreeSWITCH-IPv6: 127.0.0.1
Event-Date-Local: 2008-02-09 13:04:44
Event-Date-GMT: Sat, 09 Feb 2008 18:04:44 GMT
Event-Date-timestamp: 1202580284348009
Event-Calling-File: mod_conference.c
Event-Calling-Function: send_presence
Event-Calling-Line-Number: 5037
Multicast-Sender: example.com

<caller-controls>

Caller controls are used to modify the state of the conference. It can be lowering the volume, mute the conference and such.

To force no caller-controls group to be installed for the callers of a conference, use the built-in reserved group name "none".
To be able to establish an pre-determined outbound call from the conference, using caller-controls, build a binding as follows;

actions

• mute - Turn on/off sound in the conference.
• deaf mute - performs both a mute and a deaf in one action
• energy up - increase background energy threshhold
• energy equ - reset background energy threshhold
• energy dn - decrease background energy threshhold
• vol talk up - Increase your mic volume
• vol talk zero - Change back to default setting
• vol talk dn - Decrease your mic volume
• vol listen up - Increase your speaker volume
• vol listen zero - Switch back to default setting
• vol listen dn - Decrease your speaker volume
• hangup - Leave the conference
• event - Send the dtmf event via CUSTOM conference::maintenance subclass to the event system (even to event socket)

Example configurations

  <caller-controls>
    <group name="somekeys">
      <control action="vol talk up" digits="3"/>
      <control action="vol talk zero" digits="2"/>
      <control action="vol talk dn" digits="1"/>
      <control action="hangup" digits="#"/>
    </group>
  </caller-controls>

The following caller-controls group definition replicates the built-in reserved group name "default";

   <group name="default">
    <control action="mute" digits="0"/>
    <control action="deaf mute" digits="*"/>
    <control action="energy up" digits="9"/>
    <control action="energy equ" digits="8"/>
    <control action="energy dn" digits="7"/>
    <control action="vol talk up" digits="3"/>
    <control action="vol talk zero" digits="2"/>
    <control action="vol talk dn" digits="1"/>
    <control action="vol listen up" digits="6"/>
    <control action="vol listen zero" digits="5"/>
    <control action="vol listen dn" digits="4"/>
    <control action="hangup" digits="#"/>
   </group>

<chat-permissions>

A conference can be controlled through Jabber/XMPP. This profile exists as part of the conference entity so you can have multiple profiles to limit access. When the conference publishes its presence (above) to a Jabber server, anyone on a federated server can talk to it and issue commands by typing messages via their favourite Jabber client (even if that is another FreeSWITCH™ box). To send commands to ConferenceA, from your jabber client send a message to conf+ConferenceA@freeswitch.mydomain.com

Here is an example configuration

 <configuration name="conference.conf" description="Audio Conference">
  <profiles>
   <profile name="default">
    <param name="chat-permissions" value="default"/>
   </profile>
  </profiles>
  <chat-permissions>
   <profile name="default">
    <!-- both of these users have a functionally equivalent capability set -->
    <user name="bob@somewhere.com" commands="all"/>
    <!-- individually specified commands must be book-end'ed with the | charachter -->
    <user name="harry@somewhere.com" commands="|deaf|dial|energy|kick|list|lock|mute|norecord|play|record|relate|say|saymember|stop|transfer|undeaf|unlock|unmute|volume_in|volume_out|"/>
   </profile>
  </chat-permissions>
 </configuration>

<profiles>

You can specify a number of different profiles in the profiles section, these will let you apply a number of settings to a conference. Please note that the profiles are not conference rooms, but settings applied to conference rooms. The dialplan section in this document will describe how you create conference rooms and apply these settings.

The profiles section has this structure:

  <profiles>
    <profile name="default">
      <param name="paramName" value="paramValue"/>
    </profile>
  </profiles>

You can have any number of <profile> tags, and each <profile> can have any number of <param> tags (as long as there are parameters to configure ;-) ).

Parameters

The parameters that you can specify are the ones below. Keep in mind that if TTS is enabled all audio-file params beginning with 'say:' will be considered text to say with TTS.

Whom are the sound files played for? (user / all / everybody else) please specify below

Name	Description	Example value	Played for
domain	Huh??	$${domain}
rate	Sample Rate	8000
auto-record	Put a value in for this parameter in order to toggle recording every conference call. Within mod_conference there is a special parameter named ${conference_name}. All channel variables are accessible as well.	Example 1: /var/myNFSshare/${conference_name}_${strftime(%Y-%m-%d-%H-%M-%S)}.wav Example 2: shout://user:pass@server.com/live.mp3
interval	Number of milliseconds per frame. Which may be different from ptime in SIP SDP, or driver with TDM. Higher numbers require less CPU but can cause conversation quality issues, so experimentation with your setup is best. The default is good for conversation quality.	20
energy-level	Energy level required for audio to be sent to the other users. The energy level is a threshold of 'voice energy' that must be present before audio is bridged into the conference. Useful if a participant is in a noisy environment, so you only hear background noise when they speak. 0 disables the detection and will bridge all packets even if they are only background noise.	300
member-flags	Can be any combination of delim of waste, mute, deaf. Waste will always transmit data to each channel even during silence.	deaf
caller-controls	Name of the caller control group to use for this profile. One of the ones you specified in <caller-controls>. The profile named "default" will be used if none is specified.	somekeys
tts-engine	TTS Engine to use	cepstral
tts-voice	TTS Voice to use	david
sound-prefix	Set a default path here so you can use relative paths in the other sound params	/soundfiles
ack-sound	File to play to acknowledge success.	beep.wav	User
nack-sound	File to play to acknowledge failure	beeperr.wav	User
muted-sound	File to play to acknowledge muted	muted.wav	User
unmuted-sound	File to play to acknowledge unmuted.	unmuted.wav	User
alone-sound	File to play if you are alone in the conference	yactopitc.wav	User
enter-sound	File to play when you join the conference.	welcome.wav	All
exit-sound	File to play when you leave the conference.	exit.wav	All
kicked-sound	File to play when you are kicked from the conference.	kicked.wav	User
locked-sound	File to play when the conference is locked and someone goes to join	locked.wav	All
is-locked-sound	File to play when the conference is locked during the call to the members in the conference	is-locked.wav	All
is-unlocked-sound	File to play when the conference is unlocked during the call	is-unlocked.wav	All
pin-sound	Played when the user should enter the conference pin code.	pin.wav	User
bad-pin-sound	File to play to when the pin is invalid	invalid-pin.wav	User
pin	Pin code that must be entered before user is allowed to enter the conference.	12345
caller-id-name	Default Caller ID Name for outbound calls	FreeSWITCH
caller-id-number	Default Caller ID Number for outbound calls	8777423583
perpetual-sound	the given sound file/resource will be played on a loop forever. this can be used for some backgroundmusic.	holdmusinc.mp3	All
moh-sound	the given sound file/resource will be played only when the conference size is 1 member. It will loop over and over until the conference goes to 2+ members where it will stop. When the conference goes back to 1 member it will play again.	idlemusic.mp3	All

Dialplan configuration

The dialplan configuration file is used to create conferences and to bind a profile to them.

Syntax

<action application="conference" data="confname@profilename+flags{mute|deaf}+[conference pin number]">

The first time a conference name (confname) is used, it will be created on demand, and the pin will be set to what ever is specified at that time: the pin in the data string if specified, or if not, the "pin" setting in the conference profile, and if that is also unspecified, then there is no pin protection. Any later attempt to join the conference must specify the same pin number, if one existed when it was created.

profilename should be one of those that you specified in the conference configuration.

If the data value starts with "bridge:", then it is a bridging conference. The conference name should not be already in use. You can specify the special literal value of "_uuid_" for the conference name, and a a session-specific unique id will be generated for you.

Conferences stay alive until the number of members reaches the minimum number, and then falls below that. The minimum for bridgeing conferences is 2, and for other dynamically created conferences is 1.

Examples

Action data	Description
confname	profile is "default", no flags or pin
confname+1234	profile is "default", pin is 1234
confname@profilename+1234	no flags
confname+flags{mute,waste}+1234	profile is "default", multiple flags with pin
bridge:confname	a "bridging" conference

Or a simple example in a action tag:

<action application="conference" data="meeting@mykeys">

Sound files

Just about any format is supported, but currently it must be at the sample rate of the conference (no resampling is done). Since disk is cheaper than CPU, use a wav. Asterisk ships with some useful free sound files for conferences.

CUSTOM events

 conference::maintenance

The "suppress-events" parameter can be added to the conference profile to prevent events from firing. e.g. if you're not interested in start or stop talking events:

  <profile name="default">
    ...other options...
    <param name="suppress-events" value="start-talking,stop-talking"/>
  </profile>

The events that can be suppressed are:

add-member, del-member, energy-level, volume-level, gain-level, dtmf, stop-talking, start-talking, mute-member, unmute-member, kick-member, dtmf-member, energy-level-member, volume-in-member, volume-out-member, play-file, play-file-member, speak-text, speak-text-member, lock, unlock, transfer, bgdial-result and floor-change.

Application Reference

conference <conf_name>[@<conf_profile_name>]
conference bridge:<conf_name>[@<conf_profile_name>]|<_uuid_>:<originate_url>

API Reference

deaf

Make a conference member deaf.

Usage: conference <confname> deaf <member_id>

dial

Dial a destination via a specific endpoint (ie. call mom from the conference).

Usage: conference <confname> dial <endpoint_module_name>/<destination>

energy

Adjusts the conference energy level for a specific member.

Usage: conference <confname> energy <member_id> [<newval>]

record

conference foo record /tmp/foo.wav

norecord

conference foo norecord all

or ..

conference foo norecord /tmp/foo.wav

kick

Kicks a specific member form a conference.

Usage: conference <confname> kick <member_id>

list

Lists all or a specific conference members.

Usage: conference list [delim <string>]

Usage: conference <confname> list [delim <string>]

lock

Lock a conference so no new members will be allowed to enter.

Usage: conference <confname> lock

mute

Mutes a specific member in a conference.

Usage: conference <confname> mute <member_id>

play

Play an audio file in a conference to all members or to a specific member. You can stop that same audio with the Stop command below.

Usage: conference <confname> play <file_path> [<member_id>]

relate

Mute or Deaf a specific member to another member.

Usage: conference <confname> relate <member_id> <other_member_id> [nospeak|nohear]

say

Say text in a conference to all members.

Usage: conference <confname> say <text>

saymember

Say text to a specific member in a conference.

Usage: conference <confname> saymember <member_id> <text>

stop

Stops any queued audio from playing.

Usage: conference <confname> stop <[current|all]> [<member_id>]

transfer

Transfer a member from one conference to another conference.

Usage: conference <confname> transfer <member_id> <conference_name>

To transfer a member to another extension use the api transfer command with the uuid of their session.

undeaf

Allow a specific member to hear again.

Usage: conference <confname> undeaf <member_id>

unlock

Unlock a conference so that new members can enter.

Usage: conference <confname> unlock

unmute

Unmute a specific member of a conference.

Usage: conference <confname> unmute <member_id>

volume_in

Adjusts the input volume for a specific conference member.

Usage: conference <confname> volume_in <member_id> [<newval>]

volume_out

Adjusts the output volume for a specific conference member.

Usage: conference <confname> volume_out <member_id> [<newval>]

pin

Sets or changes a pin number for a specific conference.

Usage: conference <confname> pin <pin#>

Please note that if you set a conference pin and then issue a command like

conference <confname> dial sofia/default/123456@softswitch

123456 will not be challenged with a pin, but he will just joins the conference named <confname>.

nopin

Removes a pin for a specific conference.

Usage: conference <confname> nopin

FAQ

Q: are out-of-band DTMF's propogated to callers?

No, out-of-band DTMF's (RFC2833?) are absorbed by the conference. However, there is an api call that will allow your application to send DTMF's to any conference member:

<confname> dtmf <[member_id|all|last]> <digits>

Q: Does it require hardware, kernel modules, ztdumshit, etc.?

Nope! :D You must be thinking of [1]