View source for Conference room module

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

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 [[Regular_expressions|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|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'''

* [http://sangoma.com/assets/docs/misc/2008_09_18_Conferencing_with_Sangoma_Wanpipe.pdf Conferencing with Sangoma Wanpipe] (PDF)
* [[Pbxassist|Pbxassist module]]
* [[Conference PBX]]