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.
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.
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...
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
- 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"
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 ;-) ).
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.
Whom are the sound files played for? (user / all / everybody else) please specify below
| Name | Description | Example value | Played for | |
|---|---|---|---|---|
| domain | ??? | $${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. 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 | ||
| 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 | ||
| timer-name | ??? | ??? | ||
| 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: deaf, waste, mute-detect, dist-dtmf, moderator, endconf, mintwo. Waste will always transmit data to each channel even during silence. 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 enconf flag set, the conference will be torn down when the last endconf member leaves.) | deaf | ||
| conference-flags | Currently, the only option here is wait-mod. This can be 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. | wait-mod | ||
| 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 | Text-To-Speech (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.
??? What is it acknowledging ??? | beep.wav | User | |
| nack-sound | File to play to acknowledge failure.
??? What is it acknowledging ??? | beeperr.wav | User | |
| 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 instead of the regular muted-sound when the user gets muted. | mute-detect.wav | User | |
| max-members | Sets a maximum number of participants in conferences with this profile. | 20 | ||
| max-members-sound | If max-members has been reached, this sound plays instead of allowing new users to the conference. | max-members.wav | ??? | |
| comfort-noise | Sets the volume level of background white noise to add to the conference. | 1420 | ||
| 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 | ??? | |
| 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 | ||
| verbose-events | Maximum verbosity for transcripting. Events related to the conference will send more data. | ??? | ||
| unmuted-sound | File to play when member is 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 | |
| terminate_on_silence | If conference is silent for x number of seconds it will automatically terminate and disconnect all callers. | 300 | 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|waste|moderator}+[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+1234+flags{mute,waste} | profile is "default", multiple flags with pin |
| bridge:confname | a "bridging" conference |
| *Note that while some parameters are optional, their order is very important |
Or a simple example in a 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>
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>]
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>]
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>
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 <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>]
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 propagated to callers?
By default, out-of-band DTMF's (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.
