#### 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]