FreeSWITCH conference guide(FreeSWITCH会议指南)

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

conference基础部分

查询已经存在的会议

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

邀请用户加入会议

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

成员加入会议标志

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

剔出成员

kick 和 hup 区别，hup不播放提示音。
conference <confname> kick <member_id>|all|last|non_moderator conference <confname> hup <member_id>|all|last|non_moderator

会议密码

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

APP中设置密码

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

API设置密码

设置成员密码

conference <confname> pin <pin-number>

设置主席密码

conference <confname> pin mod <pin-number>

清除密码

conference <confname> nopin

配置文件设置密码

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

通道变量设置密码

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

通道变量验证密码

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

会议录音

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

配置会议录音

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

对会议进行放音

例子 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]

会议提示音

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

API设置提示音

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

配置文件设置提示音

     <!-- <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"/>

会议加锁

    conference <confname> lock
    conference <confname> unlock

会议静音

    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]

只说模式

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

桥接会议

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

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

事件

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

DTMF按键控制(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