[Docs] [txt|pdf] [Tracker] [Email] [Nits] [IPR]

Versions: 00 01 02 03 04 05 06 07 08 09 RFC 4722

Network Work Group                                     E. Burger (ed.)
Internet Draft                                             J. Van Dyke
Document: draft-vandyke-mscml-00.txt                        A. Spitzer
Category: Informational                       SnowShore Networks, Inc.
Expires: April 28, 2002                               October 28, 2002


      SnowShore Media Server Control Markup Language and Protocol


Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026 [1].

   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 IETF has been notified of intellectual property rights claimed
   in regard to some or all of the specification contained in this
   document.  For more information consult the online list of claimed
   rights.

   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.



Abstract

   Media Server Control Markup Language (MSCML) is a markup language
   used in conjunction with SIP to provide advanced conferencing and
   IVR functions.













Burger, et. al.     Informational - Expires 4/2002                   1

                           SnowShore MSCML           October 28, 2002


Table of Contents

1. Conventions used in this document..................................2
2. Introduction.......................................................2
3. Use of SIP Request Methods.........................................3
4. MSCML Usage and Design.............................................4
5. Advanced Conferencing..............................................4
6. Interactive Voice Response (IVR)...................................9
6.1. Play Audio <play>...............................................10
6.2. Collect Digits <playcollect>....................................10
6.3. Recording Audio <playrecord>....................................12
6.4. Stop Request <stop>.............................................14
6.5. Prompt Block <prompt>...........................................14
7. Response Attributes and Return Codes..............................15
7.1. SIP.............................................................15
7.2. HTTP............................................................15
7.3. <response> Attributes...........................................15
8. Formal Syntax.....................................................16
9. Security Considerations...........................................19
10. IANA Considerations..............................................20
11. References.......................................................20
12. Contributors.....................................................21
13. Acknowledgments..................................................21
14. Author's Addresses...............................................21


1. Conventions used in this document

   In examples, "C:" and "S:" indicate lines sent by the client and
   server respectively.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in
   this document are to be interpreted as described in RFC-2119 [2].


2. Introduction

   This document describes the SnowShore Media Server Control Markup
   Language (MSCML).  This document describes payloads that one can
   send with a standard SIP INVITE to a media server.  The document [3]
   describes media server SIP URI formats.

   Prior to MSCML, there was not a standard way for the delivery of
   SIP-based enhanced conferencing.  Basic SIP constructs, such as
   described in [3], serves simple n-way conferencing well.  The SIP
   URI provides a natural mechanism for identifying a specific SIP
   conference, while INVITE and BYE methods elegantly implement
   conference join and leave semantics.  However, enhanced conferencing
   applications also require features such as sizing and resizing, in-

Burger, et. al.     Informational - Expires 4/2003                   2

                           SnowShore MSCML           October 28, 2002


   conference IVR operations (e.g. recording/playing participant names
   to the full conference) and conference event reporting.  MSCML
   payloads within standard SIP INVITE and INFO requests realize these
   features.

   There are two broad classes of MSCML functionality.  The first class
   includes primitives for advanced conferencing such as conference
   configuration, participant leg manipulation and conference event
   reporting.  The second class comprises primitives for interactive
   voice response (IVR).  These include playing audio, collecting
   digits, and recording audio.

   The IVR features of MSCML originally evolved simply as an adjunct
   for conferencing.  In many scenarios it was impractical or
   inconvenient to establish a dialog with a distinct IVR resource and
   then re-join the conference.  However, MSCML works well for simple
   IVR such as prompt-and-collect for SIP Proxy Servers or Media
   Gateway Controllers.  On the other hand, for complex IVR it may be
   more appropriate to employ a full IVR markup language such as
   VoiceXML [4].

   In general, a media server offers services to SIP UAC's on
   application servers, feature servers, and media gateway controllers.
   See [5] for definitions of these terms.  It is unlikely, but not
   prohibited, for end user SIP UAC's to have a direct signaling
   relationship with a media server.

   This document describes a working framework and protocol with which
   there is considerable implementation experience.  Application
   developers and service providers have created several MSCML-based
   services since the initial version was made available more than a
   year ago.  This experience is highly relevant to the ongoing work of
   the IETF, particularly the SIP, SIPPING, and MMUSIC work groups.


3. Use of SIP Request Methods

   As mentioned above, MSCML payloads may be carried in either SIP
   INVITE or INFO requests.  The initial INVITE, which creates an
   enhanced conference, MUST include an MSCML payload.  The initial
   INVITE, which joins a participant leg to an enhanced conference, MAY
   include an MSCML payload.  All mid-call MSCML payloads are sent via
   SIP INFO requests.

   MSCML responses are transported in the final response to the SIP
   INVITE containing the matching MSCML request or in a SIP INFO
   message.  The only allowable final response to a SIP INFO containing
   a message body is a 200 OK (Per RFC 2976 [6]).  Therefore, when the
   MSCML request is sent via SIP INFO the MSCML response is carried in
   a separate INFO request.  In general, these responses are
   asynchronous in nature and require a separate transaction due to
   timing considerations.


