《FreeSWITCH参考手册》

1.7 mod_conference

FreeSWITCH支持多人电话会议，该功能是由mod_conference模块实现的。

mod_conference是实现了一个conferenceApp和API。在默认的配置中，直接拨打3000就可以进入一个会议。

从下列Dialplan可以看出，它使用conference App将来话送入一个会议：

<extension name="nb_conferences">
    <condition field="destination_number" expression="^(30\d{2})$">
         <action application="answer"/>
         <action application="conference" data="$1-${domain_name}@default"/>
    </condition>
</extension>

其中，conference App的参数是一个会议的名称和一个会议的Profile，它们之间是以@分隔的。domain_name一般是一个IP地址，所以，假设我们呼叫的是3000，FreeSWITCH的IP地址是192.168.1.2的话，将上述参数进行变量替换后，结果是：3000-192.168.1.2@default。

@前面的就是会议的名称，后面的default是会议的一个Profile。

会议的Profile定义了会议的一些特性，如各种提示音等。

为了简单起见，我们以3000作为会议的名称，修改Dialplan如下：

     <action application="conference" data=“3000@default"/>

这个，拨打3000就可以进入3000这个会议（室）。通过conference API命令，可以对会议执行一系列的操作，如下列命令将全部人员静音

conference 3000 mute all

取消静音：

conference 3000 unmute all

其中，会议中的每一路参与的电话称作一个成员（member），以member_id来标识，使用下列命令可以列出会议中所有的成员，进而知道成员的member_id：

conference 3000 list

得到了成员的member_id后，便可以对成员进行单独操作，如以下命令仅对member_id为2的成员静音：

conference 3000 mute 2

或将它踢出会议

conference 3000 kick 2

当然，该命令的参数还有很多，具体的可输入不带参数的conference命令查看帮助。

conference

除语音会议外，FreeSWITCH也支持视频会议。1.4版以前的FreeSWITCH不支持视频的转码，因而仅支持主持人式的视频会议。具体的讲，所有与会成员中会有一个成员会获得一个video floor，持有该floor的人的视频会广播到其它所有成员的终端上，即，所有成员都会看到该成员的视频。在默认情况下，floor的持有和转换是通过声音激励的方式实现的，即，通过一点的算法，根据当前声音的能量值来决定谁持有floor，一般来说是当前说话的成员持有该floor，即谁说话看谁。

自1.6版开始，FreeSWITCH支持视频转码和视频会议，我们以后再讲。

以下部分内容来自鼎鼎：cdevelop@qq.com qq:1280791187。

Todo: 格式待整理优化。

本文英文部分是来自https://freeswitch.org/confluence/display/FREESWITCH/mod_conference，中文部分是通过分析mod_conference的代码根据个人的理解整理而成。

1.7.1 配置

1.7.1.1 conference.conf.xml 范例

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

1.7.1.2 advertise

<advertise>
    <room name="3001@$${domain}" status="FreeSWITCH"/>
</advertise>

添加room配置后，模块load时，会发送SWITCH_EVENT_PRESENCE_IN事件。详细参考下面实现代码：

if ((advertise = switch_xml_child(cfg, "advertise"))) {
    for (room = switch_xml_child(advertise, "room"); room; room = room->next) {
        char *name = (char *) switch_xml_attr_soft(room, "name");
        char *status = (char *) switch_xml_attr_soft(room, "status");
        switch_event_t *event;

        if (name && switch_event_create(&event, id) == SWITCH_STATUS_SUCCESS) {
            switch_event_add_header_string(event, SWITCH_STACK_BOTTOM, "proto", CONF_CHAT_PROTO);
            switch_event_add_header_string(event, SWITCH_STACK_BOTTOM, "login", name);
            switch_event_add_header_string(event, SWITCH_STACK_BOTTOM, "from", name);
            switch_event_add_header_string(event, SWITCH_STACK_BOTTOM, "force-status", status ? status : "Available");
            switch_event_add_header_string(event, SWITCH_STACK_BOTTOM, "rpid", "unknown");
            switch_event_add_header_string(event, SWITCH_STACK_BOTTOM, "event_type", "presence");
            switch_event_fire(&event);
        }
    }
}

