Freeswitch: mod_conference

mod_conference provides both inbound and outbound conference bridge service for macro. It can process multiple bit rates, load various profiles that specify DTMF controls, play prompt sounds and tones, and many other functions. You can create as many conferences as you like, as long as there still are free system resources (i.e. memory, CPU power, network bandwidth) available.

Conferences created in the dialplan use profiles that are defined in conf/autoload_configs/conference.conf.xml, if you are using the standard configuration files.

Conference Configuration

Conference configuration settings are stored in conf/autoload_configs/conference.conf.xml

Community member Stanislav Sinyagin has posted a nice personal blog entry on how he configured his conference bridge.

The configuration has the following structure, each «[... config here ...]» should be replaced with specific configuration statements as detailed in the sections that follow.

 <configuration name="conference.conf" description="Standard Conference configuration">
 
   <advertise>
         [... config here ...]
   </advertise>
 
   <caller-controls>
     <group name="default">
         [... config here ...]
     </group>
   </caller-controls>
 
   <chat-permissions>
     <profile name="default">
         [... config here ...]
     </profile>
   </chat-permissions>    
 
   <profiles>
     <profile name="default">
         [... config here ...]
     </profile>
   </profiles>
 
 
 </configuration>
 

advertise

This block specifies whether empty conferences should be advertised in presence, allowing you to see status of empty conferences. Any endpoint that supports presence, such as mod_sofia, can subscribe to these presence notifications.

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

The conference 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, such as lowering the volume, mute a participant, and such. Below are the commands that can be assigned to digits and executed during a conference. The «moderator-controls» group provides additional controls for participants who enter the conference with the moderator flag set. See below.

Reserved Control Group Names

Actions

Each of these actions can be configured in caller-controls to be invoked by a conference member who enters the conference with this caller-controls group. These are instances of the conference API.

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

   <caller-controls>
     <group name="somekeys">
       <control action="vol talk dn"         digits="1"/>
       <control action="vol talk zero"       digits="2"/>
       <control action="vol talk up"         digits="3"/>
       <control action="transfer"            digits="5"   data="100 XML default"/>
       <control action="execute_application" digits="0"   data="playback conf_help.wav"/>
       <control action="execute_application" digits="#"   data="execute_dialplan conference-menu"/>
     </group>
   </caller-controls>
 

chat-permissions

The FreeSWITCH conference also provides limited chat capabilities via SIP, XMPP, and Verto.

A conference can be controlled through chat. This profile exists as part of the conference entity so you can have multiple profiles to limit access. When the conference advertises its presence (above) to a chat server, anyone on a federated server can talk to it and issue commands by typing messages via their favorite chat 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

Another Note: After spending much time trying to get control of mod_conference via Openfire XMPP server, asked around, and «bougyman» suggested that XMPP muc functionality is very limited as of January 2012.

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 enclosed with the | (pipe) character -->
     <user name="harry@elsewhere.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 easily apply a number of settings to a conference. Please note that the profiles are not conference rooms, but define settings that are later applied to conference rooms. The dialplan section in this document will describe how you create conference rooms and apply these profile settings.

   <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 up to the entire set of parameters.

Conference Profile Parameters

You may specify the conference profile parameters listed below. Keep in mind that if TTS is enabled all audio-file params beginning with 'say:' will be considered text to say with TTS. A TTS module must be loaded by FreeSWITCH for this to work.