tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 6505

 
 
 

A Mixer Control Package for the Media Control Channel Framework

Part 3 of 5, p. 28 to 56
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 28 
4.2.2.  Joining Elements

   This section contains definitions of the joining model
   (Section 4.2.2.1) as well as the <join> (Section 4.2.2.2),
   <modifyjoin> (Section 4.2.2.3), <unjoin> (Section 4.2.2.4) and
   <stream> (Section 4.2.2.5) elements.

4.2.2.1.  Joining Model

   The <join> operation creates a media stream between a connection and
   a conference, between connections, or between conferences.  This
   section describes the model of conferences and connections and
   specifies the behavior 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 mixer 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
   conference's available inputs and/or outputs, to the maximum number
   of supported participants.

   A connection is the termination of one or more RTP sessions 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
   can feed several different inputs such as both a conference mixer and
   a recording of that participant's audio.

   Joining two connections that 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 can be receiving media from one
   source (for example, a conference), and it is necessary to play an
   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 preempt the
   conference media.

Top      Up      ToC       Page 29 
   Another common case is the call-center coaching scenario where a
   supervisor can listen to the conversation between an agent and a
   customer, and provide hints to the agent that 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 then 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 straightforward 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 (and
   MUST NOT change existing streams of the entities).  A controlling AS
   uses the <createconference> request for generic conferences where the
   complex mixing algorithm is required.

   Specifications that extend this package to handle additional media
   types such as text 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.

4.2.2.2.  <join>

   The <join> element is sent to the MS to request creation of 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 can be of any media type and can 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 child <stream> elements
   (see Section 4.2.2.5).

Top      Up      ToC       Page 30 
   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 Appendix A.1 of
      [RFC6230].  The attribute is mandatory.

   id2:  an identifier for either a connection or a conference.  The
      identifier MUST conform to the syntax defined in Appendix A.1 of
      [RFC6230].  The attribute is mandatory.

   Note: Appendix A.1 of [RFC6230] 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.

   If id1 or id2 specify a conference identifier and the conference does
   not exist on the MS, the MS reports an error (406).  If id1 or id2
   specify a connection identifier and the connection does not exist on
   the MS, the MS reports an error (412).

   The <join> element has the following child element (zero 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 4.2.2.5).  The element is optional.

   If no <stream> elements are specified, then the default is to join
   all streams between the entities according to the media configuration
   of the connection or conference.

   One or more <stream> elements can 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, the configuration MUST be
   explicitly specified using <stream> elements.

   Multiple <stream> elements can be specified for precise control over
   the media flow in different directions within the same media stream.
   One <stream> element can be specified for the receiving media flow
   and another element for the sending media flow, where each
   independently controls features such as volume (see child element of
   <stream> in Section 4.2.2.5).  If there is only one <stream> element
   for a given media specifying a 'sendonly' or 'recvonly' direction,
   then the media flow in the opposite direction is inactive
   (established but there's no actual flow of media) unless this leads
   to a stream conflict.

Top      Up      ToC       Page 31 
   If the MS is unable to execute the join as specified in <stream>
   because a <stream> element is in conflict with (a) another <stream>
   element, (b) specified connection or conference media capabilities
   (including supported or available codec information), or (c) an
   Session Description Protocol (SDP) label value as part of the
   connection-id (see Appendix A.1 of [RFC6230]), then the MS reports an
   error (407) and MUST NOT join the entities and MUST NOT change
   existing streams of the entities.

   If the MS is unable to execute the join as specified in <stream>
   elements because the MS does not support the media stream
   configuration, the MS reports an error (422) and MUST NOT join the
   entities and MUST NOT change existing streams of the entities.

   If the MS is unable to join an entity to a conference because it is
   full, then the MS reports an error (410).

   If the specified entities are already joined, then the MS reports an
   error (408).

   If the MS does not support joining two specified connections
   together, the MS reports an error (426).

   If the MS does not support joining two specified conferences
   together, the MS reports an error (427).

   If the MS is unable to join the specified entities for any other
   reason, the MS reports an error (411).

   When the MS has finished processing a <join> request, it MUST reply
   with an <response> element (Section 4.2.3).

   For example, a request to join two connections together is as
   follows:

   <mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
    <join id1="1536067209:913cd14c" id2="1536067209:913cd14c"/>
   </mscmixer>

   The response if the MS doesn't support joining media streams between
   connections is as follows:

   <mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
    <response status="426" reason="mixing connections not supported"/>
   </mscmixer>

Top      Up      ToC       Page 32 
4.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 Appendix A.1 of
      [RFC6230].  The attribute is mandatory.

   id2:  an identifier for either a connection or a conference.  The
      identifier MUST conform to the syntax defined in Appendix A.1 of
      [RFC6230].  The attribute is mandatory.

   The <modifyjoin> element has the following child elements (one or
   more):

   <stream>:   an element that both identifies the media streams to
      modify and defines the way that each stream is to be configured
      from this point forward (see Section 4.2.2.5).

   The MS MUST support <modifyjoin> for any stream that was established
   using <join>.

   The MS MUST configure the streams that are included within
   <modifyjoin> to that stated by the child elements.

   If the MS is unable to modify the join as specified in <stream>
   elements because a <stream> element is in conflict with (a) another
   <stream> element, (b) specified connection or conference media
   capabilities (including supported or available codec information), or
   (c) a SDP label value as part of the connection-id (see Appendix A.1
   of [RFC6230]), then the MS reports an error (407) and MUST NOT modify
   the join between the entities and MUST NOT change existing streams of
   the entities.

   If the MS is unable to modify the join as specified in <stream>
   elements because the MS does not support the media stream
   configuration, the MS reports an error (422) and MUST NOT modify the
   join between the entities and MUST NOT change existing streams of the
   entities.

   If the specified entities are not already joined, then the MS reports
   an error (409).

Top      Up      ToC       Page 33 
   If the MS is unable to modify the join between the specified entities
   for any other reason, the MS reports an error (411).

   When an MS has finished processing a <modifyjoin> request, it MUST
   reply with an appropriate <response> element (Section 4.2.3).

   In cases where stream characteristics are controlled independently
   for each direction, then a <modifyjoin> request needs to specify a
   child element for each direction in order to retain the original
   stream directionality.  For the example, if a <join> request
   establishes independent control for each direction of an audio stream
   (see Section 4.2.2.5):

   <mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
    <join id1="1536067209:913cd14c" id2="conference1">
     <stream media="audio" direction="sendonly">
      <volume controltype="setgain" value="-3"/>
     </stream>
     <stream media="audio" direction="recvonly">
      <volume controltype="setgain" value="+3"/>
     </stream>
    </join>
   </mscmixer>

   then the following <modifyjoin> request

   <mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
    <modifyjoin id1="1536067209:913cd14c" id2="conference1">
     <stream media="audio" direction="sendonly">
       <volume controltype="setgain" value="0"/>
     </stream>
     </modifyjoin>
   </mscmixer>

   would cause, in addition to the modification of the sendonly volume,
   the overall stream directionality to change from sendrecv to sendonly
   since there is no <stream> element in this <modifyjoin> request for
   the recvonly direction.  The following would change the sendonly
   volume and retain the recvonly stream together with its original
   characteristics such as volume:

Top      Up      ToC       Page 34 
   <mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
    <modifyjoin id1="1536067209:913cd14c" id2="conference1">
     <stream media="audio" direction="sendonly">
       <volume controltype="setgain" value="0"/>
     </stream>
     <stream media="audio" direction="recvonly"/>
     </modifyjoin>
   </mscmixer>

4.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 Appendix A.1 of
      [RFC6230].  The attribute is mandatory.

   id2:  an identifier for either a connection or a conference.  The
      identifier MUST conform to the syntax defined in Section 15.1 of
      [RFC6230].  The attribute is mandatory.

   The <unjoin> element has the following child element (zero or more
   occurrences):

   <stream>:   an element that identifies the media stream(s) to remove
      (see Section 4.2.2.5).  The element is optional.  When not
      present, all currently established streams between "id1" and "id2"
      are removed.

   The MS MUST support <unjoin> for any stream that was established
   using <join> and that has not already been removed by a previous
   <unjoin> on the same stream.

   If the MS is unable to terminate the join as specified in <stream>
   elements because a <stream> element is in conflict with (a) another
   <stream> element, (b) specified connection or conference media
   capabilities, or (c) a SDP label value as part of the connection-id
   (see Appendix A.1 of [RFC6230]), then the MS reports an error (407)
   and MUST NOT terminate the join between the entities and MUST NOT
   change existing streams of the entities.

Top      Up      ToC       Page 35 
   If the MS is unable to terminate the join as specified in <stream>
   elements because the MS does not support the media stream
   configuration, the MS reports an error (422) and MUST NOT terminate
   the join between the entities and MUST NOT change existing streams of
   the entities.

   If the specified entities are not already joined, then the MS reports
   an error (409).

   If the MS is unable to terminate the join between the specified
   entities for any other reason, the MS reports an error (411).

   When an MS has successfully processed a <unjoin> request, it MUST
   reply with a successful <response> element (Section 4.2.3).

4.2.2.5.  <stream>

   <join>, <modifyjoin>, and <unjoin> require the identification and
   manipulation 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.  A valid value is a MIME type name as defined in Section
      4.2 of [RFC4288].  The following values MUST be used for common
      types of media: "audio" for audio media, and "video" for video
      media.  See [IANA] for registered MIME type names.  The attribute
      is mandatory.

   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 established but no
      media flow).  The default value is "sendrecv".  The attribute is
      optional.

Top      Up      ToC       Page 36 
   The <stream> element has the following sequence of child elements:

   <volume>:  an element (Section 4.2.2.5.1) to configure the volume or
      gain of the media stream.  The element is optional.

   <clamp>:  an element (Section 4.2.2.5.2) to configure filtering and
      removal of tones from the media stream.  The element is optional.

   <region>:  an element (Section 4.2.2.5.3) to configure a region
      within a video layout where the media stream is displayed.  The
      element is optional.

   <priority>:  an element (Section 4.2.2.5.4) to configure priority
      associated with the stream in the media mix.  The element is
      optional.

   In each child element, the media stream affected is indicated by the
   value of the 'direction' attribute of the parent element.

   If the 'media' attribute does not have the value of "audio", then the
   MS ignores <volume> and <clamp> elements.

   If the 'media' attribute does not have the value of "video", then the
   MS ignores a <region> element.

   For example, a request to join a connection to conference in both
   directions with volume control is as follows:

   <mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
    <join id1="1536067209:913cd14c" id2="conference1">
     <stream media="audio" direction="sendrecv">
      <volume controltype="setgain" value="-3"/>
     </stream>
    </join>
   </mscmixer>

   where audio flow from the connection (id1) to the conference (id2)
   has the volume lowered by 3 dB, and likewise the volume of the audio
   flow from the conference to the connection is lowered by 3 dB.

   In this example, the volume is independently controlled for each
   direction.

Top      Up      ToC       Page 37 
   <mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
    <join id1="1536067209:913cd14c" id2="conference1">
     <stream media="audio" direction="sendonly">
      <volume controltype="setgain" value="-3"/>
     </stream>
     <stream media="audio" direction="recvonly">
      <volume controltype="setgain" value="+3"/>
     </stream>
    </join>
   </mscmixer>

   where audio flow from the connection (id1) to the conference (id2)
   has the volume lowered by 3 dB, but the volume of the audio flow from
   the conference to the connection is raised by 3 dB.

4.2.2.5.1.  <volume>

   The <volume> element is used to configure the volume of an audio
   media stream.  It can 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), and "setstate" (set the
      state of the stream to "mute" or "unmute" as specified by the
      value of the 'value' attribute).  The attribute is mandatory.

   value:  a string specifying the amount or state for the volume
      control defined by the value of the 'controltype' attribute.  The
      attribute is optional.  There is no default value.

   If the audio media stream is in a muted state, then the MS also
   changes automatically the state to unmuted with an "automatic" or
   "setgain" volume control.  For example, assume an audio stream has
   been muted with <volume controltype="setstate" value="mute"/>.  If
   the gain on the same stream is changed with <volume
   controltype="setgain" value="+3"/>, then the volume is increased and
   stream state is also changed to unmuted.

Top      Up      ToC       Page 38 
4.2.2.5.2.  <clamp>

   The <clamp> element is used to configure whether tones are filtered
   and removed from a media stream.

   The <clamp> element has no child elements but has the following
   attribute:

   tones:  A space-separated list of the tones to remove.  The attribute
      is optional.  The default value is "1 2 3 4 5 6 7 8 9 0 * # A B C
      D" (i.e., all DTMF (Dual-Tone Multi-Frequency) tones are removed).

4.2.2.5.3.  <region>

   As described in Section 4.2.1.4.2.1, each <video-layout> is composed
   of one or more named regions (or areas) in which video media can be
   presented.  For example, the XCON layout <dual-view> has two regions
   named "1" and "2", respectively.

   The <region> element is used to explicitly specify the name of the
   area within a video layout where a video media stream is displayed.

   The <region> element has no attributes, and its content model
   specifies the name of the region.

4.2.2.5.4.  <priority>

   The <priority> element is used to explicitly specify the priority of
   a participant.  The MS uses this priority to determine where the
   media stream is displayed within a video layout
   (Section 4.2.1.4.3.1).

   The <priority> element has no attributes, and its content model
   specifies a positive integer (see Section 4.7.3).  The lower the
   value, the higher the priority.

4.2.3.  <response>

   Responses to requests are indicated by a <response> element.

   The <response> element has following attributes:

   status:  numeric code indicating the response status.  Valid values
      are defined in Section 4.6.  The attribute is mandatory.

   reason:  string specifying a reason for the response status.  The
      attribute is optional.

Top      Up      ToC       Page 39 
   desclang:  specifies the language used in the value of the 'reason'
      attribute.  A valid value is a language identifier
      (Section 4.7.7).  The attribute is optional.  If not specified,
      the value of the 'desclang' attribute on <mscmixer> (Section 4.1)
      applies.

   conferenceid:  string identifying the conference (see Appendix A.1 of
      [RFC6230]).  The attribute is optional.

   connectionid:  string identifying the SIP dialog connection (see
      Appendix A.1 of [RFC6230]).  The attribute is optional.

   For example, a response when a conference was created successfully is
   as follows:

   <response code="200"/>

   If conference creation failed due to the requested conference ID
   already existing, the response is:

   <response code="405" reason="Conference already exists"/>

