As per Relevance of the word specified, we have this rfc below:
Network Working Group D.
Request for Comments: 2897 Nortel
Category: Informational August 2000
Proposal for an MGCP Advanced Audio
Status of this
This memo provides information for the Internet community. It
not specify an Internet standard of any kind. Distribution of
memo is unlimited
Copyright
Copyright (C) The Internet Society (2000). All Rights Reserved
This document is a proposal to add a new event/signal package to
MGCP (Media Gateway Control Protocol) protocol to control an
(Audio Resource Function) which may reside on a Media Gateway
specialized Audio Server
This event package provides support for the standard IVR (
Voice Response) operations of PlayAnnouncement, PlayCollect,
PlayRecord. It supports direct references to simple audio as well
indirect references to simple and complex audio. It provides
variables, control of audio interruptibility, digit buffer control
special key sequences, and support for reprompting during
collection. It also provides an arbitrary number of user
qualifiers to be used in resolving complex audio structures.
example, the user could define qualifiers for any or all of
following: language, accent, audio file format, gender, speaker,
customer
Cromwell Informational [Page 1]
RFC 2897 MGCP Advanced Audio Package August 2000
Table of
1. Introduction ................................................ 2
1.1. Audio Segments ............................................ 3
1.1.1. Sequences And Sets ...................................... 3
1.1.2. Segment Types ........................................... 4
2. Advanced Audio Package ...................................... 5
3. Events ...................................................... 5
4. Event Parameters ............................................ 7
5. Return Parameters ........................................... 7
6. Variables ................................................... 14
7. Selectors ................................................... 17
8. Aliases ..................................................... 18
9. Examples .................................................... 21
10. Formal Syntax Description .................................. 22
11. References ................................................. 22
12. Formal Syntax Description .................................. 25
13. References ................................................. 32
14. Author's Address ........................................... 33
15. Full Copyright Statement ................................... 34
1.
The following syntax supports both simple and complex
structures. A simple audio structure might be a single
such as "Welcome to Bell South's Automated Directory
Service". A more complex audio structure might consist of
announcement followed by voice variable followed by
announcement, for example "There are thirty seven minutes
on your prepaid calling card," where "There are" is a prompt,
number of minutes is a voice variable, and "minutes remaining on
prepaid calling card" is another prompt
It is also possible to define complex audio structures that
qualified by user defined selectors such as language, audio
format, gender, accent, customer, or voice talent. For instance,
the above example were qualified by language and accent selectors,
would be possible to play "There are thirty seven minutes
on your prepaid calling card" in English spoken with a
accent or in English spoken with a mid-western accent, providing
the audio to support this had been provisioned
There are two methods of specifying complex audio. The first is
directly reference the individual components. This requires
complete description of each component to be specified via
protocol. The second method is to provision the components on
Audio Server as a single entity and to export a reference to
entity to the call agent. In this case, only the reference (plus
Cromwell Informational [Page 2]
RFC 2897 MGCP Advanced Audio Package August 2000
dynamic data required, such as a variable data) is passed via
protocol, and no specification of individual components is necessary
The Audio Server Package provides significant functionality most
which is controlled via protocol parameters. Most parameters
optional, and where ever possible default to reasonable values.
audio application that references to provisioned, complex
structures, and which takes advantage of parameter optionality
defaults, can specify audio events using a minimum of syntax
1.1.
The next two sections contain background information which may
helpful in understanding the syntax
1.1.1. Sequence And
The syntax supports abstractions of set and sequence for storing
referencing audio data
A sequence is a provisioned sequence of one or more audio segments
Component segments are not necessarily all of the same type.
sequence is assigned a unique segment id. On playback, a sequence
reference is deconstructed into its individual parts, each of
is played in order
A set is a provisioned collection of audio segments with
associated selector. On playback, the selector value is resolved
a particular set element. Selector types are supported by
syntax, but individual selector types are not defined in the
except for the pre-defined language selector; they are
defined by the user (i.e. provisioner). A user could define one
more of the following selector types: language, accent, audio
format, gender, accent, customer, or day of the week. For
selector type, the user must define a range of valid values.
user may also choose to define a default value. At runtime if
selector value is not supplied the default value is used
For example, to support an application which plays a particular
of audio in either English, French, or Russian, a provisioner
define a set with the pre-defined selector, "Lang", and would
three possible values for that selector, "eng", "fra", and "rus".
The provisioner would then provision three recordings of the prompt
one in each language, and would associate the French recording
the "fra" selector value, etc. The provisioner also could define
default value of the selector when no selector value is supplied
"eng" for instance. The entire set would be assigned a
segment id
Cromwell Informational [Page 3]
RFC 2897 MGCP Advanced Audio Package August 2000
At runtime a reference to the set with the selector set to "rus
would result in the Russian version of the prompt being played.
reference to the set with no selector would result in the
version of the prompt being played since English has been set as
default selector value
Nested definition of both sets and sequences is allowed, i.e.
legal to define a set of sets or a sequence of sequences.
addition, audio structures may also be specified by intermixing
and sequences, and it is possible to specify a set of sequences or
sequence containing one or more set elements. Direct or
definition of a set or segment in terms of itself is not allowed
1.1.2. Segment
The syntax supports the following segment types
RECORDING: A reference by unique id to a single piece of
audio
RECORDINGs may be provisioned or they may be made during
course of a call. A RECORDING made during the course of a
can be temporary or persistent. A temporary RECORDING lasts
for the life of the call during which it was recorded.
persistent RECORDING lasts beyond the live of the call
which it was recorded
A provisioned RECORDING may be replaced (or overridden) by
persistent RECORDING. A reference to the id of the
RECORDING will then resolve to the persistent RECORDING.
overriding persistent audio can subsequently be deleted and
original provisioned audio can be restored
A provisioned RECORDING may be overridden more than once. In
case, the id of the provisioned RECORDING refers to the
overriding RECORDING. When the overriding RECORDING is deleted
the original provisioned RECORDING is restored, even if
segment has been overridden multiple times
TEXT: A reference to a block of text to be converted to speech
to be displayed on a device. Reference may be by unique id to
block of provisioned text or by direct specification of text in
parameter
SILENCE: A specification of a length of silence to be played
units of 100 milliseconds
Cromwell Informational [Page 4]
RFC 2897 MGCP Advanced Audio Package August 2000
TONE: The specification of a tone to be played by
generation. Most tones however will probably be recorded,
generated. Exact specification of this segment type is tbd
VARIABLE: The specification of a voice variable by the
of type, subtype, and value. Specification of variables
considered in more detail in a subsequent section of
document
SEQUENCE: A reference by unique id to a provisioned sequence
mixed RECORDING, TEXT, SILENCE, TONE, VARIABLE, SET, or
segments. Nested definition of SEQUENCE segments is allowed
Direct or transitive definition of a SEQUENCE segment in terms
itself is not allowed
SET: A reference by unique id to a provisioned set of segments
The intended and recommended use of the SET type is that
segments in the set should be semantically equivalent,
there is no real way of enforcing this restriction either in
protocol or in provisioning. Every set has an associated
which is used at runtime to resolve the set reference to
specific element of the set. The elements of a set may one of
following segment types: RECORDING, TEXT, TONE, SILENCE
SEQUENCE, or SET. Specific selector types are not specified
the protocol and must be defined by the user. Nested
of SET segments is allowed. Direct or transitive definition of
SET segment in terms of itself is not allowed
2. Advanced Audio
Package Name:
This package defines events and signals for an ARF package for
Audio Server Media Gateway
3.
______________________________________________________________________
| Symbol | Definition | R | S Duration |
|______________|________________________|______|______________________|
| pa(parms) | PlayAnnouncement | | TO variable |
| pc(parms) | PlayCollect | | TO variable |
| pr(parms) | PlayRecord | | TO variable |
| es(parm) | EndSignal | | BR |
| oc(parms) | OperationComplete | x | |
| of(parms) | OperationFailed | x | |
|______________|________________________|______|______________________|
Cromwell Informational [Page 5]
RFC 2897 MGCP Advanced Audio Package August 2000
The events provided by the AS Package are defined as follows
PlayAnnouncement
Plays an announcement in situations where there is no need
interaction with the user. Because there is no need to
the incoming media stream this event is an efficient mechanism
treatments, informational announcements, etc
PlayCollect
Plays a prompt and collects DTMF digits entered by a user. If
digits are entered or an invalid digit pattern is entered,
user may be reprompted and given another chance to enter a
pattern of digits. The following digits are supported: 0-9, *,
#, A, B, C, D. By default PlayCollect does not play an
prompt, makes only one attempt to collect digits, and
functions as a simple Collect operation. Various special
keys, key sequences, and key sets can be defined for use
the PlayCollect operation
PlayRecord
Plays a prompt and records user speech. If the user does
speak, the user may be reprompted and given another chance
record. By default PlayRecord does not play an initial prompt
makes only one attempt to record, and therefore functions as
simple Record operation
OperationComplete
Detected upon the successful completion of a Play, PlayRecord,
Play Collect signal
OperationFailed
Detected upon the failure of a Play, PlayRecord, or
signal
EndSignal
Gracefully terminates a Play, PlayCollect, or PlayRecord signal
For each of these signals, if the signal is terminated with
EndSignal signal the resulting OperationComplete event
OperationFailed event will contain all the parameters it
normally, including any collected digits or the recording id
the recording that was in progress when the EndSignal signal
received
Cromwell Informational [Page 6]
RFC 2897 MGCP Advanced Audio Package August 2000
4. Signal
If an Advanced Audio Package signal is active on an endpoint
another signal of the same type is applied, the two signals
parameters and parameter values will compared If the signals
identical, the signal in progress will be allowed to continue and
new signal will be discarded. Because of this behavior the
Audio Package may not interoperate well with some other packages
as the Line and Trunk packages
5.
The PlayAnnouncement, PlayRecord, and PlayCollect events may each
qualified by a string of parameters, most of which are optional
Where appropriate, parameters default to reasonable values.
only event with a required parameter is PlayAnnouncement. If
Play-Announcement event is not provided with a parameter
some form of playable audio an error is returned to the application
Cromwell Informational [Page 7]
RFC 2897 MGCP Advanced Audio Package August 2000
These parameters are shown in the following table
_______________________________________________________________________
| Parameters |
|______________________________________________________________________|
| Symbol | Definition | pl | pc | pr |
|___________|_________________________________|________|________|______|
| an | announcement | x | | |
| ip | initial prompt | | x | x |
| rp | reprompt | | x | x |
| nd | no digits reprompt | | x | |
| ns | no speech reprompt | | | x |
| fa | failure announcement | | x | x |
| sa | success announcement | | x | x |
| ni | non-interruptible play | | x | x |
| it | iterations | x | | |
| iv | interval | x | | |
| du | duration | x | | |
| sp | speed | x | x | x |
| vl | volume | x | x | x |
| cb | clear digit buffer | | x | x |
| mx | maximum # of digits | | x | |
| mn | minimum # of digits | | x | |
| dp | digit pattern | | x | |
| fdt | first digit timer | | x | |
| idt | inter digit timer | | x | |
| edt | extra digit timer | | x | |
| prt | pre-speech timer | | | x |
| pst | post-speech timer | | | x |
| rlt | total recording length timer | | | x |
| rsk | restart key | | x | x |
| rik | reinput key | | x | x |
| rtk | return key | | x | x |
| psk | position key | | x | x |
| stk | stop key | | x | x |
| sik | start input key | | x | |
| eik | end input key | | x | x |
| iek | include end input key | | x | |
| na | number of attempts | | x | x |
|___________|_________________________________|________|________|______|
Parameters to the Advanced Audio Package events are defined
follows
Announcement
An announcement to be played. Consists of one or more
segments
Cromwell Informational [Page 8]
RFC 2897 MGCP Advanced Audio Package August 2000
Initial Prompt
The initial announcement prompting the user to either enter
digits or to speak. Consists of one or more audio segments.
not specified (the default), the event immediately begins
collection or recording
Reprompt
Played after the user has made an error such as entering
invalid digit pattern or not speaking. Consists of one or
audio segments. Defaults to the Initial Prompt
No Digits Reprompt
Played after the user has failed to enter a valid digit
during a PlayCollect event. Consists of one or more
segments. Defaults to the Reprompt
No Speech Reprompt
Played after the user has failed to speak during a
event. Consists of one or more audio segments. Defaults to
Reprompt
Failure Announcement
Played when all data entry attempts have failed. Consists of
or more audio segments. No default
Success Announcement
Played when data collection has succeeded. Consists of one
more audio segments. No default
Non-Interruptible Play
If set to true, initial prompt is not interruptible by
voice or digits. Defaults to false. Valid values are the
strings "true" and "false".
Iterations
The maximum number of times an announcement is to be played.
value of minus one (-1) indicates the announcement is to
repeated forever. Defaults to one (1).
Cromwell Informational [Page 9]
RFC 2897 MGCP Advanced Audio Package August 2000
Interval
The interval of silence to be inserted between iterative plays
Specified in units of 100 milliseconds. Defaults to 10 (1
second).
Duration
The maximum amount of time to play and possibly replay
announcement. Takes precedence over iteration and interval
Specified in units of 100 milliseconds. No default
Speed
The relative playback speed of announcement specifiable as
positive or negative percentage of the original playback speed
Volume
The relative playback volume of announcement specifiable as
positive or negative decibel variation from the original play-
volume
Clear Digit Buffer
If set to true, clears the digit buffer before playing the
prompt. Defaults to false. Valid values are the text
"true" and "false".
Maximum # Of Digits
The maximum number of digits to collect. Defaults to one.
parameter should not be specified if the Digit Pattern
is present
Minimum # Of Digits
The minimum number of digits to collect. Defaults to one.
parameter should not be specified if the Digit Pattern
is present
Digit Pattern
A legal digit map as described in section 7.1.14 of the
protocol [6] using the DTMF mappings associated with the
DTMF Detection Package described in the Megaco protocol
Cromwell Informational [Page 10]
RFC 2897 MGCP Advanced Audio Package August 2000
[6]. This parameter should not be specified if one or both of
Minimum # Of Digits parameter and the Maximum Number Of
parameter is present
First Digit Timer
The amount of time allowed for the user to enter the first digit
Specified in units of 100 milliseconds. 50 (5 seconds).
Inter Digit Timer
The amount of time allowed for the user to enter each
digit. Specified units of 100 milliseconds seconds. Defaults
30 (3 seconds).
Extra Digit Timer
The amount of time to wait for a user to enter a final digit
the maximum expected amount of digits have been entered
Typically this timer is used to wait for a terminating key
applications where a specific key has been defined to
input. Specified in units of 100 milliseconds. If not specified
this timer is not activated
Pre-speech Timer
The amount of time to wait for the user to initially speak
Specified in units of 100 milliseconds. Defaults to 30 (3
seconds).
Post-speech Timer
The amount of silence necessary after the end of the last
segment for the recording to be considered complete. Specified
units of 100 milliseconds. Defaults to 20 (2 seconds).
Recording Length Timer
The maximum allowable length of the recording, not including
or post speech silence. Specified in units of 100 milliseconds
This parameter is mandatory
Restart Key
Defines a key sequence consisting of a command key
followed by zero or more keys. This key sequence has
following action: discard any digits collected or recording
progress, replay the prompt, and resume digit collection
Cromwell Informational [Page 11]
RFC 2897 MGCP Advanced Audio Package August 2000
recording. No default. An application that defines more than
command key sequence, will typically use the same command key
all command key sequences. If more than one command key
is defined, then all key sequences must consist of a command
plus at least one other key
Reinput Key
Defines a key sequence consisting of a command key
followed by zero or more keys. This key sequence has
following action: discard any digits collected or recordings
progress and resume digit collection or recording. No default.
application that defines more than one command key sequence,
typically use the same command key for all command key sequences
If more than one command key sequence is defined, then all
sequences must consist of a command key plus at least one
key
Return Key
Defines a key sequence consisting of a command key
followed by zero or more keys. This key sequence has
following action: terminate the current event and any
event and return the terminating key sequence to the
processing agent. No default. An application that defines
than one command key sequence, will typically use the same
key for all command key sequences. If more than one command
sequence is defined, then all key sequences must consist of
command key plus at least one other key
Position Key
Defines a key with the following action. Stop playing the
announcement and resume playing at the beginning of the first
last, previous, next, or the current segment of the announcement
No default. The actions for the position key are fst, lst, prv
nxt, and cur
Stop Key
Defines a key with the following action. Terminate playback
the announcement. No default
Start Input Keys
Defines a set of keys that are acceptable as the first
collected. This set of keys can be specified to interrupt
playing announcement or to not interrupt a playing announcement
Cromwell Informational [Page 12]
RFC 2897 MGCP Advanced Audio Package August 2000
The default key set is 0-9. The default behavior is to interrupt
playing announcement when a Start Input Key is pressed.
behavior can be overidden for the initial prompt only by using
ni (Non-Interruptible Play) parameter. Specification is a list
keys with no separators, e.g. 123456789#.
End Input Key
Specifies a key that signals the end of digit collection or
recording. The default end input key is the # key. To specify
no End Input Key be used the parameter is set to the
"null". The default behavior not to return the End Input Key
the digits returned to the call agent. This behavior can
overidden by the Include End Input Key (eik) parameter
Include End Input Key
By default the End Input Key is not included in the
digits returned to the call agent. If this parameter is set
"true" then the End Input Key will be returned with the
digits returned to the call agent. Default is "false".
Number Of Attempts
The number of attempts the user needed to enter a valid
pattern or to make a recording. Defaults to 1. Also used as
return parameter to indicate the number of attempts the user made
Record Persistent Audio
If set to true, the recording that is made is persistent
of temporary. Defaults to false. Valid values are the
strings "true" and "false".
Delete Persistent
Indicates that the specified persistent audio segment is to
deleted. This parameter is carried by the PlayRecord event
although nothing is either played or recorded in this case
Override Audio
Indicates that the specified provisioned audio segment is to
overridden with a persistent audio segment to be recorded in
PlayRecord operation that carries this parameter
Cromwell Informational [Page 13]
RFC 2897 MGCP Advanced Audio Package August 2000
Restore Audio
Indicates that the provisioned audio segment originally
with the specified segment id is to be restored and that
overriding persistent audio is to be deleted. This parameter
carried by the PlayRecord event, although nothing is either
or recorded in this case
6. Return
Each event has an associated set of possible return parameters
are listed in the following tables
________________________________________________________________________
| Return Parameters |
|_______________________________________________________________________|
| Symbol | Definition | pl | pc | pr |
|___________|________________________________|________|_________|_______|
| vi | voice interrupt | | | x |
| ik | interrupting key sequence | | x | |
| ap | amount played | | x | x |
| na | number of attempts | | x | x |
| dc | digits collected | | x | |
| ri | recording id | | | x |
| rc | return code | x | x | x |
|___________|________________________________|________|_________|_______|
Voice Interrupted
Set to "true" if the initial prompt of a PlayRecord operation
interrupted by voice. Defaults to "false".
Interrupting Key Sequence
The key or key sequence that interrupted the initial prompt of
PlayCollect specified using the digit map characters "0"
"9" and "A" through "F" as defined in the DTMF Detection
in the Megaco protocol document [6].
Amount Played
The length played of an initial prompt if the prompt
interrupted, in 100 ms units
Cromwell Informational [Page 14]
RFC 2897 MGCP Advanced Audio Package August 2000
Number Of Attempts
The number of attempts the user needed to enter a valid
pattern or to make a recording. Defaults to 1. Also used as
input parameter to specify the number of attempts the user will
allowed to enter a valid digit pattern or make a recording
Digits Collected
The DTMF digits that were collected during a PlayCollect
specified using the digit map characters "0" through "9" and "A
through "F" as defined in the DTMF Detection Package in the
protocol document [6].
Recording ID
A 32 bit binary integer assigned to audio recorded during the
Record operation
Return Code
A return code giving the final status of the operation.
ranges are defined
_________________________________
| Range | Meaning |
|________|_______________________|
|100-199 | successful completion |
|300-399 | error |
|________|_______________________|
Cromwell Informational [Page 15]
RFC 2897 MGCP Advanced Audio Package August 2000
The following return codes are define
________________________________________________________________________
|Return Code | Meaning |
|____________|__________________________________________________________|
| 100 | Success |
| 300 | Unspecified failure |
| 301 | Bad audio ID |
| 302 | Bad selector type |
| 303 | Bad selector value |
| 304 | Variable type not supported |
| 305 | Variable subtype not supported |
| 306 | Invalid variable name |
| 307 | Variable value out of range |
| 308 | Inconsistent variable specification |
| 309 | Alias not found |
| 310 | Extra sequence data |
| 311 | Missing sequence data |
| 312 | Mismatch between play specification and provisioned data |
| 313 | Language not set |
| 314 | Remove override error |
| 315 | Override error |
| 316 | Delete audio error |
| 317 | Unable to record temporary audio |
| 318 | Unable to delete temporary audio |
| 319 | Unable to record persistent audio |
| 320 | Unable to delete persistent audio |
| 321 | Unable to override non-existent segment id |
| 322 | Unable to remove override from non-existent segment id |
| 323 | Provisioning error |
| 324 | Unspecified hardware failure |
| 325 | Syntax error |
| 326 | No digits |
| 327 | No speech |
| 328 | Spoke too long |
| 329 | Digit pattern not matched |
| 330 | Max attempts exceeded |
|____________|__________________________________________________________|
Here are some examples of how the return parameters are used
The PlayAnnouncement event completed successfully
O: AU/oc(rc=100)
The PlayAnnouncement event failed because an alias was not found
O: AU/of(rc=309)
Cromwell Informational [Page 16]
RFC 2897 MGCP Advanced Audio Package August 2000
The PlayCollect event completed successfully on the user's
attempt when the user entered the digits 04375182:
O: AU/oc(rc=100 na=2 dc=04375182)
The PlayRecord event was successful on the user's first attempt;
id of the recording made by the user is 983:
O: AU/oc(rc=100 na=1 ri=983)
7. Segment
Segment descriptors are used with the an, ip, rp, nd, ns, fa, and
parameters to define the segments that make up an announcement
________________________________________________________________________
| Segment Descriptors |
|_______________________________________________________________________|
| Symbol | Definition |
|____________________________________|__________________________________|
| 32 bit binary number | segment identifier |
| ts | text to speech |
| dt | display text |
| si | silence |
| to | tone |
| vb | variable |
|____________________________________|__________________________________|
Segment Identifier
A 32 bit binary integer identifying a provisioned entity such as
recording, set, sequence, etc
Text To Speech
Specifies a text string to be converted to speech
Display Text
Specifies a text string to be displayed on a device
Silence
Specifies a length of silence to be played in units of 100
milliseconds
Cromwell Informational [Page 17]
RFC 2897 MGCP Advanced Audio Package August 2000
Tone
Specifies a tone to be played by algorithmic generation.
specification of this parameter is tbd. Most tones will likely
recorded, not generated
Variable
Specifies a voice variable by type, subtype, and value.
are more completely defined in a subsequent section of
document
8.
The syntax supports two kinds of variables. Embedded
variables are variables that have been provisioned as part of
segment. Standalone variables are completely specified in
protocol message
Typically embedded variables are provisioned along with
speech, e.g. "A representative will be with you in approximately 5
minutes. If you would prefer to leave a voice message, press 1 now".
where the variable is the number of minutes. This kind of variable
often referred to as an embedded variable
Variables are specified by the following parameters: type, subtype
and value. Variable types include Date, Money, Number, Time, etc
Subtype is a refinement of type. For example the variable type
might have an associated range of subtypes such as Dollar, Rupee
Dinar, etc. Not all variables require a subtype, and for
variables the subtype parameter should be set to null
For embedded variables, the type and subtype must be provisioned
The value may be provisioned. If it is not provisioned it must
specified as part of the variable reference. In a list of segments
an embedded variable value specification applies only to the
that directly precedes it. If a segment has multiple
variables, the values must be given in the order in which
variables are encountered when the segment is played
Some examples follow below
A standalone variable
S: pa(an=vb(mny,usd,1153))
Cromwell Informational [Page 18]
RFC 2897 MGCP Advanced Audio Package August 2000
An embedded variable
S: pa(an=37<1153>)
Not all variables, such as the date variable shown in the
example, require a subtype. In that case, the subtype is
with the value "null":
S: pa(an=vb(dat,null,101598))
In some cases it may be desirable to play an announcement
contains an embedded variable without playing the variable itself
To do this a single "null" is provided for the value
S: pa(an=37)
________________________________________________________________________
| Variables Qualifiers |
|_______________________________________________________________________|
| Symbol | Definition | Type | Subtype | Subtype Of |
|_________|__________________________|________|___________|_____________|
| dat | date | x | | |
| dig | digits | x | | |
| gen | generic | | x | dig |
| ndn | North American DN | | x | dig |
| dur | duration | x | | |
| mth | month | x | | |
| mny | money | x | | |
| num | number | x | | |
| crd | cardinal | | x | nm |
| ord | ordinal | | x | nm |
| sil | silence | x | | |
| str | string | x | | |
| txt | text | x | | |
| dsp | display text | | x | txt |
| spk | text to speech | | x | txt |
| tme | time | x | | |
| t12 | twelve hour format | | x | tme |
| t24 | twenty four hour format | | x | tme |
| ton | tone | x | | |
| wkd | weekday | x | | |
|_________|__________________________|________|___________|_____________|
Date
Speaks a date specified as YYYYMMDD (per ISO 8601,
Date and Time Notation [7]). For example "19981015" is spoken
"October fifteenth nineteen ninety eight".
Cromwell Informational [Page 19]
RFC 2897 MGCP Advanced Audio Package August 2000
Digits
Speaks a string of digits one at a time. If the subtype is
American DN, the format of which is NPA-NXX-XXXX, the digits
spoken with appropriate pauses between the NPA and NXX and
the NXX and XXXX. If the subtype is generic, the digits
spoken no pauses
Duration
Duration is specified in seconds and is spoken in one or
units of time as appropriate, e.g. "3661" is spoken as "One hour
one minute, and one second".
Money
Money is specified in the smallest units of a given currency
is spoken in one or more units of currency as appropriate, e.g
"110" in U.S. Dollars would be spoken "one dollar and ten cents".
The three letter codes defined in ISO 4217, Currency And
Code List [5] are used to specify the currency subtype. A
excerpt from ISO 4217 follows
__________________________________________________________
|Alpha-code | Numeric-code | Currency | Entity |
|___________|______________|__________|___________________|
|GQE | 226 | Ekwele | Equatorial Guinea |
|GRD | 300 | Drachma | Greece |
|GTQ | 320 | Quetzal | Guatemala |
|___________|______________|__________|___________________|
Money can be specified in negative or positive units of currency
In the above example "-110" would be spoken as "minus one
and ten cents".
Month
Speaks the specified month, e.g. "10" is spoken as "October".
Specification is in MM format with "01" denoting January, "02"
denoting February, etc
Number
Speaks a number in cardinal form or in ordinal form. For example
"100" is spoken as "one hundred" in cardinal form and "
hundredth" in ordinal form. Cardinal numbers can be specified
negative or positive
Cromwell Informational [Page 20]
RFC 2897 MGCP Advanced Audio Package August 2000
Silence
Plays a specified period of silence. Specification is in 100
millisecond units
String
Speaks each character of a string, e.g. "a34bc" is spoken "A
three, four, b, c". Valid characters are a-z, A-Z, 0-9, #, and *.
Text
Produces the specified text as speech or displays it on a device
Time
Speaks a time in either twelve hour format or twenty four
format depending on the specified subtype. For example "1700"
spoken as "Five pm" in twelve hour format or as "Seventeen
hours" in twenty four hour format. Specification is in
format per ISO 8601, International Data and Time Notation [7].
Tone
Plays an algorithmically generated tone, specification of which
tbd. Probably most applications will use prerecorded tones
Weekday
Speaks the day of the week, e.g. "Monday". Weekdays are
as single digits, with "1" denoting Sunday, "2" denoting Monday
etc
9.
Selector types, except for the pre-defined "Lang" (language
selector, are definable by the user and may be applied to
individual segment within an operation or to all the segments in
operation. For each selector type, the user must also define a
of values that the selector can assume
For example, if the user defines a selector of type "phase-of-the
moon", he might also define the legal values for that selector to
"new", "half", "full", "harvest", and "blue". For the selector
actually work at runtime, audio associated with each of the
values must be provisioned
Cromwell Informational [Page 21]
RFC 2897 MGCP Advanced Audio Package August 2000
Although not required, it is suggested that the three letter
defined in ISO standard 639-2, Code For The Representation Of
Of Languages [4] be used as values for user defined
selectors. A small excerpt from ISO 639-2 follows
_________________
|Code | Language |
|_____|__________|
|cze | Czech |
|cym | Welsh |
|dan | Danish |
|_____|__________|
Selectors can apply to entire operations or to a segment within
operation. If an operation contains multiple segments, each
may have its own set of selectors. If selectors for an
segment and selectors for the entire operation are present,
selector for the individual segment takes precedence for
segment. The selectors for the operation apply to all
within that operation that do not have individual segment selectors
If a selector set is not specified, provisioned defaults are used
Selectors are applied to variables only after the variable has
resolved. For instance if a date variable resolved to "October 15th
1998" the voice with which the variable is spoken could resolve
either male or female if a gender selector had been defined
10.
Aliasing of audio segments is supported. The alias to segment
mapping is provisioned and at runtime the alias is resolved to
associated segment id. The syntax for an alias is inclusion of
alias between two forward slashes, e.g.:
S: pa(an=/not-in-service/)
11.
This section presents a number of examples of how the syntax is used
Note that arguments to an event are separated by a one or
whitespace characters, which can be either an ASCII space
or an ASCII tabulation character
Play an announcement that consists of a single segment
S: pa(an=39)
Cromwell Informational [Page 22]
RFC 2897 MGCP Advanced Audio Package August 2000
Play an announcement that consists of multiple segments
S: pa(an=39,40,47)
Play an announcement that consists of a recording followed by
followed by text to speech followed by a standalone voice variable
S: pa(an=39 si(30) ts(hello) vb(my,usd,3999))
Play an announcement with an embedded variable. If the first
segments of the previous announcement were provisioned as segment 40,
the following would be exactly equivalent to the play in
preceding example
S: pa(an=40<3999>)
Play an announcement with two embedded variables
S: pa(an=113<3999,10151998>)
Play a prompt and collect a single digit. If need be, play
reprompt, a no digits prompt, and a success or failure announcement
Give the user three attempts to enter a digit
S: pc(ip=21 rp=109 nd=102 fa=81 sa=72 na=3)
Play a prompt and collect a single digit. If the user does not
a digit replay the initial prompt. Give the user three attempts
enter a digit
S: pc(ip=21 na=3)
Play a prompt and record voice. If the user does not speak play a
speech prompt. Give the user two attempts to record
S: pr(ip=22 ns=42 na=2)
Play an announcement at ninety percent of its original speed and
decibels softer than its original volume. Play the
three times with two seconds of silence between plays
S: pa(an=27 sp=90 vl=-5 it=3 iv=20)
Give the user two attempts to enter a three digit pattern. Clear
digit buffer before playing the prompt. The user can signal end
input using the # key, which is not returned to the call agent
the collected digits
Cromwell Informational [Page 23]
RFC 2897 MGCP Advanced Audio Package August 2000
S: pc(ip=43 cb=true mn=3 mx=3 na=2)
Give the user three attempts to enter a three digit pattern. If
user enters one digits or two digits on the first or second
a reprompt is played. If the user enters no digits on the first
second attempts a no digits reprompt is played. If all
attempts fail, a failure announcement is played. If one of
attempts is successful, a success announcement is played and
collected digits are returned to the call agent. The user can
end of input using the # key. If the # key terminates a
input attempt, the collected digits, but not the # key, are
to the call agent
S: pc(ip=87 rp=5 nd=409 fa=9 sa=18 mx=3 na=3)
Give the user a single attempt to enter a a 1 to 4 digit pattern
allow 8 seconds for the user to enter the first digit, and allow 6
seconds for the user to enter each subsequent digit. If
subsequent digit timer expires after the user has less than
digits, the digits collected are returned to the call agent.
user can signal end of input using the # key which is not returned
the call agent with the collected digits
S: pc(ip=4 fdt=80 idt=60 mx=4)
Give the user three chances to enter an 11 digit number that
with 0 or 1. If the user makes a mistake while entering digits,
can press the * key to discard any digits already collected,
the prompt, and resume collection
S: pc(ip=33 mn=11 mx=11 sik=01 rsk=* na=3)
Give the user three chances to enter an 11 digit number that
with 0 or 1. If the user makes a mistake while entering digits,
can press the key sequence *11 to discard any digits
collected, replay the prompt, and resume collection. If the
enters the key sequence *12 the play collect is terminated along
any queued events, and the terminating key sequence is returned
the call agent for processing
S: pc(ip=33 mn=11 mx=11 sik=01 rsk=*11 rtk=*12 na=3)
Give the user two chances to make a recording. After playing
prompt, wait 5 seconds for the user to speak, otherwise replay
initial prompt and try again. If the user does speak, wait for
seconds after speech stops to make sure the user is finished. If
recording is successful, return a reference to the recording to
call agent
Cromwell Informational [Page 24]
RFC 2897 MGCP Advanced Audio Package August 2000
S: pr(ip=6 prt=50 pst=70 na=2)
Play an announcement in the default language
S: pa(an=5)
Play the same announcement the English. In the first example,
selector applies to the an segment; in the second it applies to
pa operation. For these particular examples, the net effect is
same
S: pa(an=5[Lang=eng]) or S: pa(an=5)[Lang=eng
Play an announcement in Danish using a female voice with a
accent
S: pa(an=6)[Lang=dan,gender=female,accent=cajun
Play the first part of an announcement in English, the second part
the default language, and the third part in French
S: pa(an=5[Lang=eng],6,7[Language=fra])
Play an announcement with an embedded variable in English
S: pa(an=5<101599>)[Lang=eng
12. Formal Syntax
AudPkgEvent = PlayAnnouncement / PlayCollect / PlayRecord /
OperationComplete / OperationFailed /
PlayAnnouncement = [ AdvAudioPkgToken SLASH ]
LPAREN PlayAnnParmList RPAREN [ OpSelectorList ]
PlayCollect = [ AdvAudioPkgToken SLASH ]
LPAREN [ PlayColParmList ] RPAREN [ OpSelectorList ]
PlayRecord = [ AdvAudioPkgToken SLASH ]
LPAREN [ PlayRecParmList ] RPAREN [ OpSelectorList ]
OperationComplete = [ AdvAudioPkgToken SLASH ]
LPAREN OpCompleteParmList
OperationFailed = [ AdvAudioPkgToken SLASH ]
LPAREN ReturnCodeParm
Cromwell Informational [Page 25]
RFC 2897 MGCP Advanced Audio Package August 2000
EndSignal = [ AdvAudioPkgToken SLASH ]
LPAREN SignalParm
OpSelectorList = LSQUARE OpSelector *( COMMA OpSelector )
OpSelector = NAME EQUALS
PlayAnnParmList = PlayAnnParm *( WSP PlayAnnParm )
PlayColParmList = PlayColParm *( WSP PlayColParm )
PlayRecParmList = PlayRecParm *( WSP PlayRecParm )
OpCompleteParmList = OpCompleteParm *( WSP OpCompleteParm )
PlayAnnParm = ( AnnouncementParm / IterationsParm / IntervalParm /
DurationParm / SpeedParm / VolumeParm )
PlayColParm = ( InitPromptParm / RepromptParm / NoDigitsParm /
FailAnnParm / SuccessAnnParm / NoInterruptParm /
SpeedParm / VolumeParm / ClearBufferParm /
MaxDigitsParm / MinDigitsParm / DigitPatternParm /
FirstDigitParm / InterDigitParm / ExtraDigitParm /
RestartKeyParm / ReinputKeyParm / ReturnKeyParm /
PosKeyParm / StopKeyParm / StartInputKeyParm /
EndInputKeyParm / IncludeEndInputKey /
NumAttemptsParm )
PlayRecParm = ( InitPromptParm / RepromptParm / NoSpeechParm /
FailAnnParm / SuccessAnnParm / NoInterruptParm /
SpeedParm / VolumeParm / ClearBufferParm /
PreSpeechParm / PostSpeechParm / RecordLenParm /
RestartKeyParm / ReinputKeyParm / ReturnKeyParm /
PosKeyParm / StopKeyParm / EndInputKeyParm /
RecPersistParm / OverrideAudioParm /
RestoreAudioParm / DeletePersistParm /
NumAttemptsParm )
OpCompleteParm = ( VoiceInterruptParm / IntKeySeqParm /
NumAttemptsParm / AmtPlayedParm / DigitsColParm /
RecordingIdParm / ReturnCodeParm )
AnnouncementParm = AnParmToken EQUALS
InitPromptParm = IpParmToken EQUALS
RepromptParm = RpParmToken EQUALS
Cromwell Informational [Page 26]
RFC 2897 MGCP Advanced Audio Package August 2000
NoDigitsParm = NdParmToken EQUALS
NoSpeechParm = NsParmToken EQUALS
FailAnnParm = FaParmToken EQUALS
SuccessAnnParm = SaParmToken EQUALS
DurationParm = DuParmToken EQUALS
IterationsParm = ItParmToken EQUALS ( NUMBER / "-1" )
IntervalParm = IvParmToken EQUALS
SpeedParm = SpParmToken EQUALS
VolumeParm = VlParmToken EQUALS
NoInterruptParm = NiParmToken EQUALS
ClearBufferParm = CbParmToken EQUALS
MaxDigitsParm = MxParmToken EQUALS
MinDigitsParm = MnParmToken EQUALS
DigitPatternParm = DpParmToken EQUALS
FirstDigitParm = FdtParmToken EQUALS
InterDigitParm = IdtParmToken EQUALS
ExtraDigitParm = EdtParmToken EQUALS
PreSpeechParm = PrtParmToken EQUALS
PostSpeechParm = PstParmToken EQUALS
RecordLenParm = RltParmToken EQUALS
RestartKeyParm = RskParmToken EQUALS
ReinputKeyParm = RikParmToken EQUALS
ReturnKeyParm = RtkParmToken EQUALS
PosKeyParm = PskParmToken EQUALS KeyPadKey COMMA
Cromwell Informational [Page 27]
RFC 2897 MGCP Advanced Audio Package August 2000
PosKeyAction = FirstSegmentToken / LastSegmentToken /
PreviousSegmentToken / NextSegmentToken /
StopKeyParm = StkParmToken EQUALS
StartInputKeyParm = SikParmToken EQUALS
EndInputKeyParm = EikParmToken EQUALS
IncludeEndinputKey = IekParmToken EQUALS
RecPersistParm = RpaParmToken EQUALS
OverrideAudioParm = OaParmToken EQUALS
RestoreAudioParm = RaParmToken EQUALS
DeletePersistParm = DpaParmToken EQUALS
NumAttemptsParm = NaParmToken EQUALS
VoiceInterruptParm = ViParmToken EQUALS
IntKeySeqParm = IkParmToken EQUALS
AmtPlayedParm = ApParmToken EQUALS
DigitsColParm = DcParmToken EQUALS
RecordingIdParm = RiParmToken EQUALS
ReturnCodeParm = RcParmToken EQUALS 3*3(DIGIT
KeyPadKey = "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" /
"*" / "#"
CommandKeySequence = 1*3(KeyPadKey
KeySequence = 1*64(KeyPadKey
KeySet = 1*11(KeyPadKey
SignalParm = SgParmToken EQUALS ( PlayAnnToken / PlayColToken /
PlayRecToken )
Segmentlist = SegmentDescriptor *( COMMA SegmentDescriptor )
Cromwell Informational [Page 28]
RFC 2897 MGCP Advanced Audio Package August 2000
SegmentDescriptor = ( ( SegmentId [ EmbedVarList ]
[ SegSelectorList ] ) /
( TextToSpeechSeg [ SegSelectorList ] ) /
( DisplayTextSeg [ SegSelectorList ] ) /
( VariableSeg [ SegSelectorList ] ) /
SilenceSeg )
SegmentId = ( Segid / Alias )
TextToSpeechSeg = TextToSpeechSegToken LPAREN NAME
DisplayTextSeg = DisplayTextSegToken LPAREN NAME
SilenceSeg = SilenceSegToken LPAREN NAME
VariableSeg = VariableSegToken LPAREN FullSpecVar
Segid =
Alias = SLASH NAME
EmbedVarList = LANGLE NAME *( COMMA NAME )
SegSelectorList = LSQUARE SegSelector *( COMMA SegSelector )
SegSelector = NAME EQUALS
FullSpecVar = ( DateVariable / DigitsVariable / DurationVariable /
MonthVariable / MoneyVariable / NumberVariable /
SilenceVariable / StringVariable / TextVariable /
TimeVariable / WeekdayVariable )
DateVariable = DateVarToken COMMA NullStrToken COMMA
Date = 8*8(DIGIT
DigitsVariable = DigitsVarToken COMMA (NorthAmericanDnToken /
GenericDigitsToken) COMMA
DurationVariable = DurationVarToken COMMA NullStrToken COMMA
MoneyVariable = MoneyVarToken COMMA 3*3(ALPHA) COMMA
MonthVariable = MonthVarToken COMMA NullStrToken COMMA
Month = "01" / "02" / "03" / "04" / "05" / "06" / "07" / "08" / "09" /
"10" / "11" / "12"
Cromwell Informational [Page 29]
RFC 2897 MGCP Advanced Audio Package August 2000
NumberVariable = (NumberVarToken COMMA CardinalNumberToken
OPTSIGNEDINT) / (NumberVarToken
OrdinalNumberToken COMMA NUMBER
SilenceVariable = SilenceVarToken COMMA NullStrToken COMMA
StringVariable = StringVarToken COMMA NullStrToken COMMA *(KeyPadKey
OrdinalNumberToken) COMMA
SilenceVariable = SilenceVarToken COMMA NullStrToken COMMA
StringVariable = StringVarToken COMMA NullStrToken
*(KeyPadKey
TextVariable = TextVarToken COMMA (DisplayTextToken /
TextToSpeechToken) COMMA
TimeVariable = TimeVarToken COMMA (TwelveHourFormatToken /
TwentyFourHourFormatToken) COMMA 4*4(DIGIT
WeekdayVariable = WeekdayVarToken COMMA NullStrToken COMMA
AdvAudioPkgToken = "A
PlayAnnToken = "pa
PlayColToken = "pc
PlayRecToken = "pr
OpCompleteToken = "oc
OpFailedToken = "of
EndSignalToken = "es
TextToSpeechSegToken = "ts
DisplayTextSegToken = "dt
SilenceSegToken = "si
VariableSegToken = "vb
AnParmToken = "an
IpParmToken = "ip
RpParmToken = "rp
NdParmToken = "nd
NsParmToken = "ns
FaParmToken = "fa
SaParmToken = "sa
NiParmToken = "ni
ItParmToken = "it
IvParmToken = "iv
DuParmToken = "du
SpParmToken = "sp
VlParmToken = "vl
CbParmToken = "cb
MxParmToken = "mx
Cromwell Informational [Page 30]
RFC 2897 MGCP Advanced Audio Package August 2000
MnParmToken = "mn
DpParmToken = "dp
FdtParmToken = "fdt
IdtParmToken = "idt
EdtParmToken = "edt
PrtParmToken = "prt
PstParmToken = "pst
RltParmToken = "rlt
RskParmToken = "rsk
RikParmToken = "rik
RtkParmToken = "rtk
PskParmToken = "psk
StkParmToken = "stk
SikParmToken = "sik
EikParmToken = "eik
IekParmToken = "iek
RpaParmToken = "rpa
DpaParmToken = "dpa
OaParmToken = "oa
RaParmToken = "ra
NaParmToken = "na
RidParmToken = "rid
ViParmToken = "vi
IkParmToken = "ik
ApParmToken = "ap
DcParmToken = "dc
RiParmToken = "ri
RcParmToken = "rc
SgParmToken = "sg
DateVarToken = "dat
DigitsVarToken = "dig
DuratioNVarToken = "dur
MoneyVarToken = "mny
MonthVarToken = "mth
NumberVarToken = "num
SilenceVarToken = "sil
StringVarToken = "str
TextVarToken = "txt
TimeVarToken = "tme
WeekdayVarToken = "wkd
GenericDigitsToken = "gen
NorthAmericanDnSToken = "ndn
CardinalNumberToken = "crd
OrdinalNumberToken = "ord
DisplayTextToken = "dsp
TextToSpeechToken = "spk
TwelveHourFormatToken = "t12"
TwentyFourHourFormatToken = "t24"
Cromwell Informational [Page 31]
RFC 2897 MGCP Advanced Audio Package August 2000
NullStrToken = "null
FirstSegmentToken = "fst
LastSegmentToken = "lst
PreviousSegmentToken = "prv
NextSegmentToken = "nxt
CurrentSegmentToken = "cur
BOOLSTR = "true" / "false
NAMECHAR = ALPHA / DIGIT / "_" / "-"
NAME = 1*64(NAMECHAR
NUMBER = DIGIT *31(DIGIT
SIGNEDINT = ("+" / "-") DIGIT *31(DIGIT
OPTSIGNEDINT = ["+" / "-"] DIGIT *31(DIGIT
EQUALS = "="
COMMA = ","
LSQUARE = "["
RSQUARE = "]"
LANGLE = "<"
RANGLE = ">"
LPAREN = "("
RPAREN = ")"
SLASH = "/"
WSP = SP /
13.
[1] Bradner, S., "Key words for use in RFCs to Indicate
Levels", BCP 14, RFC 2119, March 1997.
[2] Arango, M., Dugan, A., Elliott, I., Huitema, C. and S. Pickett
"Media Gateway Control Protocol (MGCP) Version 0.1", RFC 2705,
October 1999.
[3] Cromwell, D. and M. Durling, "Requirements For Control Of A
Services Function", Version 0.0, Work in Progres..
[4] ISO 639-2, "Code For The Representation Of Names Of Languages",
1998.
[5] ISO 4217, "Currency And Funds Code List", 1981.
[6] Cuervo, F., Hill, B., Greene, N., Huitema, C., Rayhan, A., Rosen
B. and J. Segers, "Megaco Protocol", RFC 2885, August 2000.
[7] ISO 8601, "International Date and Time Notation", 1998.
Cromwell Informational [Page 32]
RFC 2897 MGCP Advanced Audio Package August 2000
14. Author's
David
Nortel
Box 13478
35 Davis
Research Triangle Park, NC 27709
Phone: 919-991-8870
EMail: cromwell@nortelnetworks.
Cromwell Informational [Page 33]
RFC 2897 MGCP Advanced Audio Package August 2000
15. Full Copyright
Copyright (C) The Internet Society (2000). All Rights Reserved
This document and translations of it may be copied and furnished
others, and derivative works that comment on or otherwise explain
or assist in its implementation may be prepared, copied,
and distributed, in whole or in part, without restriction of
kind, provided that the above copyright notice and this paragraph
included on all such copies and derivative works. However,
document itself may not be modified in any way, such as by
the copyright notice or references to the Internet Society or
Internet organizations, except as needed for the purpose
developing Internet standards in which case the procedures
copyrights defined in the Internet Standards process must
followed, or as required to translate it into languages other
English
The limited permissions granted above are perpetual and will not
revoked by the Internet Society or its successors or assigns
This document and the information contained herein is provided on
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE
Funding for the RFC Editor function is currently provided by
Internet Society
Cromwell Informational [Page 34]
if you see any problems within the linking, don't worry be happy,
this is version 0.1 of the Relevance System and you gotta expect some crappy subroutines sometimes,
just be content we did not write this in Java, which would have made this "bigger and better" HAHAHHA.
RFC documents can be found at I.E.T.F.
Relevance System Copyright © 2002 Spectrum WorldResearch
other technical nosh by ServerMasters Corporation
collaboration of BobX