Burger, et. al.     Informational - Expires 4/2003                   3

                           SnowShore MSCML           October 28, 2002


   There has been considerable debate on the use of the SIP INFO method
   for any purpose.  Our experience is that MSCML would not have been
   possible without it.  When MSCML was implemented the first SIP Event
   Notification draft had just been published.  At that time, use of
   SUBSCRIBE/NOTIFY within an existing dialog was undefined.  This
   prevented its use in MSCML since all events occurred in an INVITE
   established dialog.  And while SUBSCRIBE/NOTIFY was well suited for
   reporting conference events its semantics seemed inappropriate for
   modifying a participant leg or conference setting where the only
   "event" was the success or failure of the request.  Lastly, since
   SIP INFO was an established RFC it was well supported in all the SIP
   stack implementations available at that time.  We had few if any
   interoperability issues as a result.

   SIP has progressed incredibly quickly and we will need to reevaluate
   some of the decisions that resulted in the original design of MSCML.
   However, we can confidently say that the availability of a widely
   supported, flexible request method was very important to the
   development and adoption MSCML.


4. MSCML Usage and Design

   To avoid undue complexity two rules were established regarding MSCML
   usage.  The first is that only one MSCML body may be present in a
   SIP request.  The second is that each MSCML body may contain only
   one request or response.  This greatly simplified transaction
   management.  MSCML syntax does provide for the unique identification
   of multiple requests in a single body part but this is not currently
   allowed.


5. Advanced Conferencing

   The advanced conferencing model is a star controller model, with
   both signaling and media directed to a central location.  Figure 1
   depicts a typical signaling relationship between end users' UAC's, a
   conference application server, and a media server.
















Burger, et. al.     Informational - Expires 4/2003                   4

                           SnowShore MSCML           October 28, 2002


     +-------+
     | UAC 1 |---\   Public URI  +-------------+
     +-------+    \ _____________| Application |
                   /    /        |   Server    |     Not shown:
     +-------+    /    /         +-------------+     RTP flows directly
     | UAC 2 |---/    /                 | Private    between UAC's and
     +-------+       /                  |   URI      Media Server
         .          /            +--------------+
         :         /             |              |
     +-------+    /              | Media Server |
     | UAC n |---/               |              |
     +-------+                   +--------------+

                        Figure 1 - Conference Model

   Each UAC sends an INVITE to a Public Conference URI.  Presumably the
   Application Server publishes this URI, or it is an ad hoc URI.  In
   any event, the Application Server generates a Private URI, following
   the rules specified by [3].  That is, the URI is of the form:

        sip:conf=UniqueID@ms.carrier.net

   Where UniqueID is a unique conference identifier, and ms.carrier.net
   is the host name or IP address of the media server.  There is
   nothing to prevent the UAC's from contacting the media server
   directly.  However, one would expect the owner of the media server
   to restrict who can use media server resources.

   As for basic conferencing, described by [3], the first INVITE to the
   media server with a UniqueID creates a conference.  However, in
   advanced conferencing, the first INVITE includes a MSCML
   configure_conference payload.  The MSCML payload conveys extended
   session parameters (e.g. number of participants) that are not
   readily expressed in SDP but must be known to allocate the
   appropriate resources.

   The first dialog established for an enhanced conference has several
   useful properties and is referred to as the "conference control
   leg."  The control leg is used for play or record audio operations
   to/from the entire conference and no RTP is expected on the
   conference control leg.  Therefore, the application must send either
   no SDP or hold SDP (c=0.0.0.0) in the initial INVITE request.  In
   addition, the lifetime of the conference is the same as that of its
   control leg.  This ensures that the conference remains in existence
   even if one or more participant legs unintentionally leaves the
   conference.

   The <configure_conference> tag has two attributes that control the
   resources the media server sets aside for the conference.  The
   attributes are reservedtalkers and reserveconfmedia.
   Reservedtalkers sets the maximum number of talker legs.
   Reserveconfmedia, if set to "Yes", allocates resources for playing