1.7.1.3 caller-controls

配置会议控制按键，profile通过<param name="caller-controls" value="none"/>设置管理的caller-controls。none就是不使用控制按键，不设置时会使用default组。

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.
default	This 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.

例子：

    <caller-controls>
    <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>
    </caller-controls>

详细配置

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).按一下噪音阈值加200，最大1800，声音只有大于这个阈值才会送到会议其他成员。
energy equ	Reset minimum energy threshold to default. 噪音阈值恢复默认值。
energy dn	Decrease minimum energy threshold by 1 unit.按一下噪音阈值减少200，最小0
vol talk up	Increase member talk (mic) volume into conference by 1 unit，按一下把说话声音放大1个等级，最大可以放大4个等级，对应 {1.3, 2.3, 3.3, 4.3} 这些倍数。
vol talk zero	Reset talk volume to default setting. 取消说话声音增溢
vol talk dn	Decrease talk volume by 1 unit.，按一下把说话声音降低1个等级，最大可以降低4个等级，对应 {.80, .60, .40, .20}这些倍数。
vol listen up	Increase member receive (earpiece) volume by 1 unit.同vol talk up一样，只是修改是听到的声音
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).触发esl事件
lock	Toggle the conference lock state (no new members can enter when locked).切换会议锁定状态，锁定时会议不能加入新成员
transfer	Transfer member to a given extension in a dialplan context.例子： `<control action="transfer" digits="5" data="100 XML default"/>`，离开会议并转到指定上下文。
execute_application	Execute a dialplan application.例子:`<control action="execute_application" digits="0" data="playback conf_help.wav"/>`,执行一个APP，APP执行完成后会返回到会议。
floor	Toggle yourself on and off of talking floor, as long as no one else has floor status. floor标记的意思是会议当前的说话人，一个会议只有一个成员拥有floor标记，会议会自动设置。我看代码的逻辑是，按钮的用处是如果一个成员拥有floor标记，执行按键后，会取消floor标记。如果会议中没有成员有floor标记，就给按键的成员设置floor标记，不会实际测试时并不想预期的这样，系统会自动修改floor标记的。
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 holder	1.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

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

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

You can have any number of tags, and each can have any number of 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.

Name	Description	Example value	Allowed value	Default value	Played for	Min. 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. 需要TTS支持，大于几人时播报会议总人数。	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. 启用自动增益控制（AGC）。如果参数设置为“true”，则使用默认的AGC值。如果设置为数字，它将覆盖默认值	900	<integer> or true	1100

1.7.2 FreeSWITCH会议指南

参考资料 https://freeswitch.org/confluence/display/FREESWITCH/mod_conference

1.7.3 conference基础部分

1.7.3.1 查询已经存在的会议

```
conference <conf name> list [delim <string>]|[count]
conference <conf name> xml_list
```

1.7.3.2 邀请用户加入会议

API bgapi originate user/1003 &conference(test@default)。呼叫分机1003，分机应答后加入会议test.会议名字字母数字都可以。FreeSWITCH会自动创建会议。
API conference <confname> bgdial <dial-string> [<callerid_number> [<callerid_name>]]。例子:conference 8000@default bgdial user/1003 8000 conference，呼叫分机1003加入会议，分机1003的来电显示为conference<1003>。

1.7.3.2.1 成员加入会议标志

例子confname++flags{endconf|moderator}.

mute (静音)Enter conference muted
deaf （不听会议声音）Enter conference deafed (can not hear conference); will also mute the mic
mute-detect (成员静音时说话播放提示)Play the mute_detect_sound when talking detected by this conferee while *muted
dist-dtmf Send any DTMF from this member to all participants
moderator （主席）Flag member as a moderator
nomoh （只有一个成员时不播放背景音乐）Disable music on hold when this member is the only member in the conference
endconf Ends conference when all members with this flag leave the conference after profile param endconf-grace-time has expired
mintwo End conference when it drops below 2 participants after a member enters with this flag
ghost Do not count member in conference tally
join-only （只允许加入已经存在的会议）Only allow joining a conference that already exists
positional Process this member for positional audio on stereo outputs 1.4
no-positional Do not process this member for positional audio on stereo outputs 1.4
join-vid-floor Locks member as the video floor holder 1.6
no-minimize-encoding Bypass the video transcode minimizer and encode the video individually for this member 1.6
vmute Enter conference video muted 1.6
second-screen Open a ‘view only’ connection to the conference, without impacting the conference count or data. 1.6

