Voice output instructions

In this section, instructions that control speech output are described. These instructions send voice data to the telephony cards. Each description is followed by a brief example using that instruction. An example at the end of this section illustrates how the instructions described here might be used in a script.

• tfile(" li stfile 1" [,"listfile2" ... ])

The tfile instruction specifies the speech database to use for the script. The first phrase listfile name, called listfile 1, is the name of the primary listfile. Its talkfile number is the default talkfile for speech referenced by phrases and is used for tnum, tchar, and talk instructions if the talkfile portion of the phrase ID is 0 (unless the talkfile number is changed later by a setalk instruction).

Each phrase in the talkfile is identified by a unique number and string in the phrase listfile. Because TAS uses this information, the tfile instruction must be specified in the script before the first voice output instruction.

The phrase listfile usually is named application_name. pl. Phrases in the primary listfile are not bound to the talkfile when the script is compiled. They are played from the talkfile currently in effect when the talk instruction is executed. However, any additional listfiles given in the file instruction have the talkfile and phrase number bound when the script is compiled. Phrases selected from these listfiles are not affected by changes in the talkfile that occur during script execution.

The following is an example of the tfile instruction:

tfile("list.stocks")

This instruction tells the TAS to use the list.stocks speech database for the next transaction.

• tchars( ctype.src [, type.inflection ])

The tchars instruction puts its first argument into a queue for speaking. The first argument is a null terminated string of alphanumeric characters. This character string is spoken character-by-character, for example, letters and digits. The second argument, when specified, controls the speech inflection.

Speech Inflection values are listed in the following table. The default for the inflection is m for medial.�

Inflection	One Phrase	Multiple Phrases
r	Rising	Rising on first, medial on others
m	Medial	Medial on all
f	Falling	Falling on last, medial on others
t	Falling	Rising on first, falling on last, medial on others

The following example of the tchars instruction directs the script to speak the contents of INITIALS with falling inflection on the last character and medial inflection on all other characters.

tchars(INITIALS,'f')

• tnum( type.src{ [,type.inflection][,type.style]} )

The tnum instruction puts the phrases that speak the numeric value, specified by the first argument, in a queue. It interprets the numeric value of the first argument and selects recorded phrases that say the number in a natural way. For example, 202 is a number that is spoken as a single phrase -- two-hundred-two. The second argument, when specified, controls the speech inflection. The optional type.style argument specifies the speech coding style.

Note:
The tnum instruction does not interpret numeric values in any language other than English because the rules for concatenating numbers varies depending on the language. The Enhanced Basic Speech package currently includes numbers 1-20, 30, 40, 50, 60, 70, 80, 90, 100, 1000, and 10000. This method forms numbers by combining these standard phrases.

The tnum instruction uses the same arguments for inflection as the tchars instruction.

The tnum instruction does not support speaking numbers in the billions and trillions because most of these numbers are too big to fit into an integer variable. However, the phrases billion and trillion are included in the Enhanced Basic Speech package. If your script requires such large numbers, we suggest that you start with an ASCII string, parse the string (getting the amounts of billions and trillions as substrings), then convert the three resulting substrings to integer values and speak them with the tnum instruction. Insert a talk instruction with the phrase for trillion or billion, where appropriate.

In the following example, the tnum instruction tells the script to speak the numeric value of int.FOUR with falling inflection on the last character and medial inflection on all other characters:

load(int.FOUR, 4)
tnum(int.FOUR,'f')

• talk(type.src [,type.style] )

The talk instruction uses the type.src argument to specify the phrase to be spoken. The second optional argument, type.style, is the coding style of the speech to play back.

Two examples of the talk instruction are:

talk(10)
talk(11)

"Hello this is the Avaya IR system"
"Please enter your ID "

To simplify writing the talk instructions used in matching the phrases in the application_name. pl file with the phrase_name arguments in the talk instruction, the talk arguments may be abbreviated. In this process, except for the final period or question mark, punctuation is for reference only and is ignored. Each character or word must be separated by a space. Also, uppercase characters are converted to lowercase characters.

Two ways of writing the talk instruction for the first example are:

talk("Hello, Avaya IR system")
talk("h, l s")

Words may be eliminated, but the words or abbreviations used must be written in the same order as in the application_name.pl file. They match as long as the argument has enough of the key words in the desired phrase.

The following examples illustrate an abbreviated talk instruction.

talk("h l s")
talk("Hello Avaya IR system")

Only the first letter of a word needs to be used in matching a phrase. Note in the following examples that although each phrase would match, a person reading these instructions would find it helpful to see more than just the first character.

talk("H I 1")
talk("H I 1 S")

Although only the first letter of each word must be specified, it is recommended that you spell the phrase to the extent that it is uniquely identifiable.

talk( type.src )

This version of the talk instruction can be used where there is a variable phrase number. Instead of entering the phrase_name to identify the speech to be queued for the telphony card, the corresponding number found by the phrase_name in the application_name.pl file can be used.

An example of the talk instruction is:

#define PHRASE 40
.
.
.
talk(int.PHRASE) /*speaks the application_name.pl file*/
/*phrase the number of which is found at*/
/*address 40*/

