AGTDDE - Feature Reference

This program provides a way for applications that can send text strings via DDE to control a Microsoft Agent V2 character, including its text-to-speech capabilites. No support for spoken text recognition and action is provided by this program. It was originally designed to be used with the ViRC program, allowing scripts to send channel text to Agent for text-to-speech rendering.

Introduction

Speech sent to AGTDDE can be altered by the program prior to sending it to the Agent character for speaking. For example, "http://a.b.c" would normally be spoken "H T T P slash slash A B C". AGTDDE can explicitly convert the ':' to "colon" and '.' to "dot" when not at the end of a sentence or at the end of text, resulting in a naturally spoken URL. The program has an area in the registry where it keeps these substitutions. See the Installation instructions on how to load the supplied starter set of substitutions suitable for IRC use.

This program can do a lot more than just send text to an Agent character for rendering into speech. It can control the Agent character in other ways by using special commands at the beginning of incoming text. For example you can play defined animations for characters. I have attempted to map much of Agent's COM interface methods into the special commands. In addition, the Microsoft Speech API (SAPI) defines in-text speech modifiers that can alter the rendered speech. Agent uses SAPI, so you can use these modifiers.

Examples:
    Move the character:     :moveto 200 300 1000
    Play an animation: :play Confused
    Speak quickly: Now I \spd=200\speak quickly\rst\

The Lernout and Hauspie TruVoice text-to-speech engine V6 supplied with Agent V2 is fully functional with the Speech API, so I have included some special commands for accessing the speech engine's management/maintenance dialogs via the ITTSDialogs interface.

Queueing of Animations and Speech:

It's important to understand that Agent queues animation and speech requests and plays them asynchronously, without slowing down your program. It is possible to load up the queue with lots of requests, making it look like the character is out of control. Use the :stop command to immediately stop the current animation or speech and flush the pending queue.

Special Commands:

Special commands are text strings that start with a colon (':'). The colon must be the first character in the text string sent to agtdde. The commands are case sensitive. Invalid commands or arguments generally result in a spoken error message. For example, if you send an unrecognized command, the character acts confused and says "colon what?"

The following are the supported special commands (items in [...] are optional).

    :play animation Plays a named animation. For the names of animations you can play see the documentation for the character you are using. Looping animations must be stopped with the :stop command. Unhides the character if hidden.
    :stop Immediatly stops the current animation or speech and flushes the pending queue. This is most often used to stop "looping" animations.
    :think text Displays the following text in the character's word balloon (if enabled) without speaking it. Does nothing if the balloon is disabled (through the Agent Property Sheet).
    :rawspk text Speaks the following text without making the Lexicon substitutions ("raw speak"). Speech modifiers in the text are still processed.
    :plysnd file [| text] Plays a sound (.wav file) through Agent and moves the characters mouth so it looks like he is speaking the sound!. If you know how to make "language-enhanced" (.LWV) files, you can play these, and they can contain text to show in the balloon. If the file name is followed by a vertical bar then text, the text will show in the balloon while the sound plays. This will override text in an LWV file.
    :show Unhides the character using an an animation.
    :hide     Hides the character using an an animation. He cannot speak when hidden.
    :idle ON|OFF Controls the idle animation of the character. Normally, characters move around while they aren't doing anything. You can turn this off and back on. Default is ON.
    :seff ON|OFF Controls whether the character's animation sound effects (if any) will be played along with the animation. You can turn this off and back on. Default is ON.
    :moveto X Y [speed] Perform an animated move of the character to the indicated screen coordinates. The speed argument is optional, and defaults to 1000 (1 sec. between steps). Lower speed numbers mean faster movement. Unhides the character if hidden.
    :setpos X Y Immediately changes the character's position to the indicated screen coordinates (no animation). This will work while the character is hidden, and it will not unhide the character.
    :setsize W H Immediately changes the size of the character. If W and H are 0 and 0, the character is restored to its default size.
    :char [pathname] Changes the character. If the optional pathname argument is given, attempts to open the Agent character file given by pathname and load it. If this fails, or if no argument is given. a character file selector box is displayed. Clicking cancel in this box leaves the current character active. NOTE: The current character is immediately vaporized, you may want to first hide it (using :hide). The new character starts out invisible, you must show it (using :show). This allows you to fiddle with it before it appears.
    :agtprop Opens the Agent property sheet. This allows you to change various interesting things about Agent and your character.
    :gendlg Displays the TTS engine's built in "general" dialog using the ITTSDialogs::GeneralDlg method.
    :lexdlg Displays the TTS engine's built in "lexicon" dialog using the ITTSDialogs::LexiconlDlg method.
    :abtdlg Displays the TTS engine's built in "about" dialog using the ITTSDialogs::GeneralDlg method.
    :tradlg Displays the TTS engine's built in "translate" dialog using the ITTSDialogs::TranslateDlg method.

