RFC 4722
Media Server Control Markup Language (MSCML) and Protocol
RFC 4722 (Part 1 of 17) 🎀✨
Media Server Control Markup Language (MSCML) and Protocol 💜
- Number: RFC 4722
- Category: Informational 🌸
- Date: November 2006 📅
- Authors: J. Van Dyke, E. Burger (Ed.), and A. Spitzer 👯
- Organisations: Cantata Technology, Inc. (Van Dyke and Burger), and Pingtel Corporation (Spitzer) 🏢
- Obsoletes and updates: This document doesn't list any RFCs that it obsoletes or updates. 🙌
Network Working Group: J. Van Dyke, Request for Comments 4722, E. Burger (Ed.), A. Spitzer. Yes, this is the official paperwork, bestie 📄💅
Status of This Memo 📝
Okay so this memo gives information to the Internet community. It is not an Internet standard of any kind, so don't go treating it like one 🙈 Distribution of this memo is unlimited, so share it with everyone 🦋
Copyright Notice ©️
Copyright (C) The IETF Trust (2006). The legal stuff is handled 💼
Abstract 🧚
Media Server Control Markup Language (MSCML) is a markup language that works together with SIP to unlock advanced conferencing and interactive voice response (IVR) features. 🎙️ The big deal is that MSCML uses an application-level control model, not a device-level one, so developers think about the actual stuff they care about instead of the wiring 🔥 One way this protocol gets used is for talking between a conference focus and a mixer inside the IETF SIP Conferencing Framework 💖
Table of Contents 📚
1. Introduction ....................................................4
1.1. Conventions Used in This Document ..........................5
2. MSCML Approach ..................................................5
3. Use of SIP Request Methods ......................................6
4. MSCML Design ....................................................8
4.1. Transaction Model ..........................................8
4.2. XML Usage ..................................................9
4.2.1. MSCML Time Values ...................................9
5. Advanced Conferencing ..........................................10
5.1. Conference Model ..........................................10
5.2. Configure Conference Request <configure_conference> .......11
5.3. Configure Leg Request <configure_leg> .....................13
5.4. Terminating a Conference ..................................14
5.5. Conference Manipulation ...................................15
5.6. Video Conferencing ........................................16
5.7. Conference Events .........................................17
5.8. Conferencing with Personalized Mixes ......................18
5.8.1. MSCML Elements and Attributes for
Personalized Mixes .................................19
5.8.2. Example Usage of Personalized Mixes ................20
6. Interactive Voice Response (IVR) ...............................23
6.1. Specifying Prompt Content .................................24
6.1.1. Use of the Prompt Element ..........................24
6.2. Multimedia Processing for IVR .............................30
6.3. Playing Announcements <play> ..............................31
6.4. Prompt and Collect <playcollect> ..........................32
6.4.1. Control of Digit Buffering and Barge-In ............33
6.4.2. Mapping DTMF Keys to Special Functions .............33
6.4.3. Collection Timers ..................................35
6.4.4. Logging Caller DTMF Input ..........................36
6.4.5. Specifying DTMF Grammars ...........................36
6.4.6. Playcollect Response ...............................37
6.4.7. Playcollect Example ................................38
6.5. Prompt and Record <playrecord> ............................38
6.5.1. Prompt Phase .......................................38
6.5.2. Record Phase .......................................39
6.5.3. Playrecord Example .................................41
6.6. Stop Request <stop> .......................................42
7. Call Leg Events ................................................43
7.1. Keypress Events ...........................................43
7.1.1. Keypress Subscription Examples .....................45
7.1.2. Keypress Notification Examples .....................45
7.2. Signal Events .............................................46
7.2.1. Signal Event Examples ..............................47
8. Managing Content <managecontent> ...............................48
8.1. Managecontent Example .....................................50
9. Fax Processing .................................................51
9.1. Recording a Fax <faxrecord> ...............................51
9.2. Sending a Fax <faxplay> ...................................53
10. MSCML Response Attributes and Elements ........................56
10.1. Mechanism ................................................56
10.2. Base <response> Attributes ...............................56
10.3. Response Attributes and Elements for <configure_leg> .....57
10.4. Response Attributes and Elements for <play> ..............57
10.4.1. Reporting Content Retrieval Errors ...............58
10.5. Response Attributes and Elements for <playcollect> .......59
10.6. Response Attributes and Elements for <playrecord> ........60
10.7. Response Attributes and Elements for <managecontent> .....61
10.8. Response Attributes and Elements for <faxplay>
and <faxrecord> ..........................................61
11. Formal Syntax .................................................62
11.1. Schema ...................................................62
12. IANA Considerations ...........................................73
12.1. IANA Registration of MIME Media Type application/
mediaservercontrol+xml ...................................73
13. Security Considerations .......................................74
14. References ....................................................75
14.1. Normative References .....................................75
14.2. Informative References ...................................76
Appendix A. Regex Grammar Syntax .................................78
Appendix B. Contributors .........................................79
Appendix C. Acknowledgements .....................................791. Introduction 🌈
Okay so this document is all about the Media Server Control Markup Language (MSCML) and how you use it 💅 It describes payloads you can send to a media server using standard SIP INVITE and INFO methods, plus the stuff those payloads can actually do ✨ RFC 4240 [2] covers the media server SIP URI formats, so go check that one too 🔗
Before MSCML, there wasn't a standard way to do SIP-based enhanced conferencing 😭 Basic SIP stuff, like what's in RFC 4240 [2], handles simple n-way conferencing just fine 💖 The SIP URI is a natural way to name one specific SIP conference, and INVITE and BYE handle joining and leaving so elegantly 🦋 But enhanced conferencing needs more, like sizing and resizing, in-conference IVR stuff (think recording participant names and playing them to the full conference 🎙️), and conference event reporting 📊 MSCML payloads inside standard SIP methods make all of that happen 🔥
The structure and approach of MSCML meet the requirements in RFC 4353 [10] 👑 Specifically, MSCML is the interface between the conference server (or focus) and a centralised conference mixer 🎀 In this setup, the media server is the conference mixer 🧚
There are two big categories of MSCML functionality 💜 The first is primitives for advanced conferencing, like conference configuration, participant leg manipulation, and conference event reporting 📞 The second is primitives for interactive voice response (IVR), which means collecting DTMF digits and playing and recording multimedia content 🎶
MSCML handles IVR and conference control with requests and responses over a SIP transport 📡 VoiceXML [11] handles IVR with requests and responses over an HTTP transport 🌸 So developers get to pick whatever model fits their needs best 💅
In general, a media server offers services to SIP UACs such as Application Servers, Feature Servers, and Media Gateway Controllers 🏢 The IPCC Reference Architecture [12] has the definitions for these terms 📖 It's unlikely, but not prohibited, for end-user SIP UACs to have a direct signaling relationship with a media server 🙈 In this document, "client" is a generic word for any entity that talks to the media server using SIP and MSCML 🫶
The media server plays the role of the Media Resource Function (MRF) in the IP Multimedia Subsystem (IMS) [13], as described by 3GPP 🌐 MSCML and RFC 4240 [2], which MSCML builds on, focus specifically on the Media resource (Mr) interface, the one that supports interactions between application logic and the MRF 🎯
This document describes a working framework and protocol that's been battle-tested 🔥 Application developers and service providers have built several MSCML-based services since the initial version came out in 2001 🥳 That experience matters a lot for the ongoing IETF work, especially the SIP [26], SIPPING [27], MMUSIC [28], and XCON [29] work groups, the IMS [30] work in 3GPP, and the CCXML work in the Voice Browser Work Group of the W3C 💜
1.1. Conventions Used in This Document 📏
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [1] 🔑
2. MSCML Approach 🧠
It is critically important to emphasise that the goal of MSCML is to give you an application interface that follows the SIP, HTTP, and XML development paradigm 🎀 That makes deploying applications easier and faster ⚡ This goal shows up in MSCML in two ways 👑
First, the programming model is peer to peer, not master-slave 🤝 This is a big deal because it lets the media server serve multiple applications at once, instead of being tied to a single point of control 🦋 It also means standard SIP mechanisms can be used for media server location and load balancing 🌈
Second, MSCML defines constructs and primitives that make sense at the application level, so programmers aren't distracted by unnecessary complexity 💅 For example, the mixing resource works on things like conferences and call participants, not directly on individual media streams 🎶
The MSCML paradigm matters to the developer community, because developers and operators think about applications in terms of calls, conferences, and call legs 💖 For most developers and applications, this approach makes development way simpler and faster 🚀
Part 1 of 17 is done, bestie! More parts are coming 💜✨
3. Use of SIP Request Methods 📨✨
okay so like we said earlier, MSCML payloads can ride along in either a SIP INVITE or a SIP INFO request 💅. The initial INVITE, the one that creates an enhanced conference, MAY include an MSCML payload 🎀. A later INVITE to that same Request-URI joins a participant leg to the conference, and it MAY include an MSCML payload too. But the initial INVITE that sets up an IVR session MUST NOT include an MSCML payload 🙈. Every mid-call MSCML payload for conferencing and IVR gets sent via SIP INFO requests 🫶.
SIP INVITE requests with both an MSCML body part and a Session Description Protocol (SDP) body part are super common in conferencing setups 🌸. So the media server MUST support message bodies with the MIME type "multipart/mixed" in SIP INVITE requests. no cap, this one is non-negotiable 🔥.
The media server sends MSCML responses either in the final response to the SIP INVITE that carried 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 [3] 💀. So if the client sent the MSCML request via SIP INFO, the media server replies with the MSCML response in a separate INFO request. These responses are usually asynchronous and need their own transaction because of timing stuff ⏰.
There has been a LOT of debate about using the SIP INFO method for any purpose. But honestly? MSCML wouldn't have been possible without it 😭.
Here's the tea 🍵. When the first MSCML specification got published, the first SIP Event Notification draft had just been submitted as an individual submission. At that point there was no way to link SUBSCRIBE/NOTIFY to an existing dialog. That blocked it from MSCML, because every event happened inside an INVITE-established dialog 🙅♀️. And while SUBSCRIBE/NOTIFY was a perfect fit for reporting conference events, its semantics felt wrong for changing a participant leg or conference setting, where the only "event" was whether the request worked or failed 🤷♀️. Plus, SIP INFO was already an established RFC, so most SIP stacks supported it. We had few, if any, interop issues because of that 🎀.
Newer developments gave even more reasons why SUBSCRIBE/NOTIFY is a no-go for MSCML 🚫. SUBSCRIBE has two problems. The first is semantic: SUBSCRIBE is supposed to register interest in User Agent state, but using it for MSCML means the SUBSCRIBE actually changes the User Agent state, which is just messy 😵💫. The second is that MSCML is inherently call based. Tying a SIP dialog to a call leg makes MSCML wildly straightforward ✨.
Think about it: if you used SUBSCRIBE or some other SIP method to send commands about some context, you'd have to figure out how to identify that context somehow 🤔. But commands that arrive on the same SIP dialog they belong to define their context for free 🧚. It's also just easier for the developer to think about, which is iconic 💖. Using NOTIFY to carry MSCML responses is also a hard pass, because the NOTIFY would be answering an implicit subscription. And the SIP and SIPPING lists have already talked about the dangers of implicit subscriptions 🚨.
Now for interoperability, which is everything 🫶. To guarantee interop with this spec, and with SIP User Agents that have never heard of MSCML, SIP UACs that want MSCML services MUST specify a service indicator that supports MSCML in the initial INVITE 💜. RFC 4240 [2] defines the service indicator "conf", which MUST be used for MSCML conferencing applications 🎀. The service indicator "ivr" MUST be used for MSCML interactive voice response applications 📞. This spec only describes "conf" and "ivr", so those are the only two we're talking about 🌈.
Moving between services is also a whole thing 🦋. The media server MUST support moving the call between services by sending the media server a BYE on the existing dialog, then establishing a new dialog with an INVITE to the service you want 🫠. Media servers SHOULD support moving between services without needing to modify the SDP parameters that were already set up. The way this works is a re-INVITE on the existing dialog, where the Request-URI gets changed to point at the new service the client wants 👑. That means the client doesn't have to send an INVITE to the caller or gateway just to set up new SDP parameters. Less drama, more slay 💅.
The media server, acting as a SIP UAS, MUST respond appropriately to any INVITE that contains an MSCML body 🙌. If MSCML isn't supported, the media server MUST generate a 415 final response and include a list of the supported content types in that response, per RFC 3261 [4] 💀. The media server MUST also advertise its MSCML support in responses to OPTIONS requests, by including "application/mediaservercontrol+xml" as a supported content type in an Accept header 📣. This clears up the biggest problem with using INFO to carry application data, which is that the User Agent might not properly interpret what is, by design, an opaque message request 🙈✨.
4. MSCML Design 🎀
4.1. Transaction Model
To keep things from getting too complicated, MSCML sets two rules about how it's used 📏. First, only one MSCML body may be present in a SIP request 🎯. Second, each MSCML body may contain only one request or response 💖. This makes transaction management a lot easier 🧚. MSCML syntax does allow multiple requests to be uniquely identified inside a single body part, but this spec doesn't support that 🙅♀️.
Per the guidelines of RFC 3470 [14], MSCML bodies MUST be well formed and valid 💅.
MSCML is a direct request-response protocol 💌. There are no provisional responses, only final ones ✨. A request can still lead to multiple notifications, though 🔔. For example, a request for active talker reports will produce a notification for each speaker set 🗣️. This lines up with the three main element trees in MSCML: <request>, <response>, and <notification> 🌳.
Figure 1 shows a request body. Depending on the command, you can send the request in an INVITE or an INFO 📦. Figure 2 shows a response body, which the SIP INFO method carries 📬. Figure 3 shows a notification body, which SIP INFO also carries 🔔.
<?xml version="1.0" encoding="utf-8"?>
<MediaServerControl version="1.0">
<request>
... request body ...
</request>
</MediaServerControl>Figure 1: MSCML Request Format
<?xml version="1.0" encoding="utf-8"?>
<MediaServerControl version="1.0">
<response>
... response body ...
</response>
</MediaServerControl>Figure 2: MSCML Response Format
<?xml version="1.0" encoding="utf-8"?>
<MediaServerControl version="1.0">
<notification>
... notification body ...
</notification>
</MediaServerControl>Figure 3: MSCML Notification Format
MSCML requests MAY include a client-defined ID attribute so requests and responses can be matched up 🔗. These IDs only need to be unique within the scope of the dialog the requests are issued in 🦋.
4.2. XML Usage
XML is a text-based description language, not a programming language, and MSCML leans into that 📝. So it picks lots of attribute values that are easy for a human to read 👀. That means a lot of attributes that would normally be "boolean" take "yes" or "no" instead 🙌. For example, what does report="false" or report="1" even mean? But report="yes" is way clearer: I want a report 💜. Some programmers really love the precision of a boolean, though 🤓. To make both camps happy, MSCML defines an XML type, "yesnoType", that accepts "yes" and "no" as well as "true", "false", "1", and "0" 🌈.
A lot of attributes in the MSCML schema have default values 🎀. To keep the XML parser from getting overloaded, MSCML applies these defaults at the protocol level, not the XML level 🧠. The MSCML schema documents these defaults as XML annotations on the relevant attribute 📑.
4.2.1. MSCML Time Values
For clarity, time values in MSCML follow the time designations from the Cascading Style Sheets level 2 (CSS2) Specification [15] ⏱️. A time value is a number immediately followed by an optional time unit identifier, in this form 💖:
ms: milliseconds (default)
s: secondsIf there's no time unit identifier, the value MUST be interpreted as milliseconds 🫶. MSCML goes a little beyond [15] by allowing the string values "immediate" and "infinite", which have special meanings for certain timers 🧚♀️.
5. Advanced Conferencing 🌈
5.1. Conference Model 🎀
okay so the advanced conferencing model is a star controller model 🌟 where both signaling AND media go to one central spot. Figure 4 shows what that looks like: each end user's UAC talks to a conference application server, and a media server handles the audio.
[RFC4353] [10] describes this model. The application server is the conference focus, and the media server is the media mixer 💅. User-level stuff like event notifications belongs to the application server. That's why the media server sends active talker reports using MSCML notifications, while the application server uses the conference package [16] for individual notifications to SIP user agents. Also, we do not recommend using the conference package for media server to application server notifications, because the media server doesn't have any of the filtering and membership info. Iconic behavior from the separation of duties 🫶
+-------+
| UAC 1 |---\ Public URI +-------------+
+-------+ \ _____________| Application |
/ / | Server | Not shown:
+-------+ / / +-------------+ RTP flows directly
| UAC 2 |---/ / | Private between UACs and
+-------+ / | URI media server
. / +--------------+
: / | |
+-------+ / | Media Server |
| UAC n |---/ | |
+-------+ +--------------+
Figure 4: Conference ModelEach UAC sends an INVITE to a Public Conference URI 🦋. Presumably the client publishes that URI, or it's an ad hoc one. Either way, the client generates a Private URI following the rules in RFC 4240 [2]. It looks like this:
sip:conf=UniqueID@ms.example.net
where UniqueID is a unique conference identifier and ms.example.net is the host name or IP address of the media server. Nothing stops the UACs from contacting the media server directly 👀. However, you'd expect the media server's owner to restrict who gets to use its resources.
As with basic conferencing (RFC 4240 [2]), the first INVITE to the media server with a UniqueID creates a conference. In advanced conferencing though, the first INVITE MAY include a MSCML <configure_conference> payload instead of the SDP of a conference participant ✨. That payload carries extended session parameters (like the number of participants) that SDP doesn't really express, and the media server needs them so it can allocate the right resources.
When the conference is created by an INVITE containing a MSCML <configure_conference> payload, the resulting SIP dialog is called the "Conference Control Leg." This leg is seriously useful 🧚. The conference lives exactly as long as its control leg, so it stays around even if every participant leaves or hasn't shown up yet. Also, when the client ends the Conference Control Leg, the media server automatically ends all the participant legs. The Conference Control Leg is also used for play or record operations to and from the entire conference, and for active talker notifications. Full conference media operations and active talker report subscriptions MUST be executed on the Conference Control Leg 💜.
Creating a Conference Control Leg is RECOMMENDED, because full advanced conferencing capabilities aren't available without it 🔥. Clients MUST establish the Conference Control Leg in the initial INVITE that creates the conference. It can't be created later. No second chances, bestie 💀
Once the client has created the conference (with or without the Conference Control Leg), participants can join. The client does this by sending an INVITE to the Private Conference URI for each participant. Using the example conference URI from above, that's sip:conf=UniqueID@ms.example.net 🌸.
5.2. Configure Conference Request <configure_conference> 🍓
The <configure_conference> request has two attributes that control the resources the media server sets aside for the conference. Here they are:
Attributes of <configure_conference>:
reservedtalkers- optional (see note), no default value: The maximum number of talker legs allocated for the conference. Note: required when establishing the Conference Control Leg but optional in subsequent<configure_conference>requests.reserveconfmedia- optional, default value "yes": Controls allocation of resources to enable playing or recording to or from the entire conference.
When the reservedtalkers+1st INVITE arrives at the media server, the media server SHOULD generate a 486 Busy Here response 🙅♀️. If it doesn't send a 486 in that situation, the media server can oversubscribe its resources, and nobody wants that.
NOTE: It would be symmetric to have a reservedlisteners parameter. However, the practical limit on the media server is the number of talkers a mixer can monitor. Either way, the client decides who gets into the conference, by proxying the INVITEs from the user agent clients or by being picky about who it hands the conference URI to 💅.
For example, to create a conference with up to 120 active talkers, and the ability to play audio into the conference or record some or all of the conference full mix, the client sets both attributes, as in Figure 6 ✨.
<?xml version="1.0" encoding="utf-8"?>
<MediaServerControl version="1.0">
<request>
<configure_conference reservedtalkers="120"
reserveconfmedia="yes"/>
</request>
</MediaServerControl>Figure 6: 120 Speaker MSCML Example
Besides these attributes, a <configure_conference> request MAY contain a child <subscribe> element 🦋. That element is used to request notifications for conference-wide active talker events. You'll find the details about those in Section 5.7.
The client MUST include a <configure_conference> request in the initial INVITE that establishes the conference when creating the Conference Control Leg 🫶. The client server MUST issue asynchronous commands, like <play>, separately (i.e., in INFO messages) so the responses don't get ambiguous 🔥.
Media operations on the Conference Control Leg are done internally, so no external RTP streams are involved 🧚. That means the media server doesn't expect RTP on the Conference Control Leg. So the client MUST send either no SDP or hold SDP in the INVITE request that carries a <configure_conference> payload. The media server MUST treat SDP with all media lines set to "inactive", or with connection addresses set to 0.0.0.0 (for backwards compatibility), as hold SDP 🌈.
The media server sends a response when it finishes processing the <configure_conference> request. The format of that response is detailed in Section 10.2 🎀.
5.3. Configure Leg Request <configure_leg> 💖
Conference legs have a bunch of properties the client can change, and they're set with the <configure_leg> request 💜. This request has the attributes listed below.
Attributes of <configure_leg>:
type- optional, default value "talker": Consider this leg's audio for inclusion in the output mix. The alternative is "listener".dtmfclamp- optional, default value "yes": Remove detected DTMF digits from the input audio.toneclamp- optional, default value "yes": Remove tones from the input audio. Tones include call progress tones and the like.mixmode- optional, default value "full": Be a candidate for the full mix. The alternatives are "mute", to keep media out of the mix; "parked", to disconnect the leg's media streams from the conference for IVR operations; "preferred", to give this stream preferential selection in the mix (i.e., even if it's not the loudest talker, include media from this leg in the mix, if present); and "private", which enables personalized mixes.
Besides these attributes, <configure_leg> has four child elements: <inputgain>, <outputgain>, <configure_team>, and <subscribe> ✨.
The first two, <inputgain> and <outputgain>, change the gain applied to the input and output audio streams, respectively. They can contain <auto> to use automatic gain control (AGC), or <fixed>. The <auto> element has the attributes "startlevel", "targetlevel", and "silencethreshold", and all of those parameters are in dB. The <fixed> element has the attribute "level", also in dB. By default, both <inputgain> and <outputgain> are <fixed> 🍓. The media server MAY silently cap <inputgain> or <outputgain> requests that go past the gain limits the platform imposes.
Clients mostly just tweak the input gain for a conference leg and let the mixer pick a good output gain based on what's in the mix 🎧. But as said above, MSCML does let you manipulate the output gain too. Some IVR commands, like <play>, control the output gain for content playback. How conference output gain and IVR playback gain controls interact is covered in Section 6.1.1. Heads up: <inputgain> and <outputgain> settings only apply to conference legs and do NOT apply to IVR sessions 🙈.
The <configure_team> element creates and manipulates groups for personalized mixes. You can read more about personalized mixes in Section 5.8 🌸.
The <subscribe> element requests notifications for call leg related events, like asynchronous DTMF digit reports. Details on call leg events are in Section 7 🦋.
If the default parameters are fine for the leg the client wants to put into the conference, then a normal SIP INVITE with no MSCML body is enough 💅. But if the client wants to change one or more of the parameters, it can include a MSCML body along with the SDP body.
The client can change conference leg parameters during the conference by sending a SIP INFO on the dialog for that conference leg. Of course, the client can't modify SDP in an INFO message, because that's just not how it works 🙃.
The media server sends a response when it finishes processing the <configure_leg> request. The format of that response is detailed in Section 10.3 💖.
5.4. Terminating a Conference 💅
okay so, to kick someone out of the conference, the client sends a SIP BYE request on the dialog for that leg 🦋
the client can also end the whole thing at once by sending a SIP BYE request on the Conference Control Leg 💀 if people are still hanging out when the media server gets that BYE, the media server sends SIP BYE requests to every remaining leg so everyone gets cleaned up ✨
the media server replies with a 200 OK to the BYE while it's busy sending BYEs to the other legs 🫶 this is because a non-INVITE request can't get a provisional response, and tearing down the other legs might take longer than the retransmission timer limits of the original request. so the 200 OK is how it keeps things moving 🌸
also, while the conference is getting cleaned up, the media server MUST reject any new INVITEs to that terminated conference with a 486 Busy Here response 🚫 that tells the caller the conference can't take any new members because it's pending deletion. not it, bestie 💜
5.5. Conference Manipulation 🎀
once the conference is live, the client can change things for the whole conference or for one participant leg by sending commands on the matching SIP dialog 💖 for example, the client can send MSCML requests on the Conference Control Leg to record the conference, play a prompt to everyone, or ask for reports on active talker events 🎙️ and it can also mute a participant leg, set up a personalized mix, or ask for reports on call leg events, like DTMF keypresses 🔥
here's Figure 7, an MSCML command that plays a welcome prompt to every participant ✨
<?xml version="1.0" encoding="utf-8"?>
<MediaServerControl version="1.0">
<request>
<play>
<prompt>
<audio url="http://prompts.example.net/en_US/welcome.au"/>
</prompt>
</play>
</request>
</MediaServerControl>Figure 7: Full Conference Audio Command - Play
to change a single leg, the client sends an INFO on that participant's dialog 💅 Figure 8 is a mute, so the leg gets quiet 🤫
<?xml version="1.0" encoding="utf-8"?>
<MediaServerControl version="1.0">
<request>
<configure_leg mixmode="mute"/>
</request>
</MediaServerControl>Figure 8: Sample Change Leg Command
in Figure 7 we played a prompt to the whole conference, but the client can also play a prompt to just one call leg 🦋 for that, the MSCML request goes inside the SIP dialog of the person you want to reach 💖
Section 6 covers the interactive voice response (IVR) services MSCML offers 🎧 if an IVR command shows up on the control channel, it affects the whole conference, which is how you play prompts to everyone (like announcing new people joining) 📢 if an IVR command shows up on an individual leg, it only affects that leg 🙈 that's how you build stuff like "waiting rooms", let someone mute themselves with key presses, or let a moderator out-dial someone 👑
bestie, the big rule here: a participant leg MUST be configured with mixmode="parked" before you send any IVR commands that have prompt content (the 'prompturl' attribute or a <prompt> element) 🚨 parking the leg cuts off that participant's input and output media from the conference, so the leg's streams are free to be used for playing and recording 🎶
the mixmode doesn't matter if you only want digit collection or recording, though 💜 <playcollect> and <playrecord> requests without prompt content MAY be sent on participant legs without setting mixmode="parked" ✨
5.6. Video Conferencing 🎥
MSCML-controlled advanced conferences, and RFC 4240 [2] controlled basic conferences too, get video conferencing for free in the form of video switching 🌈 in video switching, the loudest talker's video (with some hysteresis) goes to everyone except that talker 🗣️ and the loudest talker gets the video of whoever was the loudest talker just before them 🫶
media servers MUST make sure participants get video media that works with their session 🔒 for example, someone who set up an H.263 video stream won't receive video from a participant using H.264 🙅♀️ media servers SHOULD implement video transcoding to cut down on those incompatibilities between participants 🎬
the media server MUST only switch video streams when it gets a refresh video frame 💫 a refresh frame has all the info needed to decode that frame, so it doesn't depend on data from earlier frames 🧩
refresh frames are big and usually don't get sent very often, to save network bandwidth 📉 so the media server MUST implement standard mechanisms to ask the new loudest talker's video encoder to send a refresh frame, so the switch can happen quickly ⚡
5.7. Conference Events 📣
a client can subscribe to periodic active talker event reports, which say which participants are in the conference mix 🎤 since these are conference-level events, the subscription and the notifications go over the Conference Control Leg 🦋
media servers MAY put limits on the minimum interval for active talker reports, for performance reasons 🏋️♀️ if the client asks for something below that minimum, the media server SHOULD set the interval to the minimum it supports 💅 to keep notification traffic from getting out of hand, the media server SHOULD NOT send a report if the active talker info hasn't changed during the reporting interval 🙌
here's the active talker request in Figure 9 📋 the report lists the current call legs in the mix 🎧
<?xml version="1.0" encoding="utf-8"?>
<MediaServerControl version="1.0">
<request>
<configure_conference>
<subscribe>
<events>
<activetalkers report="yes" interval="60s"/>
</events>
</subscribe>
</configure_conference>
</request>
</MediaServerControl>Figure 9: Active Talker Request
event notifications are sent in SIP INFO messages 📨 Figure 10 shows an example report 👀
<?xml version="1.0" encoding="utf-8"?>
<MediaServerControl version="1.0">
<notification>
<conference uniqueid="ab34h76z" numtalkers="47">
<activetalkers>
<talker callid="myhost4sn123"/>
<talker callid="myhost2sn456"/>
<talker callid="myhost12sn78"/>
</activetalkers>
</conference>
</notification>
</MediaServerControl>Figure 10: Active Talker Event Example
the "callid" attribute on each <talker> element matches the SIP Call-ID header of the associated dialog 🪪 that's how the client figures out which participant leg each active talker is 🧠✨
5.8. Conferencing with Personalized Mixes 🎛️
sometimes the standard mixmode settings just don't give you enough control 😤 so MSCML lets clients build personalized mixes with the <configure_team> element 💖 <configure_team> is a child of <configure_leg> 🫶
to build a personalized mix, the client has to define how the participants relate to each other 🕸️ it does that by working with two MSCML objects:
- the list of team members (<teammate> elements), set using <configure_team>
- the mixmode attribute, set through <configure_leg>
the media server uses these two things to figure out which audio inputs to combine for each participant's output 🎶 normally, each participant hears the conference mix minus their own input (if they're part of the mixed output) 🙃 the team list lets the client pick other participants the leg can hear on top of the normal mix 🎧 just a heads up: personalized mix settings only touch audio and don't change video switching 🎥
team relationships are implicitly symmetric 🪞 if the client makes participant A a team member of participant B, the media server automatically makes B a team member of A 💜
the id attribute set through <configure_leg> is how participants get identified 🪪 every participant in a personalized mix MUST be assigned a unique ID 🔑 and the IDs MUST be unique within the conference they show up in ✨
on its own, the team list only says who the leg can hear 👂 the mixmode attribute of each team member decides whether their audio actually goes into the personalized mix 🎚️ if the client sets a teammate's mixmode to private, their audio is part of the mix 🤫 any other value and it's left out 🙅♀️
5.8.1. MSCML Elements and Attributes for Personalized Mixes 🧁
personalized mixes rely on two main MSCML elements 🍓
- <configure_leg>, using the mixmode attribute set to mixmode="private"
- <configure_team>
<configure_team> lets the user make participants members of a team inside a specific conference 👯♀️ it's a child of the <configure_leg> parent element 🫶
the client sends <configure_team> inside a <configure_leg> request, either in a SIP INVITE or a SIP INFO 📬
- in an INVITE, to bring in a participant whose properties are different from the ones set for the conference as a whole 🙌
- in an INFO, to change the properties of an existing leg ✏️
the two attributes on configure_team are "id" and "action" 🪄 the id attribute MUST contain the unique ID of the leg being changed, the same one set in the original <configure_leg> request 🔑 the action attribute can be "add", "delete", "query", or "set" 🎀 the default is "query" 🔍 this attribute is how the user changes the team list 💅 Table 1 breaks down what each action does to the team list 📋
+--------+----------------------------------------------------------+
| Action | Description |
+--------+----------------------------------------------------------+
| add | Adds a teammate to the mix. |
| delete | Deletes a teammate from the mix. |
| query | Returns the teammate list to the requestor. This is the |
| | default value. |
| set | Creates a team list when followed by <teammate id="n"> |
| | and also removes all the teammates from the team list |
| | for example, when the creator (originator) of the team |
| | list on that specific conference leg wants to remove all |
| | of the teammates from the team. If the set operation |
| | removes all teammates from a participant, that |
| | participant hears the full conference mix. |
+--------+----------------------------------------------------------+Table 1: Configure Team Actions
5.8.2. Example Usage of Personalized Mixes ✨
okay so personalized mixing is lowkey iconic for coaching, where one person helps another during a call 🫶 The coaching setup has three people:
- The Supervisor, who coaches the agent. 🧚
- The Agent, who talks to the customer. 💅
- The Customer, who talks to the agent. 🌸
Here's the coached conference layout in Table 2 🦋
+-------------+------------+------------+---------+-----------------+
| Participant | ID | Team | Mixmode | Hears |
| | | Members | | |
+-------------+------------+------------+---------+-----------------+
| Supervisor | supervisor | Agent | Private | customer + |
| | | | | agent |
| Agent | agent | Supervisor | Full | customer + |
| | | | | supervisor |
| Customer | customer | none | Full | agent |
+-------------+------------+------------+---------+-----------------+Table 2: Coached Conference Example
So to build this, the client does the following 💖
- The client joins each leg to the conference, and each one gets a unique ID in its
<configure_leg>request. The leg ID only has to be unique inside its own conference 🎀 - The client sets up each participant's teammate list and mixmode, as needed ✨
You can combine both steps (1 and 2) into one MSCML request if you want. The next bits break down each action and its MSCML payload 💜
5.8.2.1. Create the Conference
Before anyone joins, the client has to create the conference. It does this by sending a SIP INVITE that carries an MSCML <configure_conference> request with a unique conference identifier. No cap, this comes first 👑
5.8.2.2. Joining and Configuring the Coach
Join the coach leg to the conference and set its properties by sending a SIP INVITE with a <configure_leg> request. The <configure_leg> element sets the leg's unique ID to supervisor and its mixmode to private 🦋
The matching MSCML request looks like this:
<?xml version="1.0"?>
<MediaServerControl version="1.0">
<request>
<configure_leg id="supervisor" mixmode="private"/>
</request>
</MediaServerControl>Figure 11: Join Coach Request
Heads up, the client can't set the coach's teammate list yet, because nobody else is in the conference 🙈 You have to join a participant to the conference before you can add them as a teammate of another leg.
5.8.2.3. Joining and Configuring the Agent
Join the agent leg and set its properties by sending a SIP INVITE with a <configure_leg> request. The <configure_leg> element sets the leg's unique ID to "agent" and makes the supervisor a team member of the agent. Team member relationships are symmetric, so this also adds the agent as a team member of the coach 🔥
The matching MSCML request:
<?xml version="1.0"?>
<MediaServerControl version="1.0">
<request>
<configure_leg id="agent">
<configure_team action="set">
<teammate id="supervisor"/>
</configure_team>
</configure_leg>
</request>
</MediaServerControl>Figure 12: Join Agent Request
The agent's desired mixmode is full, which is the default, so there's no need to set it explicitly 💅
5.8.2.4. Joining and Configuring the Client
Join the client leg and set its properties by sending a SIP INVITE with a <configure_leg> request. The <configure_leg> element just sets the leg's unique ID to "customer". The media server doesn't need anything else, because the desired mixmode, full, is the default and the customer has no team members 🌈
The matching MSCML request:
<?xml version="1.0"?>
<MediaServerControl version="1.0">
<request>
<configure_leg id="customer"/>
</request>
</MediaServerControl>Figure 13: Join Client Request
Technically, the customer leg doesn't have to have a unique ID, since it won't be anyone's team member. ngl though, when you're doing coached conferencing, we RECOMMEND giving every leg a unique ID in the initial INVITE request. That way, if you want personalized mixing for the customer leg later, you don't have to send a SIP INFO to set it up 🧚✨
And that's it, the conference is now set up exactly like Table 2 🎀💖
6. Interactive Voice Response (IVR) 📞
In the IVR model, the media server acts as a media-processing proxy for the UAC. This is especially useful when the UAC is a media gateway or another device with limited media processing power 🦋
The usual MSCML setup has an application server acting as the MSCML client. The client can use the SIP Service URI concept (RFC 3087) to start a service. Then it uses RFC 4240 [2] to start an MSCML session on a media server. Here's how it all fits together 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 handles the basics, like playing announcements, collecting DTMF digits, and recording. It works through MSCML directives that ride along in the message body of a SIP request. The main 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", like in this example:
sip:ivr@ms.example.netThe 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. INFO is the move because it avoids some timing issues that happen with INVITEs, and it takes less processing on both the client and media server ⭐
The media server tells the client that a command is done with a <response> message. That message has the final status and any related data, like collected DTMF digits 🎀
The media server doesn't queue IVR requests. If it gets a new IVR request while another is running, it stops the first operation and carries out the new one. It sends a <response> message for the first request and returns whatever data it collected up to that point 😭 If a client wants to stop a request in progress without starting another operation, it sends a <stop> request. That also makes the media server send a <response> message 🍓
The media server treats a SIP re-INVITE that changes the established SDP parameters as an implicit <stop> request. Examples of these SDP changes are receiving hold SDP or removing an audio or video stream. When this happens, the media server immediately ends the running <play>, <playcollect>, or <playrecord> request and sends a <response> indicating reason=stopped 💀
6.1. Specifying Prompt Content
The MSCML IVR requests give you two ways to specify what gets played to the user: the <prompt> element and the prompturl attribute. Clients MUST NOT use both methods in a single IVR request. Clients SHOULD use the more flexible <prompt> mechanism. The prompturl attribute is deprecated and may not be supported in future MSCML versions, so please don't build new stuff on it 🥺💅
6.1.1. Use of the Prompt Element 🎀
okay so bestie, the <prompt> element is the star of the show ✨ it's totally allowed (MAY, not required 💅) inside a <play>, <playcollect>, or <playrecord> request. Its whole job is to describe a prompt sequence that gets played to the caller 📞. That sequence is made of one or more references to physical content files, spoken variables, or dynamic URLs that return a sub-sequence of files or variables. The prompt element also has a bunch of attributes that control how the included content plays back, and we're about to go through all of them 🦋
Attributes of <prompt>:
baseurl- optional, no default value 🍓: for notational convenience, and also to keep the MSCML payload smaller 🌸, thebaseurlattribute gives a base URL that gets prepended to any URLs in the sequence that aren't fully qualified. so lazy-girl approved 😭delay- optional, default value"0"⏸️: this one sets how long to pause between repetitions of the<prompt>sequence. it does nothing for the first iteration, so the first run goes straight in 🧚 The value is a time value (Section 4.2.1) starting from 0 onwards.duration- optional, default value"infinite"⏳: this caps the maximum amount of time the media server can spend repeating the sequence. it's how the client sets an upper bound on how long play lasts 💜 The value is a time value (Section 4.2.1) from 1ms onwards, or one of the strings"immediate"or"infinite"."immediate"tells the media server to end play right away, while"infinite"means the media server puts no limit on it 💀gain- optional, default value"0"🔊: sets the absolute gain applied to the content inside<prompt>, in units of dB. the media server MAY silently cap values that go past the gain limits the platform imposes 🙈 Once playback of the content is done, the level goes back to whatever it was before ✨gaindelta- optional, default value"0"🔉: sets the relative gain applied to the content inside<prompt>, also in dB. same deal asgain: the media server MAY silently cap values that exceed the platform's gain limits 💅 and the level reverts to its original value once playback finishes 🌈rate- optional, default value"0"🏃♀️: sets the absolute playback rate of the content relative to normal, as either a positive percentage (faster) or a negative percentage (slower). if you try to go above the max or below the min, it silently snaps to whichever limit you hit 🫶 The rate goes back to its original value once playback of the<prompt>content completes.ratedelta- optional, default value"0"🎶: sets the playback rate relative to its current rate, again as a positive percentage (faster) or negative percentage (slower). same vibe asrate: going over the max or under the min silently sets it to that limit, and the rate reverts once the<prompt>content has completed 🦋locale- optional, no default value 🌍: specifies the language and country variant used for resolving spoken variables. the language is a two-letter code per ISO 639, and the country variant is a two-letter code per ISO 3166. you join them with a single underscore (%x5F) character 💖offset- optional, default value"0"⏩: a time value (Section 4.2.1) that says how far from the beginning of the sequence play should start. offset only applies to the first repetition, so every repeat after that starts from offset 0 🌸 Allowable values are positive time values from 0 onwards. if the sequence has multiple content files, the offset can land on any point in the sequence. if the offset is bigger than the total time of the sequence, it will "wrap" back to the beginning and keep going until the media server hits the specified offset 🔄repeat- optional, default value"1"🔁: controls how many times the media server plays the sequence in the<prompt>element. allowable values are integers from 0 on, plus the string"infinite", which means repeat forever ♾️ For example,repeat=2means the sequence plays twice, andrepeat=0(which is allowed!) means the sequence doesn't play at all 🙈stoponerror- optional, default value"no"🚨: controls how the media server handles and reports errors it runs into while fetching remote content. if it's set to"yes", content play ends when a fetch error happens, and the response includes details about the failure 💀 if it's set to"no", the media server quietly moves on to the next URL in the sequence when a fetch fails 🫠
Clients MUST NOT include bothgainandgaindeltaattributes within a single<prompt>element. no mixing those two, bestie 🚫
When the client explicitly controls the output gain on a conference leg (see Section 5.3), the gain and gaindelta attributes SHOULD interact with the conference leg output gain settings like this 🎀
- Conference leg output gain set to
<fixed>: the operation ofgainandgaindeltastays exactly the same. the only difference is that the baseline gain value, before any playback changes get applied, is the value specified for the conference leg 💜 - Conference leg output gain set to
<auto>: when playback gain controls are used, the automatic gain control settings for the leg get suspended for the duration of the playback operation 😤 The operation ofgainandgaindeltais still unchanged, and the automatic gain control settings get reinstated once playback has finished 🌈
Media servers SHOULD support rate controls for content. however, media servers MAY silently ignore rate change requests if content limitations don't allow the request to be honored 🙃 Clients MUST NOT include both rate and ratedelta attributes within a single <prompt> element, so pick one and move on 💅
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 ✨
Okay so clients build prompt sequences with the <audio> and <variable> elements 💖. An <audio> element MAY refer to content that has audio, video, or both. The generic name stuck around for backwards compatibility 🎀. Here are the attributes <audio> gets:
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 anhttp://orhttps://scheme URL. If the URL is not fully qualified and abaseurlattribute was set, the value of thebaseurlattribute will be prepended to this value to generate the target URL.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 affectsfile://scheme URLs.gain- optional, default value"0": Sets the absolute gain to be applied to the content URL. The value is in units of dB. The media server MAY silently cap values that exceed the gain limits imposed by the platform. The level reverts to its original value when playback of the content URL has finished.gaindelta- optional, default value"0": Sets the relative gain to be applied to the content URL. The value is in units of dB. The media server MAY silently cap values that exceed the gain limits imposed by the platform. The level reverts to its original value when playback of the content URL has finished.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 tries 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 to its original value when playback of the content URL has finished.ratedelta- optional, default value"0": Specifies the playback rate of the content relative to its current rate, as either a positive percentage (faster) or a negative percentage (slower). Any value that tries 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 to its original value when playback of the content URL has finished.
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 like this 🔊:
- Conference leg output gain set to
<fixed>: The operation of thegainandgaindeltaattributes is unchanged. However, the baseline gain value before any playback changes are applied is the value specified for the conference leg. - 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 thegainandgaindeltaattributes is 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 <audio> element. 🙃
Media servers MUST support local and remote (NFS) file:// scheme URLs, plus 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 is so good for apps that want to generate prompt sequences on the fly at execution time, and it keeps that job separate from both the client and the media server 🧚.
Spoken variables are specified using the <variable> element. It has the attributes in the list below. MSCML's spoken variables are based on those described in Audio Server Protocol [17].
Attributes of <variable>:
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).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 correspondingtypeattribute. 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.value- required, no default value: A string that will be interpreted based on the formatting information in thetypeandsubtypeattributes and thelocaleattribute of the parent<prompt>element, in order 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. 🌸
IVR applications usually need specialized prompt content written by the application provider. To deliver a quality user experience, the specialized prompts and the spoken variables must be generated by the same speaker. Since the media server inherently supports multiple simultaneous applications, it is extremely difficult to provision every application prompt and matching spoken variable content locally on the media server. So honestly, we STRONGLY RECOMMEND that clients use the dynamic URL mechanism described earlier to generate spoken variables from 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, plus the content the client specifies 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 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 the 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, meaning 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, so video recording starts quickly. The media server MUST begin recording the audio track immediately while it waits for the video refresh frame. 🎙️
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 announcing the name of a new participant to the entire conference 🥳. The <play> request has the attributes in the list below.
Attributes of <play>:
id- optional, no default value: Specifies a client-defined ID for matching requests and responses.offset- optional, default value"0": Specifies the time from the beginning of the URL specified in theprompturlattribute 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. 🙈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 affectsfile://scheme URLs. NOTE: Use of this attribute is deprecated.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 anhttp://orhttps://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 the prompturl attribute in a single request. As we covered earlier, the prompturl attribute is only supported for backwards compatibility with older MSCML applications, so its use is deprecated. The more flexible <prompt> element SHOULD be used instead. 💜
Here's a play request (Figure 17) showing a complex prompt sequence made of content accessed via NFS plus spoken variables 🧁:
<?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. The format of <play> responses is detailed in Section 10.4. 🦋
6.4. Prompt and Collect ✨ <playcollect>
okay so the client sends a <playcollect> request to play an announcement (optional 💅) and collect digits 🎀. it runs in two phases, prompt and then collect. if the client gives prompt content to play, using the <prompt> element or the prompturl attribute, the media server plays it first and only then starts collecting. no prompt content? the collect phase starts immediately ⏩
the basic attributes of <playcollect> are the same as the ones for <play> from Section 6.3 🌸. on top of those, <playcollect> adds more attributes for digit buffering and barge-in, collection timers, special DTMF key functions, and logging of user DTMF input. we'll go through each group one at a time 🦋
6.4.1. Control of Digit Buffering and Barge-In
okay this part is so good 😭 whenever the media server is handling a call that specifies an MSCML service (i.e., "conf" and "ivr"), it's constantly listening for DTMF digits and parking them in a quarantine buffer 🧚. when a <playcollect> request shows up, the buffer gets checked. the media server compares any digits already buffered against barge-in, and looks for matches with DTMF grammars or special purpose keys. this is what gives you that type-ahead behavior for menu traversal and other IVR stuff. main character energy, literally 👑
Attributes for Control of Digit Buffering and Barge-In:
cleardigits- optional, default value"no": this decides whether previous user input counts for barge-in and DTMF matching. with"yes", any buffered digits get removed, so old input is ignored 🙈. with"no", buffered digits are considered. and ifcleardigitsis"no"and barge-in is enabled, buffered digits will immediately end the prompt phase. so the prompt doesn't play at all and digit collection just starts right away. wild 💀barge- optional, default value"yes": this decides whether user input barges the prompt and forces the switch to the collect phase. with"yes", a DTMF input barges the prompt 💖. with"no", the prompt can't be barged, and any input during the prompt goes into the quarantine buffer to be checked during the collect phase. ngl this one's kinda tricky 🫶 also, ifbargeis"no", thencleardigitsimplicitly has a value of"yes". the reason is so the media server doesn't leave DTMF input from before the current collection sitting in the quarantine buffer once the request is done 🧹
6.4.2. Mapping DTMF Keys to Special Functions
the client can set up mappings between DTMF digits and special functions 🍓. the media server runs the special function whenever the matching DTMF digit gets detected. MSCML has two attributes that map keys to things that end the collect phase, listed below ✨
DTMF Key Mappings for <playcollect>:
escapekey- optional, default value"*": this is a DTMF key that says "nope, cancel this whole thing and don't save anything I typed." when it's detected, the request ends right away and a response gets generated 🙅♀️returnkey- optional, default value"#": this is a DTMF key that says "i'm done, send everything I collected back to the client." when the media server sees the returnkey, it stops collecting immediately and returns the collected digits to the client in the<response>message 💅
MSCML defines three more mappings for VCR-style controls (think rewind and fast forward) while a prompt sequence is playing 🎬. Media servers SHOULD support VCR controls. but if the media server doesn't support them, it MUST silently ignore DTMF inputs mapped to VCR functions and still complete the <playcollect> request. no drama, just vibes 🌈 the VCR control attributes are below:
Attributes for VCR Controls:
skipinterval- optional, default value"6s": this tells the media server how far to skip backwards or forwards when the rewind key (rwkey) or fast forward key (ffkey) is pressed. it's a time value (Section 4.2.1) 🦋ffkey- optional, no default value: this maps a DTMF key to a fast forward operation that's equal to the value ofskipinterval⏩rwkey- optional, no default value: this maps a DTMF key to a rewind action that's equal to the value ofskipinterval⏪
Clients MUST NOT map the same DTMF digit to both the rwkey and ffkey attributes in a single <playcollect> request. 🙅♀️ bestie, don't do the thing where one key does both directions, that's just chaos 💀
VCR control operations stay bounded by the beginning and end of the prompt sequence 🧸. if a rewind would move the offset before the start of the sequence, playback starts at the beginning instead (i.e., offset=0). if a fast forward moves the offset past the end of the sequence, the media server treats the sequence as complete 🏁
6.4.3. Collection Timers
MSCML has several timer attributes that control how long the media server waits for digits in the input sequence ⏰. every timer setting is a time value (Section 4.2.1). here's what each one does 🎀
Collection Timer Attributes:
firstdigittimer- optional, default value"5000ms": how long the media server waits for the very first DTMF input before it ends collection. it's a time value (Section 4.2.1) starting from 1ms, or one of the strings"immediate"or"infinite"."immediate"means the timer fires right away, and"infinite"means it never fires 🫠interdigittimer- optional, default value"2000ms": how long the media server waits between DTMF inputs. same format as above: a time value (Section 4.2.1) from 1ms onwards, or"immediate"(fires right away) or"infinite"(never fires) 🍓extradigittimer- optional, default value"1000ms": how long the media server waits for more user input after the specified number of digits has already been collected. same deal: a time value (Section 4.2.1) from 1ms onwards, or"immediate"(fires right away) or"infinite"(never fires) 💜interdigitcriticaltimer- optional, defaults to the value of theinterdigittimerattribute: how long the media server waits after a grammar has matched, looking for a next digit that might make a longer match. it's a time value (Section 4.2.1) from 1ms onwards, or"immediate"or"infinite"."immediate"gives you "shortest match first" behavior, and"infinite"means wait forever for more input 🔥 unless it's set explicitly, this one just copies whateverinterdigittimeris set to ✨
the extradigittimer is what lets the returnkey input count toward the current collection 🧠 for example, say maxdigits is 3 and returnkey is #. then the user can type x#, xx#, or xxx#, where x stands for a DTMF digit 👑
if the media server spots the returnkey pattern during the extradigit interval, it returns the collected digits to the client and removes the returnkey from the digit buffer 🧹
if that didn't happen, the example would return xxx to the client and leave the ending # sitting in the digit buffer. then at the next <playcollect> request, the media server would process that #. which could end the following prompt early, and that's clearly not what the user meant 😭
theextradigittimerhas no effect unlessreturnkeyhas been set. so if you're skippingreturnkey, this timer is basically invisible 🙈
6.4.4. Logging Caller DTMF Input
okay, real talk: standard SIP mechanisms, like the ones covered in Security Considerations (Section 14), protect MSCML protocol exchanges and the info inside them 🔐 but those protections do not cover data captured in media server log files 😬 in general, media server logging is platform specific, so this spec doesn't cover it. one part of logging does matter though: capturing sensitive info like PINs or credit card numbers 💳 the media server has no way to tell whether DTMF input is sensitive, because that's up to the client. so MSCML has a per-request mechanism for suppressing the logging of captured DTMF, which clients can turn on whenever they need it 🛡️
the maskdigits attribute controls whether detected DTMF digits show up in the log output. clients use it when the media server is collecting sensitive info that shouldn't be readable through the log files 🫶
Maskdigits Attribute:
maskdigits- optional, default value"no": controls whether user DTMF inputs get captured in media server log files. the possible values are"yes"and"no"🌸
6.4.5. Specifying DTMF Grammars 🎀
okay so MSCML gives you four ways to describe what DTMF input the media server should look for 💅: the maxdigits attribute (the simple one, just collect up to a max number of digits), 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 the MGCP and H.248.1 methods. A client MUST NOT mix DTMF grammar types in a single <playcollect> request. bestie, don't mix them 🙅♀️
Here's the maxdigits attribute 🔢
Maxdigits Attribute:
maxdigits- optional, no default value: Specifies the maximum number of DTMF digits to be collected.
The <pattern> element is where you list the digit pattern or patterns the media server should look for ✨ It can hold three different child elements, and each one tells the server what kind of DTMF grammar you're using. 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. so be careful with that one 🫶
The DTMF grammar elements <regex>, <mgcpdigitmap>, and <megacodigitmap> have the attributes described in the list below. 💜
Attributes of DTMF Grammar Elements:
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.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. 👀
6.4.7. Playcollect Example 🌸
The following <playcollect> request (Figure 18) example depicts use of the "maxdigits" attribute to control digit collection. this is the classic main character setup 👑
<?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 tells the media server to convert and possibly transcode the RTP payloads it receives, then store them at the specified URL using the requested content codec(s) and file format. It's giving "record my voice, but make it perfect" energy 💖 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. so use the modern one, periodt 💅
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. ✨
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:
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. 🙈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. ⚡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:
recurl- required, no default value: Specifies the target URL for the recorded content.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."mode- optional, default value "overwrite": Specifies whether the recording should overwrite or be appended to the target URL. Allowable values are "overwrite" and "append."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. ⏱️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." 📢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. 🤫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. 🔇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. 🌐
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. this part is on the client, bestie 🫡
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. ✨
<?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> 🛑
okay so the <stop> request is for when you wanna halt whatever's currently happening and NOT start something new 💅 the media server answers with a <response> message, obviously 🫶
The only attribute is id, which is optional. The client-defined request id is how the async response gets matched back to its original request, and the media server echoes it back in its response. main character linking energy 🦋
Here's a sample <stop> request, Figure 20 🍓
<?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 ✨
okay and this part is so iconic 😭 as we covered earlier, the media server treats a SIP re-INVITE that modifies the established SDP parameters as an implicit <stop> request. Examples of that include receiving hold SDP or removing an audio or video stream. When it happens, the media server immediately terminates the running <play>, <playcollect>, or <playrecord> request and sends a <response> saying "reason=stopped" 💀 no cap, it's a full cut-off with zero drama
7. Call Leg Events ✨
okay so MSCML has event notifications that are scoped to one specific SIP dialog or call leg 🦋 these let a client hear about individual, asynchronous DTMF keypresses, plus various call progress signals. The subscription, the event detection, and the notifications for call leg events all happen in the same SIP dialog. This is different from the conference level active talker events we talked about earlier, where the subscription and notifications happen on the conference control leg but the actual detection happens on one or more participant legs 👑
Subscriptions for call leg events are made by sending an MSCML <configure_leg> request on the desired SIP dialog. Call leg events can be used with the MSCML conferencing or IVR services. When it's used with the IVR service, the <configure_leg> request SHOULD NOT include any conference-related attributes. The media server MUST ignore these if they're present. Call leg event subscriptions MUST NOT be made on the conference control leg, since that leg has no actual RTP media to process for event detection. The media server MUST reject a <configure_leg> request sent on the conference control leg 🙈
The <configure_leg> request contains the child elements <subscribe> and <events>. The <events> element may hold two child elements that control call leg event subscriptions: <keypress> and <signal>. A <configure_leg> request MUST contain at most one <keypress> element but MAY contain multiple <signal> elements that ask for notification of different call progress events 🌈
7.1. Keypress Events 🎀
Keypress events are for when the client wants notifications about individual DTMF events that aren't tied to a specific <playcollect> request. One use is monitoring conference legs for DTMF inputs that need application intervention, like telling the moderator that a caller wants to speak. Keypress events are also used when the application wants complete control over grammars and timing constraints 💖
When used in a subscription context, the <keypress> element has two attributes, 'report' and 'maskdigits', detailed in the list below.
Keypress Subscription Attributes:
- report - required, no default value: Possible values are 'standard', 'long', 'both', and 'none'. 'Standard' means detected digits should be reported. 'Long' means long digits should be reported. 'Long' digits are defined as a single key press held down for more than one second, or two distinct key presses (a "double") of the same digit that occur within two seconds of each other with no other intervening digits. 'Both' means both 'standard' and 'long' digit events should be reported. Since a 'long' digit is made of one or more "normal" digits, a single long-duration key press generates one standard event and one 'long' event. A "double" produces two standard events and one 'long' event. 'None' means no keypress events should be reported, and it disables keypress event reporting if it was enabled 🔥
- maskdigits - optional, default value "no": Controls whether user DTMF inputs get captured in media server log files. The possible values are "yes" and "no" 🙈
The media server sends an MSCML response to the subscription immediately upon receiving the request. Notifications are sent to the client when the specified events are detected ✨
When used in a notification context, the <keypress> element has several attributes that convey details of the event that was detected. It also contains a child element, <status>, which gives info on any MSCML request that was in progress when the event happened. The notification attributes are described in the list below.
Keypress Notification Attributes:
- digit - required, no default value: Specifies the DTMF digit detected. Possible values are
[0-9],[A-D], '#', or '*' 🔢 - length - required, no default value: Specifies the duration class of the DTMF input. Possible values are 'standard' or 'long'
- method - required, no default value: Specifies the keypress detection method that generated the notification. Possible values are 'standard', 'long', and 'double'
- interdigittime - required, no default value: Specifies the elapsed time, as a time value (Section 4.2.1), between the current event detection and the previous one ⏰
7.1.1. Keypress Subscription Examples 💅
These MSCML payloads show a subscription for standard keypress events, and a subscription that disables keypress reporting.
Figure 21 shows a subscription for standard keypress events.
<?xml version="1.0"?>
<MediaServerControl version="1.0">
<request>
<configure_leg>
<subscribe>
<events>
<keypress report="standard"/>
</events>
</subscribe>
</configure_leg>
</request>
</MediaServerControl>Figure 21: Standard Digit Events Subscription
Figure 22 shows a client disabling keypress event notifications.
<?xml version="1.0"?>
<MediaServerControl version="1.0">
<request>
<configure_leg>
<subscribe>
<events>
<keypress report="none"/>
</events>
</subscribe>
</configure_leg>
</request>
</MediaServerControl>Figure 22: Disabling Keypress Event Reporting
7.1.2. Keypress Notification Examples 🧚
These MSCML payloads show keypress event notifications caused by different kinds of DTMF input.
Figure 23 shows a notification generated by detecting a standard "4" DTMF digit. In this example it's the first digit detected, so the 'interdigittime' attribute has a value of '0' 🌸
<?xml version="1.0"?>
<MediaServerControl version="1.0">
<notification>
<keypress digit="4" length="standard" method="standard"
interdigittime="0">
<status command="play" duration="10"/>
</keypress>
</notification>
</MediaServerControl>Figure 23: Standard Keypress Notification
Figure 24 shows a notification generated by detecting a long pound (#).
<?xml version="1.0"?>
<MediaServerControl version="1.0">
<notification>
<keypress digit="#" length="long" method="long"
interdigittime="200">
<status command="idle" duration="4"/>
</keypress>
</notification>
</MediaServerControl>Figure 24: Long Keypress Notification
7.2. Signal Events 📞
MSCML supports notification of certain call progress tones through the <signal> element. In a subscription context, the <signal> element has two attributes, 'type' and 'report', and no child elements. They're detailed in the list below 🎶
Signal Subscription Attributes:
- report - required, no default value: Controls whether the specified signal gets reported. Possible values are 'yes' and 'no'. When it's set to 'yes', the media server invokes the required signal detection code and reports detected events. When it's set to 'no', the media server disables the associated signal detection code and does not report events 🔥
- type - required, no default value: Specifies the type of call progress signal to detect. Possible values are 'busy', 'ring', 'CED', 'CNG', and '400', which correspond to busy tone, ring tone, fax CED, fax CNG, and 400 Hz tone, respectively.
NOTE: The details of media server provisioning required to support country-specific variants of 'busy' and 'ring' are not covered by this specification. 🌍
As stated previously, a single <configure_leg> request MAY contain multiple <signal> elements that request notification of different call progress tones. A single <configure_leg> request SHOULD NOT contain multiple <signal> elements that have the same 'type' attribute value. If the media server receives such a request, it SHOULD honor the last element specifying that type that appears in the request 💜
The media server sends an immediate response to the <configure_leg> subscription request, and sends notifications when the specified signals are detected. A single notification is sent as soon as the specified signal has been reliably detected. If the signal persists continuously, no additional notifications get sent. If the signal is interrupted and then resumes, additional notifications will be sent 😭
Signal notifications have a single attribute, "type", as described in the list below.
Signal Notification Attribute:
- type - required, no default value: Specifies the type of call progress signal that was detected. Possible values are 'busy', 'ring', 'CED', 'CNG', and '400', which correspond to busy tone, ring tone, fax CED, fax CNG, and 400 Hz tone, respectively 🍓
7.2.1. Signal Event Examples 🦋
These MSCML payloads show a signal event subscription (Figure 25) and a notification (Figure 26).
<?xml version="1.0"?>
<MediaServerControl version="1.0">
<request>
<configure_leg>
<subscribe>
<events>
<signal type="busy" report="yes"/>
</events>
</subscribe>
</configure_leg>
</request>
</MediaServerControl>Figure 25: Signal Event Subscription
<?xml version="1.0"?>
<MediaServerControl version="1.0">
<notification>
<signal type="busy"/>
</notification>
</MediaServerControl>Figure 26: Signal Event Notification
8. Managing Content <managecontent> ✨
okay so <managecontent> is how MSCML moves recorded stuff from the media server out to remote places over HTTP 📦 it's a store-and-forward vibe, which means the recording has to finish saving locally before the media server can ship it to the web server 🚚 this is super useful for things like voice messaging, where the caller gets to listen back to their message before it's officially saved for good 🎧 iconic, honestly.
The <managecontent> request has no child elements, just the attributes below 💅
Managecontent Attributes:
src- required, no default value: the local source URL of the content 📍 The URL scheme MUST befile://.dest- required (see note), no default value: the destination URL 🎯 The URL scheme MUST behttp://.- Note: if the action is
delete, this attribute is optional. Otherwise it's required.
- Note: if the action is
action- optional, default valuemove: the operation the media server runs 🔄 The values can bemoveordelete.deleteoperates on the local source file. After a successful move or delete, the media server removes the source file from its local storage. If the request is unsuccessful, the source file is not deleted, which gives the client complete control of the retry strategy 🔁httpmethod- optional, default valuepost: the HTTP method the media server uses in the HTTP request 🌐 The only values arepostorput.name- required (see note), no default value: the field name for the content in the form when using thepostmethod 📝 This is not to be confused withsrcordest, they're totally different things.- Note: this attribute is required when
htttpmethodhas the valuepost, and optional otherwise.
- Note: this attribute is required when
fetchtimeout- optional, default value10000ms: the maximum time allowed for the transfer to complete ⏱️ It's expressed as a time value (Section 4.2.1) from 1ms onwards.mimetype- required (see note), no default value: the MIME type the media server uses for the content transfer 🎀 If it isn't provided, the media server MUST try to infer it from the content file extension, based on a platform-specific mapping table. A non-normative, example mapping table is shown in Table 3. To avoid ambiguity, we RECOMMEND that clients explicitly set this attribute 💖- Note: if the MIME type can't be inferred from the file extension, this attribute is required.
Table 3 shows common audio and video MIME types and possible file extension mappings 🧚
+-----------+--------------------+
| Extension | MIME Type |
+-----------+--------------------+
| alaw | audio/x-alaw-basic |
| ulaw | audio/basic |
| msgsm | audio/ms-gsm |
| wav | audio/x-wav |
| tif | image/tiff |
| tiff | image/tiff |
| mov | video/quicktime |
| qt | video/quicktime |
| 3gp | video/3gpp |
| 3gpp | video/3gpp |
+-----------+--------------------+
Table 3: Example File Extension to MIME Type Mappings<Managecontent> is purely a transport operation, so the underlying content is not changed by it 🚨 Therefore clients MUST ensure that the source and destination file name extensions and MIME types are the same. Failure to do so could result in content that is unreadable 😭The ability to move or delete any local file presents a potential risk to the security of the media server system 💀 For this reason, we STRONGLY RECOMMEND that implementers limit local file system access when using <managecontent> 🔒 For example, we encourage limiting access based on file ownership and/or specific directories 🏰
8.1. Managecontent Example ✨
The following is an example (Figure 27) showing a local file on the media server being transferred to an HTTP URL using the "put" method 🎬 The client sends the following request.
<?xml version="1.0"?>
<MediaServerControl version="1.0">
<request>
<managecontent id="102"
src="file:////var/mediaserver/rec/6A5GH49B.ulaw"
dest="http://www.example.com/recordings/myrecording.ulaw"
mimetype="audio/basic" action="move" httpmethod="put"
fetchtimeout="5000"/>
</request>
</MediaServerControl>Figure 27: Managecontent Example
Note that the client can change the temporary file name assigned by the media server as part of this operation, as shown 🦋
If the request is ambiguous, the media server MUST return a status code of "400" and text "Bad Request." 🙈 If the media server is unable to execute a syntactically correct and unambiguous request, it MUST return a "500" status code with the text "Server Error." For example, the local file system access restrictions may prevent deletion of the specified file. In this case, the "reason" attribute in the response conveys additional details on the server error that occurred 🧐 If there is a network or remote server error, the media server provides detailed error information in the <error_info> element contained in the media server response. Additional information regarding <managecontent> responses is provided in Section 10.7 📚
9. Fax Processing 📠✨
9.1. Recording a Fax <faxrecord>
The <faxrecord> request directs the media server to process a fax in answer mode 📞 The reason it's separate from <playrecord> is that the media server needs to know to process the T.30 [18] or T.38 [19] fax protocols 🧠
The <faxrecord> request has multiple attributes and one child element, <prompt> 💖 Its attributes are described in the list below.
Attributes of <faxrecord>:
lclid- optional, default value""(the empty string): a string that identifies the called station 📱prompturl- optional, no default value: the URL of the fax content to be retrieved and played 🎞️ The target may be a local or remote (NFS)file://scheme URL, or anhttp://orhttps://scheme URL. NOTE: Use of this attribute is deprecated 🥀promptencoding- optional, no default value: specifies the content encoding for files that do not have atifortiffextension 🔤 The only allowable value istiff. This attribute only affectsfile://scheme URLs. NOTE: Use of this attribute is deprecated 🥀recurl- optional, no default value: specifies the target URL for the recorded content 🎯rmtid- optional, no default value: specifies the calling station identifier of the remote terminal 📇 If present, the media server MUST reject transactions with the remote terminal if the remote terminal's identifier does not match the value ofrmtid🚫
Clients SHOULD use the more flexible <prompt> mechanism for specifying fax content 💅 Use of the prompturl attribute is deprecated and may not be supported in future MSCML versions. The <prompt> element is described in Section 6.1.1. A <prompt> element sent in a <faxrecord> request MUST NOT contain <variable> elements 🙅♀️
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 🔁
The <faxrecord> request operates in one of three modes: receive, poll, and turnaround poll 🌈 The combination of the <prompt> or prompturl attribute and the recurl attribute defines the mode. Table 4 describes these modes in detail. The prompt column in the table has the value yes if the request has either a <prompt> element or a prompturl attribute 📊
+--------+--------+---------+---------------------------------------+
| prompt | recurl | Mode | Operation |
+--------+--------+---------+---------------------------------------+
| no | no | Invalid | Request fails. |
| no | yes | Receive | Record the fax to the target URL |
| | | | specified in 'recurl'. |
| yes | no | Poll | Send fax from source specified in the |
| | | | <prompt> element or 'prompturl' |
| | | | attribute. If there is a 'rmtid', it |
| | | | MUST match the remote terminal's |
| | | | identifier, or the request will fail. |
| yes | yes | TP | Turnaround Poll (TP) mode. If the |
| | | | remote terminal wishes to transmit, |
| | | | the media server records the fax to |
| | | | the target URL specified in 'recurl'. |
| | | | If the remote terminal wishes to |
| | | | receive, the media server sends the |
| | | | fax from the source URL contained in |
| | | | <prompt> or 'prompturl'. If there is |
| | | | a 'rmtid', it MUST match remote |
| | | | terminal's identifier, or the send |
| | | | request will fail. A receive |
| | | | operation will still succeed, |
| | | | however. |
+--------+--------+---------+---------------------------------------+
Table 4: Fax Receive ModesIn receive mode, the media server receives the fax and writes the fax data to the target URL specified by the recurl attribute 📥
In poll mode, the media server sends a fax, but as a polled (called) device 📤
In turnaround poll mode, the media server will record a fax that the remote machine sends. If the remote machine requests a transmission, then the media server will send the fax 🔄✨
When transmitting a fax, the media server will advertise that it can receive faxes in the DIS message. Likewise, when receiving a fax, the media server will advertise that it can send faxes in the DIS message 📣
The media server MUST flush any quarantined digits when it receives a <faxrecord> request 🧹
9.2. Sending a Fax <faxplay> 📠✨
okay so the <faxplay> request tells the media server to handle a fax in originate mode 📠 and you might be like, "wait, why not just use <play>??" bestie, the answer is that the media server has to know it's dealing with the T.30 [18] or T.38 [19] fax protocols, and <play> just doesn't say that 💅
<faxplay> has a bunch of attributes and one child element, <prompt>. Here's the attribute rundown 🎀
Attributes of <faxplay>:
lclid- optional, default value "" (the empty string): A string that identifies the called station. 📞prompturl- optional, no default value: The URL of the content that gets fetched and played. It can be a local or remote (NFS)file://scheme URL, or anhttp://orhttps://scheme URL. NOTE: Use of this attribute is deprecated. 🙅♀️promptencoding- optional, no default value: Sets the content encoding for files that don't have a 'tif' or 'tiff' extension. The only allowed value is 'tiff'. This only affectsfile://scheme URLs. NOTE: Use of this attribute is deprecated. 🙅♀️recurl- optional, no default value: The target URL where the recorded content gets saved 💾rmtid- optional, no default value: The calling station identifier of the remote terminal 🪪 If it's there, the media server MUST reject transactions with the remote terminal whenever the remote terminal's identifier doesn't match the value of 'rmtid'. 🚫
Clients SHOULD use the more flexible <prompt> mechanism for specifying fax content, bc it's giving flexibility 🫶 The prompturl attribute is deprecated and might not be supported in future MSCML versions, so don't get too attached to it 😭 The <prompt> element is described in Section 6.1.1. And a <prompt> element sent in a <faxrecord> request MUST NOT contain <variable> elements. no exceptions, periodt 🙅♀️
Media servers MUST support local and remote (NFS) file:// scheme URLs in the recurl attribute. MSCML handles http:// and https:// scheme URLs indirectly, through the <managecontent> (Section 8) request 🌈
The <faxplay> request works in one of three modes: send, remote poll, and turnaround poll 🦋 The mode comes from whether you've got a <prompt> (or prompturl) and/or a recurl attribute. Table 5 breaks it all down. In the table's 'prompt' column, you'll see 'yes' whenever the request has either a <prompt> element or a prompturl attribute.
+--------+--------+---------+---------------------------------------+
| prompt | recurl | Mode | Operation |
+--------+--------+---------+---------------------------------------+
| no | no | Invalid | Request fails. |
| yes | no | Send | Send fax from source specified in the |
| | | | <prompt> element or 'prompturl' |
| | | | attribute. If there is a 'rmtid', it |
| | | | MUST match the remote terminal's |
| | | | identifier, or the request will fail. |
| no | yes | Poll | Send fax from source specified in the |
| | | | <prompt> element or 'prompturl' |
| | | | attribute, assuming the remote |
| | | | terminal specifies it can receive a |
| | | | fax in its DIS message. If the remote |
| | | | terminal does not support reverse |
| | | | polling, the request will fail. If |
| | | | 'rmtid' is specified, it MUST match |
| | | | remote terminal's identifier, or the |
| | | | request will fail. |
| yes | yes | TP | Turnaround Poll (TP) mode. If the |
| | | | remote terminal wishes to transmit, |
| | | | the media server records the fax to |
| | | | the target URL specified in 'recurl'. |
| | | | If the remote terminal wishes to |
| | | | receive, the media server sends the |
| | | | fax from the source URL contained in |
| | | | <prompt> or 'prompturl'. If there is |
| | | | a 'rmtid', it MUST match remote |
| | | | terminal's identifier, or the send |
| | | | request will fail. A receive |
| | | | operation will still succeed, |
| | | | however. |
+--------+--------+---------+---------------------------------------+
Table 5: Fax Send ModesIn send mode, the media server sends the fax 📤
In remote poll mode, the client places a call on behalf of the media server. The media server then asks the remote fax terminal to send it a fax 📞
In turnaround poll mode, the media server records a fax that the remote machine sends. And if the remote machine asks for a transmission, the media server sends the fax back. ping-pong, but make it fax 🏓
When the media server is transmitting a fax, it advertises that it can receive faxes in the DIS message. And when it's receiving a fax, it advertises that it can send faxes in the DIS message. it's all about being honest about what you can do 💅✨
The media server MUST flush any quarantined digits when it receives a <faxplay> request. 🧹
10. MSCML Response Attributes and Elements 💌
10.1. Mechanism
The media server acknowledges receipt of a client MSCML request sent in a SIP INVITE by replying with either 200 OK or 415 Bad Media Type. It sends back a 415 whenever the SIP request has a content type other than "application/sdp" or "application/mediaservercontrol+xml". 🙅♀️
The media server also acknowledges an MSCML request sent in a SIP INFO with a 200 OK or 415 Bad Media Type. A 415 goes out if the INFO request's content type isn't "application/mediaservercontrol+xml". 📨
The media server sends the MSCML <response> message back inside a SIP INFO request 🦋
If there's an error in the request, or the media server can't complete it, the media server sends the <response> message really quickly after getting the request ⚡ If the request can go ahead, the <response> carries the final status info, which is described below.
10.2. Base <response> Attributes
Every MSCML response has the basic attributes listed below 🎀
Basic MSCML Response Attributes:
id- optional, no default value: Echoes the client-defined ID that was in the request.request- required, no default value: The MSCML request type that produced the response. The allowed values are "configure_conference", "configure_leg", "play", "playcollect", "playrecord", "stop", "faxplay", "faxrecord", and "managecontent".code- required, no default value: The final status code for the request. MSCML uses a subset of the status classes defined in RFC 3261 [4]. In MSCML, 2XX responses mean success, 4XX responses mean client error, and 5XX responses mean the media server ran into an error. There are no 1XX, 3XX, or 6XX status codes in MSCML. 🔢text- required, no default value: The human-readable reason phrase that goes with the status code.
Responses to <configure_conference> and <stop> requests only have the attributes above. MSCML responses to other requests MAY contain additional request-specific attributes and elements. These are covered in the following sections 👀
10.3. Response Attributes and Elements for <configure_leg>
Responses to <configure_leg> requests only have the base response attributes from Section 10.2. BUT if the request contains a <configure_team> element, the response includes a <team> element that describes the teammate setup for that leg 🧑🤝🧑 The attributes of the <team> element are listed below.
Attributes of <team>:
id- required, no default value: The client-defined unique identifier for the conference leg.numteam- required, no default value: The number of team members for the leg.
Extra info on each team member comes in child <teammate> elements inside <team>. Each teammate gets its own single element in the list. The <teammate> element has just one attribute, which is described below.
Attributes of <teammate>:
id- required, no default value: The client-defined unique identifier for the teammate leg.
10.4. Response Attributes and Elements for <play>
On top of the base response attributes from Section 10.2, responses to <play> requests have the extra attributes listed below ✨
MSCML Response Attributes for <play>:
reason- optional, no default value: For requests that don't finish right away, the "reason" attribute explains why the command was finished. The possible values are "stopped", which means an explicit or implicit<stop>request came in, and "EOF", which means the end of the specified sequence of URLs was reached. 🛑playduration- required, no default value: A time value (Section 4.2.1) that returns how long the associated content played out for ⏱️playoffset- required, no default value: A time value (Section 4.2.1) that returns the time offset into the specified content sequence where play stopped. If the initial "offset" value in the sequence was "0", then "playduration" and "playoffset" are equal. But if the initial offset had some other value, "playoffset" acts as a bookmark so the client can pick up where it left off in a later request 🔖
10.4.1. Reporting Content Retrieval Errors
If the related request set "stoponerror=yes" in <prompt> and something went wrong while retrieving the specified content, the response will include an <error_info> element that details the problem 🚨 This element holds the response info that came back from the remote content server. The <error_info> element has the attributes listed below.
Attributes of <error_info>:
code- required, no default value: The status code the remote content server returned. For example, a web server might return 404 to say the requested content wasn't found 🙈text- required, no default value: The human-readable reason phrase the remote content server returned. For example, "Not Found" would come back if the requested content wasn't found.context- required, no default value: The content URL that was being fetched when the retrieval error happened. This lets the client see exactly which URL in a sequence caused the problem 🕵️♀️
An <error_info> element MAY be present in the response to any request that has a child <prompt> element. 💖
10.5. Response Attributes and Elements for <playcollect> 💖
Okay bestie, on top of the base response attributes from Section 10.2, responses to <playcollect> requests get some extra attributes too 🎀 Here's the list 💅
reason- optional, no default value: For requests that don't finish right away, thereasonattribute tells you why the command wrapped up 🦋 The possible values are"stopped"(an explicit or implicit<stop>request came in),"match"(a DTMF grammar got matched),"timeout"(no DTMF input showed up before one of the collection timers ran out), and"returnkey"or"escapekey"(the DTMF digit mapped to that key was detected, and the return key or escape key ended the operation, respectively) 🔥playduration- required, no default value: A time value (Section 4.2.1) that returns how long the associated content played 🎶 If the caller barged the prompt, this value reflects the play duration up to that moment ✨playoffset- required, no default value: A time value (Section 4.2.1) that returns the time offset into the specified content sequence where play stopped 🌸 If the initial"offset"value in the sequence was"0", thenplaydurationandplayoffsetare equal 👑 But if the initial offset had some other value,playoffsetacts like a bookmark so the client can pick up where it left off in a later request 🔖 If the caller barged the prompt, this value shows the time offset where the barge-in happened 💀digits- required, no default value: Holds the collected DTMF input characters 🍓 If no DTMF input got collected, this attribute is set to the empty string ("") 🙈name- required (see note), no default value: The client-defined name of the DTMF grammar that got matched 💜 Note: this attribute is required if the"name"attribute was set in the matching DTMF grammar 🫶
Responses to <playcollect> requests MAY include an <error_info> element, as described in Section 10.4.1 🧚
10.6. Response Attributes and Elements for <playrecord> 🌈
Same deal here: on top of the base response attributes from Section 10.2, responses to <playrecord> requests get the extra attributes in this list 💖
reason- optional, no default value: For requests that don't finish right away, thereasonattribute explains why the command wrapped up ✨ The possible values are"stopped"(an explicit or implicit<stop>request came in),"digit"(a DTMF digit was detected, so the prompt phase got barged) 🎀,"init_silence"(the recording ended because there was no input) 🙈,"end_silence"(the recording ended because the"endsilence"timer elapsed) ⭐,"max_duration"(the maximum recording time got reached) ⏰,"escapekey"(DTMF input mapped to"escapekey"got detected, which ended the recording) 💅, and"error"(a general operation failure) 💀playduration- required, no default value: A time value (Section 4.2.1) that returns how long the associated content played 🎶 If the caller barged the prompt, this value reflects the play duration up to that event 🦋playoffset- required, no default value: A time value (Section 4.2.1) that returns the time offset into the specified content sequence where play stopped 🌸 If the initial"offset"value in the sequence was"0", thenplaydurationandplayoffsetare equal 👑 If the initial offset had some other value,playoffsetworks as a bookmark for the client to resume play in a later request 🔖 If the caller barged the prompt, this value reflects the time offset where barge-in occurred 😭digits- required, no default value: Contains the DTMF digit that ended the recording 🍓 If no DTMF input got detected, this attribute is set to the empty string ("") 🙈reclength- required, no default value: The length of the recorded content, in bytes 📦recduration- required, no default value: A time value (Section 4.2.1) that shows the elapsed duration of the recording ⏱️
Responses to <playrecord> requests MAY include an <error_info> element, as described in Section 10.4.1 🧚
10.7. Response Attributes and Elements for <managecontent> 🍓
Responses to <managecontent> requests only have the base response attributes from Section 10.2, so no extras this time 💅 If a content transfer error happens while the request runs, the response also contains an <error_info> element, as described in Section 10.4.1 🚨
10.8. Response Attributes and Elements for <faxplay> and <faxrecord> 📠
On top of the base response attributes from Section 10.2, responses to <faxplay> and <faxrecord> requests get the extra attributes below 🦋
reason- required, no default value: For requests that don't finish right away, thereasonattribute tells you why the command wrapped up 🎀 The possible values are"stopped"(an explicit or implicit<stop>request came in),"complete"(successful completion, even if there were bad lines or minor negotiation problems, like when a DCN was received) ✅,"disconnect"(the session got disconnected) 📵, and"notfax"(no DIS or DCS was received on the connection) 🙅♀️pages_received- required (see note), no default value: The number of fax pages received 📄 Note: this attribute is required if any pages were received 💜pages_sent- required (see note), no default value: The number of fax pages sent 📨 Note: this attribute is required if any pages were sent 🫶faxcode- required, no default value: The value of thefaxcodeattribute is the binary-or of the bit patterns defined in Table 6 🌈 Here's the whole table, slay 💅
+------+--------------------------------------+
| Mask | description |
+------+--------------------------------------+
| 0 | Operation Failed |
| 1 | Operation Succeeded |
| 2 | Partial Success |
| 4 | Image received and placed in recurl |
| 8 | Image sent from specified source URL |
| 16 | rmtid did not match |
| 32 | Error reading source URL |
| 64 | Error writing recurl |
| 128 | Negotiation failure on send phase |
| 256 | Negotiation failure on receive phase |
| 512 | Reserved |
| 1024 | Irrecoverable IP packet loss |
| 2048 | Line errors in received image |
+------+--------------------------------------+
Table 6: Faxcode MaskResponses to <faxplay> and <faxrecord> requests MAY include an <error_info> element, as described in Section 10.4.1 🧚
11. Formal Syntax ✨
The following syntax specification uses XML Schema as described in XML [7] 🎀 Let's get into it, bestie 💖
11.1. Schema 🧚
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified">
<xs:element name="MediaServerControl">
<xs:complexType>
<xs:choice>
<xs:element name="request">
<xs:complexType>
<xs:choice>
<xs:element name="configure_conference"
type="configure_conferenceRequestType"/>
<xs:element name="configure_leg"
type="configure_legRequestType"/>
<xs:element name="play" type="playRequestType"/>
<xs:element name="playcollect"
type="playcollectRequestType"/>
<xs:element name="playrecord"
type="playrecordRequestType"/>
<xs:element name="managecontent"
type="managecontentRequestType"/>
<xs:element name="faxplay"
type="faxRequestType"/>
<xs:element name="faxrecord"
type="faxRequestType"/>
<xs:element name="stop" type="stopRequestType"/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name="response" type="responseType"/>
<xs:element name="notification">
<xs:complexType>
<xs:choice>
<xs:element name="conference"
type="conferenceNotificationType"/>
<xs:element name="keypress"
type="keypressNotificationType"/>
<xs:element name="signal"
type="signalNotificationType"/>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:choice>
<xs:attribute name="version" use="required"/>
</xs:complexType>
</xs:element>
<!-- Definitions for base and concrete MSCML requests -->
<!-- and embedded types. -->
<xs:complexType name="base_requestType" abstract="true">
<xs:attribute name="id" type="xs:string"/>
</xs:complexType>
<xs:complexType name="playRequestType">
<xs:complexContent>
<xs:extension base="base_requestType">
<xs:sequence>
<xs:element name="prompt" type="promptType"
minOccurs="0"/>
</xs:sequence>
<xs:attribute name="prompturl" type="xs:string"/>
<xs:attribute name="offset" type="xs:string"/>
<xs:attribute name="promptencoding" type="xs:string"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="configure_conferenceRequestType">
<xs:complexContent>
<xs:extension base="base_requestType">Okay bestie, the schema keeps going and it's still giving structure 🧚✨
<xs:sequence>
<xs:element name="subscribe"
type="conference_eventsubscriptionType" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="reservedtalkers"
type="xs:positiveInteger"/>
<xs:attribute name="reserveconfmedia" type="yesnoType"
default="yes"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="configure_legRequestType">
<xs:complexContent>
<xs:extension base="base_requestType">
<xs:sequence>
<xs:element name="inputgain" type="gainType"
minOccurs="0"/>
<xs:element name="outputgain" type="gainType"
minOccurs="0"/>
<xs:element name="configure_team"
type="configure_teamType" minOccurs="0"/>
<xs:element name="subscribe"
type="leg_eventsubscriptionType" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="type">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="talker"/>
<xs:enumeration value="listener"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="mixmode">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="full"/>
<xs:enumeration value="mute"/>
<xs:enumeration value="preferred"/>
<xs:enumeration value="parked"/>
<xs:enumeration value="private"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="dtmfclamp" type="yesnoType"/>
<xs:attribute name="toneclamp" type="yesnoType"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="configure_teamType">
<xs:sequence>
<xs:element name="teammate" type="teammateType" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="id" type="xs:string"/>
<xs:attribute name="action" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="add"/>
<xs:enumeration value="delete"/>
<xs:enumeration value="query"/>
<xs:enumeration value="set"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
<xs:complexType name="teammateType">
<xs:attribute name="id" type="xs:string" use="required"/>
</xs:complexType>
<xs:complexType name="playcollectRequestType">
<xs:complexContent>
<xs:extension base="base_requestType">
<xs:sequence>
<xs:element name="prompt" type="promptType"
minOccurs="0"/>
<xs:element name="pattern" type="dtmfGrammarType"
minOccurs="0"/>
</xs:sequence>
<xs:attribute name="prompturl" type="xs:string"/>
<xs:attribute name="offset" type="xs:string"/>
<xs:attribute name="barge" type="yesnoType" default="yes"/>
<xs:attribute name="promptencoding" type="xs:string"/>
<xs:attribute name="cleardigits" type="yesnoType"
default="no"/>
<xs:attribute name="maxdigits" type="xs:string"/>
<xs:attribute name="firstdigittimer" type="xs:string"
default="5000ms"/>
<xs:attribute name="interdigittimer" type="xs:string"
default="2000ms"/>
<xs:attribute name="extradigittimer" type="xs:string"
default="1000ms"/>
<xs:attribute name="interdigitcriticaltimer"
type="xs:string"/>
<xs:attribute name="skipinterval" type="xs:string"
default="6s"/>
<xs:attribute name="ffkey" type="DTMFkeyType"/>
<xs:attribute name="rwkey" type="DTMFkeyType"/>
<xs:attribute name="returnkey" type="DTMFkeyType"
default="#"/>
<xs:attribute name="escapekey" type="DTMFkeyType"
default="*"/>
<xs:attribute name="maskdigits" type="yesnoType"
default="no"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="playrecordRequestType">
<xs:complexContent>
<xs:extension base="base_requestType">
<xs:sequence>
<xs:element name="prompt" type="promptType"
minOccurs="0"/>
</xs:sequence>
<xs:attribute name="prompturl" type="xs:string"/>
<xs:attribute name="promptencoding" type="xs:string"/>
<xs:attribute name="offset" type="xs:string" default="0"/>
<xs:attribute name="barge" type="yesnoType" default="yes"/>
<xs:attribute name="cleardigits" type="yesnoType"
default="no"/>
<xs:attribute name="escapekey" type="xs:string" default="*"/>
<xs:attribute name="recurl" type="xs:string" use="required"/>
<xs:attribute name="mode" default="overwrite">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="append"/>
<xs:enumeration value="overwrite"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="recencoding" type="xs:string"/>
<xs:attribute name="initsilence" type="xs:string"/>
<xs:attribute name="endsilence" type="xs:string"/>
<xs:attribute name="duration" type="xs:string"/>
<xs:attribute name="beep" type="yesnoType" default="yes"/>
<xs:attribute name="recstopmask" type="xs:string"
default="01234567890*#"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="managecontentRequestType">
<xs:complexContent>
<xs:extension base="base_requestType">
<xs:attribute name="fetchtimeout" type="xs:string"
default="10000"/>
<xs:attribute name="mimetype" type="xs:string"/>
<xs:attribute name="name" type="xs:string"/>
<xs:attribute name="httpmethod">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="put"/>
<xs:enumeration value="post"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="action">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="move"/>
<xs:enumeration value="delete"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="dest" type="xs:string"/>
<xs:attribute name="src" type="xs:string" use="required"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="stopRequestType">
<xs:complexContent>
<xs:extension base="base_requestType"/>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="faxRequestType">
<xs:complexContent>
<xs:extension base="base_requestType">
<xs:sequence>
<xs:element name="prompt" type="promptType" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="lclid" type="xs:string"/>
<xs:attribute name="prompturl" type="xs:string"/>
<xs:attribute name="recurl" type="xs:string"/>
<xs:attribute name="rmtid" type="xs:string"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="dtmfGrammarType">
<xs:choice>
<xs:element name="regex" type="dtmfPatternType"
maxOccurs="unbounded"/>
<xs:element name="mgcpdigitmap" type="dtmfPatternType"/>
<xs:element name="megacodigitmap" type="dtmfPatternType"/>
</xs:choice>
</xs:complexType>
<xs:complexType name="dtmfPatternType">
<xs:attribute name="value" type="xs:string" use="required"/>
<xs:attribute name="name" type="xs:string"/>
</xs:complexType>
<!-- Definitions for base and concrete MSCML responses -->
<!-- and embedded types. -->
<xs:complexType name="base_responseType" abstract="true">
<xs:attribute name="request" use="required">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="configure_conference"/>
<xs:enumeration value="configure_leg"/>
<xs:enumeration value="play"/>
<xs:enumeration value="playcollect"/>
<xs:enumeration value="playrecord"/>
<xs:enumeration value="managecontent"/>
<xs:enumeration value="faxplay"/>
<xs:enumeration value="faxrecord"/>
<xs:enumeration value="stop"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="id" type="xs:string"/>
<xs:attribute name="code" type="xs:string" use="required"/>
<xs:attribute name="text" type="xs:string" use="required"/>
</xs:complexType>
<xs:complexType name="responseType">
<xs:complexContent>
<xs:extension base="base_responseType">
<xs:sequence>
<xs:element name="error_info"
type="stoponerrorResponseType" minOccurs="0"/>
<xs:element name="team" type="configure_teamResponseType"
minOccurs="0"/>
</xs:sequence>
<xs:attribute name="reason" type="xs:string"/>
<xs:attribute name="reclength" type="xs:string"/>
<xs:attribute name="recduration" type="xs:string"/>
<xs:attribute name="digits" type="xs:string"/>
<xs:attribute name="name" type="xs:string"/>
<xs:attribute name="playduration" type="xs:string"/>
<xs:attribute name="playoffset" type="xs:string"/>
<xs:attribute name="faxcode" type="xs:string"/>
<xs:attribute name="pages_sent" type="xs:string"/>
<xs:attribute name="pages_recv" type="xs:string"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="stoponerrorResponseType">
<xs:attribute name="code" type="xs:string" use="required"/>
<xs:attribute name="text" type="xs:string" use="required"/>
<xs:attribute name="context" type="xs:string" use="required"/>
</xs:complexType>
<xs:complexType name="configure_teamResponseType">
<xs:sequence>
<xs:element name="teammate" type="teammateType" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="id" type="xs:string" use="required"/>
<xs:attribute name="numteam" type="xs:integer" use="required"/>
</xs:complexType>
<!-- Definitions for MSCML event subscriptions and -->
<!-- embedded types -->
<xs:complexType name="conference_eventsubscriptionType">
<xs:sequence>
<xs:element name="events">
<xs:complexType>
<xs:sequence>
<xs:element name="activetalkers"
type="activetalkersSubscriptionType"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="activetalkersSubscriptionType">
<xs:attribute name="report" type="yesnoType" use="required"/>
<xs:attribute name="interval" type="xs:string" default="60s"/>
</xs:complexType>
<xs:complexType name="leg_eventsubscriptionType">
<xs:sequence>
<xs:element name="events">
<xs:complexType>okay so the schema is still going, and it's giving complex 💅
<xs:sequence>
<xs:element name="keypress"
type="keypressSubscriptionType" minOccurs="0"
maxOccurs="1"/>
<xs:element name="signal" type="signalSubscriptionType"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="keypressSubscriptionType">
<xs:attribute name="report" use="required">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="standard"/>
<xs:enumeration value="long"/>
<xs:enumeration value="both"/>
<xs:enumeration value="none"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="maskdigits" type="yesnoType" default="no"/>
</xs:complexType>
<xs:complexType name="signalSubscriptionType">
<xs:attribute name="type" type="xs:NMTOKEN" use="required"/>
<xs:attribute name="report" type="yesnoType" use="required"/>
</xs:complexType>
<!-- Definitions for MSCML event notifications and -->
<!-- embedded types. -->
<xs:complexType name="conferenceNotificationType">
<xs:sequence>
<xs:element name="activetalkers"
type="activetalkersNotificationType" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="uniqueid" type="xs:string" use="required"/>
<xs:attribute name="numtalkers" type="xs:string"
use="required"/>
</xs:complexType>
<xs:complexType name="activetalkersNotificationType">
<xs:sequence minOccurs="0">
<xs:element name="talker" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="callid" type="xs:string"
use="required"/>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="keypressNotificationType">
<xs:sequence>
<xs:element name="status" type="statusType"/>
</xs:sequence>
<xs:attribute name="digit" type="DTMFkeyType" use="required"/>
<xs:attribute name="length" use="required">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="standard"/>
<xs:enumeration value="long"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="method" use="required">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="standard"/>
<xs:enumeration value="long"/>
<xs:enumeration value="double"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="interdigittime" type="xs:string"
use="required"/>
</xs:complexType>
<xs:complexType name="statusType">
<xs:attribute name="command" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="idle"/>
<xs:enumeration value="play"/>
<xs:enumeration value="collect"/>
<xs:enumeration value="record"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="duration" type="xs:string" use="required"/>
</xs:complexType>
<xs:complexType name="signalNotificationType">
<xs:attribute name="type" use="required" fixed="busy"/>
</xs:complexType>
<!-- Definitions for miscellaneous embedded, helper data types -->
<xs:complexType name="promptType">
<xs:choice maxOccurs="unbounded">
<xs:element name="audio" type="promptcontentType"/>
<xs:element name="variable" type="spokenvariableType"/>
</xs:choice>
<xs:attribute name="locale" type="xs:string"/>
<xs:attribute name="baseurl" type="xs:string"/>
<xs:attribute name="stoponerror" type="yesnoType" default="no"/>
<xs:attribute name="gain" type="xs:string" default="0"/>
<xs:attribute name="gaindelta" type="xs:string" default="0"/>
<xs:attribute name="rate" type="xs:string" default="0"/>
<xs:attribute name="ratedelta" type="xs:string" default="0"/>
<xs:attribute name="repeat" type="xs:string" default="1"/>
<xs:attribute name="duration" type="xs:string"
default="infinite"/>
<xs:attribute name="offset" type="xs:string" default="0"/>
<xs:attribute name="delay" type="xs:string" default="0"/>
</xs:complexType>
<xs:complexType name="promptcontentType">
<xs:attribute name="url" type="xs:string" use="required"/>
<xs:attribute name="encoding" type="xs:string"/>
<xs:attribute name="gain" type="xs:string" default="0"/>
<xs:attribute name="gaindelta" type="xs:string" default="0"/>
<xs:attribute name="rate" type="xs:string" default="0"/>
<xs:attribute name="ratedelta" type="xs:string" default="0"/>
</xs:complexType>
<xs:complexType name="spokenvariableType">
<xs:attribute name="type" use="required">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="dat"/>
<xs:enumeration value="dig"/>
<xs:enumeration value="dur"/>
<xs:enumeration value="mth"/>
<xs:enumeration value="mny"/>
<xs:enumeration value="num"/>
<xs:enumeration value="sil"/>
<xs:enumeration value="str"/>
<xs:enumeration value="tme"/>
<xs:enumeration value="wkd"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="subtype">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="mdy"/>
<xs:enumeration value="dmy"/>
<xs:enumeration value="ymd"/>
<xs:enumeration value="ndn"/>
<xs:enumeration value="t12"/>
<xs:enumeration value="t24"/>
<xs:enumeration value="USD"/>
<xs:enumeration value="gen"/>
<xs:enumeration value="ndn"/>
<xs:enumeration value="crd"/>
<xs:enumeration value="ord"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="value" type="xs:string" use="required"/>
</xs:complexType>
<xs:simpleType name="yesnoType">
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="yes"/>
<xs:enumeration value="no"/>
<xs:enumeration value="1"/>
<xs:enumeration value="0"/>
<xs:enumeration value="true"/>
<xs:enumeration value="false"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="DTMFkeyType">
<xs:restriction base="xs:string">
<xs:pattern value="[0-9]"/>
<xs:pattern value="[A-D]"/>
<xs:pattern value="[a-d]"/>
<xs:pattern value="#"/>
<xs:pattern value="\*"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="gainType">
<xs:choice>
<xs:element name="auto" type="autogainType"/>
<xs:element name="fixed" type="fixedgainType"/>
</xs:choice>
</xs:complexType>
<xs:complexType name="autogainType">
<xs:attribute name="startlevel" type="xs:string"/>
<xs:attribute name="targetlevel" type="xs:string"/>
<xs:attribute name="silencethreshold" type="xs:string"/>
</xs:complexType>
<xs:complexType name="fixedgainType">
<xs:attribute name="level" type="xs:string"/>
</xs:complexType>
</xs:schema>12. IANA Considerations ✨
12.1. IANA Registration of MIME Media Type application/mediaservercontrol+xml 💖
here's the registration form for the new media type, bestie 🎀
MIME media type name: application
MIME subtype name: mediaservercontrol+xml
Required parameters: none
Optional parameters: charset
charset This parameter has identical semantics to the charset
parameter of the "application/xml" media type, as specified in
XML Media Types [8].
Encoding considerations: See RFC 3023 [8].
Interoperability considerations: See RFC 2023 [8] and RFC 4722.
Published specification: RFC 4722
Applications that use this media type: Multimedia, enhanced
conferencing and interactive applications.
Personal and email address for further
information: eburger@cantata.com [31]
Intended usage: COMMON13. Security Considerations 🔐
okay bestie, this section is SERIOUS 😭 because media flows through a media server during a conference, so the media server itself MUST protect the integrity, confidentiality, and security of the sessions 🛡️. it should not be possible for a conference participant, acting on her own behalf, to "tap in" to another conference without proper authorization 🚫.
conferencing is a high-value app, so the media server SHOULD implement appropriate security measures 💎. that includes, but isn't limited to, access lists for application servers. so the media server only lets a select list of application or proxy servers create conferences, invite participants to sessions, and so on 🎀. the mechanisms for this, like private networks, shared certificates, and MAC white/black lists, are out of scope for this doc 🙈.
security is one big reason MSCML limits conference-scope requests to a separate control leg per conference 🦋. MSCML uses the simple, proven, Internet-scale security model of SIP to figure out if a client is who they say they are (authentication) and whether they're allowed to create and manipulate a conference 💅. BUT a security model that lets one control leg manipulate any conference on the media server is extremely difficult, ngl 😭. you'd need to authenticate and authorize the basic conference primitives, and privacy concerns also require policies for one client to access another client's conferences, even if both clients are on the same host 🧚. for example, if the media server let any control leg control any conference, an authorized but unrelated client could sneak into an existing session and record or tap the conversation without the participant knowing or consenting. not it 💀.
participants give implicit authorization to their applications just by sending an INVITE to the application 💌. however, there's no trust, explicit or implicit, between the users of one service and a distinct client of another service 🚧.
all MSCML messages are sent within an INVITE-created SIP dialog 📞. so it'd be hard for an entity other than the original requestor to mess with an established MSCML session, because that would take detailed info on the dialog state 🧠. this lets multiple applications use the resources of a single media server at the same time without interfering with each other 👑.
because collected data can be super sensitive, like credit card numbers or other identifying info, the media server MUST support sips: and TLS 🔒. clients presumably know the value of the info they collect and what their users expect for privacy, so they're free to use clear text signaling or encrypted secure signaling, depending on what the app needs 💜. the media server SHOULD also support Secure Realtime Transport Protocol (SRTP) [9] ✨. again, clients are free to negotiate whatever level of media security is appropriate 🫶.
the media management stuff in MSCML, like the <managecontent> (Section 8) request, assumes a trust relationship between the media server and the file server 🗂️. this is similar to the scenario URLAUTH [20] deals with: the media server is acting on behalf of a given user, but the media server doesn't have that user's credentials 🤔. you might be tempted to use the user:pass facility of the HTTP URI to offer per-user security, but that also requires the media server to be secure, because it would need to know the user credentials in a form that's really easy to compromise, aka clear text passwords 😬.
the IETF is looking into ways to provide per-user or per-instance authorization of third-party http writing, which other protocols like WEBDAV [21] need too 🌈. until that work is finished, though, media server implementations MUST be prepared to authenticate themselves to file and web servers using appropriate authentication means 🔑. at a minimum, the media server MUST support HTTPS basic authentication 💖. implementers should note that the media server will need to respond appropriately to whatever authentication mechanism the file server requires 📝.
as this is an XML markup, all the security considerations of RFC 3023 [8] apply. ⚠️
14. References 📚
14.1. Normative References
[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[2] Burger, E., Van Dyke, J., and A. Spitzer, "Basic Network Media
Services with SIP", RFC 4240, December 2005.
[3] Donovan, S., "The SIP INFO Method", RFC 2976, October 2000.
[4] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A.,
Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP:
Session Initiation Protocol", RFC 3261, June 2002.
[5] "Network call signalling protocol for the delivery of time-
critical services over cable television networks using cable
modems", ITU-T J.162, March 2001.
[6] Groves, C., Pantaleo, M., Anderson, T., and T. Taylor, "Gateway
Control Protocol Version 1", RFC 3525, June 2003.
[7] Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, "XML
Schema Part 1: Structures", W3C REC REC-xmlschema-1-20010502,
May 2001.
[8] Murata, M., St. Laurent, S., and D. Kohn, "XML Media Types",
RFC 3023, January 2001.
[9] Baugher, M., McGrew, D., Naslund, M., Carrara, E., and K.
Norrman, "The Secure Real-time Transport Protocol (SRTP)", RFC
3711, March 2004.14.2. Informative References
[10] Rosenberg, J., "A Framework for Conferencing with the Session
Initiation Protocol (SIP)", RFC 4353, February 2006.
[11] Carter, J., Danielsen, P., Hunt, A., Ferrans, J., Lucas, B.,
Porter, B., Rehor, K., Tryphonas, S., McGlashan, S., and D.
Burnett, "Voice Extensible Markup Language (VoiceXML) Version
2.0", W3C REC REC-voicexml20-20040316, March 2004.
[12] International Packet Communications Consortium, "IPCC Reference
Architecture V2", June 2002.
[13] European Telecommunications Standards Institute, "Digital
cellular telecommunications system (Phase 2+); Universal Mobile
Telecommunications System (UMTS); IP Multimedia Subsystem
(IMS); Stage 2 (3GPP TS 23.228 version 7.2.0 Release 7)",
December 2005.
[14] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for the
Use of Extensible Markup Language (XML) within IETF Protocols",
BCP 70, RFC 3470, January 2003.
[15] Jacobs, I., Lie, H., Bos, B., and C. Lilley, "Cascading Style
Sheets, level 2 (CSS2) Specification", W3C REC REC-CSS2-
19980512, May 1998.
[16] Rosenberg, J., Schulzrinne, H., and O. Levin, "A Session
Initiation Protocol (SIP) Event Package for Conference State",
RFC 4575, August 2006.
[17] Cable Television Laboratories, Inc., "Audio Server Protocol",
January 2005.
[18] "Procedures for document facsimile transmission in the general
switched telephone network", Recommendation T.30, April 1999.
[19] "Procedures for real-time Group 3 facsimile communication over
IP networks", Recommendation T.38, March 2002.
[20] Crispin, M., "Internet Message Access Protocol (IMAP) - URLAUTH
Extension", RFC 4467, May 2006.
[21] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D.
Jensen, "HTTP Extensions for Distributed Authoring -- WEBDAV",
RFC 2518, February 1999.
[22] Institute of Electrical and Electronics Engineers, "Information
Technology - Portable Operating System Interface (POSIX) - Part
1: Base Definitions, Chapter 9", IEEE Standard 1003.1, June
2001.
[23] Burger, E. and M. Dolly, "A Session Initiation Protocol (SIP)
Event Package for Key Press Stimulus (KPML)", RFC 4730,
November 2006.
[24] Klensin, J., "Simple Mail Transfer Protocol", RFC 2821, April
2001.
[25] Campbell, B., Ed., Mahy, R., Ed., and C. Jennings, Ed., "The
Message Session Relay Protocol", Work in Progress, June 2006.URIs
- [26]
<http://www.ietf.org/html.charters/sip-charter.html> - [27]
<http://www.ietf.org/html.charters/sipping-charter.html> - [28]
<http://www.ietf.org/html.charters/mmusic.html> - [29]
<http://www.ietf.org/html.charters/xcon-charter.html> - [30]
<http://www.3gpp.org/ftp/Specs/html-info/23228.htm> - [31]
<mailto:eburger@cantata.com>
Appendix A. Regex Grammar Syntax 🎀
okay so the regex syntax used in MSCML is a telephony-flavoured subset of POSIX Extended Regular Expressions (ERE) [22], and it's called Digit REGular EXpression (DRegex) 📱. this syntax was first described in KPML [23] 💅.
DRegex has ordinary characters, special characters, bracket expressions, and interval expressions 🧩. here are the entities, defined below:
character matches digits 0-9, *, #, and A-D (case insensitive)
* matches the * character
# matches the # character
[character selector] matches any character in selector
[range1-range2] matches any character in range from range1 to range2,
inclusive
x matches any digit 0-9
{m} matches m repetitions of the previous pattern
{m,} matches m or more repetitions of the previous pattern
{,n} matches at most n (including zero) repetitions of the previous
pattern
{m,n} at least m and at most n repetitions of the previous pattern
L the presence of 'L' in any regex expression causes the media
server to enable "long" digit detection mode. See Section 7.1 for
the definition of "long" digits.Table 7 shows DRegex in action with examples 🦋:
+--------------+--------------------------------------------+
| Example | Description |
+--------------+--------------------------------------------+
| 1 | Matches the digit 1 |
| [179] | Matches 1, 7, or 9 |
| [2-9] | Matches 2, 3, 4, 5, 6, 7, 8, 9 |
| [02-46-9A-D] | Matches 0, 2, 3, 4, 6, 7, 8, 9, A, B, C, D |
| x | Matches 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 |
| *6[179#] | Matches *61, *67, *69, or *6# |
| x{10} | Ten digits (0-9) |
| 011x{7,15} | 011 followed by seven to fifteen digits |
| L* | Long star |
+--------------+--------------------------------------------+
Table 7: DRegex ExamplesAppendix B. Contributors 🌸
Jeff Van Dyke and Andy Spitzer did the concept, development, documentation, and execution for MSCML at SnowShore Networks, Inc., which is now part of Cantata Technology, Inc. 👏 Andy Spitzer's original work at The Telephone Connection, Inc., influenced the IVR implementation 📞. Mary Ann Leekley implemented the personalized mix feature and several other enhancements 💜.
Cliff Schornak of Commetrex and Jeff Van Dyke developed the facsimile service 📠.
Jai Cauvet, Rolando Herrero, Srinivas Motamarri, and Ashish Patel contributed greatly by testing MSCML 🫶🌈.
Appendix C. Acknowledgements ✨
Okay bestie, this is the shoutout section 🫶 Here's everyone who helped with the direction, development, or debugging of MSCML:
- Brian Badger and Phil Crable from Verizon Business
- Stephane Bastien from BroadSoft
- Peter Danielsen of Lucent Technologies
- Kevin Flemming, formerly of SnowShore Networks, Inc.
- Wesley Hicks and Ravindra Kabre, formerly from Sonus Networks
- Jon Hinckley from SkyWave/Sestro
- Terence Lobo, formerly of SnowShore Networks, Inc.
- Kunal Nawale, formerly of SnowShore Networks, Inc.
- Edwina Nowicki, formerly of SnowShore Networks, Inc.
- Diana Rawlins and Sharadha Vijay, formerly of WorldCom
- Gaurav Srivastva and Subhash Verma from BayPackets
- Kevin Summers from Sonus Networks
- Tim Wong from at&t
The authors also thanked Cullen Jennings and Dan Wing from Cisco Systems for their helpful review comments 💅
And they gave a huge thank you to Scotty Farber for using her technical writing expertise to document MSCML 📚🌸
Authors' Addresses 🦋
Jeff Van Dyke
Cantata Technology, Inc.
18 Keewaydin Dr.
Salem, NH 03079
USA
EMail: jvandyke@cantata.comEric Burger (editor)
Cantata Technology, Inc.
18 Keewaydin Dr.
Salem, NH 03079
USA
EMail: eburger@cantata.comAndy Spitzer
Pingtel Corporation
400 West Cummings Park
Woburn, MA 01801
USA
EMail: woof@pingtel.comFull Copyright Statement 💜
Copyright (C) The IETF Trust (2006).
This document is subject to the rights, licenses and restrictions in BCP 78, which you can find at www.rfc-editor.org/copyright.html. Except as set forth there, the authors keep all their rights.
This document and the information in it are provided on an "AS IS" basis, and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property 🔥
The IETF doesn't take a position on whether any Intellectual Property Rights or other rights that someone might claim for the technology in this document are valid or in scope. It also doesn't say whether any license under those rights might be available, and it hasn't independently checked for any such rights.
You can find info on how rights work for RFC documents in BCP 78 and BCP 79.
Copies of IPR disclosures sent to the IETF Secretariat, plus any assurances of licenses that might be offered, or the results of an attempt to get a general license or permission to use those proprietary rights for implementers or users of this specification, are available from the IETF's online IPR repository at http://www.ietf.org/ipr.
The IETF invites anyone who's interested to flag any copyrights, patents, patent applications, or other proprietary rights that might cover technology needed to implement this standard. Send that info to the IETF at ietf-ipr@ietf.org 📬
Acknowledgement 🌈
Funding for the RFC Editor function is currently provided by the Internet Society ⭐
📦 where this page comes from
- ietf: rfc4722 2006-11
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms