Title Page Preface Chapter 1 Chapter 2 Chapter 3 Chapter 4 Appendix A Appendix B


Appendix A:
DECtalk Software Voice Control Commands


Voice-Control Commands: Overview

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.                  


Comma Pause

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]


Error

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 Mark

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]


Log

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]


Mode

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)                 
                )                                               


Mode Name Example

Mode name allows uppercase words that occur in non sentence initial position to be interpreted as special cases and pronounced as names.

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.


Pause

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.


Period Pause

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]


Phoneme Interpretation

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.


Pronounce Alternate

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.


Pronounce Name

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


Resume

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]


Say Mode

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.


Comma Pause

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]


Voice Selection

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]


Volume

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]


Play Wave Files

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]


Dial Tones

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]


Tone

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]