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>
 

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 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

Name Description
none Use this name to prevent installing caller-controls for callers to a conference.
defaultThis group of settings will be assigned if no «caller-controls» is specified. You can also assign it explicitly. This group is defined in vanilla config, thus removing it from the configurations will make no caller controls at all.

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.

Action Description Min. Version
mute Toggle audio from this member into the conference
mute on Disable audio from this member into the conference
mute off Enable audio from this member into the conference
deaf mute Block audio from conference to this member as well as mute, in one action
energy up Increase minimum energy threshold by 1 unit above which sound will be admitted into conference (noise gate)
energy equ Reset minimum energy threshold to default
energy dn Decrease minimum energy threshold by 1 unit
vol talk up Increase member talk (mic) volume into conference by 1 unit
vol talk zero Reset talk volume to default setting
vol talk dn Decrease talk volume by 1 unit
vol listen up Increase member receive (earpiece) volume by 1 unit
vol listen zero Reset member receive volume to default setting
vol listen dn Decrease member receive volume by 1 unit
hangup Leave the conference
event Send the DTMF event via CUSTOM conference::maintenance subclass to the event system (even to event socket)
lock Toggle the conference lock state (no new members can enter when locked)
transfer Transfer member to a given extension in a dialplan context
execute_applicationExecute a dialplan application
floor Toggle yourself on and off of talking floor, as long as no one else has floor status.
vid-floor Video floor. If video floor is currently locked, it will revert to auto; if there is no current holder, you become video floor holder1.6
vid-floor-force Video floor. If video floor is currently locked, it will revert to auto, otherwise you become the locked video floor holder 1.6
vmute Video mute. Toggle video from this member into the conference 1.6
vmute on Disable video from this member into the conference 1.6
vmute off Enable video from this member into the conference 1.6
vmute snap Take a video snapshot for this user to be used when in vmute 1.6
vmute snapoff Discard the vmute video snapshot 1.6
    <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>
 
Be aware that the caller-controls are applied across the entire conference session. You cannot apply one group of caller-controls to one member and then a second group of caller-controls to a second member in the same conference session.

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

As of revision 3789 all commands except «list» have been disabled «until there is security»

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>
 

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.

Names Description Example value Allowed value Default value Played forMin. Version
announce-count Requires TTS. If the number of members equals or exceeds this value, the conference will speak the count to the conference after a new member joins 5 <integer> 0
auto-gain-level Enables Automatic Gain Control (AGC). If the parameter is set to 'true', then the default AGC value is used. If set to a number it will override the default value 900 <integer>true 1100
auto-record Set a filename or stream value for this parameter in order to enable recording every conference call. Within mod_conference there is a special parameter named ${conference_name} that can be used to form the record filename. All channel variables are accessible as well for generating a unique filename. NOTE: auto-record doesn't begin recording until the number of conferees specified in min-required-recording-participants have joined.
  • freeswitch/mod/mod_conference.txt
  • Последние изменения: 2020/08/19