• tflush([ must_hear_flag][,wait_indicator][,remember_flag] )

The tflush instruction typically follows a talk, ftalk, tnum, or tchars instruction to force queued phrases to be spoken that could otherwise be terminated by a touch-tone signal sent by the caller. Under normal operating conditions, a touch-tone signal terminates any speech activity (voice play or voice coding) on that channel. This feature usually is referred to as talkoff. Integer variables or registers, as well as literals, may be used for arguments to tflush.

The tflush instruction also causes queued speech to be output as do the other wait causing instructions. Thus, tflush can be used to force speech to be spoken at appropriate points in the script.

The three optional arguments to tflush can be set to the values listed in the following table. If tflush is used without any arguments, the default value of 0 is used for all arguments.�

Argument	Value	Value Result
must_hear_flag	0	Touch tones entered during play or voice coding cause play or voice coding to stop (default).
	1	Touch tones entered during play or voice coding do not cause play or voice coding to stop.
wait_indicator	0	Wait for the play to complete before continuing script execution (default).
	1	Do not wait for the play to complete. Continue script execution immediately after queuing.
remember_flag	0	Remember phrases played by this instruction so they may be played again with the talkresume instruction.
	1	Do not remember the speech.

The must_hear_flag option, when set to a non-zero value, disables talkoff so that speech activity (voice play or voice coding) on the current channel is not stopped by touch tones. When this option is used with speech play-related instructions (talk, tnum, tchars), a tflush(1) should follow those instructions. When using tflush with voice coding (vc), tflush(1) should precede the vc instruction. The talkoff is enabled automatically by the next wait-causing instruction in the script.

Note that if talkoff is disabled, speech play may interfere with incoming touch tones. Unless the setttfl instruction is used to enable the type-ahead feature, playing new speech causes any touch tones that have been typed up to that point to be deleted.

The tflush wait_indicator option, when set to a non-zero value, allows the script to start a play, then continues script execution immediately without waiting for completion of the play. By using a wait_indicator of 0, which is the default, the script does not start execution until a play complete message is received.

The tflush instruction stores a return value in register 0. If the value is negative, an error has occurred. If the value is +1, the play complete was caused by talkoff. If the value is 0, play completed successfully.

The following are examples of the tflush instruction:

talk("You must hear this announcement before continuing")
tflush(1) /*does not end play if caller enters a */
/*touch tone*/

tflush(1) /*do not end coding if user enters touch */
/*tones*/
vc('b',10,ADPCM32)

Note:
In the second example, any touch tones entered are encoded along with the speech.

• talkresume( type.offset )

The talkresume instruction plays whatever phrases remain from the last tflush instruction starting at the point they were interrupted (that is, by talkoff) plus the given offset in seconds. If the offset is a positive number, speech is played from a point after the interruption. If the offset is a negative number, speech is played from a point before the interruption. If the offset is 0, play starts at the point where the interruption occurred. If all of the phrases have been played, only a negative offset has any effect. For example, this allows a developer to include a fast forward or rewind feature into speech playing.

The talkresume instruction stores a return value in register 0. If the value is negative, an error has occurred. If the value is 0, play completed successfully. If the value is +1, the play complete was caused by talkoff. If the value is +2, there was no speech left to play (that is, talkresume was given with a non-negative offset when all the speech had been played already).

For talkresume to work properly, the speech it affects must have been played originally with the tflush instruction with the optional remember_flag argument set to 1. This tells the system to remember the speech that tflush tells it to play and to keep track of where that speech is interrupted. Subsequent calls to talkresume then have the desired effect on this speech. The system remembers the speech it was playing until it receives another set of phrases to play by subsequent script instructions. Only one set of phrases can be remembered per channel at a time. (Here, a set of phrases constitutes whatever phrases were played by the previous tflush instruction.)

Note:
The talkresume instruction cannot be used to resume TTS play.

• tstop( [type.scr ])

The tstop instruction lets the script developer stop any speech activity on the current channel.

The following is an example using the tstop instruction:

talk(int.MUSIC) /* Play music to the caller */
tflush(1,1) /* Do not let touch tones turn off music
and don't wait */
dbase(0, FUDB, ch.ACCOUNT_ID, 8, int.SELL_PRICE, 4)
/* Get info from host */
tstop(1)
talk("Your account has now been credited with Avaya stock for the price of")
tnum(int.SELL_PRICE)

In this example, the script wants the caller to hear music while it processes the transaction with the host computer. After this processing completes, the music is stopped, and the caller is informed of the results.

• setalk( type.talk )

The setalk instruction is used to specify a new talkfile for talk instructions. The type.talk argument is the id of the new talkfile. After setalk is executed, the previous talkfile id is returned in r.0 and can be saved for future use. The setalk instruction overrides the talkfile number contained in the first listfile specified in the tfile instruction.

• setftalk( ctype.src )

The setftalk script instruction specifies a new prepend directory for the fsay and ftalk instructions. The argument, ctype.src, is the full pathname of the prepend directory. The prepend directory cannot be longer than 128 characters. When a relative pathname is given to fsay or ftalk, the sum of lengths of the prepend directory and the relative pathname cannot exceed 128 characters.

� 2002 Avaya Inc. All Rights Reserved.