1.7.3.3 剔出成员

1.7.3.4 会议密码

呼出的通话加入会议，默认不需要密码。如果要禁用这个特性,需要设置通道变量conference_enforce_security为true。
会议密码(pin),可以在配置文件中设置，也可以在APP参数中指定密码，也可以通过API来设置密码，APP参数中指定的密码具有最高优先级。

1.7.3.4.1 APP中设置密码

<action application="conference" data="confname@profilename+pin">

1.7.3.4.2 API设置密码

设置成员密码

conference <confname> pin <pin-number>

设置主席密码

conference <confname> pin mod <pin-number>

清除密码

conference <confname> nopin

1.7.3.4.3 配置文件设置密码

    <profiles>
        <profile name="default">
            <param name="pin" value="12345"/>
            <param name="moderator-pin" value="54321"/>
        </profile>
    </profiles>

1.7.3.4.4 通道变量设置密码

通道变量·conference_moderator_pin·设置主席密码。

1.7.3.4.5 通道变量验证密码

通道变量supplied_pin=X-ConfPin=pin,可以用来验证密码。

1.7.3.5 会议录音

通过API，或者配置来对会议进行录音。 ##### API控制会议录音多次执行录音命令，可以录音到多个文件。record对应recording start，norecord对应recording stop，chkrecord对应recording check，pause对应recording pause，resume对应recording resume它们功能完全一样。

    conference <confname> record <file-path>
    conference <confname> norecord <file-path>|all
    conference <confname> resume <file-path>
    conference <confname> chkrecord
    conference <confname> pause <file-path>

    conference <confname> recording start <file-path>
    conference <confname> recording check
    conference <confname> recording stop <file-path>|all
    conference <confname> recording pause <file-path>
    conference <confname> recording resume <file-path>

1.7.3.5.1 配置会议录音

    <param name="auto-record" value="$${recordings_dir}/${conference_name}_${strftime(%Y-%m-%d-%H-%M-%S)}.wav"/>

1.7.3.6 对会议进行放音

例子 conference 8000 play test.wav

    conference <confname> play [{vol=<volume>,full-screen=true,png_ms=100}]<file-path> [async|<member_id> [nomux]]
    conference <confname> play_status [<member_id>]
    conference <confname> pause_play [<member_id>]
    conference <confname> stop [current|all|async|last]> [<member_id>]
    conference <confname> file_seek [+|-]<val>
    conference <confname> file-vol <val> [async]

1.7.3.7 会议提示音

就是会议成员加入，离开等提示音。 ##### API设置提示音

    conference <confname> enter_sound on|off|none|file <filename>
    conference <confname> exit_sound on|off|none|file <filename>

1.7.3.7.1 配置文件设置提示音

     <!-- <param name="sound-prefix" value="$${sounds_dir}/en/us/callie"/> -->
     <param name="muted-sound" value="conference/conf-muted.wav"/>
     <param name="unmuted-sound" value="conference/conf-unmuted.wav"/>
     <param name="alone-sound" value="conference/conf-alone.wav"/>
     <param name="moh-sound" value="$${hold_music}"/>
     <param name="enter-sound" value="tone_stream://%(200,0,500,600,700)"/>
     <param name="exit-sound" value="tone_stream://%(500,0,300,200,100,50,25)"/>
     <param name="kicked-sound" value="conference/conf-kicked.wav"/>
     <param name="locked-sound" value="conference/conf-locked.wav"/>
     <param name="is-locked-sound" value="conference/conf-is-locked.wav"/>
     <param name="is-unlocked-sound" value="conference/conf-is-unlocked.wav"/>
     <param name="pin-sound" value="conference/conf-pin.wav"/>
     <param name="bad-pin-sound" value="conference/conf-bad-pin.wav"/>