Speech Modifiers

SAPI defines a set of standard speech modifiers that you can embed into the text you send to Agent through agtdde. Some engines do not support all of these modifiers. The Lernout and Hauspie TruVoice engine supports many if not all of them.

Note that the Lernout and Hauspie TruVoice engine does quite a good job of altering the speech tone and speed based on punctuation. Experiment with punctuation before resorting to these tags.

The most useful speech modifier tags available from Agent are:

    \chr="string"\ Changes voice characteristic. Legal values are "Normal" (default), "Monotone", and "Whisper". Quotes are required.
    \ctx="string"\ A string specifying the context of the text that follows, which determines how symbols or abbreviations are spoken. Legal values are "Address", "Email", and "Unknown" (default). Quotes are required.
    \emp\ Emphasizes the next word spoken. This tag must immediately precede the word.
    \map="spoken"="balloon"\ (:rawspk only) Maps spoken text to text displayed in the word balloon. This tag enables you to use different spoken text than that displayed in the word balloon. Quotes are required. WARNING: Normal speaking uses the Substitution Database, which uses \MAP...\ to put the unmodified text into the balloon. Therefore, use this modifier yourself only with the :rawspk command.
    \pau=nnn\ Pauses speech for the specified number of milliseconds. The Lernout and Hauspie TruVoice engine supports values from 10 (0.01sec) to 2550 (2.55sec).
    \pit=nnn\ Sets the baseline pitch of the output to the specified value in hertz. The Lernout and Hauspie TruVoice engine supports values from 50 to 400.
    \rst\ Resets all tags to the default settings.
    \spd=nnn\ Changes speech rate to to nnn words per minute. The Lernout and Hauspie TruVoice engine supports values from 50 to 250.
    \vol=nnn\ Baseline speaking volume: 0 is silence and 65535 is maximum volume. The volume setting affects both left and right channels.

Substitution Database

AGTDDE can make substitutions in the text to be spoken, helping to produce more natural renderings. The substitution database is in the registry under

    HKEY_LOCAL_MACHINE
        Software
            Denny
                AGTDDE
                    Lexicon
Each substitution is represented by a named string (REG_SZ) value. The name must be the ASCII decimal representation of an integer. The value is a string that consists of the text to replace and the replacement, separated by a backslash. For example
    0020    "www.\ triple w dot "

Note that the substitution in this case has leading and trailing spaces. You should normally include them.

The names of the values are interpreted as a "priority", with lower numbered substitutions being performed first. AGTDDE reads in all of the substitution entries from the registry, converts the names to integer values, and then sorts on those integers. The correction order is the result of this sort. 0 will always be the first correction applied. Leading zeroes in names are ignored. The name strings must be decimal (base 10); octal and hex are not allowed, nor are numbers containing decimal points.

The supplied file lex.reg contains a set of substitutions you can use as a starting point for IRC applications. Double-click this file to add those substitutions to the registry.

EXAMPLE:
Be sure and click Lex.reg to install the registry defaults
Click on lex.reg to install the defaults into the windows registry.


For ManifoldScript2006 Extra Features Click Here!