Conference room module

Revision as of 14:41, 16 May 2013

Yate can be used as a Conference Server in two ways:

• you can execute a conference directly from routing module (e.g regexroute.conf), as you can see in the examples,

• or you can do it programmatically using call.conference message from an external script or by using module Pbxassist, that has the capability of doing PBX operations for conference on receiving DTMF sequences.

Conference room module

A conference room is an N-way audio mixer to which an arbitrary number of conference legs are attached.
Parameters that are needed for conference room are taken from call.execute and call.conference messages.

The name of the conference room to connect to depends of the message:

• for call.execute the callto parameter must be of the form "conf/NAME" (default empty) sets a specific room name, if the NAME is empty a new, unique conference room name is generated
• for call.conference the room parameter (default empty) sets a specific room name instead of generating a new, unique one

In both cases the actual name of the conference is returned in the room parameter as "conf/NAME" like it should be used for further references.

The automatically generated room names are of the form "x-NUMBER" where NUMBER is incremented for each new room created. You must never make assumptions about the next room number, you must use the returned room parameter.

Conference leg capabilities

Each conference leg has the following capabilities that are controlled by the parameters of the call.execute or call.conference message:

• existing (default false) forces using an existing room else the call fails
• smart (default true) computes energy and supresses noise
• echo (default false) hear back own voice in the conference's global mix
• voice (default true) can speak to the conference, else can only hear it
• counted (default true) conference leg is counted as regular user
• billing (default false) emits messages needed to bill conference participants
• utility (default false) creates a housekeeping conference leg that doesn't emit notifications and defaults to smart=false, echo=true, counted=false
• player (default false) marks the conference leg as music player

Conference room capabilities

The conference room itself has a set of capabilities that are taken from the parameters of the message that created the room:

• maxusers (default 10) sets a limit to the number of users that can join a room
• lonely (default false) allows the conference room to persist even when there is only one user connected
• record (default empty) allows specifying a route that will make an outgoing record-only call
• notify (default empty) enables generating notification messages for conference events
• recordwarn (default empty) allows specifying an override source for the recording channel so that the participants are warned
• rate (default 8000) sample rate used in mixing, must be 8000, 16000 or 32000 for transcoders to work properly
• speakers - true/false/interger value(0-8). If true or integer between 0-8, module notifies who speaks in the conference at some point. This must be used with parameter interval. If true, value defaults to 3.
• interval - time interval for receiving chan.notify with event speaking. Default value is 3 sec.

Messages to send to conference

The conference can be started by using:

• call.execute message - that creates or attaches to an existing conference
• call.conference messages - that creates a conference from an existing call allowing to add more call legs to it

A call.conference without a channel can be used to control recording. A record parameter that is "off" or "false" or "disable" will stop recording, else the old recorder is stopped and a new one created.

Besides the normal channel messages the conference rooms can generate chan.notify messages with the following parameters:

• targetid - ID of the notification requestor
• event - name of the event that created the message - "created", "destroyed", "joined", "left", "speaking"

The speaking event notifies what participants are speaking in the conference at a certain moment.

• room - name of the conference room
• users - number of users currently in conference (only for "joined" or "left" events)
• player - ID of the music player conference leg, if any
• caller, called, billid, username - only for the "created" event
• changed - tells if something is changed from last message received

Configuration

There is no configuration file for conference module. All parameters are taken from the call.execute or call.conference message.

Examples

• A simple conference can be executed via regexroute.conf like this

^701$ = conf/sales

Here 701 number will join people in conference.

• limit users in conference

^800$ = conf/test;lonely=true;maxusers=50

Here 800 will join people into a conference which is limited to 50 users, and where if there is only one person, they will remain in it (where the parameter lonelytimeout in pbxassist.conf specify the default global timeouts etc.)

• to create one room for each number 701 - 709:

^70\([1-9]\)$=conf/room-\1

Internally the rooms will be named room-1 to room-9 but you will access them by numbers 701-709.

• You may force a call to fail if the room is not already created (there are no participants yet):

 ^70\([1-9]\)$=conf/room-\1
 ^71\([1-9]\)$=conf/room-\1;existing=true

In this scenario calls to numbers 70x can create or join a room while calls to 71x can join a room only if already populated.

• make a conference from an external module

 $m = new Yate("chan.masquerade");
 $m->id = "";
 $m->params["message"] = "call.execute";
 $m->params["id"] = $partycallid;
 $m->params["callto"] = "conf/cs-$conference_id";
 $m->params["notify"] = "conf-monitor/cs-$conference_id";
 $m->params["billing"] = "true";
 $m->params["lonely"] = "true";
 $m->params["maxusers"] = $maxusers;
 $m->params["smart"] = "t";

 if ($is_organizer == "1") {
     $m->params["record"] = "external/nodata/conference.php";
     // set this so that script can play warnings in conference
     $m->params["recordwarn"] = "-";
     $m->params["speakers"] = $speakers;
     $m->params["interval"] = $interval_notifications;
     $m->params["waitlock"] = -200;
 } else {
     $m->params["existing"] = "t";
 }
 $m->Dispatch();

See also

• Conferencing with Sangoma Wanpipe (PDF)
• Pbxassist module
• Conference PBX