Burger, et. al.     Informational - Expires 4/2003                   5

                           SnowShore MSCML           October 28, 2002


   or recording audio to or from the entire conference.  The default
   for reserveconfmedia is "Yes".

   The application server can include any MSCML command in the initial
   INVITE, with the exception of asynchronous commands, such as <play>
   or <record>.  The application server must issue asynchronous
   commands separately (e.g., in INFO messages) to avoid ambiguous
   responses.

   For example, to create a conference with up to 120 active talkers
   and the ability to play audio into the conference or record parts or
   all of the conference, the application server specifies both
   attributes, as shown in Figure 2.

        <?xml version="1.0">
          <MediaServerControl version="1.0">
            <request>
              <configure_conference reservedtalkers="120"/>
            </request>
          </MediaServerControl>
                   Figure 2 - 120 Speaker MSCML Example

   Figure 3 shows a conference with up to five active speakers without
   the capability to play or record audio into the conference.

        <?xml version="1.0">
          <MediaServerControl version="1.0">
            <request>
              <configure_conference reservedtalkers="5"
                                    reserveconfmedia="no"/>
            </request>
          </MediaServerControl>

                    Figure 3 - 5 Speaker MSCML Example

   Once the application server has created the conference Control Leg,
   the server can join participants to the conference.  Per [3], the
   application server directs the INVITE to the Private Conference URI
   described above.  In the example given, this would be
   sip:UniqueID@ms.carrier.net .

   Conference legs have a number of parameters the application server
   can modify.  The defaults are as follows in Table 1.  Following
   sections will discuss the meaning of the parameters in detail.








Burger, et. al.     Informational - Expires 4/2003                   6

                           SnowShore MSCML           October 28, 2002


                    Table 1 - Conference Leg Parameters

        Parameter   Default  Description
        inputgain    auto    Use AGC to determine input gain for leg
        outputgain   auto    Use AGC to determine output gain for leg
        type         talker  Consider this leg's audio for mixing
                             in the output mix
        dtmfclamp    yes     Remove detected DTMF digit from audio
        toneclamp    yes     Remove loud single-frequency tone
                             from audio

   If the default parameters are acceptable for the leg the application
   server wishes to enter into the conference, then a normal SIP INVITE
   is sufficient.  However, if the application server wishes to modify
   one or more of the parameters, the application server can include a
   MSCML body in addition to the SDP body.

   The application server can modify the conference leg parameters by
   issuing a SIP INFO on the selected dialog representing the
   conference leg.  Of course, the application server cannot modify SDP
   in an INFO message.

   To remove a leg from the conference, the application server issues a
   SIP BYE request on the selected dialog representing the conference
   leg.

   The application server can terminate all legs in a conference by
   issuing a SIP BYE request on the Conference Control Leg.  If one or
   more participants are still in the conference when the media server
   receives a SIP BYE request on the Conference Control Leg, the media
   server issues SIP BYE requests on all of the remaining conference
   legs to ensure clean up of the legs.

   The media server returns a 200 OK to the SIP BYE request as it sends
   BYE requests to the other legs.  This is because we cannot issue a
   provisional response to a non-INVITE request, yet the teardown of
   the other legs may "take a while".

   Once the conference has begun, the application server can manipulate
   the conference as a whole by issuing commands on the Conference Leg.
   For example, the application server can request the media server to
   record the conference, play a prompt to the conference, change the
   input or output gain for the conference as a whole, and report on
   events.  The elements for these commands are <playrecord>, <play>,
   <inputgain>, <outputgain>, and <subscribe>, respectively.

   Figure 4 shows two sample commands.  The first plays a prompt into
   the conference.  The second records the entire conference to the URI
   specified by recurl over NFS.




Burger, et. al.     Informational - Expires 4/2003                   7

                           SnowShore MSCML           October 28, 2002


        <?xml version="1.0">
          <MediaServerControl version="1.0">
            <request>
              <play
    prompturl="http://prompts.carrier.net/us_EN/welcome.au"/>
            </request>
          </MediaServerControl>


        <?xml version="1.0">
          <MediaServerControl version="1.0">
            <request>
              <playrecord
    recurl="file://archive.carrier.net/conferences/archives/011208.au"
                            beep="no"
                            initsilence="-1" endsilence="-1" />
            </request>
          </MediaServerControl>

             Figure 4 - Sample Full Conference Audio Commands

   The response to this last request will be similar to Figure 5.

     <?xml version="1.0">
       <MediaServerControl version="1.0">
        <response request="playrecord" code="200" text="OK"/>
     </MediaServerControl>

                 Figure 5 - Sample Change Command Response

   Later event reporting comes through SIP INFO messages.  Figure 6
   shows an example report.

        <?xml version="1.0">
          <MediaServerControl version="1.0">
            <notification>
              <conference uniqueID="ab34h76z" numtalkers="16"
                          numlisteners="1382">
                <activetalkers>
                  <talker callID="myhost4sn123"/>
                  <talker callID="myhost2sn456"/>
                  <talker callID="myhost12sn78”/>
                </activetalkers>
              </conference>
            </notification>
          </MediaServerControl>

                  Figure 6 - Active Talker Event Example



Burger, et. al.     Informational - Expires 4/2003                   8

                           SnowShore MSCML           October 28, 2002


   An application server can modify a leg by issuing an INFO on the
   dialog associated with the participant leg.  For example, Figure 7
   mutes a conference leg.

        <?xml version="1.0">
          <MediaServerControl version="1.0">
            <request>
              <configure_leg mixmode="mute"/>
            <request>
          </MediaServerControl>

                   Figure 7 - Sample Change Leg Command

   In Figure 4 we saw a request to play a prompt to the entire
   conference.  We can also request to play a prompt to an individual
   call leg.  If we want to play a prompt or collect digits only on a
   single leg, we issue the commands within the dialog for the of the
   desired conference participant.