4.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 (zero or more instances of each child):

   <active-talkers-notify>:  specifies an active talkers notification
      (Section 4.2.4.1).

   <unjoin-notify>:  notifies that a connection or conference has been
      completely unjoined (Section 4.2.4.2).

   <conferenceexit>:  notifies that a conference has exited
      (Section 4.2.4.3).

4.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 4.2.1.4.4.1).

Top      Up      ToC       Page 40 
   The <active-talkers-notify> element has the following attribute:

   conferenceid:  string indicating the name of the conference from
      which the event originated.  This attribute is mandatory.

   The <active-talkers-notify> element has the following sequence of
   child elements (zero or more occurrences):

   <active-talker>:  element describing an active talker
      (Section 4.2.4.1.1).

4.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:

   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.

   Note that the element does not describe an active talker if both the
   'connectionid' and 'conferenceid' attributes are specified, or if
   neither attribute is specified.

   The <active-talker> element has no child elements.

4.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 4.7.2).  The MS MUST
      support the following values:

      0  indicates the join has been terminated by a <unjoin> request.

      1  indicates the join terminated due to an execution error.

      2  indicates that the join terminated because a connection or
         conference has terminated.

Top      Up      ToC       Page 41 
      All other valid but undefined values are reserved for future use,
      where new status codes are assigned using the Standards Action
      process defined in [RFC5226].  The AS MUST treat any status code
      it does not recognize as being equivalent to 1 (join execution
      error).  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 4.7.4).  The attribute is optional.  There is no
      default value.

   desclang:  specifies the language used in the value of the 'reason'
      attribute.  A valid value is a language identifier
      (Section 4.7.7).  The attribute is optional.  If not specified,
      the value of the 'desclang' attribute on <mscmixer> (Section 4.1)
      applies.

   id1:  an identifier for either a connection or a conference.  The
      identifier MUST conform to the syntax defined in Appendix A.1 of
      [RFC6230].  The attribute is mandatory.

   id2:  an identifier for either a connection or a conference.  The
      identifier MUST conform to the syntax defined in Appendix A.1 of
      [RFC6230].  The attribute is mandatory.

   The <unjoin-notify> element has no child elements.

4.2.4.3.  <conferenceexit>

   The <conferenceexit> element indicates that a conference has exited
   because it has been terminated or because a error occurred (for
   example, a hardware error in the conference mixing unit).  This event
   MUST be sent by the MS whenever a successfully created conference
   exits.

   The <conferenceexit> element has the following attributes:

   conferenceid:  string indicating the name of the conference.  This
      attribute is mandatory.

   status:  a status code indicating why the conference exited.  A valid
      value is a non-negative integer (see Section 4.7.2).  The MS MUST
      support the following values:

      0  indicates the conference has been terminated by a
         <destroyconference> request.

      1  indicates the conference terminated due to an execution error.

Top      Up      ToC       Page 42 
      2  indicates the conference terminated due to exceeding the
         maximum duration for a conference.

      All other valid but undefined values are reserved for future use,
      where new status codes are assigned using the Standards Action
      process defined in [RFC5226].  The AS MUST treat any status code
      it does not recognize as being equivalent to 1 (conference
      execution error).  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 4.7.4).  The attribute is optional.  There is no
      default value.

   desclang:  specifies the language used in the value of the 'reason'
      attribute.  A valid value is a language identifier
      (Section 4.7.7).  The attribute is optional.  If not specified,
      the value of the 'desclang' attribute on <mscmixer> (Section 4.1)
      applies.

   The <conferenceexit> element has no child elements.

   When a MS sends a <conferenceexit> event, the identifier for the
   conference ('conferenceid' attribute) is no longer valid on the MS
   and can be reused for another conference.

   For example, the following notification event would be sent from the
   MS when the conference with identifier "conference99" exits due to a
   successful <destroyconference/>:

   <mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
    <event>
     <conferenceexit conferenceid="conference99"
        status="0"/>
    </event>
   </mscmixer>

4.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
   enables discovery of package capabilities supported on an MS before
   an AS creates a conference mixer or joins connections and
   conferences.  The AS can then use this information 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

Top      Up      ToC       Page 43 
   currently managed by the package on the MS.  This could be used when
   one AS takes over management of mixers if the AS that created the
   mixers fails or is no longer available (see the security
   considerations in Section 7).

4.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 4.7.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 4.7.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 (406) 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 an <audit> request, it MUST reply with a
   <auditresponse> element (Section 4.3.2) that includes a mandatory
   attribute describing the status in terms of a numeric code.  Response
   status codes are defined in Section 4.6.  If the request is
   successful, the <auditresponse> contains (depending on attribute
   values) a <capabilities> element (Section 4.3.2.1) reporting package

