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 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/ DisplayText ValueTag: dt Specifies a text string to be displayed on a device. Syntax: dt/ Silence ValueTag: si Specifies a length of silence to be played in units of 100 milliseconds. Syntax: si/ 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/// 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." 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/ 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/ 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// 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=/ 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// Possible values: : 0-9,*, or # : 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]