6. Interactive Voice Response (IVR)

   In the IVR model, the Media Server acts as a media processing proxy
   for the UAC.  This is particularly useful when the UAC is a media
   gateway or other device with limited media processing capability.


                                 +--------------+
                    Service URI  | Application  |
                 /---------------|    Server    |
                /(e.g., RFC3087) +--------------+
               /                        |  MSCML
              /                         | Session
             /                   +--------------+
     +-----+/       RTP          |              |
     | UAC |=====================| Media Server |
     +-----+                     |              |
                                 +--------------+

                           Figure 8 - IVR Model

   The IVR service supports basic Interactive Voice Response functions,
   playing announcements, collecting DTMF digits, and recording audio,
   based on Media Server Control Markup Language (MSCML) directives
   added to the message body of a SIP request.

   Multifunction media servers SHOULD use the URI conventions described
   in [3].  For review, the IVR service indicator is "ivr":

        sip:ivr@ms.carrier.net


Burger, et. al.     Informational - Expires 4/2003                   9

                           SnowShore MSCML           October 28, 2002


   One may carry the request payload for IVR in either the initial SIP
   INVITE or INFO requests.

   Mid-call requests must use the INFO method.  The INFO method reduces
   certain timing issues that occur with re-INVITES and also uses less
   processing on both the application server and Media Server.

   The Media Server notifies the application that the command has
   completed through a <response> message containing final status
   information and data such as collected DTMF digits.

   The media server does not queue IVR requests.  If the media server
   receives a request while another is in progress, the media server
   stops the first operation and it carries out the new request.  The
   Media Server generates a <response> message for the first request
   and returns any data collected up to that point. If an application
   wishes to stop a request in progress but does not wish to initiate
   another operation, it issues a <stop> request.  This also causes the
   Media Server to generate a <response> message.

   The Media Server treats a SIP re-INVITE with hold media (c=0.0.0.0)
   as an implicit <stop> request.  The media server immediately
   terminates the running <play>, <playcollect> or <playrecord>
   request, and sends a <response>, indicating "reason=stopped".


6.1. Play Audio <play>

   The application issues a <play> request to play an announcement
   without interruption and with no digit collection.  One use, for
   example, is to announce the name of a new participant to the entire
   conference.

   The application specifies the announcement to play by the prompt
   block in the body of the request.

   Attributes include promptencoding (optional), which explicitly
   specifies the encoding (µ-law or a-law), and id (also optional).  ID
   is an application-defined request identifier that correlates the
   asynchronous response with its original request and echoes back to
   the application in the Media Server's response.

   When the announcement has finished playing, the Media Server sends a
   <response> payload to the application in a SIP INFO message.

   The response may carry the id, the status code (e.g., 200), the
   status text (e.g., OK), and the reason (EOF or stopped).


6.2. Collect Digits <playcollect>

   The application issues a <playcollect> request to optionally play an
   announcement and the collect digits.

Burger, et. al.     Informational - Expires 4/2003                  10

                           SnowShore MSCML           October 28, 2002



   This request has multiple attributes, all of which are optional.

   The presence or absence of the prompt block controls whether there
   will be an announcement or the result of the request is to be digit
   collection only.

   Whenever the media server receives a <playcollect> request, it will
   continuously buffer and examine collected digits.  The media server
   compares previously buffered digits to the returnkey, escapekey, and
   maxdigits attributes to determine if any immediate action is
   required.  This provides the type-ahead behavior for menu traversal
   and other types of IVR interactions.

   The application may override type-ahead behavior by setting the
   cleardigits parameter to "yes", which removes all previously-
   buffered digits such that the only user input considered is what
   occurs after the request.

   If cleardigits is set to "no", digits previously buffered will
   result in the prompt being barged immediately.  Prompt play would
   never begin, and digit collection would start immediately.

   The default for barge is "yes".  If the barge attribute is set to
   "no", the cleardigits attribute implicitly has a value of "yes".
   This ensures that DTMF input occurring before the current collection
   is not left in the buffer after the request completes.

   The application can set two special digits to invoke special
   processing when detected:

   The escapekey, which defaults to *, indicates that the user intends
   to terminate the current operation without saving any input
   collected to that point.  Detection terminates the request
   immediately and generates a response.

   The returnkey, which defaults to #, indicates the user has completed
   input and wants to return all collected digits to the application.
   When the media server detects the returnkey, it immediately
   terminates collection and returns the collected digits to the
   application in the <response> message.

   Several timer attributes control how long the Media Server waits for
   digits in the input sequence.  All timer settings are in
   milliseconds.

      o firstdigittimer controls how long the Media Server waits for
        the initial DTMF input before terminating collection.

      o interdigittimer controls how long the Media Server waits
        between DTMF inputs.



Burger, et. al.     Informational - Expires 4/2003                  11

                           SnowShore MSCML           October 28, 2002


      o extradigittimer controls how long the Media Server waits for
        additional user input after the specified number of digits
        (linkblueparatextinkblue) have been collected.

   The extradigittimer setting enables the "returnkey" input to be
   associated with the current collection.  For example, if maxdigits
   is set to 3 and returnkey is set to #, the user may enter either
   "x#", "xx#" or "xxx#", where x represents a DTMF digit.

   If the "returnkey" pattern is detected during the "extradigit"
   interval, the collected digits are returned to the application and
   the "returnkey" is removed from the digit buffer.

   If this were not the case, the example would return "xxx" to the
   application and leave the terminating "#" in the digit buffer to be
   processed by the next <playcollect> request.  This might result in
   the termination of the following prompt; clearly not what the user
   intended.

   The extradigittimer has no effect unless returnkey has been set.

   When the <playcollect> has finished playing, the Media Server sends
   a <response> payload to the application in a SIP INFO message.

   The response may carry the id, the code (e.g., 200), the text(e.g.,
   OK), the reason (match, timeout, returnkey, escapekey, or stopped),
   and the collected digits.


6.3. Recording Audio <playrecord>

   The <playrecord> request directs the Media Server to capture the RTP
   it receives and deliver it to a URL specified by the controlling
   application.

   This tag has multiple attributes. The required recurl attribute
   identifies the URL target for the recorded audio.  All other
   attributes are optional.

   The presence or absence of the prompt block controls whether or not
   a prompt plays before recording begins.

   When the application requests the media server to prompt the caller
   before recording audio, <playrecord> has two stages.  The first is
   equivalent to a <playcollect> operation.  The application may set
   the prompt phase to be interruptible by DTMF input (barge) and may
   also specify an escape key that will terminate the <playrecord>
   request before the recording phase begins.

   Detection of the escape key generates a response message, and the
   operation returns immediately.  If any other keys are pressed and if
   the prompt has been set as interruptible (barge="yes"), then the
   play stops immediately and the recording phase begins.