Top      Up      ToC       Page 44 
   capabilities and a <mixers> element (Section 4.3.2.2) reporting
   managed mixer information.  If the MS is not able to process the
   request and carry out the audit operation, the audit request has
   failed and the MS MUST indicate the class of failure using an
   appropriate 4xx response code.  Unless an error response code is
   specified for a class of error within this section, implementations
   follow Section 4.6 in determining the appropriate status code for the
   response.

   For example, a request to audit capabilities and mixers managed by
   the package is as follows:

   <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>

4.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 4.6.

   reason:  string specifying a reason for the status.  The attribute is
      optional.

   desclang:  specifies the language used in the value of the 'reason'
      attribute.  A valid value is a language identifier
      (Section 4.7.7).  The attribute is optional.  If not specified,
      the value of the 'desclang' attribute on <mscmixer> (Section 4.1)
      applies.

Top      Up      ToC       Page 45 
   The <auditresponse> element has the following sequence of child
   elements:

   <capabilities>:  element describing capabilities of the package (see
      Section 4.3.2.1).  The element is optional.

   <mixers>:  element describing information about managed mixers (see
      Section 4.3.2.2).  The element is optional.

   For example, a successful response to an <audit> request for
   capabilities and mixer information is as follows:

   <mscmixer version="1.0" xmlns="urn:ietf:params:xml:ns:msc-mixer">
    <auditresponse status="200">
     <capabilities>
      <codecs>
       <codec name="video">
        <subtype>H263</subtype>
       </codec>
       <codec name="video">
        <subtype>H264</subtype>
       </codec>
       <codec name="audio">
        <subtype>PCMU</subtype>
       </codec>
       <codec name="audio">
        <subtype>PCMA</subtype>
       </codec>
      </codecs>
     </capabilities>
     <mixers>
      <conferenceaudit conferenceid="conf1">
       <codecs>
        <codec name="audio">
         <subtype>PCMA</subtype>
        </codec>
       </codecs>
       <participants>
        <participant id="1536067209:913cd14c"/>
       </participants>
      </conferenceaudit>
      <joinaudit id1="1536067209:913cd14c" id2="conf1"/>
      <joinaudit id1="1636067209:113cd14c" id2="1836067209:313cd14c"/>
      <joinaudit id1="1736067209:213cd14c" id2="1936067209:413cd14c"/>
     </mixers>
    </auditresponse>
   </mscmixer>

Top      Up      ToC       Page 46 
4.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:

   <codecs>:  element (Section 4.4) describing codecs available to the
      package.  The element is mandatory.

   For example, a fragment describing capabilities is as follows:

     <capabilities>
      <codecs>
       <codec name="video">
        <subtype>H263</subtype>
       </codec>
       <codec name="video">
        <subtype>H264</subtype>
       </codec>
       <codec name="audio">
        <subtype>PCMU</subtype>
       </codec>
       <codec name="audio">
        <subtype>PCMA</subtype>
       </codec>
      </codecs>
     </capabilities>

4.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
   (zero or more occurrences, any order):

   <conferenceaudit>:  audit information for a conference mixer
      (Section 4.3.2.2.1).  The element is optional.

   <joinaudit>:  audit information for a join mixer (Section 4.3.2.2.2).
      The element is optional.

Top      Up      ToC       Page 47 
4.3.2.2.1.  <conferenceaudit>

   The <conferenceaudit> element has the following attribute:

   conferenceid:  string identifying the conference (see Appendix A.1 of
      [RFC6230]).  The attribute is mandatory.

   The <conferenceaudit> element has the following sequence of child
   elements:

   <codecs>  element describing codecs used in the conference.  See
      Section 4.4.  The element is optional.

   <participants>  element listing connections or conferences joined to
      the conference.  See Section 4.3.2.2.1.1.  The element is
      optional.

   <video-layout>  element describing the active video layout for the
      conference.  See Section 4.2.1.4.2.1.  The element is optional.

   For example, a fragment describing a conference that has been created
   but has no participants is as follows:

   <conferenceaudit conferenceid="conference1"/>

   A fragment when the same conference has three participants (two
   connections and another conference) joined to it is as follows:

   <conferenceaudit conferenceid="conference1">
    <codecs>
     <codec name="audio">
      <subtype>PCMU</subtype>
     </codec>
    </codecs>
    <participants>
      <participant id="connection1"/>
      <participant id="connection2"/>
      <participant id="conference2"/>
    </participants>
   </conferenceaudit>

4.3.2.2.1.1.  <participants>

   The <participants> element is a container for <participant> elements
   (Section 4.3.2.2.1.1.1).

   The <participants> element has no attributes, but the following child
   elements are defined (zero or more):

Top      Up      ToC       Page 48 
   <participant>:  specifies a participant (Section 4.3.2.2.1.1.1).

4.3.2.2.1.1.1.  <participant>

   The <participant> element describes a participant.

   The <participant> element has the following attribute:

   id:  an identifier for either a connection or a conference.  The
      identifier MUST conform to the syntax defined in Appendix A.1 of
      [RFC6230].  The attribute is mandatory.

   The <participant> element has no children.

