RFC 5022
Media Server Control Markup Language (MSCML) and Protocol
Network Working Group J. Van Dyke Request for Comments: 5022 Cantata Technology, Inc. Obsoletes: 4722 E. Burger, Ed. Category: Informational BEA Systems, Inc. A. Spitzer Bluesocket Inc. September 2007 Media Server Control Markup Language (MSCML) and Protocol Status of This Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. IESG Note This RFC is not a candidate for any level of Internet Standard. The IETF disclaims any knowledge of the fitness of this RFC for any purpose and in particular notes that the decision to publish is not based on IETF review for such things as security, congestion control, or inappropriate interaction with deployed protocols. The RFC Editor has chosen to publish this document at its discretion. Readers of this document should exercise caution in evaluating its value for implementation and deployment. See RFC 3932 for more information.Abstract
Media Server Control Markup Language (MSCML) is a markup language used in conjunction with SIP to provide advanced conferencing and interactive voice response (IVR) functions. MSCML presents an application-level control model, as opposed to device-level control models. One use of this protocol is for communications between a conference focus and mixer in the IETF SIP Conferencing Framework.
Table of Contents
1. Introduction ....................................................4 1.1. Conventions Used in This Document ..........................5 2. MSCML Approach ..................................................5 3. Use of SIP Request Methods ......................................6 4. MSCML Design ....................................................8 4.1. Transaction Model ..........................................8 4.2. XML Usage ..................................................9 4.2.1. MSCML Time Values ...................................9 5. Advanced Conferencing ..........................................10 5.1. Conference Model ..........................................10 5.2. Configure Conference Request <configure_conference> .......11 5.3. Configure Leg Request <configure_leg> .....................13 5.4. Terminating a Conference ..................................14 5.5. Conference Manipulation ...................................15 5.6. Video Conferencing ........................................16 5.7. Conference Events .........................................17 5.8. Conferencing with Personalized Mixes ......................18 5.8.1. MSCML Elements and Attributes for Personalized Mixes .................................19 5.8.2. Example Usage of Personalized Mixes ................20 6. Interactive Voice Response (IVR) ...............................23 6.1. Specifying Prompt Content .................................24 6.1.1. Use of the Prompt Element ..........................24 6.2. Multimedia Processing for IVR .............................30 6.3. Playing Announcements <play> ..............................31 6.4. Prompt and Collect <playcollect> ..........................32 6.4.1. Control of Digit Buffering and Barge-In ............33 6.4.2. Mapping DTMF Keys to Special Functions .............33 6.4.3. Collection Timers ..................................35 6.4.4. Logging Caller DTMF Input ..........................36 6.4.5. Specifying DTMF Grammars ...........................36 6.4.6. Playcollect Response ...............................37 6.4.7. Playcollect Example ................................38 6.5. Prompt and Record <playrecord> ............................38 6.5.1. Prompt Phase .......................................38 6.5.2. Record Phase .......................................39 6.5.3. Playrecord Example .................................41 6.6. Stop Request <stop> .......................................42 7. Call Leg Events ................................................43 7.1. Keypress Events ...........................................43 7.1.1. Keypress Subscription Examples .....................45 7.1.2. Keypress Notification Examples .....................45 7.2. Signal Events .............................................46 7.2.1. Signal Event Examples ..............................47 8. Managing Content <managecontent> ...............................48 8.1. Managecontent Example .....................................50
9. Fax Processing .................................................51 9.1. Recording a Fax <faxrecord> ...............................51 9.2. Sending a Fax <faxplay> ...................................53 10. MSCML Response Attributes and Elements ........................56 10.1. Mechanism ................................................56 10.2. Base <response> Attributes ...............................56 10.3. Response Attributes and Elements for <configure_leg> .....57 10.4. Response Attributes and Elements for <play> ..............57 10.4.1. Reporting Content Retrieval Errors ...............58 10.5. Response Attributes and Elements for <playcollect> .......59 10.6. Response Attributes and Elements for <playrecord> ........60 10.7. Response Attributes and Elements for <managecontent> .....61 10.8. Response Attributes and Elements for <faxplay> and <faxrecord> ..........................................61 11. Formal Syntax .................................................62 11.1. Schema ...................................................62 12. IANA Considerations ...........................................73 12.1. IANA Registration of MIME Media Type application/ mediaservercontrol+xml ...................................73 13. Security Considerations .......................................74 14. References ....................................................75 14.1. Normative References .....................................75 14.2. Informative References ...................................76 Appendix A. Regex Grammar Syntax .................................78 Appendix B. Contributors .........................................79 Appendix C. Acknowledgements .....................................79
1. Introduction
This document describes the Media Server Control Markup Language (MSCML) and its usage. It describes payloads that one can send to a media server using standard SIP INVITE and INFO methods and the capabilities these payloads implement. RFC 4240 [2] describes media server SIP URI formats. Prior to MSCML, there was not a standard way to deliver SIP-based enhanced conferencing. Basic SIP constructs, such as those described in RFC 4240 [2], serve simple n-way conferencing well. The SIP URI provides a natural mechanism for identifying a specific SIP conference, while INVITE and BYE methods elegantly implement conference join and leave semantics. However, enhanced conferencing applications also require features such as sizing and resizing, in- conference IVR operations (e.g., recording and playing participant names to the full conference), and conference event reporting. MSCML payloads within standard SIP methods realize these features. The structure and approach of MSCML satisfy the requirements set out in RFC 4353 [10]. In particular, MSCML serves as the interface between the conference server or focus and a centralized conference mixer. In this case, a media server has the role of the conference mixer. There are two broad classes of MSCML functionality. The first class includes primitives for advanced conferencing, such as conference configuration, participant leg manipulation, and conference event reporting. The second class comprises primitives for interactive voice response (IVR). These include collecting DTMF digits and playing and recording multimedia content. MSCML fills the need for IVR and conference control with requests and responses over a SIP transport. VoiceXML [11] fills the need for IVR with requests and responses over a HTTP transport. This enables developers to use whatever model fits their needs best. In general, a media server offers services to SIP UACs, such as Application Servers, Feature Servers, and Media Gateway Controllers. See the IPCC Reference Architecture [12] for definitions of these terms. It is unlikely, but not prohibited, for end-user SIP UACs to have a direct signaling relationship with a media server. The term "client" is used in this document to refer generically to an entity that interacts with the media server using SIP and MSCML.
The media server fulfills the role of the Media Resource Function (MRF) in the IP Multimedia Subsystem (IMS) [13] as described by 3GPP. MSCML and RFC 4240 [2], upon which MSCML builds, are specifically focused on the Media resource (Mr) interface which supports interactions between application logic and the MRF. This document describes a working framework and protocol with which there is considerable implementation experience. Application developers and service providers have created several MSCML-based services since the availability of the initial version in 2001. This experience is highly relevant to the ongoing work of the IETF, particularly the SIP [26], SIPPING [27], MMUSIC [28], and XCON [29] work groups, the IMS [30] work in 3GPP, and the CCXML work in the Voice Browser Work Group of the W3C.1.1. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [1].2. MSCML Approach
It is critically important to emphasize that the goal of MSCML is to provide an application interface that follows the SIP, HTTP, and XML development paradigm to foster easier and more rapid application deployment. This goal is reflected in MSCML in two ways. First, the programming model is that of peer to peer rather than master-slave. Importantly, this allows the media server to be used simultaneously for multiple applications rather than be tied to a single point of control. It also enables standard SIP mechanisms to be used for media server location and load balancing. Second, MSCML defines constructs and primitives that are meaningful at the application level to ensure that programmers are not distracted by unnecessary complexity. For example, the mixing resource operates on constructs such as conferences and call participants rather than directly on individual media streams. The MSCML paradigm is important to the developer community, in that developers and operators conceptually write applications about calls, conferences, and call legs. For the majority of developers and applications this approach significantly simplifies and speeds development.
3. Use of SIP Request Methods
As mentioned above, MSCML payloads may be carried in either SIP INVITE or INFO requests. The initial INVITE, which creates an enhanced conference, MAY include an MSCML payload. A subsequent INVITE to the same Request-URI joins a participant leg to the conference. This INVITE MAY include an MSCML payload. The initial INVITE that establishes an IVR session MUST NOT include an MSCML payload. The client sends all mid-call MSCML payloads for conferencing and IVR via SIP INFO requests. SIP INVITE requests that contain both MSCML and Session Description Protocol (SDP) body parts are used frequently in conferencing scenarios. Therefore, the media server MUST support message bodies with the MIME type "multipart/mixed" in SIP INVITE requests. The media server transports MSCML responses in the final response to the SIP INVITE containing the matching MSCML request or in a SIP INFO message. The only allowable final response to a SIP INFO containing a message body is a 200 OK, per RFC 2976 [3]. Therefore, if the client sends the MSCML request via SIP INFO, the media server responds with the MSCML response in a separate INFO request. In general, these responses are asynchronous in nature and require a separate transaction due to timing considerations. There has been considerable debate on the use of the SIP INFO method for any purpose. Our experience is that MSCML would not have been possible without it. At the time the first MSCML specification was published, the first SIP Event Notification draft had just been submitted as an individual submission. At that time, there was no mechanism to link SUBSCRIBE/NOTIFY to an existing dialog. This prevented its use in MSCML, since all events occurred in an INVITE- established dialog. And while SUBSCRIBE/NOTIFY was well suited for reporting conference events, its semantics seemed inappropriate for modifying a participant leg or conference setting where the only "event" was the success or failure of the request. Lastly, since SIP INFO was an established RFC, most SIP stack implementations supported it at that time. We had few, if any, interoperability issues as a result. More recent developments have provided additional reasons why SUBSCRIBE/NOTIFY is not appropriate for use in MSCML. Use of SUBSCRIBE presents two problems. The first is semantic. The purpose of SUBSCRIBE is to register interest in User Agent state. However, using SUBSCRIBE for MSCML results in the SUBSCRIBE modifying the User Agent state. The second reason SUBSCRIBE is not appropriate is because MSCML is inherently call based. The association of a SIP dialog with a call leg means MSCML can be incredibly straightforward.
For example, if one used SUBSCRIBE or other SIP method to send commands about some context, one must identify that context somehow. Relating commands to the SIP dialog they arrive on defines the context for free. Moreover, it is conceptually easy for the developer. Using NOTIFY to transport MSCML responses is also not appropriate, as the NOTIFY would be in response to an implicit subscription. The SIP and SIPPING lists have discussed the dangers of implicit subscription. In order to guarantee interoperability with this specification, as well as with SIP User Agents that are unaware of MSCML, SIP UACs that wish to use MSCML services MUST specify a service indicator that supports MSCML in the initial INVITE. RFC 4240 [2] defines the service indicator "conf", which MUST be used for MSCML conferencing applications. The service indicator "ivr" MUST be used for MSCML interactive voice response applications. In this specification, only "conf" and "ivr" are described. The media server MUST support moving the call between services through sending the media server a BYE on the existing dialog and establishing a new dialog with an INVITE to the desired service. Media servers SHOULD support moving between services without requiring modification of the previously established SDP parameters. This is achieved by sending a re-INVITE on the existing dialog in which the Request-URI is modified to specify the new service desired by the client. This eliminates the need for the client to send an INVITE to the caller or gateway to establish new SDP parameters. The media server, as a SIP UAS, MUST respond appropriately to an INVITE that contains an MSCML body. If MSCML is not supported, the media server MUST generate a 415 final response and include a list of the supported content types in the response per RFC 3261 [4]. The media server MUST also advertise its support of MSCML in responses to OPTIONS requests, by including "application/mediaservercontrol+xml" as a supported content type in an Accept header. This alleviates the major issues with using INFO for the transport of application data; namely, the User Agent's proper interpretation of what is, by design, an opaque message request.
4. MSCML Design
4.1. Transaction Model
To avoid undue complexity, MSCML establishes two rules regarding its usage. The first is that only one MSCML body may be present in a SIP request. The second is that each MSCML body may contain only one request or response. This greatly simplifies transaction management. MSCML syntax does provide for the unique identification of multiple requests in a single body part. However, this is not supported in this specification. Per the guidelines of RFC 3470 [14], MSCML bodies MUST be well formed and valid. MSCML is a direct request-response protocol. There are no provisional responses, only final responses. A request may, however, result in multiple notifications. For example, a request for active talker reports will result in a notification for each speaker set. This maps to the three major element trees for MSCML: <request>, <response>, and <notification>. Figure 1 shows a request body. Depending on the command, one can send the request in an INVITE or an INFO. Figure 2 shows a response body. The SIP INFO method transports response bodies. Figure 3 shows a notification body. The SIP INFO method transports notifications. <?xml version="1.0" encoding="utf-8"?> <MediaServerControl version="1.0"> <request> ... request body ... </request> </MediaServerControl> Figure 1: MSCML Request Format <?xml version="1.0" encoding="utf-8"?> <MediaServerControl version="1.0"> <response> ... response body ... </response> </MediaServerControl> Figure 2: MSCML Response Format
<?xml version="1.0" encoding="utf-8"?> <MediaServerControl version="1.0"> <notification> ... notification body ... </notification> </MediaServerControl> Figure 3: MSCML Notification Format MSCML requests MAY include a client-defined ID attribute for the purposes of matching requests and responses. The values used for these IDs need only be unique within the scope of the dialog in which the requests are issued.4.2. XML Usage
In the philosophy of XML as a text-based description language, and not as a programming language, MSCML makes the choice of many attribute values for readability by a human. Thus, many attributes that would often be "boolean" instead take "yes" or "no" values. For example, what does 'report="false"' or 'report="1"' mean? However, 'report="yes"' is clearer: I want a report. Some programmers prefer the precision of a boolean. To satisfy both styles, MSCML defines an XML type, "yesnoType", that takes on the values "yes" and "no" as well as "true", "false", "1", and "0". Many attributes in the MSCML schema have default values. In order to limit demands on the XML parser, MSCML applies these values at the protocol, not XML, level. The MSCML schema documents these defaults as XML annotations to the appropriate attribute.4.2.1. MSCML Time Values
For clarity, time values in MSCML are based on the time designations described in the Cascading Style Sheets level 2 (CSS2) Specification [15]. Their format consists of a number immediately followed by an optional time unit identifier of the following form: ms: milliseconds (default) s: seconds If no time unit identifier is present, the value MUST be interpreted as being in milliseconds. As extensions to [15] MSCML allows the string values "immediate" and "infinite", which have special meaning for certain timers.
5. Advanced Conferencing
5.1. Conference Model
The advanced conferencing model is a star controller model, with both signaling and media directed to a central location. Figure 4 depicts a typical signaling relationship between end users' UACs, a conference application server, and a media server. RFC 4353 [10] describes this model. The application server is an instantiation of the conference focus. The media server is an instantiation of the media mixer. Note that user-level constructs, such as event notifications, are in the purview of the application server. This is why, for example, the media server sends active talker reports using MSCML notifications, while the application server would instead use the conference package [16] for individual notifications to SIP user agents. Note that we do not recommend the use of the conference package for media server to application server notifications because none of the filtering and membership information is available at the media server. +-------+ | UAC 1 |---\ Public URI +-------------+ +-------+ \ _____________| Application | / / | Server | Not shown: +-------+ / / +-------------+ RTP flows directly | UAC 2 |---/ / | Private between UACs and +-------+ / | URI media server . / +--------------+ : / | | +-------+ / | Media Server | | UAC n |---/ | | +-------+ +--------------+ Figure 4: Conference Model Each UAC sends an INVITE to a Public Conference URI. Presumably, the client publishes this URI, or it is an ad hoc URI. In any event, the client generates a Private URI, following the rules specified by RFC 4240 [2]. That is, the URI is of the following form: sip:conf=UniqueID@ms.example.net where UniqueID is a unique conference identifier and ms.example.net is the host name or IP address of the media server. There is nothing to prevent the UACs from contacting the media server directly. However, one would expect the owner of the media server to restrict who can use its resources.
As for basic conferencing, described by RFC 4240 [2], the first INVITE to the media server with a UniqueID creates a conference. However, in advanced conferencing, the first INVITE MAY include a MSCML <configure_conference> payload rather than the SDP of a conference participant. The <configure_conference> payload conveys extended session parameters (e.g., number of participants) that SDP does not readily express, but the media server must know to allocate the appropriate resources. When the conference is created by sending an INVITE containing a MSCML <configure_conference> payload, the resulting SIP dialog is termed the "Conference Control Leg." This leg has several useful properties. The lifetime of the conference is the same as that of its control leg. This ensures that the conference remains in existence even if all participant legs leave or have not yet arrived. In addition, when the client terminates the Conference Control Leg, the media server automatically terminates all participant legs. The Conference Control Leg is also used for play or record operations to/from the entire conference and for active talker notifications. Full conference media operations and active talker report subscriptions MUST be executed on the Conference Control Leg. Creation of a Conference Control Leg is RECOMMENDED because full advanced conferencing capabilities are not available without it. Clients MUST establish the Conference Control Leg in the initial INVITE that creates the conference; it cannot be created later. Once the client has created the conference with or without the Conference Control Leg, participants can be joined to the conference. This is achieved by the client's directing an INVITE to the Private Conference URI for each participant. Using the example conference URI given above, this would be sip:conf=UniqueID@ms.example.net.5.2. Configure Conference Request <configure_conference>
The <configure_conference> request has two attributes that control the resources the media server sets aside for the conference. These are described in the list below. Attributes of <configure_conference>: o reservedtalkers - optional (see note), no default value: The maximum number of talker legs allocated for the conference. Note: required when establishing the Conference Control Leg but optional in subsequent <configure_conference> requests.
o reserveconfmedia - optional, default value "yes": Controls
allocation of resources to enable playing or recording to or from
the entire conference.
When the reservedtalkers+1st INVITE arrives at the media server, the
media server SHOULD generate a 486 Busy Here response. Failure to
send a 486 response to this condition can cause the media server to
oversubscribe its resources.
NOTE: It would be symmetric to have a reservedlisteners parameter.
However, the practical limitation on the media server is the
number of talkers for a mixer to monitor. In either case, the
client regulates who gets into the conference by either proxying
the INVITEs from the user agent clients or metering to whom it
gives the conference URI.
For example, to create a conference with up to 120 active talkers and
the ability to play audio into the conference or record portions or
all of the conference full mix, the client specifies both attributes,
as shown in Figure 6.
<?xml version="1.0" encoding="utf-8"?>
<MediaServerControl version="1.0">
<request>
<configure_conference reservedtalkers="120"
reserveconfmedia="yes"/>
</request>
</MediaServerControl>
Figure 6: 120 Speaker MSCML Example
In addition to these attributes, a <configure_conference> request MAY
contain a child <subscribe> element. The <subscribe> element is used
to request notifications for conference-wide active talker events.
Detailed information regarding active talker events is contained in
Section 5.7.
The client MUST include a <configure_conference> request in the
initial INVITE which establishes the conference when creating the
Conference Control Leg. The client server MUST issue asynchronous
commands, such as <play>, separately (i.e., in INFO messages) to
avoid ambiguous responses.
Media operations on the Conference Control leg are performed
internally, no external RTP streams are involved. Accordingly, the
media server does not expect RTP on the Conference Control Leg.
Therefore, the client MUST send either no SDP or hold SDP in the
INVITE request containing a <configure_conference> payload. The
media server MUST treat SDP with all media lines set to "inactive" or with connection addresses set to 0.0.0.0 (for backwards compatibility) as hold SDP. The media server sends a response when it has finished processing the <configure_conference> request. The format of the <configure_conference> response is detailed in Section 10.2.5.3. Configure Leg Request <configure_leg>
Conference legs have a number of properties the client can modify. These are set using the <configure_leg> request. This request has the attributes described in the list below. Attributes of <configure_leg>: o type - optional, default value "talker": Consider this leg's audio for inclusion in the output mix. Alternative is "listener". o dtmfclamp - optional, default value "yes": Remove detected DTMF digits from the input audio. o toneclamp - optional, default value "yes": Remove tones from the input audio. Tones include call progress tones and the like. o mixmode - optional, default value "full": Be a candidate for the full mix. Alternatives are "mute", to disallow media in the mix, "parked", to disconnect the leg's media streams from the conference for IVR operations, "preferred", to give this stream preferential selection in the mix (i.e., even if not loudest talker, include media, if present, from this leg in the mix), and "private", which enables personalized mixes. In addition to these attributes, there are four child elements defined for <configure_leg>. These are <inputgain>, <outputgain>, <configure_team>, and <subscribe>. The first two, <inputgain> and <outputgain>, modify the gain applied to the input and output audio streams, respectively. These may contain <auto>, to use automatic gain control (AGC) or <fixed>. The <auto> element has the attributes "startlevel", "targetlevel", and "silencethreshold". All the parameters are in dB. The <fixed> element has the attribute "level", which is in dB. The default for both <inputgain> and <outputgain> is <fixed>. The media server MAY
silently cap <inputgain> or <outputgain> requests that exceed the gain limits imposed by the platform. Clients most commonly manipulate only the input gain for a conference leg and rely on the mixer to set an optimum output gain based on the inputs currently in the mix. However, as described above, MSCML does allow for manipulation of the output gain as well. Some of the IVR commands, such as <play>, enable control of the output gain for content playback operations. The interaction of conference output gain and IVR playback gain controls is described in Section 6.1.1. Note that <inputgain> and <outputgain> settings apply only to conference legs and do not apply to IVR sessions. The <configure_team> element is used to create and manipulate groups for personalized mixes. Details of personalized mixes are discussed in Section 5.8. The <subscribe> element is used to request notifications for call leg related events, such as asynchronous DTMF digit reports. Detailed information regarding call leg events is discussed in Section 7. If the default parameters are acceptable for the leg the client wishes to enter into the conference, then a normal SIP INVITE, with no MSCML body, is sufficient. However, if the client wishes to modify one or more of the parameters, the client can include a MSCML body in addition to the SDP body. The client can modify the conference leg parameters during the conference by issuing a SIP INFO on the dialog representing the conference leg. Of course, the client cannot modify SDP in an INFO message. The media server sends a response when it has finished processing the <configure_leg> request. The format of the <configure_leg> response is detailed in Section 10.3.5.4. Terminating a Conference
To remove a leg from the conference, the client issues a SIP BYE request on the selected dialog representing the conference leg. The client can terminate all legs in a conference by issuing a SIP BYE request on the Conference Control Leg. If one or more participants are still in the conference when the media server receives a SIP BYE request on the Conference Control Leg, the media server issues SIP BYE requests on all remaining conference legs to ensure cleanup of the legs.
The media server returns a 200 OK to the SIP BYE request as it sends BYE requests to the other legs. This is because we cannot issue a provisional response to a non-INVITE request, yet the teardown of the other legs may exceed the retransmission timer limits of the original request. While the conference is being cleaned up, the media server MUST reject any new INVITEs to the terminated conference with a 486 Busy Here response. This response indicates that the specified conference cannot accept any new members, pending deletion.5.5. Conference Manipulation
Once the conference has begun, the client can manipulate the conference as a whole or a particular participant leg by issuing commands on the associated SIP dialog. For example, by sending MSCML requests on the Conference Control Leg the client can request that the media server record the conference, play a prompt to the conference, or request reports on active talker events. Similarly, the client may mute a participant leg, configure a personalized mix or request reports for call leg events, such as DTMF keypresses. Figure 7 shows an example of an MSCML command that plays a prompt to all conference participants. <?xml version="1.0" encoding="utf-8"?> <MediaServerControl version="1.0"> <request> <play> <prompt> <audio url="http://prompts.example.net/en_US/welcome.au"/> </prompt> </play> </request> </MediaServerControl> Figure 7: Full Conference Audio Command - Play A client can modify a leg by issuing an INFO on the dialog associated with the participant leg. For example, Figure 8 mutes a conference leg. <?xml version="1.0" encoding="utf-8"?> <MediaServerControl version="1.0"> <request> <configure_leg mixmode="mute"/> </request> </MediaServerControl> Figure 8: Sample Change Leg Command
In Figure 7, we saw a request to play a prompt to the entire conference. The client can also request to play a prompt to an individual call leg. In that case, the MSCML request is issued within the SIP dialog of the desired conference participant. Section 6 describes the interactive voice response (IVR) services offered by MSCML. If an IVR command arrives on the control channel, it takes effect on the whole conference. This is a mechanism for playing prompts to the entire conference (e.g., announcing new participants). If an IVR command arrives on an individual leg, it only affects that leg. This is a mechanism for interacting with users, such as the creation of "waiting rooms", allowing a user to mute themselves using key presses, allowing a moderator to out-dial, etc. A participant leg MUST be configured with mixmode="parked" prior to the issuance of any IVR commands with prompt content ('prompturl' attribute or <prompt> element). Parking the leg isolates the participant's input and output media from the conference and allows use of those streams for playing and recording purposes. However, the mixmode has no effect if just digit collection or recording is desired. <playcollect> and <playrecord> requests without prompt content MAY be sent on participant legs without setting mixmode="parked".5.6. Video Conferencing
MSCML-controlled advanced conferences, as well as RFC 4240 [2] controlled basic conferences, implicitly support video conferencing in the form of video switching. In video switching, the video stream of the loudest talker (with some hysteresis) is sent to all participants other than that talker. The loudest talker receives the video stream from the immediately prior loudest talker. Media servers MUST ensure that participants receive video media compatible with their session. For example, a participant who has established an H.263 video stream will not receive video from another participant employing H.264 media. Media servers SHOULD implement video transcoding to minimize media incompatibilities between participants. The media server MUST switch video streams only when it receives a refresh video frame. A refresh frame contains all the video information required to decode that frame (i.e., there is no dependency on data from previous video frames).
Refresh frames are large and generally sent infrequently to conserve network bandwidth. The media server MUST implement standard mechanisms to request that the new loudest talker's video encoder transmits a refresh frame to ensure that video can be switched quickly.5.7. Conference Events
A client can subscribe for periodic active talker event reports that indicate which participants are included in the conference mix. As these are conference-level events, the subscription and notifications are sent on the Conference Control Leg. Media servers MAY impose limits on the minimum interval for active talker reports for performance reasons. If the client request is below the imposed minimum, the media server SHOULD set the interval to the minimum value supported. To limit unnecessary notification traffic, the media server SHOULD NOT send a report if the active talker information for the conference has not changed during the reporting interval. A request for an active talker report is in Figure 9. The active talker report enumerates the current call legs in the mix. <?xml version="1.0" encoding="utf-8"?> <MediaServerControl version="1.0"> <request> <configure_conference> <subscribe> <events> <activetalkers report="yes" interval="60s"/> </events> </subscribe> </configure_conference> </request> </MediaServerControl> Figure 9: Active Talker Request Event notifications are sent in SIP INFO messages. Figure 10 shows an example of a report.
<?xml version="1.0" encoding="utf-8"?> <MediaServerControl version="1.0"> <notification> <conference uniqueid="ab34h76z" numtalkers="47"> <activetalkers> <talker callid="myhost4sn123"/> <talker callid="myhost2sn456"/> <talker callid="myhost12sn78"/> </activetalkers> </conference> </notification> </MediaServerControl> Figure 10: Active Talker Event Example The value of the "callid" attribute in the <talker> element corresponds to the value of the SIP Call-ID header of the associated dialog. This enables the client to associate the active talker with a specific participant leg.5.8. Conferencing with Personalized Mixes
MSCML enables clients to create personalized mixes through the <configure_team> element for scenarios where the standard mixmode settings do not provide sufficient control. The <configure_team> element is a child of <configure_leg>. To create personalized mixes, the client has to identify the relationships among the participants. This is accomplished by manipulating two MSCML objects. These objects are: 1. The list of team members (<teammate> elements), set using <configure_team> 2. The mixmode attribute set through <configure_leg> The media server uses the values of these objects to determine which audio inputs to combine for output to the participant. In a normal conference, each participant hears the conference mix minus their own input if they are part of the mixed output. The team list enables the client to specify other participants that the leg can hear in addition to the normal mixed output. Note that personalized mix settings apply only to audio media and do not affect video switching. Team relationships are implicitly symmetric. If the client sets participant A as a team member of participant B, then the media server automatically sets participant B as a team member for A.
The id attribute set through <configure_leg> is used to identify the various participants. A unique ID MUST be assigned to each participant included in a personalized mix. The IDs used MUST be unique within the scope of the conference in which they appear. By itself, the team list only defines those participants that the leg can hear. The mixmode attribute of each team member determines whether to include their audio input in the personalized mix. If the client sets the teammate's mixmode to private, then it is part of the mix. If the mixmode is set to any other value, it is not.5.8.1. MSCML Elements and Attributes for Personalized Mixes
Control of personalized mixes rely on two major MSCML elements: 1. <configure_leg>, using the mixmode attribute setting mixmode="private" 2. <configure_team> The <configure_team> element allows the user to make the participants members of a team within a specific conference. It is a child of the <configure_leg> parent element. The client sends the <configure_team> element in a <configure_leg> request in either a SIP INVITE or SIP INFO. o In an INVITE, to join a participant whose properties differ from the properties established for the conference as a whole. o In an INFO, to change the properties for an existing leg. The two attributes of the configure_team element are "id" and "action". The id attribute MUST contain the unique ID of the leg being modified, as set in the original <configure_leg> request. The action attribute can take on the values "add", "delete", "query", and "set". The default value is "query". This attribute allows the user to modify the team list. Table 1 describes the actions that can be performed on the team list.
+--------+----------------------------------------------------------+ | Action | Description | +--------+----------------------------------------------------------+ | add | Adds a teammate to the mix. | | delete | Deletes a teammate from the mix. | | query | Returns the teammate list to the requestor. This is the | | | default value. | | set | Creates a team list when followed by <teammate id="n"> | | | and also removes all the teammates from the team list | | | for example, when the creator (originator) of the team | | | list on that specific conference leg wants to remove all | | | of the teammates from the team. If the set operation | | | removes all teammates from a participant, that | | | participant hears the full conference mix. | +--------+----------------------------------------------------------+ Table 1: Configure Team Actions5.8.2. Example Usage of Personalized Mixes
A common use of personalized mixing is to support coaching of one participant by another. The coaching scenario includes three participants: 1. The Supervisor, who coaches the agent. 2. The Agent, who interacts with the customer. 3. The Customer, who interacts with the agent. Table 2 illustrates the details of the coached conference topology. +-------------+------------+------------+---------+-----------------+ | Participant | ID | Team | Mixmode | Hears | | | | Members | | | +-------------+------------+------------+---------+-----------------+ | Supervisor | supervisor | Agent | Private | customer + | | | | | | agent | | Agent | agent | Supervisor | Full | customer + | | | | | | supervisor | | Customer | customer | none | Full | agent | +-------------+------------+------------+---------+-----------------+ Table 2: Coached Conference Example To create this topology, the client performs the following actions: 1. The client joins each leg to the conference, being certain to include a unique ID in the <configure_leg> request. The leg ID needs to be unique only within the scope of the conference to which it belongs.
2. The client configures the teammate list and mixmode of each
participant, as required.
Both actions (steps 1 and 2) may be combined in a single MSCML
request. The following sections detail these actions and their
corresponding MSCML payloads.
5.8.2.1. Create the Conference
Before joining any participants, the client must create the
conference by sending a SIP INVITE that contains an MSCML
<configure_conference> request with a unique conference identifier.
5.8.2.2. Joining and Configuring the Coach
Join the coach leg to the conference and configure its desired
properties by sending a SIP INVITE containing a <configure_leg>
request. The <configure_leg> element sets the leg's unique ID to
supervisor and its mixmode to private.
The corresponding MSCML request is as follows.
<?xml version="1.0"?>
<MediaServerControl version="1.0">
<request>
<configure_leg id="supervisor" mixmode="private"/>
</request>
</MediaServerControl>
Figure 11: Join Coach Request
Note that the client cannot configure the teammate list for the coach
yet, as there are no other participants in the conference. One must
join a participant to the conference before one can add it as a
teammate for another leg.
5.8.2.3. Joining and Configuring the Agent
Join the agent leg to the conference and configure its desired
properties by sending a SIP INVITE containing a <configure_leg>
request. The <configure_leg> element sets the leg's unique ID to
"agent" and sets the supervisor as a team member of the agent.
Because team member relationships are symmetric, this action also
adds the agent as a team member for the coach.
The corresponding MSCML request is as follows. <?xml version="1.0"?> <MediaServerControl version="1.0"> <request> <configure_leg id="agent"> <configure_team action="set"> <teammate id="supervisor"/> </configure_team> </configure_leg> </request> </MediaServerControl> Figure 12: Join Agent Request Because the desired mixmode for this leg is full, which is the default value, there is no need to set it explicitly.5.8.2.4. Joining and Configuring the Client
Join the client leg to the conference and configure its desired properties by sending a SIP INVITE containing a <configure_leg> request. The <configure_leg> element simply sets the leg's unique ID to "customer". The media server does not need further configuration because the desired mixmode, full, is the default and the customer has no team members. The corresponding MSCML request is as follows. <?xml version="1.0"?> <MediaServerControl version="1.0"> <request> <configure_leg id="customer"/> </request> </MediaServerControl> Figure 13: Join Client Request Strictly speaking, it is not a requirement that the client give the customer leg a unique ID because it will not be a team member. However, when using coached conferencing, we RECOMMEND that one assign a unique ID to each leg in the initial INVITE request. Assigning a unique ID eliminates the need to set it later by sending a SIP INFO if one later desires personalized mixing for the customer leg. The conference is now in the desired configuration, shown previously in Table 2.
(next page on part 2)