Burger, et. al.     Informational - Expires 4/2003                  12

                           SnowShore MSCML           October 28, 2002



   Any digits collected in the prompt phase, with the exception of the
   recstopmask, are buffered and returned in the response.

   If the request proceeds to the recording phase, any digits from the
   collect phase are discarded from the buffer to eliminate unintended
   termination of the recording.

   The media server compares digits detected during the recording phase
   to the digits specified in the recstopmask to determine if they
   indicate a recording termination request.

   The media server ignores digits not present in the recstopmask and
   passes them into the recording.  If the recording is terminated
   because of a DTMF input, the collected digits are returned to the
   application in the <response>.

   Once recording has begun, the media server writes the audio to the
   specified recurl URL no matter what DTMF events are detected.  It is
   the responsibility of the application to examine the DTMF input
   returned in the <response> message to determine whether the audio
   file should be saved or if it should be deleted and potentially re-
   recorded.

   Two attributes control how long the Media Server waits for the start
   of speech to begin the recording and the absence of speech to end
   the recording:

      o initsilence determines how long to wait for initial speech
        input before terminating (cancelling) the recording.  This
        parameter may take an integer value in milliseconds, or may be
        set to -1, which directs the Media Server to wait indefinitely.
        The default is 3000 ms (3 seconds).

      o endsilence determines how long the Media Server waits after
        speech has ended to stop the recording.  This parameter may
        take an integer value in milliseconds, or may be set to -1.
        With a value of -1, the recording will continue indefinitely
        after speech has ended and may terminate due to a DTMF keypress
        or because the maximum desired duration has been reached. The
        default value is 4000 ms (4 seconds).

   If the endsilence timer expires, the Media Server trims the end of
   the recorded audio by an amount equal to the endsilence parameter.

   Additional attributes are:
      o mode (whether the recording will overwrite or append).

      o reencoding (whether encoding is mu-law or a-law).

      o duration (time in ms for the entire recording.



Burger, et. al.     Informational - Expires 4/2003                  13

                           SnowShore MSCML           October 28, 2002


      o beep (whether a beep will signify the start of recording).

   When the recording is finished, the media server generates a
   <response> message and sends it to the application in a SIP INFO
   message.  The response contains the id, the code (e.g., 200, 400,
   501), the reason (e.g., digit, end_silence, init_silence,
   max_duration, escapekey, error, or stopped), collected digits, and
   the reclength (size of the recorded file in bytes).


6.4. Stop Request <stop>


   The application issues a <stop> request when the objective is to
   stop a request in progress and not initiate another operation. This
   request generates a <response> message from the Media Server.

   The only attribute is id, which is optional.

   The application-defined request id correlates the asynchronous
   response with its original request and echoes back to the
   application in the Media Server's response.

   The response may carry the id, the code (e.g., 200), and the text
   (e.g., OK).

   Note that the Media Server treats a SIP re-INVITE with hold media
   (c=0.0.0.0) as an implicit <stop> request.  The media server
   immediately terminates the running <play>, <playcollect> or
   <playrecord> request, and sends a <response>, indicating
   "reason=stopped".


6.5. Prompt Block <prompt>

   This block in the body of the <play>, <playcollect>, or <playrecord>
   request contains one or more references to physical audio files,
   provisioned sequences, or variables that are played in the order in
   which they appear.

   The following is a sample prompt block.

        <prompt baseurl="file:////opt/snowshore/prompts/conf/">
                <audio url="please_enter.wav"/>
                <variable type="silence" value="1"/>
                <audio url="your.raw" encoding="a-law"/>
                <variable type="silence" value="1"/>
                <audio
                   url="http://prompts.carrier.net/pin_number.wav"/>
        </prompt>

   The baseurl attribute is the base URL prepended to the URL
   attributes within the <prompt> block.

Burger, et. al.     Informational - Expires 4/2003                  14

                           SnowShore MSCML           October 28, 2002



   Each audio element in a <prompt> block refers to an audio file or
   provisioned sequence for the media server to play.  The media server
   plays audio files in the order in which they are listed in the
   block.


7. Response Attributes and Return Codes

7.1. SIP

   The Media Server acknowledges receipt of an application request by
   sending a response of either 200 OK or 415 BAD MEDIA TYPE.  (The
   latter is sent when the SIP request contains a content type other
   than "application/sdp" or "application/mediaservercontrol+xml").

   The <response> message is transported in a SIP INFO request.

   If there is an error in the request or the request cannot be
   completed, the <response> message is sent very shortly after
   receiving the request. If the request is able to proceed, the
   <response> contains final status information as listed below.


7.2. HTTP

   The Media Server processes the request and returns a <response>
   message in the body of the http POST.


7.3. <response> Attributes

   If an ID was specified in the request, that id will be echoed back
   to the application in the response.

   The "code" is the result code for the request.  It can take the
   following values.

      o 200 indicates command completed.
      o 400 for <playrecord> indicates command not accepted due to an
        error. The text attribute describes the cause of the error.
      o 501 for <playrecord> indicates an error because the media
        server does not support the URL type specified.

   The "digits" are the returned digits for <playcollect> and
   <playrecord>.  Its value is the collected digits, if any.

   The "reason" is why the command terminated.  For all requests, the
   reason "stopped" indicates that a <stop> request, another command,
   or a re-INVITE with hold media stopped the request.

   For the <play> request, the "EOF" reason means the media server
   played out to the end of the file.

Burger, et. al.     Informational - Expires 4/2003                  15

                           SnowShore MSCML           October 28, 2002



   For the <playcollect> request, "match" means a match was found;
   "timeout" means no digit was received before the time-out timer
   expired; "returnkey" and "escapekey" means the return key or escape
   key terminated the operation, respsectively; and "interrupted" means
   another request interrupted the <playcollect> request.

   For the <playrecord> request, "digit" means a digit was detected;
   "end_silence" means the recording terminated because the trailing
   silence timer expired; "init_silence" means that no voice was
   detected; "max_duration" means the recording terminated because the
   maximum time for recording completed; "escapekey" means the user
   entered the escape key in either play or record mode, thus
   terminating the recording; or "error", for a general operation
   failure.

   The "reclength" is the length of the recording in bytes for a
   <playrecord>.

   The "text" is the descriptive text associated with the response
   code.


8. Formal Syntax

   The following syntax specification uses the augmented Data Type
   Definition (DTD) as described in XML [7].

   <?xml version="1.0"?>
   <!-- =========================================================== -->
   <!-- MediaServerControl Document Type Description                -->
   <!-- Copyright (c) 2001-2002 SnowShore Networks, Inc.            -->
   <!-- All Rights Reserved                                         -->
   <!-- SnowShore Networks Confidential and Proprietary Information -->
   <!-- =========================================================== -->

   <!ELEMENT MediaServerControl (request | response | notification)>
   <!ATTLIST MediaServerControl version (1.0) #REQUIRED>

   <!ELEMENT request (configure_conference | configure_leg | play |
                      playcollect | playrecord | stop)>

   <!ELEMENT configure_conference (inputgain?, outputgain?,
                                   subscribe?)>
   <!ATTLIST configure_conference
        id CDATA #IMPLIED
        reservedtalkers CDATA #IMPLIED
        reserveconfmedia (yes | no) #IMPLIED>

   <!-- Tags for gain control                                       -->
   <!ELEMENT outputgain (auto | fixed)>
   <!ELEMENT inputgain (auto | fixed)>


Burger, et. al.     Informational - Expires 4/2003                  16

                           SnowShore MSCML           October 28, 2002


   <!ELEMENT auto EMPTY>
   <!ATTLIST auto
        startlevel CDATA #IMPLIED
        targetlevel CDATA #IMPLIED
        silencethreshold CDATA #IMPLIED>

   <!ELEMENT fixed EMPTY>
   <!ATTLIST fixed
        level CDATA #IMPLIED>

   <!ELEMENT subscribe (events)>

   <!ELEMENT events (activetalkers)>

   <!ELEMENT activetalkers (talker+)?>
   <!ATTLIST activetalkers
        report (yes | no) "no"
        interval CDATA #IMPLIED>
   <!-- Acceptable values for interval range from 1-60 seconds      -->

   <!ELEMENT talker EMPTY>
   <!ATTLIST talker
        callid CDATA #REQUIRED>
   <!-- The list of current talkers is used only when sending       -->
   <!-- notifications to the calling application.  It should never  -->
   <!-- be set when subscribing.                                    -->

   <!ELEMENT configure_leg (inputgain?, outputgain?)>
   <!ATTLIST configure_leg
        id CDATA #IMPLIED
        type (talker | listener) #IMPLIED
        mixmode (full | mute | preferred | parked) #IMPLIED
        dtmfclamp (yes | no) #IMPLIED>

   <!-- Stops a play or record operation in progress                -->
   <!ELEMENT stop EMPTY>

   <!-- Plays an audio prompt, no barge-in or digit collection.     -->
   <!-- <play/> generates a <response/> message when the specified  -->
   <!-- prompt has finished playing or if an error occurs.          -->
   <!ELEMENT play (prompt)?>
   <!ATTLIST play
        id CDATA #IMPLIED
        prompturl CDATA #IMPLIED
        promptencoding (ulaw | alaw) #IMPLIED>









Burger, et. al.     Informational - Expires 4/2003                  17

                           SnowShore MSCML           October 28, 2002


   <!-- Plays an audio prompt, collects DTMF digits and returns the -->
   <!-- digits to the application.  May also be used simply to      -->
   <!-- collect digits if no sequence is specified.  <playcollect/> -->
   <!-- sends an asynchronous <response/> message which is normally -->
   <!-- generated when the desired digits have been collected or a  -->
   <!-- timeout has expired.                                        -->
   <!ELEMENT playcollect (prompt?, pattern?)>
   <!ATTLIST playcollect
        id CDATA #IMPLIED
        prompturl CDATA #IMPLIED
        barge (yes | no) "yes"
        promptencoding (ulaw | alaw) #IMPLIED
        cleardigits CDATA "yes"
        maxdigits CDATA #IMPLIED
        firstdigittimer CDATA #IMPLIED
        interdigittimer CDATA #IMPLIED
        intdigcrittimer CDATA #IMPLIED
        extradigittimer CDATA #IMPLIED
        returnkey CDATA "#"
        escapekey CDATA "*">

   <!-- <playrecord/> takes the audio from the associated session   -->
   <!-- and records it to the location and format specified.  It    -->
   <!-- generates a <response/> message if the request is in error, -->
   <!-- when the recording session has been interrupted by DTMF,    -->
   <!-- the specified duration has been exceeded or a timeout has   -->
   <!-- expired.  The request has an optional prompt to be played   -->
   <!-- prior to the start of recording.                            -->
   <!ELEMENT playrecord (prompt)?>
   <!ATTLIST playrecord
        id CDATA #IMPLIED
        prompturl CDATA #IMPLIED
        barge (yes | no) #IMPLIED
        cleardigits (yes | no) #IMPLIED
        escapekey CDATA "*"
        recurl CDATA #REQUIRED
        mode (append | overwrite) "overwrite"
        recencoding (ulaw | alaw) #IMPLIED
        initsilence CDATA #IMPLIED
        endsilence CDATA #IMPLIED
        duration CDATA #IMPLIED
        beep (yes | no) "yes"
        recstopmask CDATA "01234567890*#">

   <!ELEMENT prompt (audio | variable)+>
   <!ATTLIST prompt
        locale CDATA #IMPLIED
        baseurl CDATA #IMPLIED>






Burger, et. al.     Informational - Expires 4/2003                  18

                           SnowShore MSCML           October 28, 2002


   <!ELEMENT audio EMPTY>
   <!ATTLIST audio
        url CDATA #REQUIRED
        encoding (ulaw | alaw) #IMPLIED>
   <!-- The encoding attribute is required for files that are not in-->
   <!-- self-describing .au or .wav format and do not have a well   -->
   <!-- known extension (.ulaw).                                    -->

   <!ELEMENT pattern (regex | digitmap)+>

   <!ELEMENT regex EMPTY>
   <!ATTLIST regex
       value CDATA #REQUIRED
       name CDATA #IMPLIED>

   <!ELEMENT digitmap EMPTY>
   <!ATTLIST digitmap
       value CDATA #REQUIRED
       name CDATA #IMPLIED>

   <!ELEMENT variable EMPTY>
   <!ATTLIST variable
       type (date | digit | duration | month | money | number |
             silence | string | time | weekday) #REQUIRED
       subtype (mdy | dmy | ymd | ndn | t12 | t24 | USD | gen | ndn |
                crd | ord) #IMPLIED
       value CDATA #REQUIRED>

   <!ELEMENT response EMPTY>
   <!ATTLIST response
        request (configure_conference | configure_leg | play |
                 playcollect |playrecord | stop) #REQUIRED
        id CDATA #IMPLIED
        code CDATA #REQUIRED
        text CDATA #REQUIRED
        patternname CDATA #IMPLIED>

   <!ELEMENT notification (conference)>

   <!ELEMENT conference (activetalkers)>
   <!ATTLIST conference
        uniqueid CDATA #REQUIRED
        numtalkers CDATA #REQUIRED>


9. Security Considerations

   Because media flows through a media server in a conference, the
   media server itself MUST protect the integrity, confidentiality, and
   security of the sessions.  It should not be possible for a
   conference participant, on her own behalf, to be able to "tap in" to
   another conference without proper authorization.


Burger, et. al.     Informational - Expires 4/2003                  19

                           SnowShore MSCML           October 28, 2002


   Because conferencing is a high value application, the media server
   SHOULD implement appropriate security measures.  This includes, but
   not limited to, access lists for application servers.  That is, only
   a select list of application or proxy servers is allowed to create
   conferences, invite participants to sessions, etc.  Note that the
   mechanisms for such security, like private networks, shared
   certificates, MAC white/black lists, are beyond the scope of this
   draft.


10. IANA Considerations

   MSCML payloads are identified by the MIME type
   "application/mediaservercontrol+xml".


11. References


   1  Bradner, S., "The Internet Standards Process -- Revision 3", BCP
      9, RFC 2026, October 1996.
      INFORMATIVE

   2  Bradner, S., "Key words for use in RFCs to Indicate Requirement
      Levels", BCP 14, RFC 2119, March 1997.
      NORMATIVE

   3  Van Dyke, J., et. al., "Basic Network Media Services with SIP",
      draft-burger-sipping-netann-02.txt, June 2002, work in progress.
      INFORMATIVE

   4  McGlashan, S. (ed.), "Voice Extensible Markup Language (VoiceXML)
      Version 2.0", W3C Working Draft,
      <http://www.w3.org/TR/voicexml20/>, 24 April 2002, work in
      progress.
      INFORMATIVE

   5  International Softswitch Consortium Reference Architecture, V1.2,
      http://www.softswitch.org, June 2002.
      INFORMATIVE

   6  S. Donovan, "The SIP INFO Method", RFC 2976, October 2000.
      NORMATIVE

   7  Bray, T. et. al., "Extensible Markup Language (XML) 1.0 (Second
      Edition)", W3C Recommendation, <http://www.w3.org/TR/REC-xml>,
      October 2000.
      NORMATIVE






