Mod conference
From FreeSWITCH Wiki
Contents |
General
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.
Conferences are created according to configuration within the dialplan.
Conferences created in the dialplan use profiles that are defined in conf/autoload_configs/conference.conf.xml, if you are using the standard configuration with mod_dialplan_xml.
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... 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. Below are the possible commands that can be assigned to digits and executed during a conference... NOTE: As of Oct 3 2011 (1936c2b) , there is a new "moderator-controls" parameter. See below.
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 threshold
- energy equ - reset background energy threshold
- energy dn - decrease background energy threshold
- 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
- lock - Toggle the conference locked/unlocked (no new members can enter when locked)
- event - Send the dtmf event via CUSTOM conference::maintenance subclass to the event system (even to event socket)
- transfer - transfer caller to a given extension dialplan context
- execute_application - executes a dialplan application
Reserved Group Names
- none - Use this name to prevent installing caller-controls for callers of a conference.
- default - Use this name to utilize the hard-coded set of controls built-in to mod_conference. Do NOT name a custom set of conference-controls "default" as they will be overridden with the hard-coded set. The behavior of the "default" group is defined below:
<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>
Example Configuration
<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>
Limitations
Be aware that the caller-controls are applied across the entire conference. You cannot enter one member of the conference using caller-controls ABC and then enter a second member using caller-controls XYZ.
<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 favorite 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
Note: 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 at present (January 2012). So watch this space.
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 | character -->
<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 ;-) ).
Conference 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.
| Name | Description | Example value | Played for | |
|---|---|---|---|---|
| announce-count | Requires TTS. The system will speak the total number of callers in the conference when a new person joins, but only once the threshold specified in this parameter is reached. | 5 | ??? | |
| 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. NOTE: auto-record doesn't begin recording until two parties are on the line. | Example 1: /var/myNFSshare/${conference_name}_${strftime(%Y-%m-%d-%H-%M-%S)}.wav Example 2: shout://user:pass@server.com/live.mp3 | ||
| 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 | ||
| moderator-controls | Name of the moderator 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 | ||
| cdr-log-dr | Target directory for conference CDRs to be written. Use "auto" to store in $PREFIX/log/conference-cdr. An absolute path is acceptable as is a relative path. A relative path will yield $PREFIX/log/<value> for the conference CDR directory. | auto | ||
| caller-id-name | Default Caller ID Name for outbound calls | FreeSWITCH | ||
| caller-id-number | Default Caller ID Number for outbound calls | 8777423583 | ||
| comfort-noise | Sets the volume level of background white noise to add to the conference. | 1-10000, or "true" (1400) | ||
| conference-flags | Can be any combination of wait-mod, audio-always, video-bridge and video-floor-only. wait-mod is used to force conference participants to wait (with music) for a moderator/leader to enter the conference. The moderator is determined by setting the moderator member-flag from the dialplan where the call is sent to the conference. This might be used in conjunction with an IVR where the moderators are authenticated with an extra pass-code. By default it only mix audios of members who are considered "talking", audio-always will always mix audios of all members. | wait-mod | ||
| domain | ??? | $${domain} | ||
| 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 | ||
| 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 | ||
| max-members | Sets a maximum number of participants in conferences with this profile. | 20 | ||
| member-flags | Can be any combination of: mute, deaf, mute-detect, dist-dtmf, moderator, nomoh, endconf, mintwo, waste. "moderator" should probably not be set within the XML profile, but rather from the dialplan, and should be used in combination with the wait-mod conference-flag. Endconf causes a conference to be torn down when a member with this flag leaves the conference. (If more than one member has the endconf flag set, the conference will be torn down when the last endconf member leaves.) | deaf | ||
| pin | Pin code that must be entered before user is allowed to enter the conference. | 12345 | ||
| moderator-pin | Pin code that must be entered before moderator is allowed to enter the conference. | 12345 | ||
| pin-retries | Max number of times the user or moderator can be asked for PIN | 3 | ||
| rate | Sample Rate | 8000 | ||
| sound-prefix | Set a default path here so you can use relative paths in the other sound params. | /soundfiles | ||
| suppress-events | For use with the event socket. This parameter specifies which events will NOT be sent to the socket when getting CUSTOM conference::maintenance events. | add-member | ||
| terminate-on-silence | If conference is silent for x number of seconds it will automatically terminate and disconnect all callers. | 300 | All | |
| timer-name | ??? | ??? | ||
| tts-engine | Text-To-Speech (TTS) Engine to use | cepstral | ||
| tts-voice | TTS Voice to use | david | ||
| verbose-events | Maximum verbosity for transcripting. Events related to the conference will send more data. | ??? | ||
| ack-sound | File to play to acknowledge success. | beep.wav | User | |
| alone-sound | File to play if you are alone in the conference | yactopitc.wav | User | |
| bad-pin-sound | File to play to when the pin is invalid | invalid-pin.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 | |
| 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 | |
| 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 | |
| max-members-sound | If max-members has been reached, this sound plays instead of allowing new users to the conference. | max-members.wav | ??? | |
| 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 | |
| muted-sound | File to play when member is muted. | muted.wav | User | |
| mute-detect-sound | If the mute-detect member-flag has been set, this sound plays when the user talks while muted. | mute-detect.wav | User | |
| nack-sound | File to play to acknowledge failure.
??? What is it acknowledging ??? | beeperr.wav | User | |
| perpetual-sound | the given sound file/resource will be played on a loop forever. this can be used for some backgroundmusic. | holdmusinc.mp3 | All | |
| pin-sound | Played when the user should enter the conference pin code. | pin.wav | User | |
| unmuted-sound | File to play when member is unmuted. | unmuted.wav | User | |
| ivr-dtmf-timeout | How many ms to wait between DTMF digits to match caller-controls. | 500 | ||
| ivr-input-timeout | How many ms to wait for the first DTMF, zero = forever | 0 | ||
| enconf-grace-time | Defines how much time all members have before the conference will be torn down when the last member with endconf leaves. Default = 0. | 600 |
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+[conference pin number]+flags{mute|deaf|waste|moderator}">
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+1234+flags{mute,waste} | profile is "default", multiple flags with pin |
| confname++flags{endconf|moderator} | profile is "default", no p.i.n., multiple flags (is delimiter comma or pipe???) |
| bridge:confname | a "bridging" conference |
| *Note that while some parameters are optional, their order is very important |
Or a simple example in an action tag:
<action application="conference" data="meeting@mykeys">
Bridging conference example that plays ringback while other party is bridged in:
<extension name="test_bridging_conference">
<condition field="destination_number" expression="^(3000)$">
<action application="answer"/>
<action application="playback" data="connecting_your_call.wav"/>
<action application="set" data="ringback=${us-ring}"/>
<action application="conference" data="bridge:$1-${domain_name}@default:user/1000@${domain_name}"/>
</condition>
</extension>
Adding Callers To The Conference With DTMFs
By combining several elements - the dialplan, API calls, bind_digit_action - you can create a simple system for a caller to add another user to the conference. Click here for the code and explanation.
Announcing Caller Count While In Conference
Click here for a simple example of how to allow a caller to receive an announcement of how many members are in the conference.
Application Reference
The following command structure can be used from the CLI:
conference <conf_name>[@<conf_profile_name>] conference bridge:<conf_name>[@<conf_profile_name>]|<_uuid_>:<originate_url>
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.
Event Socket Use
You can subscribe to the following to receive conference 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.
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 [{dial string options}]<endpoint_module_name>/<destination> [<callerid_number> [<callerid_name>]]
See here for the list of dial string options available: Channel Variables
If the caller id values are not set, the variables in conference.conf.xml will be used. Specifically, the value for caller-id-number will be used for the number and the value for caller-id-name will be used for the name.
According to the issue logged as MODAPP-104 last updated on June 23rd 2008: If the conference will be dynamically created as a result of this api call (ie this will be the first participant in the conference) - and the caller id name and number is not provided in the api call - the number and name will be "00000000" and "FreeSWITCH". This appears to be unaffected by the variables in conference.conf.xml.
conference testconf dial {originate_timeout=30}sofia/default/1000@softswitch 1234567890 FreeSWITCH_Conference
The above api call will dial out of a conference named "testconf" to the user located at the specified endpoint with a 30 second timeout. The endpoint will see the call as coming from "FreeSWITCH_Conference" with a caller id of 1234567890.
Also worth noting: values provided in the dial string will overwrite the callerid_number and callerid_name variables provided at the end of the api call.
conference testconf dial {origination_caller_id_name=DialStringName,originate_timeout=30}sofia/default/1000@softswitch 1234567890 FreeSWITCH_Conference
The above api call is almost the same as the previous api call, except the endpoint will see "DialStringName" as the caller id name instead of "FreeSWITCH_Conference".
dtmf
Send DTMF to any member of the conference.
Usage: conference <confname> dtmf <[member_id|all|last]> <digits>
conference foo dtmf all 134
energy
Adjusts the conference energy level for a specific member.
Usage: conference <confname> energy <member_id> [<newval>]
enter_sound
Changes the sound played while entering the conference
Usage: conference <confname> enter_sound enter_sound on|off|none|file <filename>
exit_sound
Changes the sound played while leaving the conference
Usage: conference <confname> exit_sound enter_sound on|off|none|file <filename>
get
Get runtime parameter of a given conference.
Usage: conference <confname> get <parameter_name>
Valid <parameter_name>:
- run_time (conference time, in seconds)
- count
- max_members
- rate
- profile_name
- sound_prefix
- caller_id_name
- caller_id_number
- is_locked
- endconf_grace_time (in seconds)
Output: current value of a given parameter:
- for run_time, count, max_members, rate, endconf_grace_time: a number (converted to string).
- for is_locked: string "locked" if locked or empty if not.
- for others: string value.
It can be also used in a dialplan:
<action application="set" data="conf_runtime=${conference(${conference_name} get run_time)}"/>
<action application="set" data="conf_sounddir=${conference(${conference_name} get sound_prefix)}"/>
hup
Kick without the kick sound
Usage: conference <confname> hup <[member_id|all|last]>
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>]
Output: First line
- Conference <conference name> (<member_count> member[s][ locked])
- “locked” - The lock/unlock status of the conference.
Following lines are csv separated list for each conference leg with the following items:
- id of participant(starts at 1 after FS restart)
- Register string of participant
- UUID of participants call leg
- Caller id number
- Caller id name
- Status (hear|speak|talking|video|floor)
- “hear” - The mute/unmute status of the member.
- “speak” - The “deaf /undeaf” status of the member.
- “talking” - The input channel is providing some amount of sound energy.
- “video” - Providing video?
- “floor” - This member currently owns the floor.
- Volume In
- Volume Out
- Energy Level
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>
nopin
Removes a pin for a specific conference.
Usage: conference <confname> nopin
norecord
conference foo norecord all
Or,
conference foo norecord /tmp/foo.wav
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>.
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> [<async>|<member_id>]
record
conference foo record /tmp/foo.wav
relate
Mute or Deaf a specific member to another member.
Usage: conference <confname> relate <member_id> <other_member_id> [nospeak|nohear|clear]
Examples:
conference my_conf relate 1 2 nospeak
Member 1 may now no longer speak to member 2, i.e. member 2 now cannot hear member 1.
conference my_conf relate 1 2 clear
Member 1 may now speak to member 2 again
conference my_conf relate 1 2 nohear
Member 1 now cannot hear member 2
confernce my_conf relate 1 2 clear
Member 1 can now hear member 2 again
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>
set
Set runtime parameter of a given conference.
Usage: conference <confname> set <parameter_name> <value>
Valid <parameter_name>:
- max_members
- sound_prefix
- caller_id_name
- caller_id_number
- endconf_grace_time
Output: previous value of a given parameter.
It can be also used in a dialplan:
<action application="set" data="conf_oldsound=${conference(${conference_name} set sound_prefix ${sound_prefix_pl})}"/>
<action application="set" data="void_result=${conference(${conference_name} set endconf_grace_time 300)}"/>
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 <conference_name> <member_id>
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>]
FAQ
Q: Are out-of-band DTMFs propagated to callers?
By default, out-of-band DTMFs (RFC 2833?) are absorbed by the conference. However, there are two ways to accomplish this:
- Set the dist-dtmf member flag in the conference configuration XML, eg: <param name="member-flags" value="dist-dtmf"/> With this set, all of the caller controls such as modifying voluming will be disabled and DTMF's will simply pass through to all other members of the conference.
- There is also 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, ztdummy, etc?
No.
Q: How to create a dialplan to have callers speak their name before joining the conference and announce that to other participants when they join?
<extension name="Record Name and schedule conf announce">
<condition field="destination_number" expression="^55(3\d\d\d)$">
<action application="answer"/>
<action application="set" data="namefile=/tmp/${uuid}-name.wav" inline="true"/>
<action application="sleep" data="1000"/>>
<action application="playback" data="voicemail/vm-record_name1.wav"/>
<action application="playback" data="tone_stream://%(1000,0,500)"/>
<action application="record" data="${namefile} 1"/>
<action application="playback" data="ivr/ivr-call_being_transferred.wav"/>
<action application="set" data="res=${sched_api +1 none conference $1-${domain} play file_string://${namefile}!conference/conf-has_joined.wav}"/>
<action application="transfer" data="$1 XML default"/>
</condition>
</extension>
