DECtalk Software includes voice-control commands, also called inline commands. You can use these commands to perform simple voice-control operations, such as changing the speaking rate or speaking voice while DECtalk Software is speaking. Commands are inserted into ASCII text files displayed in one of the program applets or directly into the application sources through the API functions.
DECtalk Software also has a more complex set of voice-control commands to modify the characteristics of each voice, control intonation and stress within written text, or to create special effects, such as singing.
Commands have special syntax rules and components that you need to use when you insert them into files.
Commands are synchronous unless otherwise stated. Also, when you use several commands together, they might interact with each other and affect the output. If incorrect syntax is used in a command, the right bracket ( ] ) is ignored as it might be considered part of the illegal string. To fix this situation, insert an extra right bracket ( ] ) in the command and set the [:error] command on.
Table A-1 DECtalk Software Voice-Control Commands
Command Function Play Wave Files Plays wave files embedded in text strings Tone Creates tones of a specified length and frequency Dial Tones Dial telephone numbers Comma Pause Inserts a comma pause into spoken text. Error Sets the error mode for a module. Index Mark Inserts marks, which are recognized by the application, into text. Log Sets logging modes for the module. Mode Allows uppercases words to be interpreted for special use. Pause Pauses the audio output of the module. Period Pause Inserts a pause equivalent to a period in a sentence into spoken text. Phoneme Interpretation Allows everything within brackets to be interpreted as phonemic text. Pronounce Alternate Speaks alternate pronunication of a word Pronounce Name Pronounces words as proper names. Punctuation Turns punctuation on and off. Rate Selection Selects speed at which text is spoken Resume Resumes speech after a pause. Say Mode Allows DECtalk to speak words before they are queued. Synchronization Synchronizes activity between and DECtalk and an application program Voice Selection Selects the voice. Volume Sets the volume.
This command increases or decreases the length of the comma pause. Comma pause can be increased and decreased. [:cp 0] resets the comma pause to its default state (approximately 160 ms). Comma pauses can be increased to 30,000 ms and decreased to -40 ms. All values outside legal range default to the nearest legal values.
SYNTAX
[:comma DDD] or [:cp DDD]
OPTIONS
None
PARAMETERS
Pause time in milliseconds
DEFAULT
160 ms
EXAMPLES
[:comma 250]
This command sets the error mode for the module. This command is useful for debugging an application.
SYNTAX
[:error XX YY]
OPTIONS
ignore Ignore all errors. speak Speak error string in current command. tone Generate tone if error.
PARAMETERS
on Absolute mode off Enable mode set Disable Mode
DEFAULT
off
EXAMPLES
[:error ignore on]
Index marks are used to report the progress of the text as it is spoken. Index marks are position markers; they do not modify heuristics or word pronunciations in any way. The index mark sequence inserts a flag into the text stream. When DECtalk encounters an [:index mark 01] command, a message is sent to the user's callback function corresponding to the callback function passed in the TextToSpeechStartup() function. The LPARAM field of the message contains the index value. The index mark value can be any number between 00 and 99. If a callback function is not specified in the TextToSpeechStartup() call, index marks in the text are ignored.
SYNTAX
[:index mark DD]
OPTIONS
None
PARAMETERS
Value = DD
DEFAULT
None
EXAMPLES
[:index mark 01]
The in-line log command is used to log either text, phonemes, at a time. This command will not open a file if any other Text-To-Speech file is open or if the system is in speech-to-memory mode. In these cases, the in-line [:log XX on] command will be discarded and the in-line [:log XX off] command will cause an error.
Example;
[:log phonemes on] The phonemes for this sentence will be stored in a file named log.txt [:log phoneme off]
SYNTAX
[:log xx yy]
OPTIONS
text Log all text except escape sequences (Earlier versions of DECtalk Software used escape sequences for control). syllable Log converted syllables. s phonemes Log converted phonemic text.
PARAMETERS
on (Absolute mode) off (Enable mode) set (Disable Mode)
DEFAULT
off
EXAMPLES
[:log text on]
This command changes the mode for all text processed after the mark. It remains until to the end of the file is reached or until the next mode command is encountered.
SYNTAX
[:mode XX YY]
OPTIONS
Description
math Change interpretation of selected symbols europe Select European cardinal pronunciation spell Spell all words name Pronounce all uppercase verbs as proper nouns
see also [:pronounce name]) homograph Reserved for future use
PARAMETERS
on Absolute mode off Enable mode set Disable Mode
DEFAULT
off
EXAMPLES
[:mode spell on]
Europe Mode Example
When mode is set to Europe, a comma (,) is the separator between the integer and fraction part of a number. A period (.) is the separator between three- digit blocks.
1.255 (United States) = 1,255 (Europe) 125,873 (United States) = 125.873 (Europe)
Math Mode Example
Math takes special symbols and characters and pronounces them with mathematical meanings. Specifically, the following characters are treated differently:
Symbol Name DECtalk Software Says... + plus plus (no change from normal speech) - hyphen minus * asterisk multiplied by / slash divided by ^ circumfl to the power of ex < less less than than > greater greater than than = equal equals sign % percent percent sign . period decimal point xxE-xx (spelled (scientific notation) )
Note
Do not enable [:mode name] except when pronouncing lists of names. Mode Name interprets any uppercase word as a name. When finished, make sure that this mode is set to OFF. For the occasional use of this utility, use the [:pronounce name] command. Mode commands are asynchronous.
This command pauses the audio output. Any pending but unspoken text is retained, including index marks that might have been sent by the application. All text that occurs after the pause is not processed until the pause time is exceeded. Unlike previous versions of DECtalk hardware products, the in-line pause command is a synchronous command. This means that all text which occurs after the pause is not processed until the pause time is exceeded.
SYNTAX
[:pause DDD]
OPTIONS
None
PARAMETERS
Pause time in milliseconds; 0 = forever
DEFAULT
None
EXAMPLES
[:pause 1000] Pause for one second.
The length of the period pause can be increased and decreased with the Period Pause command. This command [:pp 0] resets the period pause to its default state (approximately 640 ms). Period pauses can be increased to 30,000 ms and decreased by -380 ms. All values outside the legal range default to the nearest legal values.
SYNTAX
[:period DDD] or [:pp 0]
OPTIONS
None
PARAMETERS
Pause time in milliseconds
DEFAULT
640 ms
EXAMPLES
[:period 250]
When set, this command allows everything within brackets to be interpreted as phonemic text. When phonemicizing text, simply put legal phoneme strings in brackets. This allows for the preferred pronunciation of a word or phrase. This command is extremely important because it sets the left bracket ( [ ) and right bracket ( ] ) characters as phoneme delimiters. When this command is set, all text and characters that appear between brackets is interpreted as phonemic text and is pronounced as such. This is useful when you do not want to turn this command on but want to have something read phonetically. For example, to say the word associate, simply embed the phonemic string [axs'owshiyeyt] in the text string.
SYNTAX
[:phoneme XX YY] or [:phoneme on] or [:phoneme arpabet on]
OPTIONS
ASCI Reserved for future use. arpabet Set phonetic interpretation to arpabet alphabet. speak Speak encountered phonemes. silent Do not speak encountered phonemes.
PARAMETERS
on Set phoneme interpretation on off Set phoneme interpretation off
DEFAULT
off
EXAMPLES
[:phoneme arpabet speak on]
Note
Make sure that you use a right bracket after entering phonetic text when this command is set. If you do not, any normal text appearing after the right bracket will sound garbled. One right bracket is sufficient to close phonemic mode. It is sometimes useful to begin a text file with a right bracket (]) to ensure that text is not interpreted phonetically. Also, the command sequence consisting of a left bracket followed by a colon ([:) is always interpreted as the beginning of a voice command. Default for phoneme mode is Off, and it must be turned On by a special command.[:phoneme on] is an abbreviated version of the [:phoneme arpabet speak on] command.
This command pronounces the alternate pronunciation for the word immediately following it. Use a [:pron alt] to obtain an alternative pronunciation for a word listed in the Homograph table in Chapter 6. For example, the primary pronunciation of the word wind is w'ihnd, as in 'the wind is blowing'. The secondary pronunciation, denoted by [:pron alt] wind, is w'aynd, as in 'wind up the top'.
SYNTAX
[:pron alt]
OPTIONS
None
PARAMETERS
None
DEFAULT
Off
EXAMPLES
He played [:pron alt] bass in the band.
This command pronounces the word immediately following it as a proper name. First names, last names, street names, and place names are all examples of proper names. This command can be used when DECtalk Software mispronounces a proper noun.
Note
This command must be used each time a new name is encountered but is also useful when the location of a name field is known.
SYNTAX
[:pron name]
OPTIONS
None
PARAMETERS
None
DEFAULT
Off
EXAMPLES
Terry [:pron name] Aresenault
Unlike previous versions of DECtalk hardware products the resume command is a synchronous command. Thus the Resume command will not restart the system after an in-line pause command. The in-line resume command may be used if the computer is not fast enough to run real time and the amount of text is not greater than approximately 256 characters. In this case the system would be paused by the TextToSpeechPause() function before queuing text by the TextToSpeechSpeak() function and the in-line resume command would be placed at the end of the text message. If the text is too long then the in-line resume command may never be processed.
Code Example:
TextToSpeechPause( phTTS ) /* Pause the system */
TextToSpeechSpeak( phTTS, "This is a slow computer. [:resume]", TTS_FORCE );
SYNTAX
[:resume]
OPTIONS
None
PARAMETERS
None
DEFAULT
N/A
EXAMPLES
[:resume]
In DECtalk each clause, word, or letter is spoken as it is queued. In word and letter mode, DECtalk does not need to wait for a clause terminator to begin speaking. This command interacts with the rate selection command so that you can set both rate selection and speak word or rate selection and letter mode for the optimal output.
Word mode is similar to letter mode except text is spoken a word at a time. A space after a character or string of characters causes that string to be spoken. This mode interacts with the rate selection command so you can increase or decrease the rate at which letters or words are spoken. In clause mode, speaking starts when DECtalk is sent a clause terminator (period, comma, exclamation point, or question mark) followed by a space. There is no time-out limit. This is the normal mode where text is spoken a phrase, clause, or sentence at a time. Clause mode is the default.
SYNTAX
[:say XX]
OPTIONS
put a table bozo
clause Speak on end of clause. word Speak on end of word. letter Speak on end of letter. line Speak on end of line.
PARAMETERS
None
DEFAULT
[:say clause]
EXAMPLES
[:say word]
Note
In [:say letter] mode, the left bracket is spoken only after the next character is entered because DECtalk needs to know if this is the beginning of a new command.
This command increases or decreases the length of the comma pause. Comma pause can be increased and decreased. [:cp 0] resets the comma pause to its default state (approximately 160 ms). Comma pauses can be increased to 30,000 ms and decreased to -40 ms. All values outside legal range default to the nearest legal values.
SYNTAX
[:comma DDD] or [:cp DDD]
OPTIONS
None
PARAMETERS
Pause time in milliseconds
DEFAULT
160 ms
EXAMPLES
[:comma 250]
This command allows the current speaking voice to be changed to one of nine built-in DECtalk Software voices. x represents the letter variable for each voice. The letter variable is the first letter of the voice.
SYNTAX
[:name X] or [:n X]
OPTIONS
Speaker Value Description
insert a table here
PAUL p Default male voice HARRY h Full male voice FRANK f Aged male voice DENNIS d Male voice BETTY b Full female voice URSULA u Aged female voice WENDY w Whispering female voice RITA r Female voice KIT k Child's voice
PARAMETERS
None
DEFAULT
PAUL
EXAMPLES
[:name KIT],[:nk]
DECtalk changes the audio system gain in increments from 0 to 99. Increments or decrements of 10 to 20 provide a perceptual increase or decrease in volume. The volume command is an absolute command; [volume up] and [volume down] are relative commands and increase or decrease the original value. This does not affect the volume when writing wave files or using the speech-to- memory capability.
Stereo Volume Control
The following monaural volume commands were supported in DECtalk Software V4.1.
[:volume set XX] Set left and right channel volume to XX
[:volume up
XX] Raise left and right channel volume by XX
[:volume down XX] Lower
left and right channel volume by XX
where XX is always from 0 to 99.
The following stereo commands have been added to DECtalk Software 4.2.
[:volume lset XX] Set left channel volume to XX
[:volume lup XX]
Raise left channel volume by XX
[:volume ldown XX] Lower left channel
volume by XX
[:volume rset XX] Set right channel volume to XX
[:volume
rup XX] Raise right channel volume by XX
[:volume rdown XX] Lower right
channel volume by XX
[:volume sset XX, YY] Set left channel volume to XX
and right channel volume to YY.
The volume commands are synchronous commands.
The volume may not be raised
above 99 or lowered below 0.
Any attempt to do so will result in limiting to
these values.
SYNTAX
[:volume XX DD]
OPTIONS
put a table hereset Sets the volume to the desired level
up Increases the volume by the desired amount down Decreases the volume by the desired amount
PARAMETERS
Volume or delta volume
EXAMPLES
[:volume up 30]
This command plays any wave file that is supported by your computer's audio system. The command is synchronous. This command does not work if the Text-To-Speech system is writing a wave file or writing the speech samples to memory.
SYNTAX
[:play <file>]
OPTIONS
none
PARAMETERS
A directory path and file name.
DEFAULT
none
EXAMPLES
[:play bell.wav][:play /usr/examples/noise.wav]
This command generates tones called Dual Tone Multiple Frequency (DTMF) Tones or Touch-Tones(™). These tones can be used to dial a telephone. Any non-tone character (0 to 9, #, *, or A, B, C, and D ) generates a silent interval between dialed digits. The dial tone command is synchronous. The tones are the touch-tones for 0-9, #, *, and A, B, C, D (in uppercase only) for handsets that contains these.
SYNTAX
[:dial X]
OPTIONS
None
PARAMETERS
String of dial characters (0-9, A, B, C, D, #, *)
DEFAULT
none
EXAMPLES
[:dial 508-555-1212]
This command generates sounds of different frequencies and lengths based on the parameters you set. This command allows you to make a wide variety of sounds for purposes such as notification or warnings. Regular tones can also be used for a number of other purposes such as indications of margin bell, etc.
COMMAND
[:tone FF, DD]
OPTIONS
None
PARAMETERS
Frequency: Tone frequency in Hertz Duration: Tone duration in milliseconds
EXAMPLES
[:tone 500,500]