Burger, et. al.     Informational - Expires 4/2003                  20

                           SnowShore MSCML           October 28, 2002


12. Contributors

   The concept, development, documentation, and execution for MSCML was
   done by Jeff Van Dyke, Andy Spitzer, and Terence Lobo at SnowShore
   Networks, Inc.  The IVR implementation was influenced by original
   work by Andy Spitzer while he was at The Telephone Connection, Inc.

   Terence Lobo, Srinivas Motamarri, Haj Elfadil, and Edwina Nowicki
   contributed in being the first to eat what got cooked up.


13. Acknowledgments

   The following individuals significantly assisted in the development,
   direction, or, most importantly, debugging of MSCML.

      o Gaurav Srivastva and Subhash Verma from BayPackets
      o Jon Hinckley from SkyWave/Sestro
      o Wesley Hicks, Ravindra Kabre, Kevin Summers from Sonus Networks
      o Diana Rawlins, Sharadha Vijay from WorldCom
      o Tim Wong from Z-Tel
      o Kevin Flemming for his feedback on the semantics of creation
        versus configuration for conferencing

   The authors would like to thank Scotty Farber who made most of our
   techno-geek into English.


14. Author's Addresses

   Jeff Van Dyke                    jvandyke@snowshore.com
   Andy Spitzer                     aspitzer@snowshore.com
   Eric Burger (Ed.)                eburger@snowshore.com
   SnowShore Networks, Inc.
   285 Billerica Rd.
   Chelmsford, MA  01824-4120
   USA

   Phone: +1 978/367-8400















Burger, et. al.     Informational - Expires 4/2003                  21

                           SnowShore MSCML           October 28, 2002



Full Copyright Statement

   Copyright (C) The Internet Society (2002).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph
   are included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.  This
   document and the information contained herein is provided on an "AS
   IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK
   FORCE DISCLAIMS 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.

Acknowledgement

   The Internet Society currently provides funding for the RFC Editor
   function.

   SnowShore Networks, Inc. is a member of the Internet Society.




















Burger, et. al.     Informational - Expires 4/2003                  22


Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/