4.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 Appendix A.1 of
      [RFC6230].  The attribute is mandatory.

   id2:  an identifier for either a connection or a conference.  The
      identifier MUST conform to the syntax defined in Appendix A.1 of
      [RFC6230].  The attribute is mandatory.

   The <joinaudit> element has no children.

   For example, a fragment describing an audit of two join mixers, one
   between connections and the second between conferences, is as
   follows:

   <mixers>
    <joinaudit id1="1536067209:913cd14" id2="1636067209:413cd14"/>
    <joinaudit id1="conference1" id2="conference2"/>
   </mixers>

4.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.

Top      Up      ToC       Page 49 
   The <codecs> element has the following sequence of child elements
   (zero or more occurrences):

   <codec>:  defines a codec and optionally its policy (Section 4.4.1).
      The element is optional.

   For example, a fragment describing two codecs is as follows:

   <codecs>
     <codec name="audio">
      <subtype>PCMA</subtype>
     </codec>
     <codec name="video">
       <subtype>H263</subtype>
     </codec>
   </codecs>

4.4.1.  <codec>

   The <codec> element describes a codec.  The element is modeled on the
   <codec> element in the XCON conference information data model
   ([RFC6501]) and allows additional information (e.g., rate, speed,
   etc.) to be specified.

   The <codec> element has the following attribute:

   name:  indicates the type name of the codec's media format as defined
      in [IANA].  A valid value is a "type-name" as defined in Section
      4.2 of [RFC4288].  The attribute is mandatory.

   The <codec> element has the following sequence of child elements:

   <subtype>:  element whose content model describes the subtype of the
      codec's media format as defined in [IANA].  A valid value is a
      "subtype-name" as defined in Section 4.2 of [RFC4288].  The
      element is mandatory.

   <params>:  element (Section 4.5) describing additional information
      about the codec.  This package is agnostic to the names and values
      of the codec parameters supported by an implementation.  The
      element is optional.

   For example, a fragment with a <codec> element describing the H263
   codec is as follows:

   <codec name="video">
    <subtype>H263</subtype>
   </codec>

Top      Up      ToC       Page 50 
   A fragment where the <codec> element describes the H264 video codec
   with additional information about the profile level and packetization
   mode is as follows:

   <codec name="video">
    <subtype>H264</subtype>
    <params>
     <param name="profile-level-id">42A01E</param>
     <param name="packetization-mode">0</param>
    </params>
   </codec>

4.5.  <params>

   The <params> element is a container for <param> elements
   (Section 4.5.1).

   The <params> element has no attributes, but the following child
   elements are defined (zero or more):

   <param>:  specifies a parameter name and value (Section 4.5.1).

4.5.1.  <param>

   The <param> element describes a parameter name and value.

   The <param> element has the following attributes:

   name:  a string indicating the name of the parameter.  The attribute
      is mandatory.

   type:  specifies a type indicating how the in-line value of the
      parameter is to be interpreted.  A valid value is a MIME media
      type (see Section 4.7.6).  The attribute is optional.  The default
      value is "text/plain".

   encoding:  specifies a content-transfer-encoding schema applied to
      the in-line value of the parameter on top of the MIME media type
      specified with the 'type' attribute.  A valid value is a content-
      transfer-encoding schema as defined by the "mechanism" token in
      Section 6.1 of [RFC2045].  The attribute is optional.  There is no
      default value.

   The <param> element content model is the value of the parameter.
   Note that a value that contains XML characters (e.g., "<") needs to
   be escaped following standard XML conventions.

Top      Up      ToC       Page 51 
4.6.  Response Status Codes

   This section describes the response codes in Table 1 for the 'status'
   attribute of mixer management <response> (Section 4.2.3) and
   <auditresponse> (Section 4.3.2).  The MS MUST support the status
   response codes defined here.  All other valid but undefined values
   are reserved for future use, where new status codes are assigned
   using the Standards Action process defined in [RFC5226].  The AS MUST
   treat any responses it does not recognize as being equivalent to the
   x00 response code for all classes.  For example, if an AS receives an
   unrecognized response code of 499, it can safely assume that there
   was something wrong with its request and treat the response as if it
   had received a 400 (Syntax error) response code.

   4xx responses are definite failure responses from a particular MS.
   The 'reason' attribute in the response SHOULD identify the failure in
   more detail, for example, "Mandatory attribute missing: id2 join
   element" for a 400 (Syntax error) response code.

   The AS SHOULD NOT retry the same request without modification (for
   example, correcting a syntax error or changing the conferenceid to
   use one available on the MS).  However, the same request to a
   different MS might be successful, for example, if another MS supports
   a capability required in the request.

   4xx failure responses can be grouped into three classes: failure due
   to a syntax error in the request (400); failure due to an error
   executing the request on the MS (405-419); and failure due to the
   request requiring a capability not supported by the MS (420-435).

   In cases where more than one request code could be reported for a
   failure, the MS SHOULD use the most specific error code of the
   failure class for the detected error.  For example, if the MS detects
   that the conference identifier in the request is invalid, then it
   uses a 406 status code.  However, if the MS merely detects that an
   execution error occurred, then 419 is used.

Top      Up      ToC       Page 52 
   +-------+---------------+----------------------+--------------------+
   | Code  | Summary       | Description          | Informational: AS  |
   |       |               |                      | Possible Recovery  |
   |       |               |                      | Action             |
   +-------+---------------+----------------------+--------------------+
   | 200   | OK            | request has          |                    |
   |       |               | succeeded.           |                    |
   |       |               |                      |                    |
   | 400   | Syntax error  | request is           | Change the request |
   |       |               | syntactically        | so that it is      |
   |       |               | invalid: it is not   | syntactically      |
   |       |               | valid with respect   | valid.             |
   |       |               | to the XML schema    |                    |
   |       |               | specified in         |                    |
   |       |               | Section 5 or it      |                    |
   |       |               | violates a           |                    |
   |       |               | co-occurrence        |                    |
   |       |               | constraint for a     |                    |
   |       |               | request element      |                    |
   |       |               | defined in           |                    |
   |       |               | Section 4.           |                    |
   |       |               |                      |                    |
   | 405   | Conference    | request uses an      | Send an <audit>    |
   |       | already       | identifier to create | request            |
   |       | exists        | a new conference     | (Section 4.3.1)    |
   |       |               | (Section 4.2.1.1)    | requesting the     |
   |       |               | that is already used | list of conference |
   |       |               | by another           | mixer identifiers  |
   |       |               | conference on the    | already used by    |
   |       |               | MS.                  | the MS and then    |
   |       |               |                      | use a conference   |
   |       |               |                      | identifier that is |
   |       |               |                      | not listed.        |
   |       |               |                      |                    |
   | 406   | Conference    | request uses an      | Send an <audit>    |
   |       | does not      | identifier for a     | request            |
   |       | exist         | conference that does | (Section 4.3.1)    |
   |       |               | not exist on the MS. | requesting the     |
   |       |               |                      | list of conference |
   |       |               |                      | mixer identifiers  |
   |       |               |                      | used by the MS and |
   |       |               |                      | then use a         |
   |       |               |                      | conference         |
   |       |               |                      | identifier that is |
   |       |               |                      | listed.            |
   |       |               |                      |                    |

Top      Up      ToC       Page 53 
   | 407   | Incompatible  | request specifies a  | Change the media   |
   |       | stream        | media stream         | stream             |
   |       | configuration | configuration that   | configuration to   |
   |       |               | is in conflict with  | match the          |
   |       |               | itself, the          | capabilities of    |
   |       |               | connection, or       | the connection or  |
   |       |               | conference           | conference.        |
   |       |               | capabilities (see    |                    |
   |       |               | Section 4.2.2.2).    |                    |
   |       |               |                      |                    |
   | 408   | Joining       | request attempts to  | Send an <audit>    |
   |       | entities      | create a join mixer  | request            |
   |       | already       | (Section 4.2.2.2)    | (Section 4.3.1)    |
   |       | joined        | where the entities   | requesting the     |
   |       |               | are already joined.  | list of join       |
   |       |               |                      | mixers on the MS   |
   |       |               |                      | and then use       |
   |       |               |                      | entities that are  |
   |       |               |                      | not listed.        |
   |       |               |                      |                    |
   | 409   | Joining       | request attempts to  | Send an <audit>    |
   |       | entities not  | manipulate a join    | request            |
   |       | joined        | mixer where the      | (Section 4.3.1)    |
   |       |               | entities are not     | requesting the     |
   |       |               | joined.              | list of join       |
   |       |               |                      | mixers on the MS   |
   |       |               |                      | and then use       |
   |       |               |                      | entities that are  |
   |       |               |                      | listed.            |
   |       |               |                      |                    |
   | 410   | Unable to     | request attempts to  |                    |
   |       | join -        | join a participant   |                    |
   |       | conference    | to a conference      |                    |
   |       | full          | (Section 4.2.2.2)    |                    |
   |       |               | but the conference   |                    |
   |       |               | is already full.     |                    |
   |       |               |                      |                    |
   | 411   | Unable to     | request attempts to  |                    |
   |       | perform join  | create, modify, or   |                    |
   |       | mixer         | delete a join        |                    |
   |       | operation     | between entities but |                    |
   |       |               | fails.               |                    |
   |       |               |                      |                    |
   | 412   | Connection    | request uses an      |                    |
   |       | does not      | identifier for a     |                    |
   |       | exist         | connection that does |                    |
   |       |               | not exist on the MS. |                    |
   |       |               |                      |                    |

