Internet DRAFT - draft-cromwell-megaco-advanced-audio-pkg
draft-cromwell-megaco-advanced-audio-pkg
Internet Engineering Task Force David Cromwell
INTERNET DRAFT Nortel Networks
File: draft-cromwell-megaco-advanced-audio-pkg-00.txt Date: December 1, 1999
Proposal for an MEGACO Advanced Audio Package
<draft-cromwell-megaco-advanced-audio-pkg-00.txt>
Status of this Document
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet- Drafts as reference
material or to cite them other than as work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
Abstract
This document is a proposal to add a new event/signal package to the
Megaco protocol to control an ARF (Audio Resource Function) which may
reside on a Media Gateway or specialized Audio Server.
This event package provides support for the standard IVR operations
of PlayAnnouncement, PlayCollect, and PlayRecord. It supports direct
references to simple audio as well as indirect references to simple
and complex audio. It provides audio variables, control of audio
interruptibility, digit buffer control, special key sequences, and
support for reprompting during data collection. It also provides an
arbitrary number of user defined qualifiers to be used in resolving
complex audio structures. For example, the user could define qualif-
iers for any or all of the following: language, accent, audio file
format, gender, speaker, or customer.
Cromwell expires June 1, 2000 [Page 1]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Table of Contents
1. Introduction ................................................... 3
1.1. Sequences And Sets ........................................... 3
1.2. Segment Types ................................................ 4
1.3. Variables .................................................... 6
2. Advanced Audio Package Definition .............................. 6
2.1. Properties ................................................... 7
2.2. Events ....................................................... 7
2.2.1. Audio Operation Complete ................................... 7
2.2.2. Audio Operation Failure .................................... 9
2.3. Signals ...................................................... 9
2.3.1. Play ....................................................... 9
2.3.2. PlayCollect ................................................ 19
2.3.3. PlayRecord ................................................. 26
2.3.4. EndAudioSignal ............................................. 32
2.4. Statistics ................................................... 32
2.5. Procedures ................................................... 32
3. Syntax Rules ................................................... 32
4. Formal Syntax Description ...................................... 33
5. Examples ....................................................... 33
6. References ..................................................... 37
7. Author's Address ............................................... 37
Cromwell expires June 1, 2000 [Page 2]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
1. Introduction
The following syntax supports both simple and complex audio struc-
tures. A simple audio structure might be a single announcement such
as "Welcome to Bell South's Automated Directory Assistance Service."
A more complex audio structure might consist of an announcement fol-
lowed by voice variable followed by another announcement, for example
"There are thirty seven minutes remaining on your prepaid calling
card," where "There are" is a prompt, the number of minutes is a
voice variable, and "minutes remaining on your prepaid calling card"
is another prompt.
It is also possible to define complex audio structures that are qual-
ified by user defined selectors such as language, accent, audio file
format, gender, speaker, or customer. For instance, if the above
example were qualified by language and accent selectors, it would be
possible to play "There are thirty seven minutes remaining on your
prepaid calling card" in English spoken with a southern accent or in
English spoken with a mid-western accent, providing that the audio to
support this had been provisioned.
There are two methods of specifying complex audio. The first is to
directly reference the individual components. This requires a com-
plete description of each component to be specified via the protocol.
The second method is to provision the components on the Audio Server
as a single entity and to export a reference to that entity to the
call agent. In this case, only the reference (plus any dynamic data
required, such as a variable data) is passed via the protocol, and no
specification of individual components is necessary.
The Advanced Audio Package provides significant functionality con-
trolled via protocol parameters. Most parameters are optional, and
where ever possible default to reasonable values. An audio applica-
tion that references to provisioned, complex audio structures, and
which takes advantage of parameter optionality and defaults, can
specify audio events using a minimum of syntax.
The next three sections contain background information which may be
helpful in understanding the syntax.
1.1. Sequence And Sets
The syntax supports abstractions of set and sequence for storing and
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. Every
Cromwell expires June 1, 2000 [Page 3]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
sequence is assigned a unique segment id. On playback, a sequence id
reference is deconstructed into its individual parts, each of which
is played in order.
A set is a provisioned collection of audio segments with an associ-
ated selector. On playback, the selector value is resolved to a par-
ticular set element. Selector types are supported by the syntax, but
individual selector types are not defined in the syntax; they are
defined by the user (i.e. provisioner). For example, a user could
define one or more of the following selector types: language, accent,
audio file format, gender, accent, customer, or day of the week. For
each selector type, the user must define a range of valid values.
The user may also choose to define a default value. Then if a selec-
tor value is not supplied at runtime the default value is used.
For example, suppose that a user has defined a selector of type
language as well as a set of legal values for that selector consist-
ing of English, French, and Russian, and that the user has set
English to be the default value. Let us also assume that the user
has provisioned English, French, and Russian versions of a particular
prompt, "Please enter your id" for instance. At runtime a reference
to the set with the selector set to Russian would result in the Rus-
sian version of the prompt being played. A reference to the set with
no selector would result in the English version of the prompt being
played since English has been set as the default.
Recursive definition of both sets and sequences is allowed, i.e. it
legal to define a set of sets or a sequence of sequences. In addi-
tion, audio structures may also be specified by intermixing sets and
sequences, and it is possible to specify a set of sequences or a
sequence containing one or more set elements. Direct or transitive
definition of a set or segment in terms of itself is not allowed.
1.2. Segment Types
The syntax supports the following segment types:
RECORDING: A reference by unique id to a single piece of
recorded audio.
RECORDINGs may be provisioned or they may be made during the
course of a call. A RECORDING made during the course of a call
can be temporary or persistant. A temporary RECORDING lasts
only for the life of the call during which it was recorded. A
persistant RECORDING lasts beyond the live of the call during
which it was recorded.
Cromwell expires June 1, 2000 [Page 4]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
A provisioned RECORDING may be replaced (or overriden) by a per-
sistant RECORDING. A reference to the id of the provisioned
RECORDING will then resolve to the persistant RECORDING. The
overriding persistant audio can subsequently be deleted and the
original provisioned audio can be restored.
A provisioned RECORDING may be overrided more than once. In
this case, the id of the provisioned RECORDING refers to the
latest overriding RECORDING. When the overriding RECORDING is
deleted, the original provisioned RECORDING is restored, even if
the segment has been overriden multiple times.
TEXT: A reference to a block of text to be converted to speech
or to be displayed on a device. Reference may be by unique id
to a block of provisioned text or by direct specification of
text in a parameter.
SILENCE: A specification of a length of silence to be played in
units of 100 milliseconds.
TONE: The specification of a tone to be played by algorithmic
generation. Most tones however will probably be recorded, not
generated. Exact specification of this segment type is tbd.
VARIABLE: The specification of a voice variable by the parame-
ters of type, subtype, and value. Specification of variables is
considered in more detail in a subsequent section of this docu-
ment.
SEQUENCE: A reference by unique id to a provisioned sequence of
mixed RECORDING, TEXT, SILENCE, TONE, VARIABLE, SET, or SEQUENCE
segments. Recursive definition of SEQUENCE segments is allowed.
Direct or transitive definition of a SEQUENCE segment in terms
of itself is not allowed.
SET: A reference by unique id to a provisioned set of seg-
ments. The intended and recommended use of the SET type is that
all segments in the set should be semantically equivalent, how-
ever there is no real way of enforcing this restriction either
in the protocol or in provisioning. Every set has an associated
selector which is used at runtime to resolve the set reference
to a specific element of the set. The elements of a set may one
of the following segment types: RECORDING, TEXT, TONE, SILENCE,
SEQUENCE, or SET. Specific selector types are not specified by
the protocol and must be defined by the user. Recursive defini-
tion of SET segments is allowed. Direct or transitive definition
of a SET segment in terms of itself is not allowed.
Cromwell expires June 1, 2000 [Page 5]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
1.3. Variables
The Advanced Audio Package provides two kinds of voice variables.
Embedded embedded variables are variables that have been provisioned
as part of a segment. Direct variables are completely specified in
the protocol message.
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 Money
might have an associated range of subtypes such as Dollar, Rupee,
Dinar, etc. Not all variables require a subtype, and for these vari-
ables the subtype parameter should be set to null.
For embedded variables, only the value is specified since the type
and subtype have been provisioned. In a list of segments, an embed-
ded variable specification applies only to the segment that directly
preceeds it. If a segment has multiple embedded variables, the
values must be given in the order in which the variables are encoun-
tered when the segment is played.
Typically embedded variables are provisioned along with recorded
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. To play the preceeding
announcement the MGC would specify the id of the audio segment and a
variable value, in this case 5.
In some cases it may be desirable to play an announcement that con-
tains an embedded variable without playing the variable itself. To
do this set the value of the embedded variable to "null".
2. Advanced Audio Package
PackageID: au
Version: 1
Extends: None
This package defines events and signals for an ARF package for an
Audio Server Media Gateway.
Cromwell expires June 1, 2000 [Page 6]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
2.1. Properties
None
2.2. Events
2.2.1. Audio Operation Complete
EventID: audcomp
Signifies the successful completion of a play, playcol, or
playrec signal.
EventDescriptor parameters
None
ObservedEventDescriptor parameters
Voice interrupted
ParameterID: vi
Whether or not the initial prompt of a playrec signal
was interrupted by voice.
Type: string
Possible values: true or false
Interrupting key sequence
ParameterID: ik
The key or key sequence that interrupted the initial
prompt of a playrec signal, if any.
Type: string
Possible values: any sequence of valid DTMF digits.
Amount played
Cromwell expires June 1, 2000 [Page 7]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
ParameterID: ap
The length played of an interrupted prompt, in 100 ms
units. Type: integer
Possible values:
Number of attempts
ParameterID: na
The number of attempts the user needed to enter a
valid digit pattern or to make a recording.
Type: integer
Possible Values:
Digits collected
ParameterID: dc
The DTMF digits that were collected during a play sig-
nal.
Type: string
Possible Values: any sequence of valid DTMF digits.
Recording id
ParameterID: ri
A 32 bit binary integer assigned to audio recording
made during a playrec signal.
Type: integer
Possible Values:
Return code
ParameterID: rc
Cromwell expires June 1, 2000 [Page 8]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
A return code indicating that the signal was success-
ful and possibly carrying other information as well.
Currently the only defined success return code is 100
(unspecified success.
Type: integer
Possible Values: success return codes range from
100-1999.
2.2.2. Audio Operation Failure
EventID: audfail
Signifies the failure of a play, playcol, or playrec sig-
nal.
EventDescriptor parameters
None
ObservedEventDescriptor parameters
ParameterID: rc
A return code indicating why the signal failed.
Currently the only defined failure return code is 300
(unspecified failure).
Type: integer
Possible Values: failure return codes range from
300-399.
2.3. Signals
2.3.1. Play
SignalID: play
Plays one or more audio segments.
Cromwell expires June 1, 2000 [Page 9]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Required Parameters: Announcement.
Parameters:
Announcement
ParameterID: an
An announcement to be played. Consist of one or more
audio segments.
Type: string
Possible values: integer,ts,dt,si,tn,vb,ev,alias,lsl
TextToSpeech
ValueTag: ts
Specifies a text string to be converted to
speech.
Syntax: ts/<string>
DisplayText
ValueTag: dt
Specifies a text string to be displayed on a
device.
Syntax: dt/<string>
Silence
ValueTag: si
Specifies a length of silence to be played in
units of 100 milliseconds.
Syntax: si/<integer>
Tone
ValueTag: tn
Cromwell expires June 1, 2000 [Page 10]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Specifies a tone to be played by algorithmic
generation. Exact specification of this param-
eter is tbd. Most tones will likely be
recorded, not generated.
Syntax: tbd
Variable
ValueTag: vb
Specifies a voice variable by type, subtype,
and value.
Syntax: vb/<type>/<subtype>/<value>
Variable Types:
dat (date)
Speaks a date specified as YYYYMMDD
(per ISO 8601, International Date and
Time Notation [8]). For example
"19981015" is spoken as "October
fifteenth nineteen ninety eight."
dig (digits)
Speaks a string of digits one at a
time. If the subtype is North Ameri-
can DN, the format of which is NPA-
NXX-XXXX, the digits are spoken with
appropriate pauses between the NPA
and NXX and between the NXX and XXXX.
If the subtype is generic, the digits
are spoken no pauses.
dur (duration)
Duration is specified in seconds and
is spoken in one or more units of
time as appropriate, e.g. "3661" is
spoken as "One hour, one minute, and
one second."
mny (money)
Cromwell expires June 1, 2000 [Page 11]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Money is specified in the smallest
units of a given currency and is spo-
ken in one or more units of currency
as appropriate, e.g. "110" in U.S.
Dollars would be spoken "one dollar
and ten cents."
mth (month)
Speaks the specified month, e.g. "10"
is spoken as "October." Specifica-
tion is in MM format with "01" denot-
ing January, "02" denoting February,
etc.
num (number)
Speaks a number in cardinal form or
in ordinal form. For example, "100"
is spoken as "one hundred" in cardi-
nal form and "one hundredth" in ordi-
nal form.
sil (silence)
Plays a specified period of silence.
Specification is in 100 millisecond
units.
str (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 *.
txt (text) Text:
Produces the specified text as speech
or displays it on a device.
tme (time)
Speaks a time specified as HHMM (per
ISO 8601, International Data and Time
Notation [8]) in twenty four hour
format in either twelve hour format
Cromwell expires June 1, 2000 [Page 12]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
or twenty four hour format. For exam-
ple "1700" is spoken as "Five pm" in
twelve hour format or as "Seventeen
hundred hours" in twenty four hour
format.
ton (tone)
Plays an algorithmically generated
tone, specification of which is tbd.
Probably most applications will use
prerecorded tones.
wkd (weekday)
Speaks the day of the week, e.g.
"Monday." Weekdays are specified as
single digits, with "1" denoting Sun-
day, "2" denoting Monday, etc.
Variable Subtypes:
null
If a particular variable type does
not have an associated subtype the
subtype must be set to "null".
gen
Generic digits; only valid when used
used with the digits variable type.
Causes a string of digits supplied by
the variable value parameter to be
played one at a time with no pauses
between digits.
ndn
North American DN; only valid when
used used with the digits variable
type. Causes a string of nine digits
supplied by the variable value param-
eter to be spoken in NPA-NXX-XXXX
format, i.e. the digits are spoken
with appropriate pauses between the
NPA and NXX and between the NXX and
XXXX.
Cromwell expires June 1, 2000 [Page 13]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
crd
Cardinal Number; only valid when used
used with the digits variable type.
Causes the number supplied by the
variable value parameter to be spoken
in cardinal form, e.g. "100" is spo-
ken as "one hundred." form.
ord
Ordinal Number; only valid when used
used with the digits variable type.
Causes the number supplied by the
variable value parameter to be spoken
in cardinal for, e.g. "100" is spoken
as "one hundredth."
dsp
Display text; only valid when used
with the text variable type. Causes
the text supplied by the variable
value parameter to be displayed on a
device.
spk
Spoken text; only valid when used
with the text variable type. Causes
the text supplied by the variable
value parameter to be spoken (i.e.
text to speech).
t12
Twelve hour format; only valid when
used with the time variable type.
Causes the time supplied by the vari-
able value parameter to be spoken in
twelve hour format. For example
"1700" would be spoken as "Five pm."
t24
Twenty four hour format; only valid
when used with the time variable
type. Causes the time supplied by the
variable value parameter to be spoken
in twenty four hour format. For
example "1700" would be spoken as
Cromwell expires June 1, 2000 [Page 14]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
"Seventeen hundred hours."
<various language codes>
The three letter codes defined in ISO
4217, Currency And Funds Code List
[7] are used to specify the currency
subtype. A small excerpt from ISO
4217 follows:
__________________________________________________________
|Alpha-code | Numeric-code | Currency | Entity |
|___________|______________|__________|___________________|
|GQE | 226 | Ekwele | Equatorial Guinea |
|GRD | 300 | Drachma | Greece |
|GTQ | 320 | Quetzal | Guatemala |
|___________|______________|__________|___________________|
Embedded Variable
ValueTag: ev
Specifies the value for a previously pro-
visioned voice variable.
Syntax: ev/<string>
Possible values: In some cases it may be desir-
able to play an announcement that contains an
embedded variable without playing the variable
itself. To do this set the value of the embed-
ded variable to "null".
Alias
ValueTag: alias
Indicates a reference to an audio segments is
by alias rather than segment id. The ARF
software supports alias to segment id mapping.
The mapping is set up via provisioning.
Syntax: alias/<string>
Cromwell expires June 1, 2000 [Page 15]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Possible values:
LocalSelector
ValueTag: lsl
See the definition of the GlobalSelector param-
eter (following) for a discussion of selectors,
tags, and values. A LocalSelector works
exactly like a GlobalSelector except that it
applies to only a single audio segment within
an announcement.
Syntax: lsl/<tag>/<value>
GlobalSelector
ParameterID: gsl
A selector is a user defined tag and an associated value
which is used to resolve a reference to a set of semanti-
cally related segment ids to a particular id. There is
one pre-defined selector name for language, "lang". The
values associated with this selector are the three letter
codes defined in ISO standard 639-2, Code For The
Representation Of Names Of Languages [6]. A small excerpt
from ISO 639-2 follows:
_________________
|Code | Language |
|_____|__________|
|cze | Czech |
|cym | Welsh |
|dan | Danish |
|_____|__________|
For example, an ARF provisioner could define the selector
tag "accent", a set of possible values: "southernUS",
"northernUS", and "midwesternUS", and a default value,
"midwesternUS" for instance. The provisioner would then
provision the audio required to support each of these
accents. During a call if the MGC asked the ARF to play
a prompt it could specify the "accent" selector tag and
one of the three defined values, and the prompt would be
played in the accent selected. If the MGC did not
Cromwell expires June 1, 2000 [Page 16]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
specify a selector the prompt would be played in the
default accent.
Global selectors apply to all segments within an
announcement (e.g. Announcement, InitialPrompt, Reprompt,
etc.).
Type: string
Syntax: gsl=<tag>/<value>
Possible values: all tags and values are defined by the
ARF provisioner with the exception of the "lang" selector
tag and associated values which are defined in ISO stan-
dard 639-2.
NonInterruptiblePlay
ParameterID: ni
Specifies whether or not an initial prompt is interrupti-
ble by either voice or digits. Defaults to false.
Type: string
Possible values: true or false. Defaults to false.
Iterations
ParameterID: it
The maximum number of times an announcement is to be
played.
Type: string
Possible values: Defaults to one. A value of minus one
indicates that the announcement is to be repeated for-
ever.
Interval
ParameterID: iv
The interval of silence to be inserted between iterative
Cromwell expires June 1, 2000 [Page 17]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
plays. Specified in units of 100 milliseconds.
Type: integer
Possible values: Defaults to one second.
Duration
ParameterID: du
The maximum amount of time to play and possibly replay an
announcement. Takes precedence over iteration and inter-
val. Specified in units of 100 milliseconds. No
default.
Type: integer
Possible values:
Speed
ParameterID: sp
The relative playback speed of announcement specifiable
as a positive or negative percentage variation from the
normal playback speed.
Type: signed integer
Possible values:
Volume
ParameterID: vl
The relative playback volume of announcement specifiable
as a positive or negative percentage variation from the
normal playback volume.
Type: signed integer
Possible values:
Cromwell expires June 1, 2000 [Page 18]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
2.3.2. PlayCollect
SignalID: playcol
Plays an announcement (optionally) and collects dtmf digits input
by the user.
Required Parameters: none.
Parameters:
InitialPrompt
ParameterID: ip
The initial announcement prompting the user to either
enter DTMF digits or to speak. Consists of one or more
audio segments. If not specified, digit collection or
recording begins immediately.
Type: string
Possible values: See Play Signal Announcement Parameter
for details.
Reprompt
ParameterID: rp
Played after the user has made an error such as entering
an invalid digit pattern or not speaking. Consists of
one or more audio segments. Defaults to Initial Prompt.
Type: string
Possible values: see Play Signal Annoumcement Parameter
for details.
NoDigitsPrompt
ParameterID: nd
Played after the user has failed to enter a valid digit
pattern during a Play Collect event. Consists of one or
more audio segments. Defaults to Reprompt.
Cromwell expires June 1, 2000 [Page 19]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Type: string
Possible values: see Play Signal Annoumcement Parameter
for details.
SuccessAnnouncement
ParameterID: sa
Played when data collection has succeeded. Consists of
one or more audio segments. No default.
Type: string
Possible values: see Play Signal Annoumcement Parameter
for details.
FailureAnnouncement
ParameterID: fa
Played when all data entry attempts have failed. Con-
sists of one or more audio segments. No default.
Type: string
Possible values: see Play Signal Annoumcement Parameter
for details.
GlobalSelector
ParameterID: gsl
See definition of this parameter in the play Signal sec-
tion.
NonInterruptiblePlay
ParameterID: ni
Specifies whether or not an initial prompt is interrupti-
ble by either voice or digits. Defaults to false.
Type: string
Cromwell expires June 1, 2000 [Page 20]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Possible values: true or false. Defaults to false.
Speed
ParameterID: sp
See definition of this parameter in the play Signal sec-
tion.
Volume
ParameterID: vl
See definition of this parameter in the play Signal sec-
tion.
ClearDigitBuffer
ParameterID: cb
If set to true, clears the digit buffer before playing
the initial prompt.
Type: string
Possible values: true and false. Defaults to false.
MaxDigits
ParameterID: mx
The maximum number of digits to collect. Defaults to
one.
Type: integer
Possible values:
MinDigits
ParameterID: mn
The minimum number of digits to collect. Defaults to
one.
Cromwell expires June 1, 2000 [Page 21]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Type: integer
Possible values:
DigitPattern
ParameterID: dp
Type: string
An extended regular expression specifying a digit collec-
tion pattern. Uses extended regular expressions as sup-
ported by the Rogue Wave Class Library [9], which sup-
ports a subset of the POSIX.2 standard [10] for regular
expressions. If a pattern is not specified, pattern
matching is not attempted.
OPEN ISSUE: Currently the H.248 specification does not
allow the left square bracket, right square bracket, or
vertical line characters in parameter values. These
characters are necessary to implement extended regular
expressions.
Possible values:
FirstDigitTimer
ParameterID: fdt
The amount of time allowed for the user to enter the
first digit. Specified in units of 100 milliseconds.
Defaults to five seconds.
Type: integer
Possible values:
InterDigitTimer
ParameterID: idt
The amount of time allowed for the user to enter each
subsequent digit. Specified units of 100 milliseconds
seconds. Defaults to three seconds.
Cromwell expires June 1, 2000 [Page 22]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Type: integer
Possible values:
ExtraDigitTimer
ParameterID: edt
The amount of time to wait for a user to enter a final
digit once the maximum expected amount of digits have
been entered. Typically this timer is used to wait for a
terminating key in applications which have defined a
specific key to terminate input. Specified in units of
100 milliseconds. If not specified, this timer is not
activated.
Type: integer
Possible values:
RestartKey
ParameterID: rsk
Defines a key sequence consisting of a command key
optionally followed by zero or more keys. This key
sequence has the following action: discard any digits
collected or recording in progress, replay the prompt,
and resume digit collection or recording. No default.
An application that defines more than one command key
sequence, will typically use the same command key for all
command key sequences. If more than one command key
sequence is defined, then all key sequences must consist
of a command key plus at least one other key. Restart ,
reinput, and return keys take precedence over all other
keys.
Type: string
Possible values: 0-9,*,#
Reinput Key:
ParameterID: rik
Defines a key sequence consisting of a command key
Cromwell expires June 1, 2000 [Page 23]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
optionally followed by zero or more keys. This key
sequence has the following action: discard any digits
collected or recordings in progress and resume digit col-
lection or recording. No default. An application that
defines more than one command key sequence, will typi-
cally use the same command key for all command key
sequences. If more than one command key sequence is
defined, then all key sequences must consist of a command
key plus at least one other key. Restart , reinput, and
return keys take precedence over all other keys.
Type: string
Possible values: 0-9,*,#
Return Key:
ParameterID: rtk
Defines a key sequence consisting of a command key
optionally followed by zero or more keys. This key
sequence has the following action: terminate the current
event and any queued event and return the terminating key
sequence to the call processing agent. No default. An
application that defines more than one command key
sequence, will typically use the same command key for all
command key sequences. If more than one command key
sequence is defined, then all key sequences must consist
of a command key plus at least one other key. Restart ,
reinput, and return keys take precedence over all other
keys.
Type: string
Possible values: 0-9,*,#
Position Key:
ParameterID: psk
Defines a key with the following action. Stop playing
the current announcement and resume playing at the begin-
ning of the first, last, previous, next, or the current
segment of the announcement. The position key is valid
only during the play phase of a signal and takes pre-
cedence over the start input key and the end input key.
No default.
Cromwell expires June 1, 2000 [Page 24]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Type: string
Syntax: psk/<key>/<action>
Possible values:
<key> : 0-9,*, or #
<action> : fst, lst, prv, nxt, or cur
StopKey
ParameterID: stk
Defines a key the striking of which terminates playback
of the announcement. The position key is valid only dur-
ing the play phase of a signal and takes precedence over
the start input key and the end input key. No default.
Type: string
Possible values: 0-9,*, or #
StartInputKey
ParameterID: sik
Defines a set of keys that are acceptable as the first
digit collected. This set of keys can be specified to
interrupt a playing announcement or to not interrupt a
playing announcement. The default key set is 0-9. The
default behavior is to interrupt a playing announcement
when a Start Input Key is pressed. This behavior can be
overidden by using the ni (Non-Interruptible Play) param-
eter. Specification is a list of keys with no sepera-
tors, e.g. 123456789#.
Type: string
Possible values: 0-9,*,#
EndInputKey
ParameterID: eik
Cromwell expires June 1, 2000 [Page 25]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Specifies a key that signals the end of digit collection
or voice recording. The default end input key is the #
key. To specify that no End Input Key be used the parame-
ter is set to the string "null". The default behavior
not to return the End Input Key in the digits returned to
the call agent. This behavior can be overidden by the
Include End Input Key (eik)
Type: string
Possible values: 0-9,*, or #
IncludeEndInputKey
ParameterID: iek
By default the End Input Key is not included in the col-
lected digits returned to the call agent. If this param-
eter is set to true then the End Input Key will be
returned with the collected digits returned to the call
agent.
Type: string
Possible values: true or false. Defaults to false.
NumberOfAttempts
ParameterID: na
The number of attempts the user is given to enter a valid
digit pattern or to make a recording. Defaults to one.
Type: integer
Possible values:
2.3.3. PlayRecord
SignalID: playrec
Plays an announcement (optionally) and records user speech.
Required Parameters: RecordLengthTimer
Cromwell expires June 1, 2000 [Page 26]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Parameters:
InitialPrompt
ParameterID: ip
See definition of this parameter in the playcol Signal
section.
Reprompt
ParameterID: rp
See definition of this parameter in the playcol Signal
section.
NoSpeechPrompt
ParameterID: ns
Played after the user has failed to speak during a Play
Record event. Consists of one or more audio segments.
Defaults to Reprompt.
Type: string
Possible values: see play Signal Annoumcement Parameter
for details.
SuccessAnnouncement
ParameterID: sa
See definition of this parameter in the playcol Signal
section.
FailureAnnouncement
ParameterID: fa
See definition of this parameter in the playcol Signal
section.
Cromwell expires June 1, 2000 [Page 27]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
GlobalSelector
ParameterID: gsl
See definition of this parameter in the play Signal sec-
tion.
NonInterruptiblePlay
ParameterID: ni
See definition of this parameter in the playcol Signal
section.
Speed
ParameterID: sp
See definition of this parameter in the play Signal sec-
tion.
Volume
ParameterID: vl
See definition of this parameter in the play Signal sec-
tion.
ClearDigitBuffer
ParameterID: cb
See definition of this parameter in the playcol Signal
section.
PreSpeechTimer
ParameterID: prt
The amount of time to wait for the user to initially
speak. Specified in units of 100 milliseconds. Defaults
to three seconds.
Cromwell expires June 1, 2000 [Page 28]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Type: integer
Possible values:
PostSpeechTimer
ParameterID: pst
The amount of silence necessary after the end of the last
speech segment for the recording to be considered com-
plete. Specified in units of 100 milliseconds. Defaults
to two seconds.
Type: integer
Possible values:
RecordLengthTimer
ParameterID: rlt
The maximum allowable length of the recording, not
including pre or post speech silence. Specified in units
of 100 milliseconds.
Type: integer
Possible values:
RestartKey
ParameterID: rsk
See definition of this parameter in the playcol Signal
section.
Reinput Key:
ParameterID: rik
See definition of this parameter in the playcol Signal
section.
Return Key:
Cromwell expires June 1, 2000 [Page 29]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
ParameterID: rtk
See definition of this parameter in the playcol Signal
section.
Position Key:
ParameterID: rtk
See definition of this parameter in the playcol Signal
section.
StopKey
ParameterID: stk
See definition of this parameter in the playcol Signal
section.
EndInputKey
ParameterID: eik
See definition of this parameter in the playcol Signal
section.
NumberOfAttempts
ParameterID: na
The number of attempts the user is given to enter a valid
digit pattern or to make a recording. Defaults to one.
Type: integer
Possible values:
RecordPersistantAudio
ParameterID: rpa
If set to true, the recording that is made is persistant
instead of temporary.
Cromwell expires June 1, 2000 [Page 30]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Type: string
Possible values: true or false. Defaults to false.
DeletePersistantAudio
ParameterID: dpa
Indicates that the specified persistant audio segment is
to be deleted.
Type: string
Possible values:
OverrideAudio
ParameterID: oa
Indicates that the specified provisioned audio segment is
to be overridden with a persistant audio segment to be
recorded shortly.
Type: string
Possible values:
RestoreAudio
ParameterID: ra
Indicates that the provisioned audio segment originally
associated with the specified segment id is to to be
restored and that the overriding persistant audio is to
be deleted. This parameter is carried by the play record
signal, although nothing is either played or recorded in
this case.
Type: string
Possible values:
Cromwell expires June 1, 2000 [Page 31]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
2.3.4. EndAudioSignal
SignalID: endaudsig
Causes a play, playcol, or playrec signal to terminate normally.
This signal would be applied for example to gracefully terminate an
open ended playrec. Application of a new signal list (possibly
empty) that did not contain the currently executing signal would
abort the operation; no recording would be saved and no recording
id would be returned to the MGC.
OPEN ISSUE: This type of event is not currently defined in H.248,
however it is clear that mechanisms for both aborting and grace-
fully terminating certain signals are needed.
Parameters:
None
2.4. Statistics
None
2.5. Procedures
None
3. Syntax Rules
1. Parameters to Advanced Audio Package signals may occur in any
order.
2. The following parameters may be have more than one value, i.e.
the value may be an orderded list of values: Announcement (an),
InitialPrompt (ip), Reprompt (rp), NoDigits (nd), No Speech (ns),
Success Announcement (sa), or FailureAnnouncement (fa) parameter
value. These parameters are known collectively as announcement
parameters. The values in parameter list are played from left to
right.
3. An announcement parameter value list may contain the following
types of values: a audio segment id (integer), TextToSpeech value,
DisplayText value, Silence value, Tone value, Variable value,
EmbeddedVariable value, and LocalSelector value.
Cromwell expires June 1, 2000 [Page 32]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
4. There are two types of values in an announcement parameter
list. The first type is a playable value: audio segment id,
TextToSpeech, DisplayText, Silence, Tone, and Variable. The second
type qualifies a playable value: EmbeddedVariable and LocalSelec-
tor. A qualifier value must always be preceeded by a playable
value.
5. Qualifier values apply to the immediately preceeding value in
the list.
6. If an EmbeddedVariable value and a LocalSelector value apply to
the same value, the EmbeddedVariable value always comes first. In
this case the LocalSelector applies to both the value being modi-
fied and the embedded variable.
7. LocalSelector values have precedence over GlobalSelector parame-
ters.
4. Formal Syntax Description
ABNF specification needs to be added.
5. Examples
This section presents a number of examples of how to specify Advanced
Audio Package signals.
Play an announcement that consists of a single segment:
Signals { au/play { an = 39 } }
Play an announcement that consists of multiple segments:
Signals { au/play { an = 39 , 121 , 67 } }
Play an announcement that consists of a recording followed by silence
followed by text to speech followed by a direct voice variable:
Signals { au/play { an = [ 39 , si/30 , ts/hello ,
vb/mny/usd/1995 ] }
Cromwell expires June 1, 2000 [Page 33]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Play an announcement with an embedded variable. If the four segments of
the previous announcement were provisioned as segment 239 with the vari-
able type provisioned as mny and the variable subtype provisioned as
usd, the following would be exactly equivalent to the play in the
preceeding example:
Signals { au/play { an = [ 239 , ev/1995 ] } }
Play an announcement with two embedded variables:
Signals { au/play { an = [ 113 , ev/3999 , ev/20001015 ] } }
Play a prompt and collect a single digit (the default). If need be,
play a reprompt, a no digits prompt, and a success or failure announce-
ment. Give the user three attempts to enter a digit:
Signals { au/playcol { ip = 21 , rp = 109 , nd = 102 , sa = 72 ,
fa = 81 , na = 3 } }
Play a prompt and collect a single digit. If the user does not enter a
digit replay the intial prompt. Give the user three attempts to enter a
digit:
Signals { au/playcol { ip = 21 , na = 3 } }
Play a prompt and record voice. If the user does not speak play a no
speech prompt. Give the user two attempts to record:
Signals { au/playrec { ip = 22 , ns = 42 , na = 2 } }
Play an announcement ten percent faster than normal speed and five per-
cent softer than normal volume. Play the announcement three times with
two seconds of silence between plays.
Signals { au/play { an = 27 , sp = +10 , vl = -5 , it = 3 ,
iv = 20 } }
Give the user two attempts to enter a three digit pattern. Clear the
digit buffer before playing the prompt. The user can signal end of input
using the # key (the default), which is not returned to the call agent
with the collected digits (by default).
Cromwell expires June 1, 2000 [Page 34]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
Signals { au/playcol { ip = 43 , cb = true , mn = 3 , mx = 3 ,
na = 2 } }
Give the user three attempts to enter a three digit pattern. If the
user enters one digits or two digits on the first or second attempts a
reprompt is played. If the user enters no digits on the first or second
attempts a no digits reprompt is played. If all three attempts fail, a
failure announcement is played. If one of the attempts is successful, a
success announcement is played and the collected digits are returned to
the call agent. The user can signal end of input using the # key (the
default). If the # key terminates a successful input attempt, the col-
lected digits, but not the # key (the default), are returned to the call
agent.
Signals { au/playcol { ip = 87 , rp = 5 , nd = 409 , fa = 9 ,
sa = 18 , mx = 3 , mn = 3 , na = 3 } }
Give the user a single attempt to enter a 1 (the default minimum) 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 the
subsequent digit timer expires after the user has less than four digits,
the digits collected are returned to the call agent. The user can sig-
nal end of input using the # key which is not returned to the call agent
with the collected digits.
Signals { au/playcol { ip = 4 , fdt = 80 , idt = 60 , mx = 4 } }
Give the user one chance to enter 2 digits where the first digit is 3,4,
or 5 and the second digit is any digit except 5, 6, or 7.
Signals { au/playcol { ip = 8 , dp = [3-5][^567] } }
Give the user three chances to enter an 11 digit number that begins with
0 or 1. If the user makes a mistake while entering digits, he can press
the * key to discard any digits already collected, replay the prompt,
and resume collection.
Signals { au/playcol { ip = 33 , mn = 11 , mx = 11 , sik = 01 ,
rsk = * , na = 3 } }
Give the user three chances to enter an 11 digit number that begins with
0 or 1. If the user makes a mistake while entering digits, he can press
the key sequence *11 to discard any digits already collected, replay the
Cromwell expires June 1, 2000 [Page 35]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
prompt, and resume collection. If the user enters the key sequence *12
the play collect is terminated along with any queued events, and the
terminating key sequence is returned to the call agent for processing.
Signals { au/playcol { 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 the
prompt, wait 5 seconds for the user to speak. If no speech is detected
replay the initial prompt and try again. If the user does speak, wait
for seven seconds after speech stops to make sure the user is finished.
If the recording is successful, return a reference to the recording to
the call agent.
Signals { au/playrec { ip = 6 , prt = 50 , pst = 70 , rlt = 600 ,
na = 2 } }
Play an announcement in the default language:
Signals { au/play { an = 5 } }
Play the same announcement in the English. In the first example, the
selector applies to the an segment; in the second it applies to the pa
operation. For these particular examples, the net effect is the same.
Signals { au/play { an = [ 5 , lsl/lang/eng ] } }
Signals { au/play { an = 5 , gsl = lang/eng } }
Play an announcement in Danish using a female voice.
Signals { au/play { an = 6 , gsl = lang/dan ,
gsl = gender/female } }
Play the first part of an announcement in English, the second part in
the default language, and the third part in French.
Signals { au/play { an = [ 5 , lsl/lang/eng , 6 , 7 ,
lsl/lang/fra } }
Play an announcement with an embedded variable in English:
Signals { au/play { an = [ 5 , ev/20001015 ] , gsl = lang/eng } }
Cromwell expires June 1, 2000 [Page 36]
INTERNET DRAFT MEGACO Advanced Audio Package December 1, 1999
6. References
[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[2] ITU Proposed Recommendation H.248, Version 12, October 29,
1999.
[3] Cromwell, D., Durling, M., "Suggested Requirements For Control
Of An IVR Function", Version 0.0, April 1999, INTERNET DRAFT.
[5] Greene, N., Ramalho, M, and Rosen, B., "Media Gateway control
protocol architecture and requirements", Version 0.8, October 21,
1999, INTERNET DRAFT.
[6] ISO 639-2, "Code For The Representation Of Names Of
Languages", 1998.
[7] ISO 4217, "Currency And Funds Code List", 1981.
[8] ISO 8601, "International Date and Time Notation", 1998.
[9] Tools.h++ Class Reference Version 7, Rouge Wave Software Inc.,
1996.
[10] ANSI/IEEE Standard 1003.2 (Portable Operating System
Interface), Version D11.2, September 1991.
7. Author's Address
David Cromwell
Nortel Networks
Box 130010
35 Davis Drive
Research Triangle Park, NC 27709
Email: cromwell@nortelnetworks.com
Phone: (919) 991-8870
Cromwell expires June 1, 2000 [Page 37]
