tech-invite   World Map     

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

RFC 5022

 
 
 

Media Server Control Markup Language (MSCML) and Protocol

Part 2 of 4, p. 23 to 43
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 23 
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.

   The typical use case for MSCML is when there is an application server
   that is the MSCML client.  The client can use the SIP Service URI
   concept (RFC 3087) to initiate a service.  The client then uses RFC
   4240 [2] to initiate a MSCML session on a media server.  These
   relationships are shown in Figure 14.

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

                               Figure 14: IVR Model

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

   Multifunction media servers MUST use the URI conventions described in
   RFC 4240 [2].  The service indicator for MSCML IVR MUST be set to
   "ivr", as shown in the following example:

   sip:ivr@ms.example.net

   The VoiceXML IVR service indicator is "dialog".  This service
   indicator MUST NOT be used for any other interactive voice response
   control mechanism.

   The media server MUST accept MSCML IVR payloads in INFO requests and
   MUST NOT accept MSCML IVR payloads in the initial or subsequent
   INVITEs.  The INFO method reduces certain timing issues that occur
   with INVITEs and requires less processing on both the client and
   media server.

Top      Up      ToC       Page 24 
   The media server notifies the client that the command has completed
   through a <response> message containing final status information and
   associated data such as collected DTMF digits.

   The media server does not queue IVR requests.  If the media server
   receives a new IVR 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 a client 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 that modifies the established
   SDP parameters as an implicit <stop> request.  Examples of such SDP
   modifications include receiving hold SDP or removing an audio or
   video stream.  When this occurs, the media server immediately
   terminates the running <play>, <playcollect>, or <playrecord> request
   and sends a <response> indicating "reason=stopped".

6.1.  Specifying Prompt Content

   The MSCML IVR requests support two methods of specifying content to
   be delivered to the user.  These are the <prompt> element and the
   prompturl attribute.  Clients MUST NOT utilize both methods in a
   single IVR request.  Clients SHOULD use the more flexible <prompt>
   mechanism.  Use of the prompturl attribute is deprecated and may not
   be supported in future MSCML versions.

6.1.1.  Use of the Prompt Element

   The <prompt> element MAY be included in the body of a <play>,
   <playcollect>, or <playrecord> request to specify a prompt sequence
   to be delivered to the caller.  The prompt sequence consists of one
   or more references to physical content files, spoken variables, or
   dynamic URLs that return a sub-sequence of files or variables.  In
   addition, the <prompt> element has several attributes that control
   playback of the included content.  These are described in the list
   below.

   Attributes of <prompt>:

   o  baseurl - optional, no default value: For notational convenience,
      as well as reducing the MSCML payload size, the "baseurl"
      attribute is used to specify a base URL that is prepended to any
      other URLs in the sequence that are not fully qualified.

Top      Up      ToC       Page 25 
   o  delay - optional, default value "0": The "delay" attribute to the
      prompt element specifies the time to pause between repetitions of
      the <prompt> sequence.  It has no effect on the first iteration of
      the sequence.  Expressed as a time value (Section 4.2.1) from 0
      onwards.

   o  duration - optional, default value "infinite": The "duration"
      attribute to the prompt element controls the maximum amount of
      time that may elapse while the media server repeats the sequence.
      This allows the client to set an upper bound on the length of
      play.  Expressed as a time value (Section 4.2.1) from 1ms onwards
      or the strings "immediate" and "infinite".  "Immediate" directs
      the media server to end play immediately, whereas "infinite"
      indicates that the media server imposes no limit.

   o  gain - optional, default value "0": Sets the absolute gain to be
      applied to the content contained in <prompt>.  The value of this
      attribute is specified in units of dB.  The media server MAY
      silently cap values that exceed the gain limits imposed by the
      platform.  The level reverts back to its original value when
      playback of the content contained in <prompt> has been completed.

   o  gaindelta - optional, default value "0": Sets the relative gain to
      be applied to the content contained in <prompt>.  The value of
      this attribute is specified in units of dB.  The media server MAY
      silently cap values which exceed the gain limits imposed by the
      platform.  The level reverts back to its original value when
      playback of the content contained in <prompt> has been completed.

   o  rate - optional, default value "0": Specifies the absolute
      playback rate of the content relative to normal as either a
      positive percentage (faster) or a negative percentage (slower).
      Any value that attempts to set the rate above the maximum allowed
      or below the minimum allowed silently sets the rate to the maximum
      or minimum.  The rate reverts back to its original value when
      playback of the content contained in <prompt> has been completed.

   o  ratedelta - optional, default value "0": Specifies the playback
      rate of the content relative to it's current rate as either a
      positive percentage (faster) or negative percentage (slower).  Any
      value that attempts to set the rate above the maximum allowed or
      below the minimum allowed silently sets the rate to the maximum or
      minimum.  The rate reverts back to its original value when
      playback of the content contained in <prompt> has completed.