Top      Up      ToC       Page 54 
   | 419   | Other         | requested operation  |                    |
   |       | execution     | cannot be executed   |                    |
   |       | error         | by the MS.           |                    |
   |       |               |                      |                    |
   | 420   | Conference    | request to create a  |                    |
   |       | reservation   | new conference       |                    |
   |       | failed        | (Section 4.2.1.1)    |                    |
   |       |               | failed due to        |                    |
   |       |               | unsupported          |                    |
   |       |               | reservation of       |                    |
   |       |               | talkers or           |                    |
   |       |               | listeners.           |                    |
   |       |               |                      |                    |
   | 421   | Unable to     | request to create or |                    |
   |       | configure     | modify a conference  |                    |
   |       | audio mix     | failed due to        |                    |
   |       |               | unsupported audio    |                    |
   |       |               | mix.                 |                    |
   |       |               |                      |                    |
   | 422   | Unsupported   | request contains one |                    |
   |       | media stream  | or more <stream>     |                    |
   |       | configuration | elements             |                    |
   |       |               | (Section 4.2.2.5)    |                    |
   |       |               | whose configuration  |                    |
   |       |               | is not supported by  |                    |
   |       |               | the MS.              |                    |
   |       |               |                      |                    |
   | 423   | Unable to     | request to create or |                    |
   |       | configure     | modify a conference  |                    |
   |       | video layouts | failed due to        |                    |
   |       |               | unsupported video    |                    |
   |       |               | layout               |                    |
   |       |               | configuration.       |                    |
   |       |               |                      |                    |
   | 424   | Unable to     | request to create or |                    |
   |       | configure     | modify a conference  |                    |
   |       | video switch  | failed due to        |                    |
   |       |               | unsupported video    |                    |
   |       |               | switch               |                    |
   |       |               | configuration.       |                    |
   |       |               |                      |                    |
   | 425   | Unable to     | request to create or |                    |
   |       | configure     | modify a conference  |                    |
   |       | codecs        | failed due to        |                    |
   |       |               | unsupported codec.   |                    |
   |       |               |                      |                    |

Top      Up      ToC       Page 55 
   | 426   | Unable to     | request to join      |                    |
   |       | join - mixing | connection entities  |                    |
   |       | connections   | (Section 4.2.2.2)    |                    |
   |       | not supported | failed due to lack   |                    |
   |       |               | of support for       |                    |
   |       |               | mixing connections.  |                    |
   |       |               |                      |                    |
   | 427   | Unable to     | request to join      |                    |
   |       | join - mixing | conference entities  |                    |
   |       | conferences   | (Section 4.2.2.2)    |                    |
   |       | not supported | failed due to lack   |                    |
   |       |               | of support for       |                    |
   |       |               | mixing conferences.  |                    |
   |       |               |                      |                    |
   | 428   | Unsupported   | the request contains |                    |
   |       | foreign       | attributes or        |                    |
   |       | namespace     | elements from        |                    |
   |       | attribute or  | another namespace    |                    |
   |       | element       | that the MS does not |                    |
   |       |               | support.             |                    |
   |       |               |                      |                    |
   | 435   | Other         | request requires     |                    |
   |       | unsupported   | another capability   |                    |
   |       | capability    | not supported by the |                    |
   |       |               | MS.                  |                    |
   +-------+---------------+----------------------+--------------------+

                           Table 1: Status Codes

4.7.  Type Definitions

   This section defines types referenced in attribute definitions.

4.7.1.  Boolean

   The value space of boolean is the set {true, false, 1, 0} as defined
   in Section 3.2.2 of [XMLSchema:Part2].  In accordance with this
   definition, the concept of false can be lexically represented by the
   strings "0" and "false" and the concept of true by the strings "1"
   and "true"; implementations MUST support both styles of lexical
   representation.

4.7.2.  Non-Negative Integer

   The value space of non-negative integer is the infinite set
   {0,1,2,...} as defined in Section 3.3.20 of [XMLSchema:Part2].

Top      Up      ToC       Page 56 
4.7.3.  Positive Integer

   The value space of positive integer is the infinite set {1,2,...} as
   defined in Section 3.3.25 of [XMLSchema:Part2].

4.7.4.  String

   A string in the character encoding associated with the XML element as
   defined in Section 3.2.1 of [XMLSchema:Part2].

4.7.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".

4.7.6.  MIME Media Type

   A string formatted as an IANA MIME media type [MIME.mediatypes].  The
   ABNF ([RFC5234]) production for the string is:

   media-type = type-name "/" subtype-name *(";" parameter)

   parameter = parameter-name "=" value

   where "type-name" and "subtype-name" are defined in Section 4.2 of
   [RFC4288], "parameter-name" is defined in Section 4.3 of [RFC4288],
   and "value" is defined in Section 5.1 of [RFC2045].

4.7.7.  Language Identifier

   A language identifier labels information content as being of a
   particular human language variant.  Following the XML specification
   for language identification [XML], a legal language identifier is
   identified by a [RFC5646] code and matched according to [RFC4647].



(page 56 continued on part 4)

Next RFC Part