1.7.3.8 会议加锁

    conference <confname> lock
    conference <confname> unlock

1.7.3.9 会议静音

    conference <confname> mute <member_id>|all|last|non_moderator [quiet]
    conference <confname> tmute <member_id>|all|last|non_moderator [quiet]
    conference <confname> unmute <member_id>|all|last|non_moderator [quiet]

1.7.3.10 只说模式

    conference <confname> deaf <member_id>|all|last|non_moderator
    conference <confname> undeaf <member_id>|all|last|non_moderator

1.7.3.11 桥接会议

桥接会议，就是连接2会议。

    <action application="conference" data="bridge:confname[@profile]:none|endpoint[+flags{mute|deaf|...}]">

1.7.3.12 事件

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

energy-level Conference default energy level changed
gain-level Conference default gain level changed
volume-level Conference default volume level changed
floor-change Conference floor changed
lock Conference locked, no one else can enter
record Conference recording started or stopped
unlock Conference unlocked
play-file-done Conference–level play file ended
play-file Conference–level play file started
mute-detect Detected member speaking (as detected by energy level) while muted
dtmf-member Key bound to DTMF is hit by member
dtmf Key bound to transfer, event, or execute_application is hit by member
add-member Member added to a conference
mute-member Member became muted
unmute-member Member became unmuted
energy-level-member Member energy level changed
volume-in-member Member gain level changed
kick-member Member kicked
del-member
Member removed from a conference
start-talking Member started talking (as detected by energy level)
stop-talking Member stopped talking (as detected by energy level)
transfer Member transferred to another conference
volume-out-member Member volume level changed
play-file-member Member–level play file started
bgdial-result Result from bgdial API command

1.7.3.13 DTMF按键控制(caller-controls)

配置会议控制按键，profile通过<param name="caller-controls" value="none"/>设置管理的caller-controls。none就是不使用控制按键，不设置时会使用default组。

Name	Description
none	Use this name to prevent installing caller-controls for callers to a conference.
default	This 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.

例子：

      <caller-controls>
        <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>
      </caller-controls>

详细配置

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).按一下噪音阈值加200，最大1800，声音只有大于这个阈值才会送到会议其他成员。
energy equ	Reset minimum energy threshold to default. 噪音阈值恢复默认值。
energy dn	Decrease minimum energy threshold by 1 unit.按一下噪音阈值减少200，最小0
vol talk up	Increase member talk (mic) volume into conference by 1 unit，按一下把说话声音放大1个等级，最大可以放大4个等级，对应 {1.3, 2.3, 3.3, 4.3} 这些倍数。
vol talk zero	Reset talk volume to default setting. 取消说话声音增溢
vol talk dn	Decrease talk volume by 1 unit.，按一下把说话声音降低1个等级，最大可以降低4个等级，对应 {.80, .60, .40, .20}这些倍数。
vol listen up	Increase member receive (earpiece) volume by 1 unit.同vol talk up一样，只是修改是听到的声音
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).触发esl事件
lock	Toggle the conference lock state (no new members can enter when locked).切换会议锁定状态，锁定时会议不能加入新成员
transfer	Transfer member to a given extension in a dialplan context.例子： `<control action="transfer" digits="5" data="100 XML default"/>`，离开会议并转到指定上下文。
execute_application	Execute a dialplan application.例子:`<control action="execute_application" digits="0" data="playback conf_help.wav"/>`,执行一个APP，APP执行完成后会返回到会议。
floor	Toggle yourself on and off of talking floor, as long as no one else has floor status. floor标记的意思是会议当前的说话人，一个会议只有一个成员拥有floor标记，会议会自动设置。我看代码的逻辑是，按钮的用处是如果一个成员拥有floor标记，执行按键后，会取消floor标记。如果会议中没有成员有floor标记，就给按键的成员设置floor标记，不会实际测试时并不想预期的这样，系统会自动修改floor标记的。
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 holder	1.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