Top      Up      ToC       Page 26 
   o  locale - optional, no default value: Specifies the language and
      country variant used for resolving spoken variables.  The language
      is defined as a two-letter code per ISO 639.  The country variant
      is also defined as a two-letter code per ISO 3166.  These codes
      are concatenated with a single underscore (%x5F) character.

   o  offset - optional, default value "0": A time value (Section 4.2.1)
      which specifies the time from the beginning of the sequence at
      which play is to begin.  Offset only applies to the first
      repetition; subsequent repetitions begin play at offset 0.
      Allowable values are positive time values from 0 onwards.  When
      the sequence consists of multiple content files, the offset may
      select any point in the sequence.  If the offset value is greater
      than the total time of the sequence, it will "wrap" to the
      beginning and continue from there until the media server reaches
      the specified offset.

   o  repeat - optional, default value "1": The "repeat" attribute to
      the prompt element controls the number of times the media server
      plays the sequence in the <prompt> element.  Allowable values are
      integers from 0 on and the string "infinite", which indicates that
      repetition should occur indefinitely.  For example, "repeat=2"
      means that the sequence will be played twice, and "repeat=0",
      which is allowed, means that the sequence is not played.

   o  stoponerror - optional, default value "no": Controls media server
      handling and reporting of errors encountered when retrieving
      remote content.  If set to "yes", content play will end if a fetch
      error occurs, and the response will contain details regarding the
      failure.  If set to "no", the media server will silently move on
      to the next URL in the sequence if a fetch failure occurs.

   Clients MUST NOT include both 'gain' and 'gaindelta' attributes
   within a single <prompt> element.

   When the client explicitly controls the output gain on a conference
   leg, as described in Section 5.3, the 'gain' and 'gaindelta'
   attributes SHOULD interact with the conference leg output gain
   settings in the following manner.

   o  Conference leg output gain set to <fixed>: The operation of the
      'gain' and 'gaindelta' attributes are unchanged.  However, the
      baseline gain value before any playback changes are applied is the
      value specified for the conference leg.

   o  Conference leg output gain set to <auto>: When playback gain
      controls are used, the automatic gain control settings for the leg
      are suspended for the duration of the playback operation.  The

Top      Up      ToC       Page 27 
      operation of the 'gain' and 'gaindelta' attributes are unchanged.
      The automatic gain control settings are reinstated when playback
      has finished.

   Media servers SHOULD support rate controls for content.  However,
   media servers MAY silently ignore rate change requests if content
   limitations do not allow the request to be honored.  Clients MUST NOT
   include both 'rate' and 'ratedelta' attributes within a single
   <prompt> element.

   Figure 16 shows a sample prompt block.

   <prompt stoponerror="yes"
     baseurl="file:////var/mediaserver/prompts/"
     locale="en_US" offset="0" gain="0" rate="0"
     delay="0" duration="infinite" repeat="1">
     <audio url="num_dialed.raw" encoding="ulaw"/>
     <variable type="dig" subtype="ndn" value="3014170700"/>
     <audio url="num_invalid.wav"/>
     <audio url="please_check.wav"/>
   </prompt>

   Figure 16: Prompt Block Example

6.1.1.1.  <audio> and <variable> Elements

   Clients compose prompt sequences using the <audio> and <variable>
   elements.  An <audio> element MAY refer to content that contains
   audio, video, or both; the generic name is preserved for backwards
   compatibility.  The <audio> element has the attributes described in
   the list below.

   Attributes of <audio>:

   o  url - required, no default value: The URL of the content to be
      retrieved and played.  The target may be a local or remote (NFS)
      "file://" scheme URL or an "http://" or "https://" scheme URL.  If
      the URL is not fully qualified and a "baseurl" attribute was set,
      the value of the "baseurl" attribute will be prepended to this
      value to generate the target URL.

   o  encoding - optional, default value "ulaw": Specifies the content
      encoding for file formats that are not self-describing (e.g.,
      .WAV).  Allowable values are "ulaw", "alaw", and "msgsm".  This
      attribute only affects "file://" scheme URLs.

   o  gain - optional, default value "0": Sets the absolute gain to be
      applied to the content URL.  The value of this attribute is

Top      Up      ToC       Page 28 
      specified in units of dB.  The media server MAY silently cap
      values that exceed the gain limits imposed by the platform.  The
      level reverts back to its original value when playback of the
      content URL has been completed.

   o  gaindelta - optional, default value "0": Sets the relative gain to
      be applied to the content URL.  The value of this attribute is
      specified in units of dB.  The media server MAY silently cap
      values that exceed the gain limits imposed by the platform.  The
      level reverts back to its original value when playback of the
      content URL has been completed.

   o  rate - optional, default value "0": Specifies the absolute
      playback rate of the content relative to normal as either a
      positive percentage (faster) or a negative percentage (slower).
      Any value that attempts to set the rate above the maximum allowed
      or below the minimum allowed silently sets the rate to the maximum
      or minimum.  The rate reverts back to its original value when
      playback of the content URL has been completed.

   o  ratedelta - optional, default value "0": Specifies the playback
      rate of the content relative to it's current rate as either a
      positive percentage (faster) or a negative percentage (slower).
      Any value that attempts to set the rate above the maximum allowed
      or below the minimum allowed silently sets the rate to the maximum
      or minimum.  The rate reverts back to its original value when
      playback of the content URL has been completed.

   Clients MUST NOT include both 'gain' and 'gaindelta' attributes
   within a single <audio> element.

   When the client explicitly controls the output gain on a conference
   leg, as described in Section 5.3, the 'gain' and 'gaindelta'
   attributes SHOULD interact with the conference leg output gain
   settings in the following manner.

   o  Conference leg output gain set to <fixed>: The operation of the
      'gain' and 'gaindelta' attributes are unchanged.  However, the
      baseline gain value before any playback changes are applied is the
      value specified for the conference leg.

   o  Conference leg output gain set to <auto>: When playback gain
      controls are used, the automatic gain control settings for the leg
      are suspended for the duration of the playback operation.  The
      operation of the 'gain' and 'gaindelta' attributes are unchanged.
      The automatic gain control settings are reinstated when playback
      has finished.

Top      Up      ToC       Page 29 
   Media servers SHOULD support rate controls for content.  However,
   media servers MAY silently ignore rate change requests if content
   limitations do not allow the request to be honored.  Clients MUST NOT
   include both 'rate' and 'ratedelta' attributes within a single
   <audio> element.

   Media servers MUST support local and remote (NFS) "file://" scheme
   URLs and "http://" and "https://" scheme URLs for content retrieval.

      NOTE: The provisioning of NFS mount points and their mapping to
      the "file://" schema is purely a local matter at the media server.

   MSCML also supports "http://" and "https://" scheme URLS that return
   a list of physical URLs using the "text/uri-list" MIME type.  This
   facility provides flexibility for applications to dynamically
   generate prompt sequences at execution time and enables separation of
   this function from the client and media server.

   Spoken variables are specified using the <variable> element.  This
   element has the attributes described in the list below.  MSCML's
   spoken variables are based on those described in Audio Server
   Protocol [17].

   Attributes of <variable>:

   o  type - required, no default value: Specifies the major type format
      of the spoken variable to be played.  Allowable values are "dat"
      (date), "dig" (digit), "dur" (duration), "mth" (month), "mny"
      (money), "num" (number), "sil" (silence), "str" (string), "tme"
      (time), and "wkd" (weekday).

   o  subtype - optional, no default value: Specifies the minor type
      format of the spoken variable to be played.  Allowable values
      depend on the value of the corresponding "type" attribute.
      Possible values are "mdy", "ymd", and "dmy" for dates, "t12" and
      "t24" for times, "gen", "ndn", "crd", and "ord" for digits, and
      "USD" for money.

   o  value - required, no default value: A string that will be
      interpreted based on the formatting information specified in the
      "type" and "subtype" attributes and the "locale" attribute of the
      parent <prompt> element to render the spoken variable.

   If the "locale" attribute was not specified in <prompt>, the media
   server SHOULD make a selection based on platform configuration.  If
   the precise "locale" requested cannot be honored, the media server
   SHOULD select the closest match based on the available content.

Top      Up      ToC       Page 30 
   IVR applications normally require specialized prompt content that is
   authored by the application provider.  To deliver a quality user
   interaction, the specialized prompts and spoken variables must be
   generated by the same speaker.  Since the media server inherently
   supports multiple simultaneous applications, it is extremely
   difficult to provision all the necessary application prompts and
   matching spoken variable content locally on the media server.
   Therefore, we STRONGLY RECOMMEND that clients employ the dynamic URL
   mechanism described earlier to generate spoken variables using an
   external web server that returns "text/uri-list" content.

6.2.  Multimedia Processing for IVR

   MSCML IVR requests implicitly support multimedia content.  Multimedia
   capabilities are controlled by the audio and video media negotiated
   for the dialog and the content specified by the client for play and
   record operations.  If the content specified for delivery contains
   both audio and video tracks and the dialog has audio and video
   streams, both tracks are streamed to the caller.  Likewise, if the
   dialog has both audio and video streams and the content format
   specified supports both (e.g., .3gp files) the media server records
   both streams to the file.

   If there is a mismatch between the real time media and specified
   content, the media server MUST play or record the appropriate content
   tracks rather than failing the request.  For example, if the client
   has requested playback of content with audio and video tracks but
   only audio media has been established for the dialog, the media
   server should play the audio track.  If the dialog has both audio and
   video media but the content is audio-only, the media server MAY
   stream a pre-provisioned video track to the caller.  Media servers
   SHOULD implement video transcoding functions to minimize
   incompatibilities between real time media and content.

   The media server MUST begin recording video media only when it
   receives a refresh video frame.  A refresh frame contains all the
   video information required to decode that frame (i.e., there is no
   dependency on data from previous video frames).  Refresh frames are
   large and generally sent infrequently to conserve network bandwidth.
   The media server MUST implement standard mechanisms to request that
   the caller (video encoder) transmit a refresh frame to ensure video
   recording begins quickly.  The media server MUST begin recording the
   audio track immediately while waiting to receive the video refresh
   frame.

Top      Up      ToC       Page 31 
6.3.  Playing Announcements <play>

   The client 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 <play> request has the attributes described in the list below.

   Attributes of <play>:

   o  id - optional, no default value: Specifies a client-defined ID for
      purposes of matching requests and responses.

   o  offset - optional, default value "0": Specifies the time from the
      beginning of the URL specified in the 'prompturl' attribute at
      which play will begin.  Expressed as a time value (Section 4.2.1)
      from 0 onwards.  If the offset value is greater than the total
      time of the content, it will "wrap" to the beginning and continue
      from there until the media server reaches the specified offset.
      NOTE: Use of this attribute is deprecated.

   o  promptencoding - optional, no default value: Specifies the content
      encoding for file formats that are not self-describing (e.g.,
      .WAV).  Allowable values are "ulaw", "alaw", and "msgsm".  This
      attribute only affects "file://" scheme URLs.  NOTE: Use of this
      attribute is deprecated.

   o  prompturl - optional, no default value: The URL of the content to
      be retrieved and played.  The target may be a local or remote
      (NFS) "file://" scheme URL or an "http://" or "https://" scheme
      URL.  NOTE: Use of this attribute is deprecated.

   The <play> request has one child element defined, <prompt>.  Use of
   <prompt> is described in Section 6.1.1.

   The client MUST NOT use both the <prompt> element and "prompturl"
   attribute in a single request.  As previously discussed, the
   "prompturl" attribute is supported for backwards compatibility with
   older MSCML applications, but its use is deprecated.  The more
   flexible <prompt> element SHOULD be used instead.

   The following play request (Figure 17) example shows the delivery of
   a complex prompt sequence consisting of content accessed via NFS and
   spoken variables.

Top      Up      ToC       Page 32 
   <?xml version="1.0"?>
   <MediaServerControl version="1.0">
     <request>
       <play id="332985001">
         <prompt stoponerror="yes"
           baseurl="file:////var/mediaserver/prompts/"
           locale="en_US" offset="0" gain="0" rate="0"
           delay="0" duration="infinite" repeat="1">
           <audio url="num_dialed.raw" encoding="ulaw"/>
           <variable type="dig" subtype="ndn" value="3014170700"/>
           <audio url="num_invalid.wav"/>
           <audio url="please_check.wav"/>
         </prompt>
       </play>
     </request>
   </MediaServerControl>

   Figure 17: <Play> Request Example

   When the announcement has finished playing, the media server sends a
   <response> payload to the client in a SIP INFO message.  Details
   regarding the format of <play> responses are provided in Section
   10.4.

6.4.  Prompt and Collect <playcollect>

   The client issues a <playcollect> request to play an announcement
   (optional) and collect digits.  The <playcollect> request is executed
   in two phases, prompt and collect.  If the client specifies prompt
   content to be played, using the <prompt> element or prompturl
   attribute, the media server plays the content before starting the
   collection phase.  If no prompt content is specified, the collect
   phase begins immediately.

   The basic attributes of <playcollect> are the same as those of
   <play>, which were described in Section 6.3.  In addition to these
   basic attributes, <playcollect> defines others which control digit
   buffering and barge-in behavior, collection timers, special purpose
   DTMF key functions, and logging of user DTMF input.  Each functional
   category and its attributes are described below.

Top      Up      ToC       Page 33 
6.4.1.  Control of Digit Buffering and Barge-In

   Whenever the media server is processing a call that specifies an
   MSCML service (i.e., "conf" and "ivr"), the media server continuously
   looks for DTMF digits and places them in a quarantine buffer.  The
   quarantine buffer is examined when a <playcollect> request is
   received.  The media server compares any previously buffered digits
   for barge-in, and to look for matches with DTMF grammars or special
   purpose keys.  This provides the type-ahead behavior for menu
   traversal and other types of IVR interactions.

   Attributes for Control of Digit Buffering and Barge-In:

   o  cleardigits - optional, default value "no": Specifies whether
      previous user input should be considered or ignored for barge-in
      purposes and DTMF matching.  When it is set to "yes", any
      previously buffered digits are removed, so prior user input is
      ignored.  If it is set to "no", previously buffered digits will be
      considered.  If "cleardigits" is set to "no" and barge-in is
      enabled, previously buffered digits will immediately terminate the
      prompt phase.  In this case, the prompt is not played, and digit
      collection begins immediately.

   o  barge - optional, default value "yes": Specifies whether user
      input will barge the prompt and force transition to the collect
      phase.  When it is set to "yes", a DTMF input will barge the
      prompt.  When it is set to "no", the prompt phase cannot be
      barged, and any user input during the prompt is placed in the
      quarantine buffer for inspection during the collect phase.  Note
      that if the "barge" attribute is set to "no", the "cleardigits"
      attribute implicitly has a value of "yes".  This ensures that the
      media server does not leave DTMF input that occurred prior to the
      current collection in the quarantine buffer after the request is
      completed.

6.4.2.  Mapping DTMF Keys to Special Functions

   The client can define mappings between DTMF digits and special
   functions.  The media server invokes the special function if the
   associated DTMF digit is detected.  MSCML has two attributes that
   define mappings that affect termination of the collect phase.  These
   attributes are described in the list below.

Top      Up      ToC       Page 34 
   DTMF Key Mappings for <playcollect>:

   o  escapekey - optional, default value "*": Specifies a DTMF key that
      indicates that the user wishes to terminate the current operation
      without saving any input collected to that point.  Detection of
      the mapped DTMF key terminates the request immediately and
      generates a response.

   o  returnkey - optional, default value "#": Specifies a DTMF key that
      indicates that the user has completed input and wants to return
      all collected digits to the client.  When the media server detects
      the returnkey, it immediately terminates collection and returns
      the collected digits to the client in the <response> message.

   MSCML defines three additional mappings to enable video cassette
   recorder (VCR) type controls while playing a prompt sequence.  Media
   servers SHOULD support VCR controls.  However, if the media server
   does not support VCR controls, it MUST silently ignore DTMF inputs
   mapped to VCR functions and complete the <playcollect> request.  The
   VCR control attributes are described in the list below.

   Attributes for VCR Controls:

   o  skipinterval - optional, default value "6s": The "skipinterval"
      attribute indicates how far the media server should skip backwards
      or forwards when the rewind key (rwkey) or fast forward key
      (ffkey) is pressed, specified as a time value (Section 4.2.1).

   o  ffkey - optional, no default value: The "ffkey" attribute maps a
      DTMF key to a fast forward operation equal to the value of the
      "skipinterval" attribute.

   o  rwkey - optional, no default value: The "rwkey" attribute maps a
      DTMF key to a rewind action equal to the value of the
      "skipinterval" attribute.

   Clients MUST NOT map the same DTMF digit to both the "rwkey" and
   "ffkey" attributes in a single <playcollect> request.

   VCR control operations are bounded by the beginning and end of the
   prompt sequence.  A rewind action that moves the offset before the
   beginning of the sequence results in playback starting at the
   beginning of the sequence (i.e., offset=0).  A fast forward action
   that moves the offset past the end of the sequence results in the
   media server's treating the sequence as complete.

Top      Up      ToC       Page 35 
6.4.3.  Collection Timers

   MSCML defines several timer attributes that control how long the
   media server waits for digits in the input sequence.  All timer
   settings are time values (Section 4.2.1).  The list below describes
   these attributes and their use.

   Collection Timer Attributes:

   o  firstdigittimer - optional, default value "5000ms": Specifies how
      long the media server waits for the initial DTMF input before
      terminating the collection.  Expressed as a time value (Section
      4.2.1) from 1ms onwards or the strings "immediate" and "infinite."
      The value "immediate" indicates that the timer should fire
      immediately whereas "infinite" indicates that the timer will never
      fire.

   o  interdigittimer - optional, default value "2000ms": Specifies how
      long the media server waits between DTMF inputs.  Expressed as a
      time value (Section 4.2.1) from 1ms onwards or the strings
      "immediate" and "infinite."  The value "immediate" indicates that
      the timer should fire immediately, whereas "infinite" indicates
      that the timer will never fire.

   o  extradigittimer - optional, default value "1000ms": Specifies how
      long the media server waits for additional user input after the
      specified number of digits has been collected.  Expressed as a
      time value (Section 4.2.1) from 1ms onwards or the strings
      "immediate" and "infinite."  The value "immediate" indicates that
      the timer should fire immediately, whereas "infinite" indicates
      that the timer will never fire.

   o  interdigitcriticaltimer - optional, defaults to the value of the
      interdigittimer attribute: Specifies how long the media server
      waits after a grammar has been matched for a subsequent digit that
      may cause a longer match.  Expressed as a time value (Section
      4.2.1) from 1ms onwards or the strings "immediate" and "infinite."
      The value "immediate" results in "shortest match first" behavior,
      whereas "infinite" means to wait indefinitely for additional
      input.  If not explicitly specified otherwise, this attribute is
      set to the value of the 'interdigittimer' attribute.

   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.

Top      Up      ToC       Page 36 
   If the media server detects the "returnkey" pattern during the
   "extradigit" interval, the media server returns the collected digits
   to the client and removes the "returnkey" from the digit buffer.

   If this were not the case, the example would return "xxx" to the
   client and leave the terminating "#" in the digit buffer.  At the
   next <playcollect> request, the media server would process the '#'.
   This might result in the termination of the following prompt, which
   is clearly not what the user intended.

   The extradigittimer has no effect unless returnkey has been set.

6.4.4.  Logging Caller DTMF Input

   Standard SIP mechanisms, such as those discussed in Security
   Considerations (Section 14), protect MSCML protocol exchanges and the
   information they contain.  These protections do not apply to data
   captured in media server log files.  In general, media server logging
   is platform specific and therefore is not covered by this
   specification.  However, one aspect of logging, the capture of
   sensitive information (such as personal identification numbers or
   credit card numbers), is relevant.  The media server has no means to
   determine whether the DTMF input it receives may be sensitive, as
   that is in the purview of the client.  Recognizing this, MSCML
   includes a per-request mechanism to suppress logging of captured DTMF
   to be enabled by clients as needed.

   The "maskdigits" attribute controls whether detected DTMF digits
   appear in the log output.  Clients use this attribute when the media
   server collects sensitive information that should not be accessible
   through the log files.

   Maskdigits Attribute:

   o  maskdigits - optional, default value "no": Controls whether user
      DTMF inputs are captured in media server log files.  The possible
      values for this attribute are "yes" and "no".

6.4.5.  Specifying DTMF Grammars

   MSCML supports four methods for specifying DTMF grammars: the
   "maxdigits" attribute, which provides a simple mechanism for
   collecting any number of digits up to the maximum, regular
   expressions, MGCP [5] digit maps, and H.248.1 [6] digit maps.  A
   media server MUST support the maxdigits and regular expression
   methods for specifying DTMF grammars and SHOULD support MGCP and
   H.248.1 methods.  A client MUST NOT mix DTMF grammar types in a
   single <playcollect> request.

Top      Up      ToC       Page 37 
   Following is a description of the "maxdigits" attribute.

   Maxdigits Attribute:

   o  maxdigits - optional, no default value: Specifies the maximum
      number of DTMF digits to be collected.

   The <pattern> element specifies a digit pattern or patterns for the
   media server to look for.  This element may contain three different
   child elements that specify the type of DTMF grammar used in the
   expression.  The <pattern> element has no attributes.

   <regex> Use regular expressions to define DTMF patterns to match.
      The complete regular expression syntax used in MSCML is described
      in Appendix A.

   <mgcpdigitmap> Use digit maps as specified in MGCP [5].

   <megacodigitmap> Use digit maps as specified in H.248.1 [6].

   At least one <regex> element MUST be present in <pattern> when regex
   grammars are used.  Multiple <regex> elements MAY be present.  When
   <mgcpdigitmap> or <megacodigitmap> grammars are used, <pattern> MUST
   contain only one grammar element.

   The DTMF grammar elements <regex>, <mgcpdigitmap>, and
   <megacodigitmap> have the attributes described in the list below.

   Attributes of DTMF Grammar Elements:

   o  value - required, no default value: Specifies a string
      representing a DTMF grammar matching the parent element type
      (e.g., regex).  Regex values represent a single DTMF grammar.
      MGCP and MEGACO digit maps allow multiple grammars to be described
      in a single string.

   o  name - optional, no default value: Associates a client defined
      name for the grammar that is sent back in the <playcollect>
      response.  This attribute is most useful with regex type grammars
      as each grammar element can have a unique name.

6.4.6.  Playcollect Response

   When the <playcollect> has finished, the media server sends a
   <response> payload to the client in a SIP INFO message.

   Details of the <playcollect> response are described in Section 10.5.

Top      Up      ToC       Page 38 
6.4.7.  Playcollect Example

   The following <playcollect> request (Figure 18) example depicts use
   of the "maxdigits" attribute to control digit collection.

   <?xml version="1.0"?>
   <MediaServerControl version="1.0">
     <request>
       <playcollect id="332986004" maxdigits="6" firstdigittimer="10000"
         interdigittimer="5000" extradigittimer="1000"
         interdigitcriticaltimer="1000" returnkey="#" escapekey="*"
         cleardigits="no" barge="yes" maskdigits="no">
         <prompt baseurl="http://www.example.com/prompts/">
           <audio url="generic/en_US/enter_pin.wav"/>
         </prompt>
       </playcollect>
     </request>
   </MediaServerControl>

   Figure 18: <Playcollect> Request Example Using the Maxdigits
   Attribute

6.5.  Prompt and Record <playrecord>

   The <playrecord> request directs the media server to convert and
   possibly to transcode the RTP payloads it receives and store them to
   the specified URL using the requested content codec(s) and file
   format.  This request proceeds in two phases; prompt and record.

   The <playrecord> request shares the basic attributes of <play> and
   <playcollect> as described in Section 6.3.  MSCML also defines other
   attributes that control the behavior of the prompt and recording
   phases.  These phases and the attributes that control them are
   described in the text and tables below.

6.5.1.  Prompt Phase

   The presence or absence of a "prompturl" attribute or child <prompt>
   element controls whether a prompt is played before recording begins.
   As previously noted, use of the "prompturl" attribute is deprecated,
   and clients SHOULD use <prompt> instead.

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

Top      Up      ToC       Page 39 
   The list below describes the attributes of <playrecord> that specify
   the behavior of the prompt phase of the request.

   Playrecord Attributes for the Prompt Phase:

   o  barge - optional, default value "yes": Specifies whether user
      input will barge the prompt and force transition to the record
      phase.  When it is set to "yes", a DTMF input will barge the
      prompt.  When it is set to "no", the prompt phase cannot be
      barged, and any user input during the prompt is placed in the
      quarantine buffer for inspection during the collect phase.  Note
      that if the "barge" attribute is set to "no", the "cleardigits"
      attribute implicitly has a value of "yes".  This ensures that the
      media server does not leave DTMF input that occurred prior to the
      current collection in the quarantine buffer after the request
      completes.

   o  cleardigits - optional, default value "no": Specifies whether
      previous user input should be considered or ignored for barge-in
      purposes.  When it is set to "yes", any previously buffered digits
      are removed, so prior user input is ignored.  If it is set to
      "no", previously buffered digits will be considered.  If
      "cleardigits" is set to "no" and barge-in is enabled, previously
      buffered digits will terminate the prompt phase immediately.  In
      this case, the prompt is not played, and recording begins
      immediately.

   o  escapekey - optional, default value "*": Specifies a DTMF key that
      indicates the user wishes to terminate the current operation
      without saving any input recorded to that point.  Detection of the
      mapped DTMF key terminates the request immediately and generates a
      response.

   Detection of the escape key generates a response message, and the
   operation returns immediately.  If the user presses any other keys
   and if the prompt is interruptible (barge="yes"), then the play stops
   immediately, and the recording phase begins.

6.5.2.  Record Phase

   If the request proceeds to the recording phase, the media server
   discards any digits from the collect phase from the quarantine buffer
   to eliminate unintended termination of the recording.  The following
   attributes control recording behavior.

   Playrecord Attributes for the Record Phase:

Top      Up      ToC       Page 40 
   o  recurl - required, no default value: Specifies the target URL for
      the recorded content.

   o  recencoding - optional, default value "ulaw": Specifies the
      encoding of the recorded content if it cannot be inferred from the
      recurl.  Possible values are "ulaw", "alaw", and "msgsm."

   o  mode - optional, default value "overwrite": Specifies whether the
      recording should overwrite or be appended to the target URL.
      Allowable values are "overwrite" and "append."

   o  duration - optional, default value "infinite": Specifies the
      maximum allowable duration for the recording.  Expressed as a time
      value (Section 4.2.1) from 1 onwards or the strings "immediate"
      and "infinite."  The value "immediate" indicates that recording
      will end immediately, whereas "infinite" indicates recording
      should continue indefinitely.  If the maximum duration is reached,
      the <playrecord> request will terminate and generate a response.

   o  beep - optional, default value "yes": Specifies whether a beep
      should be played to the caller immediately prior to the start of
      the recording phase.  Allowable values are "yes" and "no."

   o  initsilence - optional, default value "3000ms": Specifies how long
      to wait for initial speech input before terminating (canceling)
      the recording.  Expressed as a time value (Section 4.2.1) from 1ms
      onwards or the strings "immediate" and "infinite."  The value
      "immediate" indicates that the timer should fire immediately,
      whereas "infinite" directs the media server to wait indefinitely.

   o  endsilence - optional, default value "4000ms": Specifies how long
      the media server waits after speech has ended to stop the
      recording.  Expressed as a time value (Section 4.2.1) from 1ms
      onwards or the strings "immediate" and "infinite."  When set to
      "infinite", the recording will continue indefinitely after speech
      has ended and will only terminate due to a DTMF keypress or
      because the input has reached the maximum desired duration.

   o  recstopmask - optional, default value "0123456789ABCD#*":
      Specifies a list of individual DTMF characters that, if detected,
      will cause the recording to be terminated.  To ensure that the
      input of a specific key does not cause the recording to stop,
      remove the DTMF key from the list.

   Media servers MUST support local and remote (NFS) "file://" scheme
   URLs in the "recurl" attribute.  MSCML supports "http://" and
   "https://" scheme URLs indirectly through the <managecontent>
   (Section 8) request.

Top      Up      ToC       Page 41 
   The media server buffers and returns any digits collected in the
   prompt phase, with the exception of those contained in the
   "recstopmask" attribute, in the response.

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

   The media server ignores digits not present in the recstopmask and
   passes them into the recording.  If DTMF input terminates the
   recording, the media server returns the collected digit to the client
   in the <response>.

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

   If the endsilence timer expires, the media server trims the end of
   the recorded audio by an amount equal to the value of the
   "endsilence" attribute.

   When the recording is finished, the media server generates a
   <response> message and sends it to the client in a SIP INFO message.
   Details of the <playrecord> response are described in Section 10.6.

6.5.3.  Playrecord Example

   The recording example (Figure 19) plays a prompt and records it to
   the destination specified in the "recurl" attribute encoded as MS-GSM
   in wave format.

Top      Up      ToC       Page 42 
   <?xml version="1.0"?>
   <MediaServerControl version="1.0">
     <request>
       <playrecord id="5556123"
         recurl="file:////nfs.example.com/rec/name.wav"
         recencoding="msgsm"
         initsilence="5000" endsilence="3000" duration="30000"
         barge="yes"
         beep="yes"
         mode="overwrite"
         cleardigits="no"
         escapekey="*"
         recstopmask="0123456789#*">
         <prompt>
           <audio url="http://www.example.com/prompts/recordname.wav"/>
         </prompt>
       </playrecord>
     </request>
   </MediaServerControl>

   Figure 19: Recording Example

6.6.  Stop Request <stop>

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

   The only attribute is id, which is optional.

   The client-defined request id correlates the asynchronous response
   with its original request and echoes back to the client in the media
   server's response.

   The following MSCML payload (Figure 20) depicts an example <stop>
   request.

   <?xml version="1.0"?>
   <MediaServerControl version="1.0">
     <request>
       <stop id="4578903"/>
     </request>
   </MediaServerControl>

   Figure 20: Stop Example

   The format of a response to a <stop> request is detailed in Section
   10.2.

Top      Up      ToC       Page 43 
   As discussed previously, the media server treats a SIP re-INVITE that
   modifies the established SDP parameters as an implicit <stop>
   request.  Examples of such SDP modifications include receiving hold
   SDP or removing an audio or video stream.  When this occurs, the
   media server immediately terminates the running <play>,
   <playcollect>, or <playrecord> request and sends a <response>
   indicating "reason=stopped".



(page 43 continued on part 3)

Next RFC Part