Internet DRAFT - draft-saleem-msml
draft-saleem-msml
Internet-draft Media Server Markup Language August 2008
(MSML)
SIPPING A. Saleem
Internet Draft Y. Xin
Expires: February 03, 2009 Radisys
G. Sharratt
August 07, 2008
Media Server Markup Language (MSML)
draft-saleem-msml-07
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that other
groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on February 03, 2009.
Copyright Notice
Copyright (C) The IETF Trust (2008).
Abstract
The Media Server Markup Language (MSML) is used to control and invoke
many different types of services on IP Media Servers. Clients can use
it to define how multimedia sessions interact on a Media Server and
to apply services to individuals or groups of users. MSML can be
used, for example, to control Media Server conferencing features such
as video layout and audio mixing, create sidebar conferences or
Saleem, et al. Expires - February 03 2009 [Page 1]
Internet-draft Media Server Markup Language August 2008
(MSML)
personal mixes, and set the properties of media streams. As well,
clients can use MSML to define media processing dialogs, which may be
used as parts of application interactions with users or conferences.
Transformation of media streams to and from users or conferences as
well as IVR dialogs are examples of such interactions, which are
specified using MSML. MSML clients may also invoke dialogs with
individual users or with groups of conference participants using
VoiceXML.
Table of Contents
1. Introduction...................................................4
2. Conventions used in this document..............................5
3. Glossary.......................................................5
4. MSML SIP Usage.................................................6
4.1 SIP INFO...................................................7
4.2 SIP Control Framework......................................8
5. Language Structure............................................15
5.1 Package Scheme............................................15
5.2 Profile Scheme............................................19
6. Execution Flow................................................19
7. Media Server Object Model.....................................21
7.1 Objects...................................................21
7.2 Identifiers...............................................24
8. MSML Core Package.............................................26
8.1 <msml>....................................................26
8.2 <send>....................................................26
8.3 <result>..................................................27
8.4 <event>...................................................27
9. MSML Conference Core Package..................................28
9.1 Conferences...............................................28
9.2 Media Streams.............................................29
9.3 <createconference>........................................31
9.4 <modifyconference>........................................33
9.5 <destroyconference>.......................................35
9.6 <audiomix>................................................35
9.7 <videolayout>.............................................37
9.8 <join>....................................................43
9.9 <modifystream>............................................45
9.10 <unjoin>.................................................46
9.11 <monitor>................................................47
9.12 <stream>.................................................48
10. MSML Dialog Packages.........................................51
10.1 Overview.................................................51
10.2 Primitives...............................................53
10.3 Events...................................................55
Saleem, et al. Expires - February 03 2009 [Page 2]
Internet-draft Media Server Markup Language August 2008
(MSML)
10.4 MSML Dialog Usage with SIP...............................56
10.5 MSML Dialog Structure and Modularity.....................57
10.6 MSML Dialog Core Package.................................58
10.7 MSML Dialog Base Package.................................63
10.8 MSML Dialog Group Package................................81
10.9 MSML Dialog Transform Package............................85
10.10 MSML Dialog Speech Package..............................88
10.11 MSML Dialog Fax Detection Package.......................92
10.12 MSML Dialog Fax Send/Receive Package....................93
11. MSML Audit Package..........................................100
11.1 MSML Audit Core Package.................................100
11.2 MSML Audit Conference Package...........................102
11.3 MSML Audit Connection Package...........................105
11.4 MSML Audit Dialog Package...............................108
11.5 MSML Audit Stream Package...............................110
12. Response Codes..............................................111
13. MSML Conference Examples....................................113
13.1 Establishing a Dial-in Conference.......................113
13.2 Example of a Sidebar Audio Conference...................117
13.3 Example of Removing a Conference........................118
13.4 Example of Modifying Video Layout.......................119
14. MSML Dialog Examples........................................120
14.1 Announcement............................................120
14.2 Voice Mail Retrieval....................................120
14.3 Play and Record.........................................121
14.4 Speech Recognition......................................123
14.5 Play and Collect........................................124
14.6 User Controlled Gain....................................125
15. MSML Audit Examples.........................................126
15.1 Audit All Conferences...................................126
15.2 Audit Conference Dialogs................................127
15.3 Audit Conference Streams................................128
15.4 Audit All Connections...................................128
15.5 Audit Connection Dialogs................................129
15.6 Audit Connection Streams................................129
15.7 Audit Connection With Selective States..................130
16. Change Summary..............................................131
17. Future Work.................................................133
18. XML Schema..................................................133
18.1 MSML Core...............................................135
18.2 MSML Conference Core Package............................139
18.3 MSML Dialog Packages....................................148
18.4 MSML Audit Packages.....................................169
19. Security Considerations.....................................175
20. IANA Considerations.........................................175
20.1 IANA registrations for 'application' MIME Media Type....175
20.2 IANA registrations for 'text' MIME Media Type...........177
20.3 URN Sub-Namespace Registration..........................179
Saleem, et al. Expires - February 03 2009 [Page 3]
Internet-draft Media Server Markup Language August 2008
(MSML)
20.4 XML Schema Registration.................................180
21. Normative References........................................180
22. Informative References......................................181
Acknowledgments.................................................182
Authors' Addresses..............................................182
Intellectual Property Statement.................................183
Full Copyright Statement........................................183
Disclaimer of Validity..........................................184
Acknowledgement.................................................184
1. Introduction
Media servers contain dynamic pools of media resources. Control
Agents and other users of media servers (called media server clients)
can define and create many different services based on how they
configure and use those resources. Often, that configuration and the
ways in which those resources interact will be changed dynamically
over the course of a call, to reflect changes in the way that an
application interacts with a user.
For example, a call may undergo an initial IVR dialog before being
placed into a conference. Calls may be moved from a main conference
to a sidebar conference and then back again. Individual calls may be
directly bridged to create small n-way calls or simple sidebars. None
of these change the SIP [n1] dialog or RTP [i3] session. Yet these do
affect the media flow and processing internal to the media server.
The Media Server Markup Language (MSML) is an XML [n2] language used
to control the flow of media streams and services applied to media
streams within a media server. It is used to invoke many different
types of services on individual sessions, groups of sessions, and
conferences. MSML allows the creation of conferences, bridging
different sessions together, and bridging sessions into conferences.
MSML may also be used to create user interaction dialogs and allows
the application of media transforms to media streams. Media
interaction dialogs created using MSML allow construction of IVR
dialog sessions to individual users as well as to groups of users
participating in a conference. Dialogs may also be specified using
other languages, VoiceXML [n5], which support complete single-party
application logic to be executed on the Media Server.
MSML is a transport independent language, such that it does not rely
on underlying transport mechanisms and language semantics are
independent of transport. However, SIP is a typical and commonly used
transport mechanism for MSML, invoked using the SIP URI scheme. This
Saleem, et al. Expires - February 03 2009 [Page 4]
Internet-draft Media Server Markup Language August 2008
(MSML)
specification defines using MSML Dialogs using SIP as the transport
mechanism.
A network connection may be established with the media server using
SIP. Media received and transmitted on that connection will flow
through different media resources on the media server depending on
the requested service. Basic Network Media Services with SIP [n7]
defines conventions for associating a basic service with a SIP
Request-URI. MSML allows services to be dynamically applied and
changed by a Control Agent during the lifetime of the SIP dialog.
MSML has been designed to address the control and manipulation of
media processing operations (e.g., announcement, IVR, play and
record, ASR/TTS, fax, video), as well as control and relationships of
media streams (e.g., simple and advanced conferencing). It provides a
general-purpose media server control architecture. MSML can
additionally be used to invoke other more complex IVR languages such
as VoiceXML.
2. 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 [i14].
3. Glossary
Media Server: a general-purpose platform for executing real-time
media processing tasks. This is a logical function that maps either
to a single physical device or to a portion of a physical device.
Media Server Client: an application which originates MSML requests to
a media server and also referred to as a Control Agent in this
specification.
Network Connection: a participant that represents the termination on
a media server of one or more RTP [i3] sessions (for example audio
and video) associated with a call. Network connections are
established and removed using a session establishment protocol such
as SIP. An instance of a network connection is independent of MSML
processing instructions applied to it.
Dialog: an automated IVR participant. Examples of dialogs may be
announcement players, IVR interfaces, or voice recorders. Dialogs may
be defined in MSML or using VoiceXML [n5].
Conference: an intermediary function that provides multimedia mixing
and other advanced conferencing services. This specification
Saleem, et al. Expires - February 03 2009 [Page 5]
Internet-draft Media Server Markup Language August 2008
(MSML)
currently considers conferences with audio and/or video media types,
but is extensible to other media types.
Identifier: a name that is used to refer to a specific instance of an
object on the media server, such as a conference or a dialog.
Identifiers are composed of one or more terms where each term
identifies an object class and instance.
Object: the generic term for a media server entity that terminates,
originates, or processes media. This specification defines four
classes of objects and specifies mechanisms to create them, join them
together, and destroy them.
Participant Object: an object in a media server that sources original
media in a call and/or receives and terminates media in a call.
Intermediary Object: an object in a media server that acts on media
within a call for the benefit of the participants.
Independent Object: an object that can exist on a media server
independent of other objects.
Operator: an intermediary transformer that modifies or transforms a
media stream. Examples of operators may be audio gain controls, video
scaling, or voice masking. MSML defines operators as media transform
objects, which transform media using operations such as gain control,
when applied to media streams.
Media Stream: a single media flow between two objects. A media stream
has a media type and may be unidirectional or bidirectional.
4. MSML SIP Usage
SIP is used to create and modify media sessions with a media server
according to the procedures defined in RFC 3261 [n1]. Often, SIP
third party call control [i4] will be used to create sessions to a
media server on behalf of end users. MSML is used to define and
change the service which a user connected to a media server will
receive. MSML clients are application servers, softswitches, or other
forms of control agents, and SHOULD have an authorized security
relationship with the media server. MSML itself does not define
authorization mechanisms.
MSML transactions are originated based upon events that occur in the
application domain. These events may be independent from any media or
user interaction. For example, an application may wish to play an
announcement to a conference warning that its scheduled completion
time is approaching. Applications themselves are structured in many
Saleem, et al. Expires - February 03 2009 [Page 6]
Internet-draft Media Server Markup Language August 2008
(MSML)
different ways. Their structure and requirements contribute to their
selection of protocols and languages. To accommodate differing
application needs, MSML has been designed to be neutral to other
languages and independent of the transport used to carry it.
MSML language is purposely designed to be transport independent. In
this release of the specification, SIP INFO [i5] and SIP Control
Framework [i13] have been chosen for transport mechanisms for MSML,
as described in the following sections.
4.1 SIP INFO
SIP INVITE and INFO [i5] requests and responses MAY be used to carry
MSML. INFO requests allow asynchronous mid-call messages within SIP
with few additional semantics. In addition, there are existing widely
deployed implementations of that method, it aids in initial
developments which are closely coupled with SIP session
establishment, and it allows MSML to be directly associated with user
dialogs when third party call control is used.
Although INFO is sometimes considered to not be a suitable general-
purpose transport mechanism for messages within SIP, there have been
proposals to make it more acceptable. MSML may evolve to include
other SIP usage and/or to work with other protocols or as a stand-
alone protocol established through SIP, in future releases of this
document.
MSML supports several models for client interaction. When clients use
3PCC to establish media sessions on behalf of end users, clients will
have a SIP dialog for each media session. MSML MAY be sent on these
dialogs. However the targets of MSML actions are not inferred from
the session associated with the SIP dialog. The targets of MSML
actions are always explicitly specified using identifiers as
previously defined.
An application, after interacting with a user, may want to affect
multiple objects within a media server. For example, tones or
messages are often played to a conference when connections are added
or removed. A separate message may also be played to a participant as
they are joined, or to moderators. Explicit identifiers, that is, not
inferred from a transport mechanism allow these multiple actions to
be easily grouped into a single transaction sent on any SIP dialog.
MSML also supports a model of dedicated control associations. This
supports decoupled application architectures where a client can
control media server services without also establishing all of the
media sessions itself. Control associations are created using SIP but
they do not have any associated media session. Although initially
Saleem, et al. Expires - February 03 2009 [Page 7]
Internet-draft Media Server Markup Language August 2008
(MSML)
INFO messages will be sent on this SIP dialog, just as with dialogs
associated with media sessions, it is possible that in the future,
the SIP dialog will be used to establish a separate control session
(defined in SDP [n9]) that does not use SIP as the transport for MSML
messages.
A media server using MSML also sends asynchronous events to a client
using MSML scripts in SIP INFO. Events are sent based on previous
MSML requests and are sent within the SIP dialog on which the MSML
request that caused the event to be generated was received. If this
dialog no longer exists when the event is generated, the event is
discarded.
Events may be generated during the execution of a dialog created by a
<dialogstart> element. For example, dialogs can send events based on
user input. VoiceXML dialogs, on the other hand, generally interact
with other servers outside of MSML using HTTP.
An event is also generated when the execution of a dialog terminates,
either because of completion or failure. The exact information
returned is dependent on the dialog language, the capabilities of the
dialog execution environment, and what was requested by the dialog.
Both MSML and VoiceXML [n5] allow information to be returned when
they exit. These events may be sent in a SIP INFO or a SIP BYE. SIP
BYE is used when the dialog itself specifies that the connection
should be disconnected, for example through the use of the
<disconnect> element.
Conferences may also generate events based upon their configuration.
An example of this is the notification of the set of active speakers.
4.2 SIP Control Framework
The SIP Control Framework [i13] MAY be used as a transport mechanism
for MSML.
The Control Framework provides a generic approach for establishment
and reporting capabilities of remotely initiated commands. The
framework utilizes many functions provided by the Session Initiation
Protocol [n1] (SIP) for the rendezvous and establishment of a
reliable channel for control interactions. Compared to SIP INFO, the
SIP Control Framework is a more general purpose transport mechanism
and one which is not constrained by limitations of the SIP INFO
mechanism.
The Control Framework also introduces the concept of a Control
Package, which is an explicit usage of the Control Framework for a
particular interaction set. This specification has already specified
Saleem, et al. Expires - February 03 2009 [Page 8]
Internet-draft Media Server Markup Language August 2008
(MSML)
a list of packages for MSML to control the Media Server in many
aspects, including basic dialog, advanced conferencing, advanced
dialog and audit service. Each of these packages has a unique Control
Package name assigned in order for MSML to be used with the Control
Framework.
This section fulfills the mandatory requirement for information that
MUST be specified during the definition of a Control Framework
Package, as detailed in SIP Control Framework [i13].
4.2.1 Control Framework Package Names
The Control Framework [i13] requires a Control Package definition to
specify and register a unique name.
MSML specification defines Control Package names using a hierarchical
scheme to indicate the inherited relationship across packages. For
example, package "msml-x" is derived from package "msml", and package
"msml-x-y" is derived from package "msml-x".
The following is a list of Control Package names reserved by the MSML
specification.
"msml": this Control Package supports MSML Core package as
specified in section 8.
"msml-conf": this Control Package supports MSML Conference
Core package as specified in section 9.
"msml-dialog": this Control Package supports MSML Dialog
Core package as specified in section 10.6.
"msml-dialog-base": this Control Package supports MSML
Dialog Base package as specified in section 10.7.
"msml-dialog-transform": this Control Package supports MSML
Dialog Transform package as specified in section
10.9.
"msml-dialog-group": this Control Package supports MSML
Dialog Group package as specified in section 10.8.
"msml-dialog-speech": this Control Package supports MSML
Dialog Speech package as specified in section
10.10.
Saleem, et al. Expires - February 03 2009 [Page 9]
Internet-draft Media Server Markup Language August 2008
(MSML)
"msml-dialog-fax-detect": this Control Package supports MSML
Dialog Fax Detection package as specified in
section 10.11.
"msml-dialog-fax-sendrecv": this Control Package supports
MSML Dialog Fax Send/Receive package as specified
in section 10.12.
"msml-audit": this Control Package supports MSML Audit Core
Package as specified in section 11.1.
"msml-audit-conf": this Control Package supports MSML Audit
Conference Package as specified in section 11.2.
"msml-audit-conn": this Control Package supports MSML Audit
Connection Package as specified in section 11.3.
"msml-audit-dialog": this Control Package supports MSML
Audit Dialog Package as specified in section 11.4.
"msml-audit-stream": this Control Package supports MSML
Audit Stream Package as specified in section 11.5.
An Application Server using the Control Framework as transport for
MSML, MUST use one or multiple package names, depending on the
service required from the Media Server. The package name(s) are
identified in the "Control-Packages" SIP header that is present in
the SIP INVITE dialog request that creates the control channel, as
specified in [i13]. The "Control-Packages" value MAY be re-negotiated
via the SIP re-INVITE mechanism.
4.2.2 Control Framework Messages
The usage of CONTROL, response and REPORT messages, as defined in
[i13], by each Control Package defined in MSML is different and
described separately in the following sections.
MSML Core Package "msml"
The Application Server may send CONTROL message with a body of
MSML request using following elements to the MS:
<msml>: the root element that may contain a list of child
elements which request a specific operation. The child
elements are defined in extended packages (eg. "msml-conf" and
"msml-dialog"). This element is also the root element which
contains MSML result and event.
Saleem, et al. Expires - February 03 2009 [Page 10]
Internet-draft Media Server Markup Language August 2008
(MSML)
<send>: sends an event to the specified recipient within the
Media Server. Specific event types are defined within the
extended packages.
The Media Server replies with a response message containing a
MSML result using the following elements:
<result>: reports the results of an MSML transaction.
The Media Server MAY send MSML event to the Application
Server, in a REPORT or CONTROL message, using element <event>.
The actual content of the <event> and which Control Framework
message to use is defined within the extended packages.
MSML Conference Core Package "msml-conf"
This package extends the MSML Core Package to define a
framework for creation, manipulation and deletion of a
conference.
AS can send CONTROL message with a body of MSML request which
contains one or multiple conference related commands to MS. MS
then replies with a response message with a body of MSML
result to indicate if the request has been fulfilled or not.
During the lifetime of a conference, whenever an event occurs,
the Media Server MAY send CONTROL messages containing MSML
events to notify the Application Server. The Application
Server SHOULD reply with a response message with no MSML body
to acknowledge the event has been received.
This package does NOT use the REPORT message.
Dialog Core Package "msml-dialog"
This package extends the MSML Core Package to define the
structural framework and abstractions for MSML dialogs.
The Application Server MAY send CONTROL messages containing a
MSML request using following elements:
<dialogstart>: instantiate an MSML media dialog on a
connection or a conference.
<dialogend>: terminates a MSML dialog.
Saleem, et al. Expires - February 03 2009 [Page 11]
Internet-draft Media Server Markup Language August 2008
(MSML)
<send>: sends an event and an optional namelist to the dialog,
dialog group, or dialog primitive.
<exit>: used by the dialog description language to cause the
execution of the MSML dialog to terminate.
For the <dialogstart> command, the response message MUST
contain a MSML result which indicates that the dialog has been
started successfully. The MSML result MAY contain <dialogid>
to return dialog identifier, if the identifiers was assigned
by the Media Server. Subsequently, zero of more MSML events
MAY be initiated by the Media Server in (update) REPORT
messages to report information gathered during the dialog.
Finally, a MSML event "msml.dialog.exit" SHOULD be generated
in a (terminate) REPORT message when the dialog terminates
(eg. MSML execution of <exit>).
For the <dialogend> and <send> commands, the response message
contains the final MSML result which indicates that the
request has either been fulfilled or rejected.
Dialog Base Package "msml-dialog-base"
This package extends the MSML Dialog Core Package to define a
set of base functionality for MSML dialogs. The extension
defines individual media primitives, including <play>,
<dtmfgen>, <tonegen>, <record>, <dtmf> and <collect>, to be
used as child element of <dialogstart>. This package does not
change the framework message usage as defined by the MSML
Dialog Core Package.
Dialog Transform Package "msml-dialog-transform"
This package extends the MSML Dialog Core Package to define a
set of transform primitives which works as filter on half
duplex media streams. The extension defines transform
primitives, including <vad>, <gain>, <agc>, <gate>, <clamp>
and <relay>, which MAY be used as child elements of
<dialogstart>. This package does not change the framework
message usage as defined by the MSML Dialog Core Package.
Dialog Group Package "msml-dialog-group"
This package extends the MSML Dialog Core, Base and Transform
Packages to define a single control flow construct that
Saleem, et al. Expires - February 03 2009 [Page 12]
Internet-draft Media Server Markup Language August 2008
(MSML)
specifies concurrent execution of multiple media primitives.
The extension defines the <group> element which MAY be used as
a child element of <dialogstart> to enclose multiple media
primitives, such that they can be executed concurrently. This
package does not change the framework message usage as defined
by the MSML Dialog Core Package.
Dialog Speech Package "msml-dialog-speech"
This package extends the MSML Dialog Core and MSML Base
Package to define functionality which MAY be used for
automatic speech recognition and text-to-speech. The extension
extends the <dialogstart> and the <play> elements.
For <dialogstart>, it defines a new child element <speech> to
activate grammars or user input rules associated with speech
recognition. For <play>, it defines a new child element <tts>
to initiate the text-to-speech service.
This package does not change the framework message usage as
defined by the MSML Dialog Core Package.
Dialog Fax Detection Package "msml-dialog-fax-detect"
This package extends the MSML Dialog Core Package to define
primitives provide fax detection service. The extension
defines a primitive <faxdetect> to be used as a child element
of <dialogstart>. This package does not change the framework
message usage as defined by the MSML Dialog Core Package.
Dialog Fax Send/Receive Package "msml-dialog-fax-sendrecv"
This package extends the MSML Dialog Core Package to define
primitives which allow a media server to provide fax send or
receive service. The extension defines new primitives
<faxsend> and <faxrcv>, to be used as child element of
<dialogstart>. This package does not change the framework
message usage as defined in MSML Dialog Core Package.
Dialog Audit Core Package "msml-audit"
Saleem, et al. Expires - February 03 2009 [Page 13]
Internet-draft Media Server Markup Language August 2008
(MSML)
This package extends the MSML Core Package to define a
framework for auditing media resource(s) allocated on the
Media Server.
This package follows a simple request/response transaction,
allowing the Application Server to send CONTROL messages
containing MSML <audit> requests. The Media Server MUST reply
with a response message containing the result. The result is
contained within the <auditresult> element, returning the
queried state information.
This package does NOT use the REPORT message.
Dialog Audit Conference Package "msml-audit-conf"
This package extends the MSML Audit Core Package to define
conference specific states which MAY be queried via the
<audit> command and the corresponding response MUST be
returned by the <auditresult> element. This package does not
change the framework message usage as defined by the MSML
Audit Core Package.
Dialog Audit Connection Package "msml-audit-conn"
This package extends the MSML Audit Core Package to define
connection specific states which MAY be queried via the
<audit> command and the corresponding response MUST be
returned by the <auditresult> element. This package does not
change the framework message usage as defined by the MSML
Audit Core Package.
Dialog Audit Dialog Package "msml-audit-dialog"
This package extends the MSML Audit Core Package to define
dialog specific states which MAY be queried via the <audit>
command and the corresponding response MUST be returned by the
<auditresult> element. This package does not change the
framework message usage as defined by the MSML Audit Core
Package.
Dialog Audit Stream Package "msml-audit-stream"
This package extends the MSML Audit Core Package to define
stream specific states which MAY be queried via the <audit>
Saleem, et al. Expires - February 03 2009 [Page 14]
Internet-draft Media Server Markup Language August 2008
(MSML)
command and the corresponding response MUST returned by the
<auditresult> element. This package does not change the
framework message usage as defined by the MSML Audit Core
Package.
4.2.3 Common XML Support
The XML schema described in [i13] MUST be supported by all Control
Packages defined by MSML. However, the "connection-id" value MUST be
constructed as defined by MSML (i.e. the identifier MUST contain
local dialog tag only, while the SIP Control Framework [i13] requires
that the "connection-id" contain both local and remote dialog tags).
4.2.4 Control Message Body
A valid CONTROL body message MUST conform to the MSML schema, as
included in this specification, for the MSML package(s) used.
4.2.5 REPORT Message Body
A valid REPORT body message MUST conform to the MSML schema, as
included in this specification, for the MSML package(s) used.
5. Language Structure
5.1 Package Scheme
The primary mechanism for extending MSML is the "package". A package
is an integrated set of one or more XML schemas that define
additional features and functions via new or extended use of elements
and attributes. Each package, except for those defined in the current
document, is defined in a separate standards document, e.g., an
Internet Draft or an RFC. All packages, that extend the base MSML
functionality, MUST include references to the MSML base set of
schemas provided in the Internet drafts. A schema in a package MUST
only extend MSML, this is, it must not alter the existing
specification.
A particular MSML script will include references to all the schemas
defining the packages whose elements and attributes it makes use of.
A particular script MUST reference MSML base and optionally extension
package(s). See IANA Considerations section.
Each package MUST define its own namespace so that elements or
attributes with the same name in different packages do not conflict.
A script using a particular element or attribute MUST prefix the
namespace name on that element or attribute's name if it is defined
in a package (as opposed to being defined in the base).
Saleem, et al. Expires - February 03 2009 [Page 15]
Internet-draft Media Server Markup Language August 2008
(MSML)
MSML consists of a core package which provides structure without
support for any specific feature set. Additional packages, relying on
the core package, provide functional features. Any combination of
additional packages may be used along with the core package. The
following describes the set of MSML packages defined in this
document.
+--------------------------------------------------------+
| MSML Core |
+--------------------------------------------------------+
/ \ \
+--------+ +--------+ +-------+
| Dialog | | Conf | | Audit |
| Core | | Core | | Core |
+--------+ +--------+ +-------+
________ \_______________________________________ |
------------------------------------------------ |
/ \ \ \ \ \ |
+------+ +---------+ +------+ +------+ +------+ +-------+ |
|Dialog| |Dialog | |Dialog| |Dialog| |Dialog| |Dialog | |
|Base | |Transform| |Group | |Speech| |Fax | |Fax | |
+------+ +---------+ +------+ +------+ |Detect| |Send/ | |
+------+ |Receive| |
+-------+ |
________________________|
-------------------------
/ \ \ \
+-----+ +-----+ +------+ +------+
|Audit| |Audit| |Audit | |Audit |
|Conf | |Conn | |Dialog| |Stream|
+-----+ +-----+ +------+ +------+
o MSML Core package (Mandatory)
Describes the minimum base framework which MUST be implemented
to support additional core packages.
o MSML Conference Core package (Conditionally Mandatory, for
Conferencing)
Describes the audio and multimedia basic and advanced
conferencing package, which MAY be implemented.
o MSML Dialog Core package (Conditionally Mandatory, for Dialogs)
Describes the dialog core package which MUST be implemented for
any dialog services. However, systems supporting conferencing
Saleem, et al. Expires - February 03 2009 [Page 16]
Internet-draft Media Server Markup Language August 2008
(MSML)
only, MAY omit support for MSML dialogs. The MSML dialog core
package specifies the framework within which additional dialog
packages are supported. The MSML dialog base package MUST be
supported, while all other dialog packages MAY be supported.
o MSML Dialog Base package (Conditionally Mandatory, for
Dialogs)
o MSML Dialog Group package (Optional)
o MSML Dialog Transform package (Optional)
o MSML Dialog Fax Detection package (Optional)
o MSML Dialog Fax Send/Receive package (Optional)
o MSML Dialog Speech package (Optional)
o MSML Audit Core package (Conditionally Mandatory, for Auditing)
Describes the audit core package which MUST be implemented to
support auditing services. The MSML audit core package
specifies the framework within which additional audit packages
are supported.
o MSML Audit Conference package (Conditionally Mandatory, for
Auditing Conference, Conference Dialog and Conference Stream)
o MSML Audit Connection package (Conditionally Mandatory, for
Auditing Connection, Connection Dialog and Connection Stream)
o MSML Audit Dialog package (Conditionally Mandatory, for
Auditing Dialog, and MUST be used with either MSML Audit
Conference Package or MSML Audit Connection Package)
o MSML Audit Stream package (Conditionally Mandatory, for
Auditing Stream, and MUST be used with either MSML Audit
Conference Package or MSML Audit Connection Package)
The formal process for defining extensions to MSML Dialogs is to
define a new package. The new package MUST provide a text description
of what extensions are included and how they work. It MUST also
define an XML schema file (if applicable) that defines the new
package (which may be through extension, restriction of an existing
package, or a specific profile of an existing package). Dependencies
upon other packages MUST be stated. For example a package that
extends or restricts has a dependency on the original package
Saleem, et al. Expires - February 03 2009 [Page 17]
Internet-draft Media Server Markup Language August 2008
(MSML)
specification. Finally, the new package MUST be assigned a unique
name and version.
The types of things which can be defined in new packages are:
o new primitives
o extensions to existing primitives (events, shadow variables,
attributes, content)
o new recognition grammars for existing primitives
o new markup languages for speech generation
o languages for specifying a topology schema
o new pre-defined topology schemas
o new variables / segment types (sets & languages)
o new control flow elements
MSML Packages are assembled together to form a specific MSML profile
that is shared between different implementations. The base MSML
Dialog profiles which are defined in this document consist of the
MSML Core package, MSML Dialog Core package, MSML Dialog Base
package, MSML Dialog Group package, MSML Transform package, MSML Fax
packages, and the MSML Speech package.
MSML extension packages, which define primitives, MUST define the
following for each primitive within the package:
o the function which the primitive performs
o the attributes which may be used to tailor its behavior
o the events which it is capable of understanding
o the shadow variables which provide access to information
determined as a result of the primitive's operation.
The mechanism used to insure that a media server and its client share
a compatible set of packages is not defined. Currently it is expected
that provisioning will be used, possibly coupled with a future
auditing capability. Additionally, when used in SIP networks,
packages could be defined using feature tags and the procedures
defined for Indicating User Agent Capabilities in SIP [i1] used to
Saleem, et al. Expires - February 03 2009 [Page 18]
Internet-draft Media Server Markup Language August 2008
(MSML)
allow a media server to describe its capabilities to other user
agents.
5.2 Profile Scheme
Not all devices and applications using MSML will need to support the
entire MSML schema. For example, a media processing device might
support only audio announcements, only audio simple conferencing, or
only multimedia IVR. It is highly desirable to have a system for
describing what portion of MSML a particular media processing device
or Control Agent supports.
The Package scheme described earlier allows MSML functionality to be
functionally grouped, relying on the MSML core package. This scheme
allows a portion of the complete MSML specification to be
implemented, on a per package basis and also creates a framework for
future extension packages. However, within a given package, in some
cases, only a subset of the package functionality may be required. In
order to support subsets of packages, with greater degree of
granularity than at the package level, a profile scheme is required.
MSML package profiles would identify a subset of a given MSML package
with specific definitions of elements and attributes. Each MSML
package profile MUST be accompanied by one or more corresponding
schemas. To use the examples above, there could be an audio
announcements profile of the MSML Dialog Base package, an audio
simple conferencing profile of the MSML Conference Core package, and
a multimedia IVR profile of the MSML Dialog Base package.
MSML package profiles MUST be published separately from the MSML
specification, in one or more standards documents (e.g., Internet
Drafts or RFCs) dedicated to MSML package profiles. Profiles would
not be registered with IANA and any organization would additionally
be free to create its own profile(s) if required.
6. Execution Flow
MSML assumes a model where there is a single control context within a
media server for MSML processing. That context may have one or many
SIP [n1] dialogs associated with it. It is assumed that any SIP
dialogs associated with the MSML control context have been
authorized, as appropriate, by mechanisms outside the scope of MSML.
A media server control context maintains information about the state
of all media objects and media streams within a media server. It
receives and processes all MSML requests from authorized SIP dialogs
and receives all events generated internally by media objects and
sends them on the appropriate SIP dialog. An MSML request is able to
Saleem, et al. Expires - February 03 2009 [Page 19]
Internet-draft Media Server Markup Language August 2008
(MSML)
create new media objects and streams, and to modify or destroy any
existing media objects and streams.
An MSML request may simply specify a single action for a media server
to undertake. In this case, the document is very similar to a simple
command request. Often, though, it may be more natural for a client
to request multiple actions at one time, or the client would like
several actions to be closely coordinated by the media server.
Multiple MSML elements received in a single request MUST be processed
sequentially in document order.
An example of the first scenario would be to create a conference and
join it with an initial participant. An example of the second case
would be to unjoin one or more participants from a main conference
and join them to a sidebar conference. In the first scenario, network
latencies may not be an issue, but it is simpler for the client to
combine the requests. In the second case, the added network latency
between separate requests could mean perceptible audio loss to the
participant.
Each MSML request is processed as a single transaction. A media
server MUST ensure that it has the necessary resources available to
carry out the complete transaction before executing any elements of
the request. If it does not have sufficient resources, it MUST return
a 520 response and MUST NOT execute the transaction.
The MSML request MUST be checked for well-formedness and validated
against the schema prior to executing any elements. This allows XML
[n2] errors to reported immediately and minimizes failures within a
transaction and the corresponding execution of only part of the
transaction.
Each element is expected to execute immediately. Elements such as
<dialogstart>, which take an unpredictable amount of time, are
"forked" and executed in a separate thread (see MSML Dialog
packages). Once successfully forked, execution continues with the
element following the </dialogstart>. As such, MSML does not provide
mechanisms to sequence or coordinate other operations with dialog
elements.
Processing within a transaction MUST stop if any errors occur.
Elements that were executed prior to the error are not rolled back.
It is the responsibility of the client to determine appropriate
actions based upon the results indicated in the response. Most
elements MAY contain an optional "mark" attribute. The value of that
attribute from the last successfully executed element MUST be
returned in an error response. Note that errors that occur during the
Saleem, et al. Expires - February 03 2009 [Page 20]
Internet-draft Media Server Markup Language August 2008
(MSML)
execution of a dialog occur outside the context of an MSML
transaction. These errors will be indicated in an asynchronous event.
Transaction results are returned as part of the SIP request response.
The transaction results indicate the success or failure of the
transaction. The result MUST also include identifiers for any objects
created by a media server for which the client did not provide an
instance name. Additionally, if the transaction fails, the reason for
the failure MUST be returned, as well as an indication of how much of
the transaction was executed before the failure occurred SHOULD be
returned.
7. Media Server Object Model
Media servers are general-purpose platforms for executing real-time
media processing tasks. These tasks range in complexity from simple
ones such as serving announcements, to complex ones, such as speech
interfaces, centralized multimedia conferencing, and sophisticated
gaming applications.
Calls are established to a media server using SIP. Clients will often
use SIP third party call control (3PCC) [i4] to establish calls to a
media server on behalf of end users. However MSML does not require
that 3PCC be used; only that the client and the media server share a
common identifier for the call and its associated RTP [i3] sessions.
Objects represent entities which source, sink, or modify media
streams. A media streams is a bidirectional or unidirectional media
flow between objects on a media server. The following subsections
define the classes of objects that exist on a media server and the
way these are identified in MSML.
7.1 Objects
A media object is an endpoint of one or more media streams. It may be
a connection that terminates RTP sessions from the network or a
resource that transforms or manipulates media. MSML defines four
classes of media objects. Each class defines the basic properties of
how object instances are used within a media server. However, most
classes require that the function of specific instances be defined by
the client, using MSML or other languages such as VoiceXML.
The following classes of media processing objects are defined. The
class names are given in parentheses:
o network connection (conn)
o conference (conf)
Saleem, et al. Expires - February 03 2009 [Page 21]
Internet-draft Media Server Markup Language August 2008
(MSML)
o dialog (dialog)
Network connection is an abstraction for the media processing
resources involved in terminating the RTP session(s) of a call. For
audio services a connection instance presents a full-duplex audio
stream interface within a media server. Multimedia connections have
multiple media streams of different media types, each corresponding
to an RTP session. Network connections get instantiated through SIP
[n1].
A conference represents the media resources and state information
required for a single logical mix of each media type in the
conference (e.g. audio and video). MSML models multiple mixes/views
of the same media type as separate conferences. Each conference has
multiple inputs. Inputs may be divided into classes that allow an
application to request different media treatment for different
participants. For example, the video streams for some participants
may be assigned to fixed regions of the screen while those for other
participants may only be shown when they are speaking.
A conference has a single logical output per media type. For each
participant, it consists of the audio conference mix, less any
contributed audio of the participant, and the video mix shared by all
conference participants. Video conferences using voice activated
switching have an optional ability to show the previous speaker to
the current speaker.
Conferences are instantiated using the <createconference> element.
The content of the <createconference> element specifies the
parameters of the audio and/or video mixes.
Dialogs are a class of objects that represent automated participants.
They are similar to network connections from a media flow perspective
and may have one or more media streams as the abstraction for their
interface within a media server. Unlike connections however, dialogs
are created and destroyed through MSML, and the media server itself
implements the dialog participant. Dialogs are instantiated through
the <dialogstart> element. Contents of the <dialogstart> element
define the desired or expected dialog behavior. Dialogs may also be
invoked by referencing VoiceXML as the dialog description language.
Operators are functions that are used to filter or transform a media
stream. The function that an instance of an operator fulfills is
defined as a property of the media stream. Operators may be
unidirectional or bidirectional and have a media type. Unidirectional
operators reflect simple atomic functions such as automatic gain
control, filtering tones from conferences, or applying specific gain
values to a stream. Unidirectional operators have a single media
Saleem, et al. Expires - February 03 2009 [Page 22]
Internet-draft Media Server Markup Language August 2008
(MSML)
input, which is connected to the media stream from one object, and a
single media output, which is connected to the media stream of a
different object.
Bidirectional operators have two media inputs and two media outputs.
One media input and output is associated with the stream to one
object and the other input and output is associated with a stream to
a different object. Bidirectional objects may treat the media
differently in each direction. For example, an operator could be
defined which changed the media sent to a connection based upon
recognized speech or DTMF received from the connection. Operators are
implicitly instantiated when streams are created or modified using
the elements <join> and <modifystream> respectively.
The relationships between the different object classes (conf, conn,
and dialog) are shown in the figure below.
+--------------------------------------+
| Media Server |
| |
|------+ ,---. |
| | +------+ / \ |
<== RTP ==>| conn |<---->| oper |<---->( conf ) |
| | +------+ \ / |
|------+ `---' |
| ^ ^ |
| | | |
| | +------+ +------+ | |
| | | | | | | |
| +-->|dialog| |dialog|<---+ |
| | | | | |
| +------+ +------+ |
+--------------------------------------+
A single, full-duplex instance of each object class is shown together
with common relationships between them. An operator (such as gain) is
shown between a connection and a conference and dialogs are shown
participating both with an individual connection and with a
conference. The figure is not meant to imply only one to one
relationships. Conferences will often have hundreds of participants,
and either connections or conferences may be interacting with more
than one dialog. For example, one dialog may be recording a
conference while other dialogs announce participants joining or
leaving the conference.
Saleem, et al. Expires - February 03 2009 [Page 23]
Internet-draft Media Server Markup Language August 2008
(MSML)
7.2 Identifiers
Objects are referenced using identifiers that are composed of one or
more terms. Each term specifies an object class and names a specific
instance within that class. The object class and instance are
separated by a colon ":" in an identifier term.
Identifiers are assigned to objects when they are first created. In
general, either the MSML client or a media server may specify the
instance name for an object. Objects for which a client does not
assign an instance name will be assigned one by a media server. Media
server assigned instance names are returned to the client as a
complete object identifier in the response to the request that
created the object.
It is meaningful for some classes of objects to exist independently
on a media server. Network connections may be created through SIP at
any time. MSML can then be used to associate their media with other
objects as required to create services. Conferences may be created
and have specific resources reserved waiting for participant
connections.
Objects from these two classes, connections and conferences, are
considered independent objects since they can exist on a standalone
basis. Identifiers for independent objects consist of single term as
defined above. For example, identifiers for a conference and
connection could be "conf:abc" or "conn:1234" respectively. Clients
which choose to assign instance names to independent objects must use
globally unique instance names. One way to create globally unique
names is to include the domain name of the client as part of the
name.
Dialogs are created to provide a service to independent objects.
Dialogs may act as a participant in a conference or interact with a
connection similar to a two participant call. Dialogs depend upon the
existence of independent objects and this is reflected in the
composition of their identifiers. Operators modify the media flow
between other objects, such as application of gain between a
connection and a conference. As operators are merely media transform
primitives defined as properties of the media stream, they are not
represented by identifiers and created implicitly.
Identifiers for dialogs are composed of a structured list of slash
('/') separated terms. The left-most term of the identifier must
specify a conference or connection. This serves as the root for the
identifier. An example of an identifier for a dialog acting as a
conference participant could be:
Saleem, et al. Expires - February 03 2009 [Page 24]
Internet-draft Media Server Markup Language August 2008
(MSML)
conf:abc/dialog:recorder
All objects except connections are created using MSML. Connections
are created when media sessions get established through SIP. There
are several options clients and media servers can use to establish a
shared instance name for a connection and its media streams.
When media servers support multiple media types, the instance name
SHOULD be a call identifier that can be used to identify the
collection of RTP sessions associated with a call. When MSML is used
in conjunction with SIP and third party call control, the call
identifier MUST be the same as the local tag assigned by the media
server to identify the SIP dialog. This will be the tag the media
server adds to the "To" header in its response to an initial invite
transaction. RFC 3261 requires the tag values to be globally unique.
An example of a connection identifier is: conn:74jgd63956ts.
With third party call control, the MSML client acts as a back to back
user agent (B2BUA) to establish the media sessions. SIP dialogs are
established between the client and the media server allowing the use
of the media server local tag as a connection identifier. If third
party call control is not used, a SIP event package MAY be used to
allow a media server to notify new sessions to a client that has
subscribed to this information.
Identifiers as described above allow every object in a media server
to be uniquely addressed. They can also be used to refer to multiple
objects. There are two ways in which this can currently be done:
wildcards
common instance names
An identifier can reference multiple objects when a wildcard is used
as an instance name. MSML reserves the instance name comprised of a
single asterisk ('*') to mean all objects that have the same
identifier root and class. Instance names containing an asterisk
cannot be created. Wildcards MUST only be used as the right most term
of an identifier and MUST NOT be used as part of the root for dialog
identifiers. Wildcards are only allowed where explicitly indicated
below.
The following are examples of valid wildcards:
conf:abc/dialog:*
conn:*
Saleem, et al. Expires - February 03 2009 [Page 25]
Internet-draft Media Server Markup Language August 2008
(MSML)
Examples of illegal wildcard usage are:
conf:*/dialog:73849
Although identifiers share a common syntax, MSML elements restrict
the class of objects which are valid in a given context. As an
example, although it is valid to join two connections together, it is
not valid to join two IVR dialogs.
8. MSML Core Package
This section describes the core MSML package which MUST be supported
in order to use any other MSML packages. The core MSML package
defines a framework, without explicit functionality, over which
functional packages are used.
8.1 <msml>
<msml> is the root element. When received by a media server, it
defines the set of operations that form a single MSML request.
Operations are requested by the contents of the element. Each
operation MAY appear zero or more times as children of <msml>.
Specific operations are defined within the Conference package and in
the set of Dialog packages.
The results of a request or the contents of events sent by a media
server are also enclosed within the <msml> element. The results of
the transaction are included as a body in the response to the SIP
request that contained the transaction. This response will contain
any identifiers that the media server assigned to newly created
objects. All messages that a media server generates are correlated to
an object identifier. Objects and identifiers are discussed in
section 7 (Media Server Object Model).
Attributes:
version: "1.1" Mandatory
8.2 <send>
Events are used to affect the behavior of different objects within a
media server. The <send> element is used to send an event to the
specified recipient within the Media Server.
Attributes:
event: the name of an event. Mandatory.
Saleem, et al. Expires - February 03 2009 [Page 26]
Internet-draft Media Server Markup Language August 2008
(MSML)
target: an object identifier. When the identifier is for a
dialog, it may optionally be appended with a slash "/" followed
by the target to be included in a MSML Dialog <send>.
Mandatory.
valuelist: a list of zero or more parameters that are included
with the event.
mark: a token that can be used to identify execution progress
in the case of errors. The value of the mark attribute from the
last successfully executed MSML element is returned in an error
response. Therefore the value of all mark attributes within an
MSML document should be unique.
8.3 <result>
The <result> element is used to report the results of an MSML
transaction. It is included as a body in the final response to the
SIP request which initiated the transaction. An optional child
element <description> may include text which expands on the meaning
of error responses. Response codes are defined in section 11
(Response Codes).
Attributes:
response: a numeric code indicating the overall success or
failure of the transaction, and in the case of failure, an
indication of the reason. Mandatory.
mark: in the case of an error, the value of the mark attribute
from the last successfully executed element that included the
mark attribute.
In the case of failure, a description of the reason SHOULD be
provided using the child element <description>.
Three other child elements allow the response to include identifiers
for objects created by the request but which did not have instance
names specified by the client. Those elements are <confid> and
<dialogid>, for objects created though a <createconference> and
<dialogstart> respectively.
8.4 <event>
The <event> element is used to notify an event to a media server
client. Three types of events are defined by MSML Core package;
"msml.dialog.exit", "msml.conf.nomedia", and "msml.conf.asn". These
correspond to the termination of an executing dialog, a conference
Saleem, et al. Expires - February 03 2009 [Page 27]
Internet-draft Media Server Markup Language August 2008
(MSML)
being automatically deleted when the last participant has left, and
the notification of the current set of active speakers for a
conference, respectively. Events may also be generated by an
executing dialog. In this case the event type is specified by the
dialog. (see MSML Dialog Core Package <send>).
Attributes:
name: the type of event. If the event is generated because of
the execution MSML Dialog <send>, the value MUST be the value
of the "event" attribute from the <send> element within the
MSML Dialog Core package. If the event is generated because of
the execution of an <exit>, the value MUST be "moml.exit". If
the event is generated because of the execution of a
<disconnect>, the value MUST be "moml.disconnect". If the event
is generated because of an error, the value must be
"moml.error". Mandatory.
id: the identifier of the conference or dialog that generated
the event or caused the event to be generated. Mandatory.
<event> has two children, <name> and <value>, which contain the
name and value respectively of each namelist item associated
with the event.
9. MSML Conference Core Package
9.1 Conferences
A conference has a mixer for each type of media that the conference
supports. Each mix has a corresponding description that defines how
the media from participants contributes to that mix. A mixer has
multiple inputs that are combined in a media specific way to create a
single logical output.
The elements that describe the mix for each media type are called
mixer description elements. They are:
<audiomix> defines the parameters for mixing audio media.
<videolayout> defines the composition of a video window.
These elements, defined in sections 9.6 (Audio Mix) and 9.7 (Video
Layout) respectively, are used as content of the <createconference>
element to establish the initial properties of a conference. The
elements are used within the <modifyconference> element to change the
properties of a conference once it has been created, or within the
Saleem, et al. Expires - February 03 2009 [Page 28]
Internet-draft Media Server Markup Language August 2008
(MSML)
<destroyconference> element to remove individual mixes from the
conference.
Conferences may be terminated by an MSML client using the
<destroyconference> element to remove the entire conference or by
removing the last mixer(s) associated with the conference.
Conferences can also be terminated automatically by a media server
based on criteria specified when the conference is created. When the
conference is deleted, any remaining participants will have their
associated SIP dialogs left unchanged or deleted based on the value
of the "term" attribute specified when the conference was created.
9.2 Media Streams
Objects have at least one media input and output for each type of
media that they support. Each object class defines the number of
inputs and outputs objects of that class support. Media streams are
created when objects are joined, either explicitly using <join>, or
implicitly when dialogs are created using <dialogstart>. Dialog
creation has two stages, allocating and configuring the resources
required for the dialog instance, and implicitly joining those
resources to the dialog target during the dialog execution. Refer to
MSML Dialog Base package.
A join operation by default creates a bidirectional audio stream
between two objects. Video and unidirectional streams may also be
created. A media stream is created by connecting the output from one
object to the input of another object and vice versa (assuming a
bidirectional or full-duplex join).
Many objects may only support a single input for each type of media.
Within this specification, only the conference object class supports
an arbitrary number of inputs. When a stream is requested to be
created to an object that already has a stream of the same type
connected to its single input, the result of the request depends upon
the type of the media stream.
Audio mixing is done by summing audio signals. Automatically mixing
audio streams has common and straight forward applications. For
example, the ability to bridge two streams allows for the easy
creation of simple three-way calls or to bridge private announcements
with a [whispered] conference mix for an individual participant. In
the case of general conferences however, an MSML client SHOULD create
an audio conference and then join participants to the conference.
Conference mixers SHOULD subtract the audio of each participant from
the mix so that they do not hear themselves.
Saleem, et al. Expires - February 03 2009 [Page 29]
Internet-draft Media Server Markup Language August 2008
(MSML)
A media server that receives a request that requires joining an audio
stream to the single audio input of an object that already has an
audio stream connected, SHOULD automatically bridge the new stream
with the existing stream, creating a mix of the two audio streams.
The maximum number of streams that may be bridged in this manner is
implementation-specific. It is RECOMMENDED that a media server
support bridging at least two streams. A media server that cannot
bridge a new stream with any existing streams MUST fail the operation
requesting the join.
Unlike audio mixing, there are many different ways that two video
streams may be combined and presented. For example, they may be
presented side by side in separate panes, picture in picture, or in a
single pane which displays only a single stream at a time based on a
heuristic such as active speaker. Each of these options creates a
very different presentation and require significantly different media
resources.
A join operation does not describe how a new stream can be combined
with an existing stream. Therefore automatic bridging of video is not
supported. A media server MUST fail requests to join a new video
stream to an object that only supports a single video input and
already has a video stream connected to that input. For an object to
have multiple video streams joined to it, the object itself must be
capable in supporting multiple video streams. Conference objects can
support multiple video streams and provide a way to specify the
mixing presentation for the video streams.
A media server MUST NOT establish any streams unless the media server
is able to create all the streams requested by an operation. Streams
are only able to be created if both objects support a media type and
at least one of the following conditions is true:
1. each object that is to receive media is not already receiving a
stream of that type.
2. any object that is to receive media and is already receiving a
stream of that type supports receiving an additional stream of
that type. The only class of objects defined in this
specification that directly support receiving multiple streams
of the same type are conferences.
3. the media server is able to automatically bridge media streams
for an object that is to receive media and that is already
receiving a stream of the requested type. The only type of
media defined in this specification that MAY be automatically
bridged is audio.
Saleem, et al. Expires - February 03 2009 [Page 30]
Internet-draft Media Server Markup Language August 2008
(MSML)
The directionality of media streams associated with a connection are
modeled independently from what SDP [n9] allows for the corresponding
RTP [i3] sessions. Media servers MUST respect the SDP in what they
actually transmit but MUST NOT allow the SDP to affect the
directionality when joining streams internal to the media server.
9.3 <createconference>
<createconference> is used to allocate and configure the media mixing
resources for conferences. A description of the properties for each
type of media mix required for the conference is defined within the
content of the <createconference> element. Mixer descriptions are
described in Audio Mix and Video Layout sections. When no mixer
descriptions are specified, the default behavior MUST be equivalent
to inclusion of a single <audiomix>.
Clients can request that a media server automatically delete a
conference when a specified condition occurs by using the
"deletewhen" attribute. A value of "nomedia" indicates that the
conference MUST be deleted when no participants remain into the
conference. When this occurs, an "msml.conf.nomedia" event MUST be
notified to the MSML client. A value of "nocontrol" indicates the
conference MUST be deleted when the SIP [n1] dialog that carries the
<createconference> element is terminated. When this occurs, a media
server MUST terminate all participant dialogs by sending a BYE for
their associated SIP dialog. A value of "never" MUST leave the
ability to delete a conference under the control of the MSML client.
Attributes:
name: the instance name of the conference. If the attribute is
not present, the media server MUST assign a globally unique
name for the conference. If the attribute is present but the
name is already in use, an error (432) will result and MSML
document execution MUST stop. Events which the conference
generates use this name as the value of their "id" attribute
(see section 5.6.2 (<event>)).
deletewhen: defines whether a media server should automatically
delete the conference. Possible values are "nomedia",
"nocontrol", and "never". Default is "nomedia".
term: when true, the media server MUST send a BYE request on
all SIP dialogs still associated with the conference when the
conference is deleted. Setting term equal to false allows
clients to start dialogs on connections once the conference has
completed. Default true.
Saleem, et al. Expires - February 03 2009 [Page 31]
Internet-draft Media Server Markup Language August 2008
(MSML)
mark: a token which MAY be used to identify execution progress
in the case of errors. The value of the mark attribute from the
last successfully executed MSML element is returned in an error
response. Therefore the value of all mark attributes within an
MSML document should be unique.
An example of creating an audio conference is shown below. This
conference allows at most two participants to contend to be heard and
reports the set of active speakers no more frequently than every ten
seconds.
<?xml version="1.0" encoding="UTF-8"?>
<msml version="1.1">
<createconference name="example">
<audiomix>
<n-loudest n="3"/>
<asn ri="10s"/>
</audiomix>
</createconference>
</msml>
9.3.1 <reserve>
Conference resources may be reserved by including the <reserve>
element as a child of <createconference>. <reserve> allows the
specification of a set of resources which a media server will reserve
for the conference. Any requests for resources beyond those that have
been reserved should be honored on a best-effort basis by a media
server.
Attributes:
required: boolean that specifies whether <createconference>
should fail if the requested resources are not available. When
set to false, the conference will be created, with no reserved
resources, if the complete reservation cannot be honored.
Default true.
9.3.1.1 <resource>
The resources to be reserved are defined using <resource>. The
contents of these elements describe a resource that is to be
reserved. Descriptions are implementation-dependent. Media servers
that support MSML Dialogs may use the elements from that package as
the basis for resource descriptions. Each resource element may use
the attribute "n" to define the quantity of the resource to reserve.
Saleem, et al. Expires - February 03 2009 [Page 32]
Internet-draft Media Server Markup Language August 2008
(MSML)
For example, the following creates a conference and reserves two
types of resources. One resource element may represent resources that
are shared by all participants of the conference while the other may
represent resources that are reserved for each of the expected
participants.
Attributes:
n: number of resources to be reserved. Default 1.
type: specifies whether the resource is to be reserved by each
individual participant or reserved as a shared conference
resource. Valid values for this attribute are "individual" or
"shared". Default "individual".
<createconference>
<reserve>
<resource n="20">
<!--description of resources used by each participant-->
</resource>
<resource n="2" type="shared">
<!--description of the shared conference resources-->
</resource>
</reserve>
</createconference>
9.4 <modifyconference>
All of the properties of an audio mix or the presentation of a video
mix may be changed during the life of a conference using the
<modifyconference> element. Changes to an audio mix are requested by
including an <audiomix> element as a child of <modifyconference>.
This may also be used to add an audio mixer to the conference if none
was previously allocated. Changes to a video presentation are
requested by including a <videolayout> element as a child of
<modifyconference>. Similar to an audio mixer, this may be used to
add a video mixer if none was previously allocated.
Mixers are removed by including a mixer description element within
<destroyconference/>.
Features and presentation aspects are enabled/added or modified by
including the element(s) that define the feature or presentation
aspect within a mixer description. The complete specification of the
element must be included just as it would be included when the
conference is created. The new definition completely replaces any
previous definition that existed. Only things that are defined by
elements included in the mixer descriptions are affected. Any
Saleem, et al. Expires - February 03 2009 [Page 33]
Internet-draft Media Server Markup Language August 2008
(MSML)
existing configuration aspects of a conference, which are not
specified within the <modifyconference/> element, MUST maintain their
current state in the Media Server.
For example, if an MSML client wanted to change the minimum reporting
interval for active speaker notification from that shown in the
Conference Examples section (<createconference>) it would send the
following to the media server:
<?xml version="1.0" encoding="UTF-8"?>
<msml version="1.1">
<modifyconference id="conf:example">
<audiomix>
<asn ri="4"/>
</audiomix>
</modifyconference>
</msml>
This would also enable active speaker notification if it had not
previously been enabled. The N-loudest mixing is unaffected.
Multiple elements MAY be included in the mixer descriptions similar
to when conferences are created. For example, in a video conference,
the video mix description (<videolayout>) could specify that the
layout of the video being displayed should change such that the
regions currently displaying participants get smaller and new
region(s) are created to support additional participants. A media
server MUST make all of the requested changes or none of the
requested changes.
Additional examples of modifying conferences are presented in the
Conference Examples section.
Attributes:
id: the identifier for a conference. Wildcards MUST NOT be
used. Mandatory.
mark: a token which can be used to identify execution progress
in the case of errors. The value of the mark attribute from the
last successfully executed MSML element is returned in an error
response. Therefore the value of all "mark" attributes within
an MSML document SHOULD be unique.
Saleem, et al. Expires - February 03 2009 [Page 34]
Internet-draft Media Server Markup Language August 2008
(MSML)
9.5 <destroyconference>
Destroy conference is used to delete mixers or to delete the entire
conference and all state and shared resources. When a mixer is
removed, all of the streams joined to that mixer are unjoined. When a
conference is destroyed, SIP dialogs for any remaining participants
MUST be maintained or removed based on the value of the "term"
attribute when the conference was created.
When there is no element content, <destroyconference/> deletes the
entire conference. Individual mixer(s) are removed by including a
mixer description element identifying the mix(es) to be removed as
content to <destroyconference/>. <audiomix/> is used remove audio
mixers and <videolayout/> is used remove video mixers. When one or
more mixer descriptions are specified, then Media Server MUST only
delete the specified mixer and MUST NOT affect any other existing
mixers. When <audiomix/> or <videolayout/> are identified for
individual removal, other feature aspects of the mix MUST NOT be
included. If specified, the Media Server MUST ignore any such
elements. When the last mixer is removed from a conference, a media
server MUST remove all conference state, leaving or removing any
remaining SIP dialogs as described above.
Attributes:
id: the identifier for a conference. Mandatory.
mark: a token which can be used to identify execution progress
in the case of errors. The value of the mark attribute from the
last successfully executed MSML element is returned in an error
response. Therefore the value of all "mark" attributes within
an MSML document SHOULD be unique.
9.6 <audiomix>
The properties of the overall audio mix are specified using the
<audiomix> element.
Attributes:
id: an optional identifier for the audio mix.
samplerate: Integer value specifies the sample rate (in Hz) for
the audio mixer. Optional, default value of 8000.
An example of the description for an audio mix is:
<audiomix id="mix1">
Saleem, et al. Expires - February 03 2009 [Page 35]
Internet-draft Media Server Markup Language August 2008
(MSML)
<asn ri="10s"/>
<n-loudest n="3"/>
</audiomix>
9.6.1 <n-loudest>
The <n-loudest> element defines that participants contend to be
included in the conference mix based upon their audio energy. When
the element is not present, all participants are mixed.
Attributes:
n: the number of participants that will be included in the
audio mix based upon having the greatest audio energy.
Mandatory.
9.6.2 <asn>
The <asn> element enables notification of active speakers. Active
speakers MUST be notified using the <event> element with an event
name of "msml.conf.asn". The namelist of the event consists of the
set of active speakers. The name of each item is the string "speaker"
with a value of the connection identifier for the connection.
Attributes:
ri: the minimum reporting interval defines the minimum duration
of time which must pass before changes to active speakers will
be reported. A value of zero disables active speaker
notification.
asth: specifies the active speaker threshold (in unit of dBm0).
Valid value range is 0 to -96. Optional, default is -96.
An example of an active speaker notification is:
<event name="msml.conf.asn" id="conf:example">
<name>speaker</name>
<value>conn:hd93tg5hdf</value>
<name>speaker</name>
<value>conn:w8cn59vei7</value>
<name>speaker</name>
<value>conn:p78fnh6sek47fg</value>
</event>
Saleem, et al. Expires - February 03 2009 [Page 36]
Internet-draft Media Server Markup Language August 2008
(MSML)
9.7 <videolayout>
A video layout is specified using the <videolayout> element. It is
used as a container to hold elements that describe all of the
properties of a video mix. The parameters of the window that displays
the video mix are defined by the <root> element. When the video mix
in composed of multiple panes, the location and characteristics of
the panes are defined by one or more <region> elements. A <region>
element is not required when only a single video stream is displayed
at one time and none of the visual attributes of regions are
required.
Some regions may be used to display a video stream based on a
selection criteria rather than having a video stream of a single
participant continuously presented in the region. One such an example
is a distance learning lecture where the instructor sees each of the
students periodically displayed in a region. When a region is used to
display one of a number of streams, it is placed as a child of a
<selector> element.
Attributes:
type: specifies the language used to define the layout. Layouts
defined using MSML MUST use the value "text/msml-basic-layout".
This is the same convention as defined for the layout package
from the W3C SMIL 2.0 specification [i6]. The default when
omitted is "text/msml-basic-layout".
id: an optional identifier for the video layout.
9.7.1 <root>
The <root> element describes the root window or virtual screen in
which the conference video mix will be displayed. Simple conferences
can display participant video directly within the root window but
more complex conferences will use regions for this purpose. Areas of
the window which are not used to display video will show the root
window background.
All video presentations require a root window. It MUST be present
when a video mix is created and it cannot be deleted, however its
attributes MAY be changed using the <modifyconference> element.
Attributes:
size: the size of the root window specified as one of the five
standard common intermediate formats (e.g. CIF, QCIF, etc.).
Saleem, et al. Expires - February 03 2009 [Page 37]
Internet-draft Media Server Markup Language August 2008
(MSML)
backgroundcolor: the color for the root window background
defined using the values for the "background-color" property of
the CSS2 specification [n10].
backgroundimage: the URI for an image to be displayed as the
root window background. Transparent portions of the image allow
the background color to show through.
9.7.2 <region>
<region> elements define video panes that are used to display
participant video streams. Regions are rendered on top of the root
window.
The size of a region is specified relative to the size of the root
window using the "relativesize" attribute. Relative sizes are
expressed as fractions (e.g. 1/4, 1/3) that preserve the aspect ratio
of the original video stream while allowing for efficient scaling
implementations.
Regions are located on the root window based on the value of the
position attributes "top" and "left". These attributes define the
position of the top left corner of the region as an offset from the
top left corner of the root window. Their values may be expressed
either as a number of pixels or as a percent of the vertical or
horizontal dimension of the root window. Percent values are appended
with a percent ('%') character. Percent values of "33%" and "67%"
should be interpreted as "1/3" and "2/3" to allow easy alignment of
regions whose size is expressed relative to the size of the root
window.
An example of a video layout with six regions is:
+-------+---+
| | 2 |
| 1 +---+
| | 3 |
+---+---+---+
| 6 | 5 | 4 |
+---+---+---+
<videolayout type="text/msml-basic-layout">
<root size="CIF"/>
<region id="1" left="0" top="0" relativesize="2/3"/>
<region id="2" left="67%" top="0" relativesize="1/3"/>
<region id="3" left="67%" top="33%" relativesize="1/3">
<region id="4" left="67%" top="67%" relativesize="1/3"/>
Saleem, et al. Expires - February 03 2009 [Page 38]
Internet-draft Media Server Markup Language August 2008
(MSML)
<region id="5" left="33%" top="67%" relativesize="1/3"/>
<region id="6" left="0" top="67%" relativesize="1/3"/>
</videolayout>
The area of the root window covered by a region is a function of the
region's position and its size. When areas of different regions
overlap, they are layered in order of their "priority" attribute. The
region with the highest value for the "priority" attribute is below
all other regions and will be hidden by overlapping regions. The
region with the lowest non-zero value for the "priority" attribute is
on top of all other regions and will not be hidden by overlapping
regions. The priority attribute may be assigned values between 0 and
1. A value of zero disables the region, freeing any resources
associated with the region, and unjoining any video stream displayed
in the region.
Regions that do not specify a priority will be assigned a priority by
a media server when a conference is created. The first region within
the <videolayout> element that does not specify a priority will be
assigned a priority of one, the second a priority of two, etc. In
this way, all regions that do not explicitly specify a priority will
be underneath all regions that do specify a priority. As well, within
those regions that do not specify a priority, they will be layered
from top to bottom, in the order they appear within the <videolayout>
element.
For example, if a layout was specified as follows:
<videolayout>
<root size="CIF"/>
<region id="a" ... priority=".3" .../>
<region id="b" ... />
<region id="c" ... priority=".2" ...>
<region id="d" ... />
</videolayout>
Then the regions would be layered, from top to bottom, c,a,b,d.
Portions of regions that extend beyond the root window will be
cropped. For example, a layout specified as:
<videolayout>
<root size="CIF"/>
<region id="foo" left="50%" top="50%" relativesize="2/3"/>
</videolayout>
Saleem, et al. Expires - February 03 2009 [Page 39]
Internet-draft Media Server Markup Language August 2008
(MSML)
would appear similar to:
+-----------+
| root |
|background |
| +-----+--
| | |//
| | foo |//
+-----+-----+//
|////////
Visual attributes are used to define aspects of the visual appearance
of individual regions. A border may be defined together with a title
and/or logo. Text and logos are displayed as images on top of the
region's video, below all regions with a lower priority. The visual
attributes are "title", "titletextcolor", "titlebackgroundcolor",
"bordercolor", "borderwidth", and "logo".
Visual attributes can also be defined for individual streams (Video
Stream Properties). When visual attributes are specified as part of
both a region and a stream, those associated with the stream MUST
take precedence. This allows streams that are chosen for display
automatically (Stream Selection) to have proper text and logos
displayed. The region visual attributes are displayed when no stream
is associated with the region.
Two other attributes associated with a region, "blank" and "freeze",
define the state of the video displayed in the region. When the blank
or freeze attribute is assigned the value "true", then the Media
Server MUST display the region either as a blank region, or the video
image frozen at the last received frame.
These attributes are specified for a region and not allowed for
streams because that appears to be the common use case. Applying them
to streams would allow only that stream to be affected within a
selector while other streams continue to display normally. Except for
personal mixing scenarios, the same effect can be achieved by having
the participant mute their own transmission to the media server.
Attributes: associated with each region:
id: a name that can be used to refer to the region.
left: the position of the region from the left side of the root
window.
Saleem, et al. Expires - February 03 2009 [Page 40]
Internet-draft Media Server Markup Language August 2008
(MSML)
top: the position of the region from the top of the root
window.
relativesize: the size of the region expressed as a fraction of
the root window size.
priority: a number between 0 and 1 that is used to define the
precedence when rendering overlapping regions. A value of zero
disables the region.
title: text to be displayed as the title for the region
titletextcolor: the color of the text
titlebackgroundcolor: the color of the text background
bordercolor: the color of the region border
borderwidth: the width of the region border
logo: the URI of an image file to be displayed
freeze: a boolean value, with a default of false, that defines
whether the video image should be frozen at the currently
displayed frame
blank: a boolean value, with a default of false, that defines
whether the region should display black instead of the
associated video stream
9.7.3 <selector>
It is often desired that one of several video streams be
automatically selected to be displayed. The <selector> element is
used to define the selection criteria and its associated parameters.
The selection algorithm is specified by the "method" attribute.
Currently defined selection methods allow for voice activated
switching and to iterate sequentially through the set of associated
video streams.
The regions that will display the selected video stream are placed as
child elements of the <selector> element. Including regions within a
<selector> element does not affect their layout with respect to
regions not subject to the selection. For simple video conferences
that display the video directly in the root window, the <root>
element can be placed as a child of <selector>. Region elements MUST
NOT be used in this case.
Saleem, et al. Expires - February 03 2009 [Page 41]
Internet-draft Media Server Markup Language August 2008
(MSML)
For example, below is a common video layout that allows the video
stream from the currently active speaker to be displayed in the large
region ("1") at the top left of the layout while the streams from
five other participants are displayed in regions located at the
layout periphery.
+-------+---+
| | 2 |
| 1 +---+
| | 3 |
+---+---+---+
| 6 | 5 | 4 |
+---+---+---+
<videolayout type="text/msml-basic-layout">
<root size="CIF"/>
<selector id="switch" method="vas">
<region id="1" left="0" top="0" relativesize="2/3"/>
</selector>
<region id="2" left="67%" top="0" relativesize="1/3"/>
<region id="3" left="67%" top="33%" relativesize="1/3">
<region id="4" left="67%" top="67%" relativesize="1/3"/>
<region id="5" left="33%" top="67%" relativesize="1/3"/>
<region id="6" left="0" top="67%" relativesize="1/3"/>
</videolayout>
All selector methods must be defined so that they work if only a
single region is a child of the selector. Selector methods that
support more than one child region MUST specify how the method works
across multiple regions. Media server implementations MAY support
only a single region for methods that are defined to allow multiple
regions.
The selector or region for a participant's video is defined using the
"display" attribute of <stream> during a join operation. Specifying a
selector allows the stream to be displayed according to the criteria
defined by the selector method. Specifying a region supports
continuous presence display of participants. Some streams may be
joined with both a selector and a region. In this case, the value of
<blankothers> attribute defines whether the streams associated with a
continuous presence region should be blanked when the stream is
selected for display in one of the selector regions.
Attributes: common to all selector methods are:
Saleem, et al. Expires - February 03 2009 [Page 42]
Internet-draft Media Server Markup Language August 2008
(MSML)
id: a name that can be used to refer to the selector.
method: the name of the method used to select the video stream.
A value of "vas" (see section on Voice Activated Switching) MAY
be specified.
status: specifies whether the selector is "active" or
"disabled".
blankothers: when "true", video streams that are also displayed
in continuous presence regions will have the continuous
presence regions blanked when the stream is displayed in a
selection region.
9.7.3.1 Voice Activate Switching (vas)
Voice activated switching (VAS) is used to display the video stream
that correlates with the participant who is currently speaking. It is
specified using a selector method value of "vas".
If the video stream associated with the active speaker is not
currently displayed in a selection region, then it replaces the video
in the region that is displaying the video of the speaker that was
least recently active. If the video of the active speaker is
currently displayed in a selection region, then there is no change to
any region. When VAS is applied to a single region, this has the
effect that the current speaker is displayed in that region.
Attributes:
si: switching interval is the minimum period of time that must
elapse before allowing the video to switch to the active
speaker.
speakersees: defines whether the active speaker sees the
"current" speaker (themselves) or the "previous" speaker.
9.8 <join>
<join> is used to create one or more streams between two independent
objects. Streams may be audio or video and may be bidirectional or
unidirectional. A bidirectional stream is implicitly composed of two
unidirectional streams that can be manipulated independently. The
streams to be established are specified by <stream> elements (section
<stream>) as the content of <join>.
Without any content, <join> by default establishes a bidirectional
audio stream. When only a stream of a single type has previously been
Saleem, et al. Expires - February 03 2009 [Page 43]
Internet-draft Media Server Markup Language August 2008
(MSML)
created between two objects, or when only a unidirectional stream
exists, <join> can be used to add a stream of another media type or
make the stream bidirectional by including the necessary <stream>
elements. Bidirectional streams are made unidirectional by using
<unjoin> (section <unjoin>) to remove the unidirectional stream for
the direction that is no longer required.
In addition to defining the media type and direction of streams,
<stream> elements are also used to establish the properties of
streams, such as gain, voice masking, or tone clamping of audio
streams, or labels and other visual characteristics of video streams.
Properties are often defined asymmetrically for a single direction of
a stream. Creating a bidirectional stream requires two <stream>
elements within the <join>, one for each direction, if one direction
is to have different properties from the other direction.
If a media server can provide services using both compressed or
uncompressed media, the MSML client may need to distinguish within
requests which format is to be used. When compressed streams are
created, both objects must use the same media format or an error
response (450) is generated.
Attributes:
id1: an identifier of either a connection or conference.
Wildcards MUST NOT be used. Mandatory. Any other object class
results in a 440 error.
id2: an identifier of either a connection or conference.
Wildcards MUST NOT be used. Mandatory. Any other object class
results in a 440 error.
mark: a token which can be used to identify execution progress
in the case of errors. The value of the mark attribute from the
last successfully executed MSML element is returned in an error
response. Therefore the value of all mark attributes within an
MSML document SHOULD be unique.
For example, consider a call center coaching scenario where a
supervisor can listen to the conversation between an agent and a
customer, and provide hints to the agent, which are not heard by the
customer. One join establishes a stream between the agent and the
customer and another join establishes a stream between the agent and
the supervisor. A third join is used to establish a half-duplex
stream from the customer to the supervisor. The media server
automatically bridges the media streams from the customer and the
supervisor for the agent, and from the customer and the agent for the
supervisor.
Saleem, et al. Expires - February 03 2009 [Page 44]
Internet-draft Media Server Markup Language August 2008
(MSML)
Assuming the following connections, each with a single audio stream:
conn:supervisor
conn:agent
conn:customer
The following would create the media flows previously described:
<?xml version="1.0" encoding="UTF-8"?>
<msml version="1.1">
<join id1="conn:supervisor" id2="conn:agent"/>
<join id1="conn:agent" id2="conn:customer"/>
<join id1="conn:supervisor" id2="conn:customer">
<stream media="audio" dir="to-id1"/>
</join>
</msml>
The following example, shows joining a participant to a multimedia
conference. It assumes that the conference has a video presentation
region named "topright". The "display" attribute is explained in
section Video Stream Properties.
<?xml version="1.0" encoding="UTF-8"?>
<msml version="1.1">
<join id1="conn:hd83t5hf7g3" id2="conf:example">
<stream media="audio"/>
<stream media="video" dir="from-id1" display="topright"/>
<stream media="video" dir="to-id1"/>
</join>
</msml>
9.9 <modifystream>
Media streams can have different properties such as the gain for an
audio stream or a visual label for a video stream. These properties
are specified as the content of <stream> elements (section <stream>).
<modifystream> is used to change the properties of a stream by
including one or more <stream> elements that are to have their
properties changed.
Stream properties MUST be set as specified by the element <stream> as
a child element of <modifystream> element. Any properties not
included in the <stream> element when modifying a stream MUST remain
unchanged. Setting a property for only one direction of a
bidirectional stream MUST NOT affect the other direction. The
Saleem, et al. Expires - February 03 2009 [Page 45]
Internet-draft Media Server Markup Language August 2008
(MSML)
directionality of streams can be changed using issuing an <unjoin>
followed by a <join>. Any streams that exist between the two objects
that are not included within <modifystream> MUST NOT be affected.
Attributes:
id1: an identifier of either a conference or a connection. The
instance name MUST NOT contain a wildcard if "id2" contains a
wildcard. Mandatory.
id2: an identifier of either a conference or a connection. The
instance name MUST NOT contain a wildcard if "id1" contains a
wildcard. Mandatory.
mark: a token which can be used to identify execution progress
in the case of errors. The value of the mark attribute from the
last successfully executed MSML element is returned in an error
response. Therefore the value of all mark attributes within an
MSML document are RECOMMENDED to be unique.
9.10 <unjoin>
Unjoin removes one or more media streams between two objects. In the
absence of any content in <stream> element, all media streams between
the objects MUST be removed. Individual streams may be removed by
specifying them using <stream> elements, while the unspecified
streams MUST NOT be removed. A bidirectional stream is changed to a
unidirectional stream by unjoining the direction that is no longer
required, using the <unjoin> element. Operator elements MUST NOT be
specified within <stream> elements when streams are being unjoined
using the <unjoin> element. Any specified stream operators MUST be
ignored.
<unjoin> and <join> may be used together to move a media stream, such
as from a main conference to a sidebar conference.
Attributes:
id1: an identifier of either a conference or a connection. The
instance name MUST NOT contain a wildcard if "id2" contains a
wildcard. Mandatory.
id2: an identifier of either a conference or a connection. The
instance name MUST NOT contain a wildcard if "id1" contains a
wildcard. Mandatory.
mark: a token which can be used to identify execution progress
in the case of errors. The value of the mark attribute from the
Saleem, et al. Expires - February 03 2009 [Page 46]
Internet-draft Media Server Markup Language August 2008
(MSML)
last successfully executed MSML element is returned in an error
response. Therefore the value of all mark attributes within an
MSML document SHOULD be unique.
The following removes a participant from a conference and plays a
leave tone for the remaining participants in the conference.
<?xml version="1.0" encoding="UTF-8"?>
<msml version="1.1">
<unjoin id1="conn:jd73ht89sf489f" id2="conf:1"/>
<dialogstart target="conf:1" type="application/moml+xml">
<play>
<audio uri="file://leave_tone.wav"/>
</play>
</dialogstart>
</msml>
9.11 <monitor>
Monitor is a specialized unidirectional join that copies the media
that is destined for a connection object. One example of the use for
<monitor> may be quality monitoring within a conference. The media
stream may be removed using the <unjoin> element (see section
<unjoin>).
Attributes:
id1: an identifier of the connection to be monitored.
Mandatory. Any other object class results in a 440 error.
Wildcards MUST NOT be used.
id2: an identifier of the object which is to receive the copy
of the media destined to id1. id2 may be a connection or a
conference. Mandatory. Any other object class results in a 440
error. Wildcards MUST NOT be used.
compressed: "true" or "false". Specifies whether the join
should occur before or after compression. When "true", id2 must
be a connection using the same media format as id1 or an error
response (450) is generated. Default is "false.
mark: a token which can be used to identify execution progress
in the case of errors. The value of the mark attribute from the
last successfully executed MSML element is returned in an error
response. Therefore the
