Network Working Group T. Melanchuk
Internet-Draft Rain Willow Communications
Intended status: Standards Track S. McGlashan
Expires: January 7, 2009 Hewlett-Packard
C. Boulton
Avaya
July 6, 2008
A Mixer Control Package for the Media Control Channel Framework
draft-ietf-mediactrl-mixer-control-package-00
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 January 7, 2009.
Melanchuk, et al. Expires January 7, 2009 [Page 1]
Internet-Draft Mixer Control Package July 2008
Abstract
This document defines a Mixer Control Package for the Media Control
Channel Framework. This Control Package aims to fulfill Conferencing
requirements using the SIP Control Framework.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Conventions and Terminology . . . . . . . . . . . . . . . . . 5
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4. Control Package Definition . . . . . . . . . . . . . . . . . . 7
4.1. Control Package Name . . . . . . . . . . . . . . . . . . . 7
4.2. Framework Message Usage . . . . . . . . . . . . . . . . . 7
4.3. Common XML Support . . . . . . . . . . . . . . . . . . . . 8
4.4. CONTROL Message Body . . . . . . . . . . . . . . . . . . . 8
4.5. REPORT Message Body . . . . . . . . . . . . . . . . . . . 8
4.6. Audit . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5. Element Definitions . . . . . . . . . . . . . . . . . . . . . 10
5.1. <mscmixer> . . . . . . . . . . . . . . . . . . . . . . . . 10
5.2. Mixer Elements . . . . . . . . . . . . . . . . . . . . . . 11
5.2.1. Conference Elements . . . . . . . . . . . . . . . . . 12
5.2.1.1. <createconference> . . . . . . . . . . . . . . . . 12
5.2.1.2. <modifyconference> . . . . . . . . . . . . . . . . 15
5.2.1.3. <destroyconference> . . . . . . . . . . . . . . . 16
5.2.1.4. Conference Configuration . . . . . . . . . . . . . 16
5.2.1.4.1. <audio-mixing> . . . . . . . . . . . . . . . . 17
5.2.1.4.2. <video-layouts> . . . . . . . . . . . . . . . 17
5.2.1.4.2.1. <video-layout> . . . . . . . . . . . . . . 18
5.2.1.4.3. <video-switch> . . . . . . . . . . . . . . . . 19
5.2.1.4.4. <subscribe> . . . . . . . . . . . . . . . . . 20
5.2.1.4.4.1. <active-talkers-sub> . . . . . . . . . . . 20
5.2.2. Joining Elements . . . . . . . . . . . . . . . . . . . 21
5.2.2.1. Joining Model . . . . . . . . . . . . . . . . . . 21
5.2.2.2. <join> . . . . . . . . . . . . . . . . . . . . . . 22
5.2.2.3. <modifyjoin> . . . . . . . . . . . . . . . . . . . 24
5.2.2.4. <unjoin> . . . . . . . . . . . . . . . . . . . . . 25
5.2.2.5. <stream> . . . . . . . . . . . . . . . . . . . . . 26
5.2.2.5.1. <volume> . . . . . . . . . . . . . . . . . . . 27
5.2.2.5.2. <clamp> . . . . . . . . . . . . . . . . . . . 28
5.2.2.5.3. <region> . . . . . . . . . . . . . . . . . . . 28
5.2.3. <response> . . . . . . . . . . . . . . . . . . . . . . 28
5.2.4. <event> . . . . . . . . . . . . . . . . . . . . . . . 29
5.2.4.1. <active-talkers-notify> . . . . . . . . . . . . . 29
5.2.4.1.1. <active-talker> . . . . . . . . . . . . . . . 29
5.2.4.2. <unjoin-notify> . . . . . . . . . . . . . . . . . 30
5.3. Audit Elements . . . . . . . . . . . . . . . . . . . . . . 30
Melanchuk, et al. Expires January 7, 2009 [Page 2]
Internet-Draft Mixer Control Package July 2008
5.3.1. <audit> . . . . . . . . . . . . . . . . . . . . . . . 31
5.3.2. <auditresponse> . . . . . . . . . . . . . . . . . . . 32
5.3.2.1. <capabilities> . . . . . . . . . . . . . . . . . . 33
5.3.2.2. <mixers> . . . . . . . . . . . . . . . . . . . . . 34
5.3.2.2.1. <conferenceaudit> . . . . . . . . . . . . . . 34
5.3.2.2.1.1. <participants> . . . . . . . . . . . . . . 35
5.3.2.2.1.1.1. <participant> . . . . . . . . . . . . 35
5.3.2.2.2. <joinaudit> . . . . . . . . . . . . . . . . . 36
5.4. <codecs> . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.4.1. <codec> . . . . . . . . . . . . . . . . . . . . . . . 37
5.5. Response Status Codes . . . . . . . . . . . . . . . . . . 37
5.6. Type Definitions . . . . . . . . . . . . . . . . . . . . . 39
6. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 40
7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7.1. AS-MS Dialog Interaction Examples . . . . . . . . . . . . 41
7.1.1. Creating a conference mixer and joining a
participant . . . . . . . . . . . . . . . . . . . . . 41
7.1.2. Receiving active talker notifications . . . . . . . . 42
8. Security Considerations . . . . . . . . . . . . . . . . . . . 43
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44
9.1. Control Package Registration . . . . . . . . . . . . . . . 44
9.2. URN Sub-Namespace Registration . . . . . . . . . . . . . . 44
9.3. MIME Registration . . . . . . . . . . . . . . . . . . . . 44
10. Change Summary . . . . . . . . . . . . . . . . . . . . . . . . 45
11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 47
12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 48
13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 49
13.1. Normative References . . . . . . . . . . . . . . . . . . . 49
13.2. Informative References . . . . . . . . . . . . . . . . . . 49
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 51
Intellectual Property and Copyright Statements . . . . . . . . . . 52
Melanchuk, et al. Expires January 7, 2009 [Page 3]
Internet-Draft Mixer Control Package July 2008
1. Introduction
This document defines a Media Control Channel Framework Package for
conference mixers and connection mixers. The package defines mixer
management elements for creating, modifying and deleting conference
mixers, elements for joining, modifying and unjoining media streams
between connections and conferences (including mixers between
connections), as well as associated responses and notifications. The
package also defines elements for auditing package capabilities and
mixers.
Melanchuk, et al. Expires January 7, 2009 [Page 4]
Internet-Draft Mixer Control Package July 2008
2. Conventions and Terminology
In this document, BCP 14/RFC 2119 [RFC2119] defines the key words
"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL". In addition, BCP 15 indicates requirement levels for
compliant implementations.
The following additional terms are defined for use in this document:
Application server: A SIP [RFC3261] application server (AS) is a
control client that hosts and executes services such as
interactive media and conferencing in an operator's network. An
AS controls the media server (MS), influencing and impacting the
SIP sessions terminating on a media server, which the AS may have
established for example using SIP third party call control.
Media Server: A media server (MS) processes media streams on behalf
of an AS by offering functionality such as interactive media,
conferencing, and transcoding to the end user. Interactive media
functionality is realized by way of dialogs, which are identified
by a URI and initiated by the application server.
MS Conference: A MS Conference provides the media related mixing
resources and services for conferences. In this document, A MS
Conference is often referred to simply as a conference.
MS Connection: A Media Server connection represents the termination
on a media server of one or more RTP [RFC3550] sessions that are
associated to a single SIP dialog. A media server receives media
from the output(s) of a connection and it transmits media on the
input(s) of a connection.
Media Stream: A media stream on a media server represents a media
flow between either a connection and a conference, between two
connections, or between two conferences. Streams may be audio or
video and may be bi-directional or uni-directional.
Melanchuk, et al. Expires January 7, 2009 [Page 5]
Internet-Draft Mixer Control Package July 2008
3. Overview
The SIP Control Framework [I-D.ietf-mediactrl-sip-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 [RFC3261]
(SIP) for the rendezvous and establishment of a reliable channel for
control interactions. The Control Framework also introduces the
concept of a Control Package. A Control Package is an explicit usage
of the Control Framework for a particular interaction set. This
specification defines a package for media conference mixers and media
connection mixers.
This package defines mixer management elements for creating,
modifying and deleting conference mixers, elements for joining,
modifying and unjoining media streams between connections and
conferences (including mixers between connections), as well as
associated responses and notifications. The package also defines
elements for auditing package capabilities and mixers.
This package has been designed to satisfy the IETF MediaCtrl
requirements ([RFC5167]). The package provides the major
conferencing functionality of SIP Media Server languages such as
MSCML ([RFC5022]) and MSML ([MSML]). A key differentiator is that
this package provides such functionality using the Media Control
Channel Framework.
The functionality of this package is defined by messages, containing
XML [XML] elements, transported using the Media Control Channel
Framework. The XML elements can be divided into two types: mixer
management elements; and elements for auditing package capabilities
as well as mixers managed by the package.
The document is organized as follows. Section 4 descibes how this
control package fulfills the requirements for a Media Control Channel
Framework control package. Section 5 describes the syntax and
semantics of defined elements, including mixer management
(Section 5.2) and audit elements (Section 5.3). Section 6 describes
an XML schema for these elements and provides extensibility by
allowing attributes and elements from other namespaces. Section 7
provides examples of package usage.
Melanchuk, et al. Expires January 7, 2009 [Page 6]
Internet-Draft Mixer Control Package July 2008
4. Control Package Definition
This section fulfils the mandatory requirement for information that
MUST be specified during the definition of a Control Framework
Package, as detailed in Section 8 of
[I-D.ietf-mediactrl-sip-control-framework].
4.1. Control Package Name
The Control Framework requires a Control Package definition to
specify and register a unique name. The name and version of this
Control Package is "msc-mixer/1.0" (Media Server Control - Mixer -
version 1.0). Its IANA registration is specified in Section 9.1.
4.2. Framework Message Usage
The Control Framework requires a Control Package to explicitly detail
the control messages that can be used as well as provide an
indication of directionality between entities. This will include
which role type is allowed to initiate a request type.
This package specifies CONTROL and response messages in terms of XML
elements defined in Section 5. These elements describe requests,
response and notifications and all are contained within a root
<mscmixer> element (Section 5.1).
In this package, the MS operates as a Control Framework Server in
receiving requests from, and sending responses to, the AS (operating
as Control Framework Client). Mixer management requests and
responses are defined in Section 5.2. Audit requests and responses
are defined in Section 5.3. Mixer management and audit responses are
carried in a framework 200 response or REPORT message bodies. This
package's response codes are defined in Section 5.5.
Note that package responses are different from framework response
codes. Framework error response codes (see Section 8 of
[I-D.ietf-mediactrl-sip-control-framework]) are used when the request
or event notification is invalid; for example, a request is invalid
XML (400), or not understood (500).
The MS also operates as a Control Framework Client in sending event
notification to the AS (Control Framework Server). Event
notifications (Section 5.2.4) are carried in CONTROL message bodies.
The AS MUST respond with a Control Framework 200 response.
Melanchuk, et al. Expires January 7, 2009 [Page 7]
Internet-Draft Mixer Control Package July 2008
4.3. Common XML Support
The Control Framework requires a Control Package definition to
specify if the attributes for media dialog or conference references
are required.
This package requires that the XML Schema in Section 17.1 of
[I-D.ietf-mediactrl-sip-control-framework] MUST be supported for
media dialogs and conferences.
The package uses "connectionid" and "conferenceid" attributes for
various element definitions (Section 5). The XML schema (Section 6)
imports the definitions of these attributes from the framework
schema.
4.4. CONTROL Message Body
The Control Framework requires a Control Package to define the
control body that can be contained within a CONTROL command request
and to indicate the location of detailed syntax definitions and
semantics for the appropriate body types.
When operating as Control Framework Server, the MS receives CONTROL
messages with a body containing an <mscmixer> element with either a
mixer management or audit request child element.
The following mixer management request elements are carried in
CONTROL message bodies to MS: <createconference> (Section 5.2.1.1),
<modifyconference> (Section 5.2.1.2), <destroyconference>
(Section 5.2.1.3), <join> (Section 5.2.2.2), <modifyjoin>
(Section 5.2.2.3) and <unjoin> (Section 5.2.2.4) elements.
The <audit> request element (Section 5.3.1) is also carried in
CONTROL message bodies.
When operating as Control Framework Client, the MS sends CONTROL
messages with a body containing a notification <event> element
(Section 5.2.4).
4.5. REPORT Message Body
The Control Framework requires a control package definition to define
the REPORT body that can be contained within a REPORT command
request, or that no report package body is required. This section
should indicate the location of detailed syntax definitions and
semantics for the appropriate body types.
When operating as Control Framework Server, the MS sends REPORT
Melanchuk, et al. Expires January 7, 2009 [Page 8]
Internet-Draft Mixer Control Package July 2008
bodies containing a <mscmixer> element with a response child element.
The response element for mixer management requests is a <response>
element (Section 5.2.3). The response element for an audit request
is a <auditresponse> element (Section 5.3.2).
4.6. Audit
The Control Framework encourages Control Packages to specify whether
auditing is available, how it is triggered as well as the query/
response formats.
This Control Packages supports auditing of package capabilities and
mixers on the MS. An audit request is carried in a CONTROL messages
and an audit response in a REPORT message (or a 200 reponse to the
CONTROL if it can execute the audit in time).
The syntax and semantics of audit request and response elements is
defined in Section 5.3.
Melanchuk, et al. Expires January 7, 2009 [Page 9]
Internet-Draft Mixer Control Package July 2008
5. Element Definitions
This section defines the XML elements for this package. The elements
are defined in the XML namespace specified in Section 9.2.
The root element is <mscmixer> (Section 5.1). All other XML elements
(requests, responses and notification elements) are contained within
it. Child elements describe mixer management (Section 5.2) and audit
(Section 5.3) functionality. Response status codes are defined in
Section 5.5 and type definitions in Section 5.6.
Implementation of this control package MUST adhere to the syntax and
semantics of XML elements defined in this section and the schema
(Section 6). The XML schema supports extensibility by allowing
attributes and elements from other namespaces. Implementations MAY
support attributes and elements from other namespaces. If an
implementation encounters attributes or elements from another
namespace which it does not understand, it MUST ignore them and
continue processing.
Extensible attributes and elements are not described in this section.
In all other cases where there is a difference in constraints between
the XML schema and the textual description of elements in this
section, the textual definition takes priority.
Usage examples are provided in Section 7.
5.1. <mscmixer>
The <mscmixer> element has the following attributes (in addition to
standard XML namspace attributes such as xmlns):
version: a string specifying the mscmixer package version. The
value is fixed as '1.0' for this version of the package. The
attribute is mandatory.
The <mscmixer> element has the following defined child elements, only
one of which can occur:
1. mixer management elements defined in Section 5.2:
<createconference> create and configure a new a conference
mixer. See Section 5.2.1.1
<modifyconference> modify the configuration of an existing
conference mixer. See Section 5.2.1.2
Melanchuk, et al. Expires January 7, 2009 [Page 10]
Internet-Draft Mixer Control Package July 2008
<destroyconference> destroy an existing conference mixer. See
Section 5.2.1.3
<join> create and configure media streams between connections
and/or conferences (for example, add a participant to a
conference). See Section 5.2.2.2
<modifyjoin> modify the configuration of joined media streams.
See Section 5.2.2.3
<unjoin> delete a media stream (for example, remove a
participant from a conference). See Section 5.2.2.4
<response> response to a mixer request. See Section 5.2.3
<event> mixer or subscription notification. See Section 5.2.4
2. audit elements defined in Section 5.3:
<audit> audit package capabilities and managed mixers. See
Section 5.3.1
<auditresponse> response to an audit request. See Section 5.3.2
For example, a request to the MS to create a conference mixer:
<mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
<createconference/>
</mscmixer>
and a response from the MS that the conference was sucessfully
created:
<mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
<response status="200" conferenceid="conference1"/>
</mscmixer>
5.2. Mixer Elements
This section defines the mixer management XML elements for this
control package. These elements are divided into requests, responses
and notifications.
Request elements are sent to the MS to request a specific mixer
operation to be executed. The following request elements are
defined:
Melanchuk, et al. Expires January 7, 2009 [Page 11]
Internet-Draft Mixer Control Package July 2008
<createconference> create and configure a new a conference mixer.
See Section 5.2.1.1
<modifyconference> modify the configuration of an existing
conference mixer. See Section 5.2.1.2
<destroyconference> destroy an existing conference mixer. See
Section 5.2.1.3
<join> create and configure media streams between connections and/or
conferences (for example, add a participant to a conference). See
Section 5.2.2.2
<modifyjoin> modify the configuration of joined media streams. See
Section 5.2.2.3
<unjoin> delete a media stream (for example, remove a participant
from a conference). See Section 5.2.2.4
Responses from the MS describe the status of the requested operation.
Responses are specified in a <response> element (Section 5.2.3). The
MS MUST respond to a request message with a response message. If the
MS is not able to carry out the requested mixer operation, it is an
error and the MS MUST indicate the error in the status code of the
response.
Notifications are sent from the MS to provide updates on the status
of a mixer operation or subscription. Notifications are specified in
an <event> element (Section 5.2.4).
[Editors Note: MIXER-XXX. Should we define conferenceexit
notification to indicate that a conference has exited? Cf. IVR
package with dialogexit. Use case: conference encounters runtime
error. ]
5.2.1. Conference Elements
5.2.1.1. <createconference>
The <createconference> element is sent to the MS to request creation
of a new conference (multiparty) mixer.
The <createconference> element has the following attributes:
conferenceid: string indicating a unique name for the new
conference. If this attribute is not specified, the MS MUST
create a unique name for the conference. The value is used in
subsequent references to the conference (e.g. as conferenceid in a
Melanchuk, et al. Expires January 7, 2009 [Page 12]
Internet-Draft Mixer Control Package July 2008
<response>). The attribute is optional. There is no default
value.
reserved-talkers: indicates the requested number of guaranteed
speaker slots to be reserved for the conference. A valid value is
a non-negative integer (see Section 5.6.2). The attribute is
optional. The default value is 0.
reserved-listeners: indicates the requested number of guaranteed
listener slots to be reserved for the conference. A valid value
is a non-negative integer (see Section 5.6.2). The attribute is
optional. The default value is 0.
The <createconference> element has the following sequence of child
elements:
<codecs>: an element to configure the codecs supported by the
conference (see Section 5.4). The element is optional.
<audio-mixing>: an element to configure the audio mixing
characteristics of a conference (see Section 5.2.1.4.1). The
element is optional.
<video-layouts>: an element to configure the video layouts of a
conference (see Section 5.2.1.4.2). The element is optional.
<video-switch>: an element to configure the video switch policy for
the layout of a conference (see Section 5.2.1.4.3). The element
is optional.
<subscribe>: an element to request subscription to conference
events. (see Section 5.2.1.4.4). The element is optional.
If the conferenceid attribute specifies the name of a conference
which already exists, the MS MUST report an error (403) and MUST NOT
create the conference.
If the MS is unable to configure the conference according to a
specified <codecs> element, the MS MUST report an error (410) and
MUST NOT create the conference.
If the MS is unable to configure the conference according to a
specified <audio-mixing> element, the MS MUST report an error (405)
and MUST NOT create the conference.
If the MS is unable to configure the conference according to a
specified <video-layouts> element, the MS MUST report an error (408)
and MUST NOT create the conference.
Melanchuk, et al. Expires January 7, 2009 [Page 13]
Internet-Draft Mixer Control Package July 2008
If the MS is unable to configure the conference according to a
specified <video-switch> element, the MS MUST report an error (409)
and MUST NOT create the conference.
If the MS is unable to configure the conference according to
specified reserved-talkers or reserved-listeners attributes, the MS
MUST report an error (407) and MUST NOT create the conference.
If the MS is unable to configure the conference for any specified
conference event specified in the <subscribe> element, the MS MUST
report an error (406) and MUST NOT create the conference.
When a MS has finished processing a <createconference> request, it
MUST reply with an appropriate <response> element (Section 5.2.3).
For example, a request to create an audio video conference mixer with
specified codecs, video layout, video switch and subscription:
<mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
<createconference conferenceid="conference1"
reserved-talkers="1" reserved-listeners="10">
<codecs>
<codec>
<subtype>H264</subtype>
</codec>
<codec>
<subtype>PCMA</subtype>
</codec>
</codecs>
<audio-mixing type="nbest"/>
<video-layouts>
<video-layout>single-view</video-layout>
<video-layout>dual-view</video-layout>
<video-layout>quad-view</video-layout>
</video-layouts>
<video-switch type="vas" interval="5"/>
<subscribe>
<active-talkers-sub interval="4"/>
</subscribe>
</createconference>
</mscmixer>
and a response from the MS if the conference was sucessfully created:
<mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
<response status="200" conferenceid="conference1"/>
</mscmixer>
Melanchuk, et al. Expires January 7, 2009 [Page 14]
Internet-Draft Mixer Control Package July 2008
alternatively, a response if MS could not create the conference due
to a lack of support for the H264 codec:
<mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
<response status="410" conferenceid="conference1"
reason="H264 codec not supported"/>
</mscmixer>
5.2.1.2. <modifyconference>
The <modifyconference> element is sent to the MS to request
modification of an existing conference.
The <modifyconference> element has the following attributes:
conferenceid: string indicating the name of the conference to
modify. This attribute is mandatory.
The <modifyconference> element has the following sequence of child
elements (1 or more):
<codecs>: an element to configure the codecs supported by the
conference (see Section 5.4). Existing participants are
unaffected by any policy chage. The element is optional.
<audio-mixing>: an element to configure the audio mixing
characteristics of a conference (see Section 5.2.1.4.1). The
element is optional.
<video-layouts>: an element to configure the video layouts of a
conference (see Section 5.2.1.4.2). The element is optional.
<video-switch>: an element to configure the video switch policy for
the layout of a conference (see Section 5.2.1.4.3). The element
is optional.
<subscribe>: an element to request subscription to conference
events. (see Section 5.2.1.4.4). The element is optional.
If the conferenceid attribute specifies the name of a conference
which does not exist, the MS MUST report an error (404).
If the MS is unable to configure the conference according to a
specified <codecs> element, the MS MUST report an error (410) and
MUST NOT modify the conference.
If the MS is unable to configure the conference according to a
specified <audio-mixing> element, the MS MUST report an error (405)
Melanchuk, et al. Expires January 7, 2009 [Page 15]
Internet-Draft Mixer Control Package July 2008
and MUST NOT modify the conference in any way.
If the MS is unable to configure the conference according to a
specified <video-layouts> element, the MS MUST report an error (408)
and MUST NOT modify the conference in any way.
If the MS is unable to configure the conference according to a
specified <video-switch> element, the MS MUST report an error (409)
and MUST NOT modify the conference in any way.
If the MS is unable to configure the conference for any specified
conference event specified in the <subscribe> element, the MS MUST
report an error (406) and MUST NOT modify the conference in anyway.
When a MS has finished processing a <modifyconference> request, it
MUST reply with an appropriate <response> element (Section 5.2.3).
5.2.1.3. <destroyconference>
The <destroyconference> element is sent to the MS to request
destruction of an existing conference.
The <destroyconference> element has the following attributes:
conferenceid: string indicating the name of the conference to
destroy. This attribute is mandatory.
The <destroyconference> element does not specify any child elements.
If the conferenceid attribute specifies the name of a conference
which does not exist, the MS MUST report an error (404).
When a MS has finished processing a <destroyconference> request, it
MUST reply with an appropriate <response> element (Section 5.2.3).
Successfully destroying the conference (status code 200) will result
in all connection or conference particpants being removed from the
conference mixer and <unjoin-notify> notification events being sent
(Section 5.2.4.2). A <response> with any other status code indicates
that the conference mixer still exists and participants are still
joined to the mixer.
5.2.1.4. Conference Configuration
The elements in this section are used to establish and modify the
configuration of conferences.
Melanchuk, et al. Expires January 7, 2009 [Page 16]
Internet-Draft Mixer Control Package July 2008
5.2.1.4.1. <audio-mixing>
The <audio-mixing> element defines the configuration of the
conference audio mix. It has no child elements and has the following
attributes:
type: is a string indicating the audio stream mixing policy.
Defined values are: "nbest" (where the N best participant signals
are mixed) and "controller" (where the contributing participant(s)
is/are selected by the controlling AS via an external floor
control protocol). The default value is "nbest". The attribute
is optional.
5.2.1.4.2. <video-layouts>
The <video-layouts> element describe the video presentation layout
configuration for participants providing a video input stream to the
conference. This element allows multiple video layouts to be
specified so that the MS automatically changes layout depending on
the number of video-enabled participants.
The <video-layouts> element has no attributes.
The <video-layouts> element has the following sequence of child
elements (1 or more):
<video-layout>: element describing a video layout
(Section 5.2.1.4.2.1).
If the MS does not support video conferencing at all, or does not
support multiple video layouts, or does not support a specific video
layout, the MS MUST report an error in the response to the request
element containing the <video-layouts> element.
An MS MAY support more than one <video-layout> element, although only
one layout can be active at a time. A <video-layout> is active if
the number of participants in the conference is equal to or greater
than the value of its "min-participants" attribute, but less than the
value of the "min-participants" attribute for any other <video-
layout> element. An MS MUST report an error if more than one <video-
layout> has the same value for the "min-participants" attribute.
When the number of regions within the active layout is greater than
the number of participants in the conference, the display of
unassigned regions is implementation-specific.
The assignment of participant video streams to regions within the
layout is according to the video switch policy specified by the
<video-switch> element (Section 5.2.1.4.3).
Melanchuk, et al. Expires January 7, 2009 [Page 17]
Internet-Draft Mixer Control Package July 2008
[Editors Note: MIXER-XXX. This definition assumes that only
participants providing a video input stream to the conference are
displayed on the layout. Other participants are not displayed: i.e.
no support for associating avatars with participants not contributing
a video input stream to the conference.]
For example, a fragment describing a single layout:
<video-layouts>
<video-layout>single-view</video-layout>
</video-layouts>
And a fragment describing a sequence of layouts:
<video-layouts>
<video-layout min-participants='1' >single-view</video-layout>
<video-layout min-participants='2'>dual-view</video-layout>
<video-layout min-participants='3'>quad-view</video-layout>
<video-layout min-participants='5'>multiple-3x3</video-layout>
</video-layouts>
When the conference has one participant providing a video input
stream to the conference, then the single-view format is used. When
the conference has two such participants, the dual-view layout is
used. When the conference has three or four particpants, the quad-
view layout is used. When the conference has five or more
particpants, the multiple-3x3 layout is used.
5.2.1.4.2.1. <video-layout>
The <video-layout> element describes a video layout containing one or
more regions in which participant video input stream are displayed.
The <video-layout> element has the following attributes:
min-participants: the minimum number of conference participants
needed to allow this layout to be active. A valid value is a
positive integer (see Section 5.6.3). The attribute is optional.
The default value is one.
The <video-layout> element has a content model specifying the name of
the video layout.
It is RECOMMENDED that an MS support the predefined video layouts
defined in the XCON conference information data model
([I-D.ietf-xcon-common-data-model]). The MS MAY support other video
layouts. It is RECOMMENDED that non-XCON layouts are prefixed with a
label; for example, <video-layout>mylayout:single-view<video-layout>.
Melanchuk, et al. Expires January 7, 2009 [Page 18]
Internet-Draft Mixer Control Package July 2008
Each video layout has associated with it one or more regions. The
XCON layouts have associated the following named regions:
single-view one region with name "region1"
dual-view two regions: left named "region1", right "region2"
XXX etc
[Editors Note: MIXER-XXX. ASCII art help required to draw the layout
and name the regions for the remaining XCON layouts. ]
5.2.1.4.3. <video-switch>
The <video-switch> element describe the configuration of the
conference policy for how participant's input video streams are
assigned to regions within the active video layout.
The <video-switch> element has the following attributes:
type: a string indicating the video switching policy of the
conference. Defined values are:
vas (Voice Activated Switching) enables automatic display of the
most active speaker providing a video input stream to the
conference. If there is only one region in the layout, then
the most active speaker is displayed there. If more than one
region is available, then the most active speaker is displayed
in the largest region, if any, and then in the first region
from the top-left corner of the layout. The policy for how the
remaining regions are assigned is implementation-specific.
controller enables manual control over video switching. The
controller AS determines how the regions are assigned based on
an external floor control policy. The MS receives <join>,
<modifyjoin> and <join> commands with a <stream> element
(Section 5.2.2.5) indicating the region where the stream is
displayed.
An MS MAY support other video switching policies. It is
RECOMMENDED that other policy names are prefixed with a label;
e.g. "mypolicies:policy1". The attribute is optional. The
default value is 'vas'.
interval: specifies the period between video switches as a number of
seconds. In the case of 'vas' policy, a speaker needs to be the
most active speaker for the interval before the switch takes
place. A valid value is a non-negative integer (see
Melanchuk, et al. Expires January 7, 2009 [Page 19]
Internet-Draft Mixer Control Package July 2008
Section 5.6.2). A value of 0 indicates that switching is applied
immediately. The attribute is optional. The default value is 3
(seconds).
If the MS does not support the specified video switching policy, the
MS MUST report an error in the response to the request element
containing the <video-swtich> element.
If the MS receives a <join> or <modifyjoin> request containing a a
<stream> element (Section 5.2.2.5) specifying a region and the
conference video switching policy is set to 'vas', then the MS MUST
ignore the region (i.e. conference switching policy takes
precedence).
The <video-switch> element has no child elements.
For example, a fragment specifying a 'vas' video switching policy
with an interval of 2s
<video-switch type="vas" interval="2"/>
For example, a fragment specifying a 'controller' video switching
policy where video switching takes place immediately:
<video-switch type="controller" interval="0"/>
5.2.1.4.4. <subscribe>
The <subscribe> element is a container for specifying conference
notification events to which a controlling entity subscribes.
Notifications of conference events are delivered using the <event>
element (see Section 5.2.4).
The <subscribe> element has no attributes, but has the following
child element:
<active-talkers-sub>: subscription to active talker events
(Section 5.2.1.4.4.1). The element is optional.
The MS SHOULD support a <active-talkers-sub> subscription. It MAY
support other event subscriptions. If the MS does not support a
requested subscription, it MUST send a <response> with a 406 status
code.
5.2.1.4.4.1. <active-talkers-sub>
The <active-talkers-sub> element has the following attributes:
Melanchuk, et al. Expires January 7, 2009 [Page 20]
Internet-Draft Mixer Control Package July 2008
interval: the minimum amount of time (in seconds) that must elapse
before further active talker events can be generated. A valid
value is a non-negative integer (see Section 5.6.2). A value of 0
suppresses further notifications. The attribute is optional.
There is no default value.
The <active-talker-sub> element has no child elements.
Active talker notifications are delivered in the <active-talker-
notify> element (Section 5.2.4.1).
5.2.2. Joining Elements
5.2.2.1. Joining Model
The <join> operation creates a media stream between a connection and
a conference, between connections, or between conferences. This sub-
section describes the model of conferences and connections and
specifies the behaviour for join requests to targets that already
have an associated media stream.
Conferences support multiple inputs and have resources to mix them
together. A media server conference in essence is a mixer that
combines media streams. A simple audio mix simply sums its input
audio signals to create a single common output. Conferences however
use a more complex algorithm so that participants do not hear
themselves as part of the mix. That algorithm, sometimes called an
n-minus mix, subtracts each participants input signal from the summed
input signals, creating a unique output for each contributing
participant. Each <join> operation to a conference uses one of the
conferences available inputs and/or outputs, to the maximum number of
supported participants.
A connection is the termination of a RTP session(s) on a media
server. It has a single input and output for each media session
established by its SIP dialog. The output of a connection may feed
several different inputs such as both a conference mix and a
recording of that participants audio.
Joining two connections which are are not joined to anything else
simply creates a media stream from the outputs(s) of one connection
to the corresponding inputs(s) of the other connection. It is not
necessary to combine media from multiple sources in this case. There
are however several common scenarios where combining media from
several sources to create a single input to a connection is needed.
In the first case, a connection may be receiving media from one
source, for example a conference, and it is necessary to play an
Melanchuk, et al. Expires January 7, 2009 [Page 21]
Internet-Draft Mixer Control Package July 2008
announcement to the connection so that both the conference audio and
announcement can be heard by the conference participant. This is
sometimes referred to as a whisper announcement. An alternative to a
whisper announcement is to have the announcement pre-empt the
conference media.
Another common case is the call centre 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.
Both of these cases can be solved by having the controlling AS create
one or more conferences for audio mixing and to join and unjoin the
media streams as required. A better solution is to have the media
server automatically mix media streams that are requested to be
joined to a common input when only the simple summing of audio
signals as described above is required. This is the case for both
the use cases presented above.
Automatically mixing streams has several benefits. Conceptually, it
is straight forward and simple, requiring no indirect requests on the
part of the controlling AS. This increases transport efficiency and
reduces the coordination complexity and the latency of the overall
operation. Therefore, it is RECOMMENDED that a media server be able
to automatically mix at least two audio streams where only the simple
summing of signals is required.
When a media server receives a <join> request, it MUST automatically
mix all of the media streams included in the request with any streams
already joined to one of the entities identified in the request, or
it MUST fail the request and MUST NOT join any of the streams. A
controlling AS MUST use the <createconference> request for generic
conferences where the complex mixing algorithm is required.
Specifications which extend this package to handle additional media
types such as text or video, MUST define the semantics of the join
operation when multiple streams are requested to be joined to a
single input, such as that for a connection with a single RTP session
per media type.
5.2.2.2. <join>
The <join> element is sent to the MS to request creation one or more
media streams either between a connection and a conference, between
connections, or between conferences. The two entities to join are
specified by the attributes of <join>.
Streams may be of any media type, and may be bi-directional or uni-
Melanchuk, et al. Expires January 7, 2009 [Page 22]
Internet-Draft Mixer Control Package July 2008
directional. A bi-directional stream is implicitly composed of two
uni-directional streams that can be manipulated independently. The
streams to be established are specified by child <stream> elements
(see Section 5.2.2.5).
The <join> element has the following attributes:
id1: an identifier for either a connection or a conference. The
identifier MUST conform to the syntax defined in Section 17.1 of
[I-D.ietf-mediactrl-sip-control-framework] The attribute is
mandatory.
id2: an identifier for either a connection or a conference. The
identifier MUST conform to the syntax defined in Section 17.1 of
[I-D.ietf-mediactrl-sip-control-framework] The attribute is
mandatory.
Note: Section 17.1 of [I-D.ietf-mediactrl-sip-control-framework]
defines the semantics for a conference identifier but not its syntax.
Media server implementations need to distinguish between conferences
and connections based upon the values of the "id1" and "id2"
attributes.
The <join> element has the following child element (0 or more):
<stream>: an element that both identifies the media streams to join
and defines the way that they are to be joined (see
Section 5.2.2.5). The element is optional.
One or more <stream> elements may be specified so that individual
media streams can be controlled independently. For example, if a
connection supports both audio and video streams, a <stream> element
could be used to indicate that only the audio stream is used in
receive mode. In cases where there are multiple media streams of the
same type for a connection or conference, it is RECOMMENDED that the
configuration is explicitly specified using <stream> elements. If no
<stream> elements are specified, then the default is the media
configuration of the connection or conference.
It is an error if a <stream> element is in conflict with (a) another
<stream> element, (b) with specified connection or conference media
capabilities, (c) with a SDP label value as part of the connection-id
(see Section 17.1 of [I-D.ietf-mediactrl-sip-control-framework]) or
(d) if the media stream configuration is not supported by the MS.
If the MS is unable to execute the join as specified in <stream>
elements, the MS MUST report an error (424) and MUST NOT join the
entities.
Melanchuk, et al. Expires January 7, 2009 [Page 23]
Internet-Draft Mixer Control Package July 2008
If the MS is unable to join an entity to a conference because it is
full, then the MS MUST report an error (421).
If the specified entities are already joined, then the MS MUST report
an error (425).
If the MS does not support joining two specified connections
together, the MS MUST report an error (422).
If the MS does not support joining two specified conferences
together, the MS MUST report an error (423).
If the MS is unable to join the specified entities for any other
reason, the MS MUST report an error (420).
When the MS has finished processing a <join> request, it MUST reply
with an <response> element (Section 5.2.3).
For example, a request to join two connection together:
<mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
<join id1="connnection1" id2="connection2"/>
</mscmixer>
and the response if the MS doesn't support joining media streams
between connections:
<mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
<response status="422" reason="mixing connections not supported"/>
</mscmixer>
5.2.2.3. <modifyjoin>
The <modifyjoin> element is sent to the MS to request changes in the
configuration of media stream(s) that were previously established
between a connection and a conference, between two connections, or
between two conferences.
The <modifyjoin> element has the following attributes:
id1: an identifier for either a connection or a conference. The
identifier MUST conform to the syntax defined in Section 17.1 of
[I-D.ietf-mediactrl-sip-control-framework] The attribute is
mandatory.
Melanchuk, et al. Expires January 7, 2009 [Page 24]
Internet-Draft Mixer Control Package July 2008
id2: an identifier for either a connection or a conference. The
identifier MUST conform to the syntax defined in Section 17.1 of
[I-D.ietf-mediactrl-sip-control-framework] The attribute is
mandatory.
The <modifyjoin> element has the following child elements (1 or
more):
<stream>: an element that both identifies the media streams to
modify and defines the way that each stream should now be
configured (see Section 5.2.2.5).
The MS MUST support <modifyjoin> for any stream that was established
using <join>.
The media server MUST configure the streams that are included within
<modifyjoin> to that stated by the child elements. It MUST NOT
change the configuration of any streams not included as child
elements.
If the MS is unable to modify the join as specified in <stream>
elements, the MS MUST report an error (424) and MUST NOT modify the
join between the entities.
If the specified entities are not already joined, then the MS MUST
report an error (426).
If the MS is unable to modify the join between the specified entities
for any other reason, the MS MUST report an error (420).
When an MS has finished processing a <modifyjoin> request, it MUST
reply with an appropriate <response> element (Section 5.2.3).
5.2.2.4. <unjoin>
The <unjoin> element is sent to the MS to request removal of
previously established media stream(s) from between a connection and
a conference, between two connections, or between two conferences.
The <unjoin> element has the following attributes:
id1: an identifier for either a connection or a conference. The
identifier MUST conform to the syntax defined in Section 17.1 of
[I-D.ietf-mediactrl-sip-control-framework] The attribute is
mandatory.
Melanchuk, et al. Expires January 7, 2009 [Page 25]
Internet-Draft Mixer Control Package July 2008
id2: an identifier for either a connection or a conference. The
identifier MUST conform to the syntax defined in Section 17.1 of
[I-D.ietf-mediactrl-sip-control-framework] The attribute is
mandatory.
The <unjoin> element has the following child element (0 or more
occurrences):
<stream>: an element that identifies the media stream(s) to remove
(see Section 5.2.2.5). The element is optional. When not
present, all streams between "id1" and "id2" are removed.
The MS MUST support <unjoin> for any stream that was established
using <join>.
If the MS is unable to terminate any join as specified in <stream>
elements, the MS MUST report an error (424) and MUST NOT terminate
the join between the entities.
If the specified entities are not already joined, then the MS MUST
report an error (426).
If the MS is unable to terminate the join between the specified
entities for any other reason, the MS MUST report an error (420).
When an MS has successfully processed a <unjoin> request, it MUST
reply with a successful <response> element (Section 5.2.3).
5.2.2.5. <stream>
<join>, <modifyjoin> and <unjoin> require the identification and
manipulations of media streams. Media streams represent the flow of
media between a participant connection and a conference, between two
connections, or between two conferences. The <stream> element is
used (as a child to <join>, <modifyjoin> and <unjoin) to identify the
media stream(s) for the request and to specify the configuration of
the media stream.
The <stream> element has the following attributes:
media: a string indicating the type of media associated with the
stream. It is strongly recommended that the following values are
used for common types of media: "audio" for audio media, and
"video" for video media. The attribute is mandatory.
Melanchuk, et al. Expires January 7, 2009 [Page 26]
Internet-Draft Mixer Control Package July 2008
label: a string indicating the SDP label associated with a media
stream ([RFC4574]). The attribute is optional.
direction: a string indicating the allowed media flow of the stream
relative to the value of the "id1" attribute of the parent
element. Defined values are: "sendrecv" (media can be sent and
received), "sendonly" (media can only be sent), "recvonly" (media
can only be received) and "inactive" (stream is not to be used).
The default value is "sendrecv". The attribute is optional.
The <stream> element has the following sequence of child elements:
<volume>: an element to configure the volume or gain of the media
stream (Section 5.2.2.5.1). The element is optional.
<clamp>: an element to configure filtering and removal of tones from
a media stream (Section 5.2.2.5.2). The element is optional.
<region>: an element to configure region within a video layout where
the media stream is displayed (Section 5.2.2.5.3). The element is
optional.
If the "media" attribute does not have the value of "audio", then the
MS MUST ignored <volume> and <clamp> elements.
If the "media" attribute does not have the value of "video", then the
MS MUST ignored <region> element.
5.2.2.5.1. <volume>
The <volume> element is used to configure the volume of an audio
media stream. It may be set to a specific gain amount, to
automatically adjust the gain to a desired target level, or to mute
the volume.
The <volume> element has no child elements but has the following
attributes:
controltype: a string indicating the type of volume control to use
for the stream. Defined values are: "automatic" (the volume will
be adjusted automatically to the level specified by the "value"
attribute), "setgain" (use the value of the "value" attribute as a
specific gain measured in dB to apply), "setstate" (set the state
of the stream to "mute" or "unmute" as specified by the value of
the "value" attribute). The attribute is optional.
Melanchuk, et al. Expires January 7, 2009 [Page 27]
Internet-Draft Mixer Control Package July 2008
value: a string specifying the amount or state for the volume
control defined by the value of the "controltype" attribute.
5.2.2.5.2. <clamp>
The <clamp> element is used to configure whether tones should be
filtered and removed from a media stream.
The <clamp> element has no child elements but has the following
attributes:
tones: A list of the tones to remove.
5.2.2.5.3. <region>
The <region> element is used to manually specify the region within a
video layout where the media stream is displayed.
The <region> element has no attributes and its content model
specifies the name of the region layout.
If the region name is invalid, then the MS MUST report an error in
the response to the request element containing the <region> element.
5.2.3. <response>
Reponses to requests are indicated by a <response> element.
The <response> element has following attributes:
status: numeric code indicating the response status. Valid valies
are defined in Section 5.5. The attribute is mandatory.
reason: string specifying a reason for the response status. The
attribute is optional.
conferenceid: string identifying the conference (see Section 17.1 of
[I-D.ietf-mediactrl-sip-control-framework]). The attribute is
optional.
connectionid: string identifying the SIP dialog connection (see
Section 17.1 of [I-D.ietf-mediactrl-sip-control-framework]). The
attribute is optional.
For example, a response when a conference was created successfully:
<response code="200">
<reason>Success</reason>
Melanchuk, et al. Expires January 7, 2009 [Page 28]
Internet-Draft Mixer Control Package July 2008
</response>
The response if conference creation failed due to the requested
conference id already existing:
<response code="403">
<reason>Conf already exists</reason>
</response>
5.2.4. <event>
When a mixer generates a notification event, the MS sends the event
using an <event> element.
The <event> element has no attributes, but has the following sequence
of child elements (0 or more instances of each child):
<active-talkers-notify> specifies an active talkers notification
(Section 5.2.4.1).
<unjoin-notify> notifies that a connection or conference has been
completely unjoined (Section 5.2.4.2).
5.2.4.1. <active-talkers-notify>
The <active-talkers-notify> element describes zero or more speakers
that have been active in a conference during the specified interval
(see Section 5.2.1.4.4.1).
The <active-talkers-notify> element has the following attributes:
conferenceid: string indicating the name of the conference from
which the event orginated. This attribute is mandatory.
The <active-talkers-notify> element has the following sequence of
child elements (0 or more occurences):
<active-talker> element describing an active talker
(Section 5.2.4.1.1).
5.2.4.1.1. <active-talker>
The <active-talker> element describes an active talker, associated
with either a connection or conference participant in a conference.
The <active-talker> element has the following attributes:
Melanchuk, et al. Expires January 7, 2009 [Page 29]
Internet-Draft Mixer Control Package July 2008
connectionid: string indicating the connectionid of the active
talker. This attribute is optional. There is no default value.
conferenceid: string indicating the conferenceid of the active
talker. This attribute is optional. There is no default value.
It is an error if both the connectionid and conferenceid attributes
are specified.
The <active-talker> element has no child elements.
5.2.4.2. <unjoin-notify>
The <unjoin-notify> element describes a notification event where a
connection and/or conference have been completely unjoined.
The <unjoin-notify> element has the following attributes:
status: a status code indicating why the unjoin occurred. A valid
value is a non-negative integer (see Section 5.6.2). A value of 1
indicates that the join has been terminated by a <unjoin> request.
A value of 2 indicates that the unjoin occured because the a
connection or conference has terminated. A value of 3 indicates
the join terminated due to an internal error. Any other value
indicates an error defined by the MS. The attribute is mandatory.
reason: a textual description providing a reason for the status
code; e.g. details about an error. A valid value is a string (see
Section 5.6.4). The attribute is optional. There is no default
value.
id1: an identifier for either a connection or a conference. The
identifier MUST conform to the syntax defined in Section 17.1 of
[I-D.ietf-mediactrl-sip-control-framework] The attribute is
mandatory.
id2: an identifier for either a connection or a conference. The
identifier MUST conform to the syntax defined in Section 17.1 of
[I-D.ietf-mediactrl-sip-control-framework] The attribute is
mandatory.
The <unjoin-notify> element has no child elements.
5.3. Audit Elements
The audit elements defined in this section allow the MS to be audited
for package capabilities as well as mixers managed by the package.
Auditing is particularly important for two use cases. First, it
Melanchuk, et al. Expires January 7, 2009 [Page 30]
Internet-Draft Mixer Control Package July 2008
enables discovery of package capabilities supported on an MS before
an AS creates a conference mixer or joins connections and
conferences. The AS may then use this informaton to create request
elements using supported capabilities and, in the case of codecs, to
negotiate an appropriate SDP for a user agent's connection. Second,
auditing enables discovery of the existence and status of mixers
currently managed by the package on the MS. This allows one AS to
take over management of mixers when the AS which initiated the mixers
fails or is no longer available.
5.3.1. <audit>
The <audit> request element is sent to the MS to request information
about the capabilities of, and mixers currently managed with, this
control package. Capabilities include supported conference codecs
and video layouts. Mixer information includes the status of managed
mixers as well as codecs.
The <audit> element has the following attributes:
capabilities: indicates whether package capabilities are to be
audited. A valid value is a boolean (see Section 5.6.1). A value
of true indicates that capability information is to be reported.
A value of false indicates that capability information is not to
be reported. The attribute is optional. The default value is
true.
mixers: indicates whether mixers currently managed by the package
are to be audited. A valid value is a boolean (see
Section 5.6.1). A value of true indicates that mixer information
is to be reported. A value of false indicates that mixer
information is not to be reported. The attribute is optional.
The default value is true.
conferenceid: string identifying a specific conference mixer to
audit. It is an error if the conferenceid attribute is specified
and the conference identifier is not valid. The attribute is
optional. There is no default value.
If the mixers attribute has the value true and conferenceid attribute
is specified, then only audit information about the specified
conference mixer is reported. If the mixers attribute has the value
false, then no mixer audit information is reported even if a
conferenceid attribute is specified.
The <audit> element has no child elements.
When the MS receives a <audit> request, it MUST reply with a
Melanchuk, et al. Expires January 7, 2009 [Page 31]
Internet-Draft Mixer Control Package July 2008
<auditresponse> element (Section 5.3.2). If the request is
successful, <auditresponse> contains (depending on atrribute values)
a <capabilities> element (Section 5.3.2.1) reporting package
capabilities and a <mixers> element (Section 5.3.2.2) reporting
managed mixer information.
For example, a request to audit capabilities and mixers managed by
the package:
<mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
<audit/>
</mscmixer>
In this example, only capabilities are to be audited:
<mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
<audit mixers="false"/>
</mscmixer>
With this example, only a specific conference mixer is to be audited:
<mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
<audit capabilities="false" conferenceid="conf4"/>
</mscmixer>
5.3.2. <auditresponse>
The <auditresponse> element describes a response to a <audit>
request.
The <auditresponse> element has the following attributes:
status: numeric code indicating the audit response status. The
attribute is mandatory. Valid values are defined in Section 5.5.
reason: string specifying a reason for the status. The attribute is
optional.
The <auditresponse> element has the following sequence of child
elements:
<capabilities> element (Section 5.3.2.1) describing capabilities of
the package. The element is optional.
<mixers> element (Section 5.3.2.2) describing information about
managed mixers. The element is optional.
For example, a successful response to a <audit> request requesting
Melanchuk, et al. Expires January 7, 2009 [Page 32]
Internet-Draft Mixer Control Package July 2008
capabilities and mixer information:
<mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
<auditresponse status="200">
<capabilities>
<codecs>
<codec>
<subtype>H263</subtype>
</codec>
<codec>
<subtype>H264</subtype>
</codec>
<codec>
<subtype>PCMU</subtype>
</codec>
<codec>
<subtype>PCMA</subtype>
</codec>
</codecs>
</capabilities>
<mixers>
<conferenceaudit conferenceid="conf1">
<codecs>
<codec>
<subtype>PCMA</subtype>
</codec>
</codecs>
<participants>
<participant id="connection1"/>
</participants>
</conferenceaudit>
<joinaudit id1="connection1" id2="conf1"/>
<joinaudit id1="connection2" id2="connection3"/>
<joinaudit id1="connection4" id2="connection5"/>
</mixers>
</auditresponse>
</mscmixer>
5.3.2.1. <capabilities>
The <capabilities> element provides audit information about package
capabilities.
The <capabilities> element has no attributes.
The <capabilities> element has the following sequence of child
elements:
Melanchuk, et al. Expires January 7, 2009 [Page 33]
Internet-Draft Mixer Control Package July 2008
<codecs>: element (Section 5.4) describing codecs available to the
package. The element is mandatory.
For example, a fragment describing capabilities:
<capabilities>
<codecs>
<codec>
<subtype>H263</subtype>
</codec>
<codec>
<subtype>H264</subtype>
</codec>
<codec>
<subtype>PCMU</subtype>
</codec>
<codec>
<subtype>PCMA</subtype>
</codec>
</codecs>
</capabilities>
5.3.2.2. <mixers>
The <mixers> element provides audit information about mixers.
The <mixers> element has no attributes.
The <mixers> element has the following sequence of child elements (0
or more occurences, any order):
<conferenceaudit>: audit information for a conference mixer
(Section 5.3.2.2.1). The element is optional.
<joinaudit>: audit information for a join mixer (Section 5.3.2.2.2).
The element is optional.
5.3.2.2.1. <conferenceaudit>
The <conferenceaudit> element has the following attributes:
conferenceid: string identifying the conference (see Section 17.1 of
[I-D.ietf-mediactrl-sip-control-framework]). The attribute is
mandatory.
The <conferenceaudit> element has the following sequence of child
elements:
Melanchuk, et al. Expires January 7, 2009 [Page 34]
Internet-Draft Mixer Control Package July 2008
<codecs> element describing codecs used in the conference. See
Section 5.4. The element is optional.
<participants> element listing connections or conferences joined to
the conference. See Section 5.3.2.2.1.1. The element is
optional.
[Editors Note: MIXER-XXX. More conference information required? AV
mixing policies? etc]
For example, a fragment describing a conference which has been
created but has no participants:
<conferenceaudit conferenceid="conference1"/>
And a fragment when the same conference has three participants (two
connections and another conference) joined to it:
<conferenceaudit conferenceid="conference1">
<codecs>
<codec>
<subtype>PCMU</subtype>
</codec>
</codecs>
<participants>
<participant id="connection1"/>
<participant id="connection2"/>
<participant id="conference2"/>
</participants>
</conferenceaudit>
5.3.2.2.1.1. <participants>
[Editors Note: MIXER-XXX. Is 'participants' too xcon? endpoints? ]
The <participants> element is a container for <participant> elements
(Section 5.3.2.2.1.1.1).
The <participants> element has no attributes, but the following child
elements are defined (0 or more):
<participant>: specifies a participant (Section 5.3.2.2.1.1.1).
5.3.2.2.1.1.1. <participant>
The <participant> element describes a participant.
The <participant> element has the following attributes:
Melanchuk, et al. Expires January 7, 2009 [Page 35]
Internet-Draft Mixer Control Package July 2008
id: an identifier for either a connection or a conference. The
identifier MUST conform to the syntax defined in Section 17.1 of
[I-D.ietf-mediactrl-sip-control-framework]. The attribute is
mandatory.
The <participant> element has no children.
5.3.2.2.2. <joinaudit>
The <joinaudit> element has the following attributes:
id1: an identifier for either a connection or a conference. The
identifier MUST conform to the syntax defined in Section 17.1 of
[I-D.ietf-mediactrl-sip-control-framework] The attribute is
mandatory.
id2: an identifier for either a connection or a conference. The
identifier MUST conform to the syntax defined in Section 17.1 of
[I-D.ietf-mediactrl-sip-control-framework] The attribute is
mandatory.
The <joinaudit> element has no children.
[Editors Note: MIXER-XXX. Do we need to specify stream information
associated with the join?]
For example, a fragment describing an audit of two join mixers, one
between connections and the second between conferences:
<mixers>
<joinaudit id1="connection1" id2="connection2"/>
<joinaudit id1="conference1" id2="conference2"/>
</mixers>
5.4. <codecs>
The <codecs> element is a container for one or more codec
definitions. Codec definitions are used by an AS to specify the
codecs allowed for a conference (e.g. when used as a child of
<createconference> or <modifyconference). Codec definitions are used
by an MS to provide audit information about the codecs supported by
an MS and used in specific conferences.
The <codecs> element has no attributes.
The <codecs> element has the following sequence of child elements (0
or more occurences):
Melanchuk, et al. Expires January 7, 2009 [Page 36]
Internet-Draft Mixer Control Package July 2008
<codec>: defines a codec and optionally its policy(Section 5.4.1).
The element is optional.
For example, a fragment describing two codecs:
<codecs>
<codec>
<subtype>PCMA</subtype>
</codec>
<codec>
<subtype>H263</subtype>
</codec>
</codecs>
5.4.1. <codec>
The <codec> element describes a codec. The element is defined in the
XCON conference information data model
([I-D.ietf-xcon-common-data-model]).
Note that additional information about the codec can be provided
through schema extensibility (see Section 6).
[Editors Note: MIXER-XXX. Do we need to define additional
information? specific (rate, speed, etc)?]
For example, a fragment with a <codec> element describing the H263
codec:
<codec>
<subtype>H263</subtype>
</codec>
5.5. Response Status Codes
The following status codes for mixer management reponses
(Section 5.2.3) and audit responses Section 5.3.2) responses are
defined.
Melanchuk, et al. Expires January 7, 2009 [Page 37]
Internet-Draft Mixer Control Package July 2008
+-----------+-------------------------------------------------------+
| code | description |
+-----------+-------------------------------------------------------+
| 200 | OK |
| | |
| 403 | Conference already exists |
| | |
| 404 | Conference does not exist |
| | |
| 405 | Unable to configure audio mix |
| | |
| 406 | Unable to create subscription |
| | |
| 407 | Conference reservation failed |
| | |
| 408 | Unable to configure video layouts |
| | |
| 409 | Unable to configure video switch |
| | |
| 410 | Unable to configure codecs |
| | |
| 420 | Unable to join requested entities |
| | |
| 421 | Unable to join - conference full |
| | |
| 422 | Unable to join - mixing connections not supported |
| | |
| 423 | Unable to join - mixing conferences not supported |
| | |
| 424 | invalid joining stream configuration |
| | |
| 425 | joining already joined |
| | |
| 426 | joining entities not joined |
| | |
| 450 | Unknown or unsupported element |
| | |
| 451 | Element required |
| | |
| 452 | Unknown or unsupported attribute |
| | |
| 453 | Attribute required |
+-----------+-------------------------------------------------------+
Table 1: response status codes
Melanchuk, et al. Expires January 7, 2009 [Page 38]
Internet-Draft Mixer Control Package July 2008
5.6. Type Definitions
This section defines types referenced in attribute definitions.
5.6.1. Boolean
The value space of boolean is the set {true, false}.
5.6.2. Non-Negative Integer
The value space of non-negative integer is the infinite set
{0,1,2,...}.
5.6.3. Positive Integer
The value space of positive integer is the infinite set {1,2,...}.
5.6.4. String
A string in the character encoding associated with the XML element.
5.6.5. Time Designation
A time designation consists of a non-negative real number followed by
a time unit identifier.
The time unit identifiers are: "ms" (milliseconds) and "s" (seconds).
Examples include: "3s", "850ms", "0.7s", ".5s" and "+1.5s".
Melanchuk, et al. Expires January 7, 2009 [Page 39]
Internet-Draft Mixer Control Package July 2008
6. Formal Syntax
This section defines the XML schema for the Mixer Control Package.
The schema defines datatypes, attributes, and mixer elements in the
urn:ietf:params:xml:ns:msc-mixer namespace. In most elements the
order of child elements is significant. The schema is extensible:
elements allow attributes and child elements from other namespaces.
Elements from outside this package's namespace can occur after
elements defined in this package.
The schema is dependent upon the schema (framework.xsd) defined in
Section 17.1 of the Control Framework
[I-D.ietf-mediactrl-sip-control-framework].
Figure 1: Mixer Package XML Schema
Melanchuk, et al. Expires January 7, 2009 [Page 40]
Internet-Draft Mixer Control Package July 2008
7. Examples
This section provides examples of the Mixer Control package.
7.1. AS-MS Dialog Interaction Examples
The following example assume a control channel has been established
and synced as described in the Media Control Channel Framework
([I-D.ietf-mediactrl-sip-control-framework]).
The XML messages are in angled brackets (with the root <mscmixer>
omitted); the REPORT status is in round brackets. Other aspects of
the protocol are omitted for readability.
7.1.1. Creating a conference mixer and joining a participant
A conference mixer is created successfully and a participant is
joined.
Application Server (AS) Media Server (MS)
| |
| (1) CONTROL: <createconference> |
| ----------------------------------------> |
| |
| (2) 202 |
| <--------------------------------------- |
| |
| |
| (3) REPORT: <response status="200"/> |
| (terminate) |
| <---------------------------------------- |
| |
| (4) 200 |
| ----------------------------------------> |
| |
| (5) CONTROL: <join id1=.. id2=..> |
| ----------------------------------------> |
| |
| (6) 202 |
| <--------------------------------------- |
| |
| (7) REPORT: <response status="200"/> |
| (terminate) |
| <---------------------------------------- |
| |
| (8) 200 |
| ----------------------------------------> |
Melanchuk, et al. Expires January 7, 2009 [Page 41]
Internet-Draft Mixer Control Package July 2008
7.1.2. Receiving active talker notifications
An active talker notification event is sent by the MS.
Application Server (AS) Media Server (MS)
| |
| (1) CONTROL: <event ...> |
| <--------------------------------------- |
| |
| (4) 200 |
| ----------------------------------------> |
| |
Melanchuk, et al. Expires January 7, 2009 [Page 42]
Internet-Draft Mixer Control Package July 2008
8. Security Considerations
As this control package uses XML markup, implementation MUST address
the security considerations of [RFC3023].
Melanchuk, et al. Expires January 7, 2009 [Page 43]
Internet-Draft Mixer Control Package July 2008
9. IANA Considerations
This specification instructs IANA to register a new Media Control
Channel Framework Package, a new XML namespace and a new mime type.
9.1. Control Package Registration
Control Package name: msc-mixer/1.0
9.2. URN Sub-Namespace Registration
XML namspace: urn:ietf:params:xml:ns:msc-mixer
9.3. MIME Registration
Mime type: application/msc-mixer+xml
Melanchuk, et al. Expires January 7, 2009 [Page 44]
Internet-Draft Mixer Control Package July 2008
10. Change Summary
Note to RFC Editor: Please remove this whole section.
The following are the major changes between the -00 of this work
group item draft and the individual submission -04 version.
o Control package name is now 'msc-mixer/1.0'. Namespace is now
'urn:ietf:params:xml:ns:msc-mixer'. Mime type is now
'application/msc-mixer+xml'.
o Added XML root element <mscmixer>.
o Editorial tidy up of sections.
o Added audit request/response elements.
o Added video layout and switching conference configuration.
o <audio-mixing>: changed 'mix-type' attribute to 'type'
(consistency with video-switch)
o Added "inactive" as value of <stream>'s direction attribute.
o Added <region> child to <stream> element.
o <createconference>: <audio-mixing> element is no longer mandatory;
added <video-layouts> and <video-switch> child elements. reserved-
talkers and reserved-listeners as attributes.
o replaced conf-id attribute with conferenceid attribute.
o Removed <data> element. Active talkers subscription and
notifications used dedicated elements now.
o Added <unjoin-notif> notification event to indicate when
(un)expected joins occur. Use case: connection or conference
joined to a conference and conference exits (either by request or
runtime error.
The following are the major changes between the -04 of the draft and
the -03 version.
o Updated reference for Media Control Channel Framework
The following are the major changes between the -03 of the draft and
the -02 version.
Melanchuk, et al. Expires January 7, 2009 [Page 45]
Internet-Draft Mixer Control Package July 2008
o None
The following are the major changes between the -02 of the draft and
the -01 version.
o clarified the model for join operations and introduced several new
package error codes
o added definition for MS connection
The following are the major changes between the -01 of the draft and
the -00 version.
o restructured into single request response model for non-trival
operations
o aligned with XML structure of other control framework packages
Melanchuk, et al. Expires January 7, 2009 [Page 46]
Internet-Draft Mixer Control Package July 2008
11. Contributors
Asher Shiratzky from Radvision provided valuable support and
contributions to early versions of this document.
Melanchuk, et al. Expires January 7, 2009 [Page 47]
Internet-Draft Mixer Control Package July 2008
12. Acknowledgments
The authors would like to thank Roni Even, Lorenzo Miniero and Steve
Buko for expert reviews of this work.
Melanchuk, et al. Expires January 7, 2009 [Page 48]
Internet-Draft Mixer Control Package July 2008
13. References
13.1. Normative References
[I-D.ietf-mediactrl-sip-control-framework]
Boulton, C., Melanchuk, T., and S. McGlashan, "Media
Control Channel Framework",
draft-ietf-mediactrl-sip-control-framework-02 (work in
progress), April 2008.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
13.2. Informative References
[I-D.ietf-xcon-common-data-model]
Novo, O., Camarillo, G., Morgan, D., and R. Even,
"Conference Information Data Model for Centralized
Conferencing (XCON)", draft-ietf-xcon-common-data-model-10
(work in progress), March 2008.
[MSML] Saleem, A., Xin, Y., and G. Sharratt, "Media Session
Markup Language (MSML)", draft-saleem-msml-06 (work in
progress), February 2008.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media
Types", RFC 3023, January 2001.
[RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston,
A., Peterson, J., Sparks, R., Handley, M., and E.
Schooler, "SIP: Session Initiation Protocol", RFC 3261,
June 2002.
[RFC3262] Rosenberg, J. and H. Schulzrinne, "Reliability of
Provisional Responses in Session Initiation Protocol
(SIP)", RFC 3262, June 2002.
[RFC3263] Rosenberg, J. and H. Schulzrinne, "Session Initiation
Protocol (SIP): Locating SIP Servers", RFC 3263,
June 2002.
[RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model
with Session Description Protocol (SDP)", RFC 3264,
June 2002.
Melanchuk, et al. Expires January 7, 2009 [Page 49]
Internet-Draft Mixer Control Package July 2008
[RFC3550] Schulzrinne, H., Casner, S., Frederick, R., and V.
Jacobson, "RTP: A Transport Protocol for Real-Time
Applications", STD 64, RFC 3550, July 2003.
[RFC3725] Rosenberg, J., Peterson, J., Schulzrinne, H., and G.
Camarillo, "Best Current Practices for Third Party Call
Control (3pcc) in the Session Initiation Protocol (SIP)",
BCP 85, RFC 3725, April 2004.
[RFC4574] Levin, O. and G. Camarillo, "The Session Description
Protocol (SDP) Label Attribute", RFC 4574, August 2006.
[RFC5022] Van Dyke, J., Burger, E., and A. Spitzer, "Media Server
Control Markup Language (MSCML) and Protocol", RFC 5022,
September 2007.
[RFC5167] Dolly, M. and R. Even, "Media Server Control Protocol
Requirements", RFC 5167, March 2008.
[XML] Bray, T., Paoli, J., Sperberg-McQueen, C M., Maler, E.,
and F. Yergeau, "Extensible Markup Language (XML) 1.0
(Third Edition)", W3C Recommendation, February 2004.
Melanchuk, et al. Expires January 7, 2009 [Page 50]
Internet-Draft Mixer Control Package July 2008
Authors' Addresses
Tim Melanchuk
Rain Willow Communications
Email: tim.melanchuk@gmail.com
Scott McGlashan
Hewlett-Packard
Gustav III:s boulevard 36
SE-16985 Stockholm, Sweden
Email: scott.mcglashan@hp.com
Chris Boulton
Avaya
Building 3
Wern Fawr Lane
St Mellons
Cardiff, South Wales CF3 5EA
Email: cboulton@avaya.com
Melanchuk, et al. Expires January 7, 2009 [Page 51]
Internet-Draft Mixer Control Package July 2008
Full Copyright Statement
Copyright (C) The IETF Trust (2008).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Melanchuk, et al. Expires January 7, 2009 [Page 52]
