XtrAgent Documentation

XtrAgent™ version 2.0 Documentation

Developed by Tomer Berda, Copyright (C) DirectXtras Inc. 1998-99.

Last updated: 5.2.99

XtrAgent is an Asset Xtra which enables the use of Microsoft's revolutionary "Agent" technology in Director, Authorware and Shockwave applications, that provides a foundation for more natural ways for people to communicate with their computers.

XtrAgent adds a new type of member to your cast - Agent.
Agent is an interactive animated character that can be drawn on top
of all other sprites and windows and even outside of the stage area.
It can speak, via a text-to-speech engine or recorded audio, and accept spoken voice commands.
Agents can be used as guides, coaches, entertainers, or other types of assistants or specialists.

Using XtrAgent, developers can utilize Text-To-Speech & Speech Recognition engines and freely distribute them with their applications!

In addition, XtrAgent provides powerful animation capability and interactivity, with support for high-quality lip-synching at an incredible ease of development. It comes with ready-to-use characters and also support custom characters that developers can create using the Microsoft Agent character editor.

XtrAgent is available for Windows 9X & NT. It is possible to use it along with the MacOS version of Xpress Xtra to have a cross-platform Text-To-Speech solution.

XtrAgent Installation

Locate your Director\Xtras and/or Authorware\Xtras folder.
In this folder, if not exists already, create a new folder named "DirectXtras".

Copy the authoring or trial version of XtrAgent to the "DirectXtras" folder you've just created.

If you didn't already, follow the instructions located at the XtrAgent home page to download and install the Microsoft Agent core components, text-to-speech engine, speech recognition engine and character files.

# Getting Started

Before starting, if you're using Director 5 or 6, you should configure Director's authoring environment to properly display external palettes in 256 color mode. This can be done by editing the DIRECTOR.INI file, which is located in the same directory of your Director application. You need to edit the palette section to look like:

[Palette]

Animation=0

; 1: allows director to take control of the palette for fast palette effects and transitions.

; 0: prevents director from taking control of the palette so other apps, wallpaper etc. look better but palette effects and transitions will be slower.

You will need to include a copy of this modified DIRECTOR.INI file with your Projectors.

It is also recommended to enable the "Animate in Background" option. This can be done by selecting the FILE->PREFERENCES->GENERAL menu in Director and checking the "Animate in Background" option.

Animation Services

XtrAgent's animation services manage the animation and movement of a character's image in its own window on the screen. An animation is defined as a sequence of timed and optionally branched frames, composed of one or more images.

### Loading a Character

To animate a character, you must first load the character file into a cast member/icon. From the Insert menu, select DirectXtras->XtrAgent. A Dialog Box will appear, prompting you to choose an Agent character file to associate with this cast member/icon. XtraAgent supports single structured character files (.ACS).

After choosing an Agent character file, a new cast member/icon will appear. It has the XtrAgent icon, and the name of the character you've just insert. In Director, you can click on it and drag it to the score. A new sprite will be created on your score window, presenting the Agent character, and you can adjust the position and the size of the character directly in the score.

Applications can load only a single instance of the same character. Therefore, any attempt to load the same character into more than one sprite will fail.

Microsoft Agent provides a set of characters you can download and use, subject to the provisions of the license agreement. The Microsoft Agent Characters can be downloaded from the Microsoft Agent Web site at http://msdn.microsoft.com/msagent/characterdata.asp.

You can also define your own characters for use with Microsoft Agent. You may use any rendering tool you prefer to create the images, provided that you end up with Windows bitmap format files. To assemble and compile a character's images into animations for use with Microsoft Agent, use the Microsoft Agent Character Editor. This tool enables you to define a character's default properties as well as define animations for the character. You can download the Microsoft Agent Character Editor from the Microsoft Agent Web site at http://msdn.microsoft.com/msagent/agentdevdl.asp.

### Loading the Default Character

Instead of loading only a specific character directly by specifying its filename, you can load the default character. The default character is a service intended to provide a shared, central Windows assistant that the user chooses. Microsoft Agent includes a property sheet as part of the default character service, known as the Character Properties window, which enables the user to change their selection of the default character.

Selection of the default character is limited to a character that supports the standard animation set, ensuring a basic level of consistency across characters. This does not exclude a character from having additional animations.

However, because the default character is intended for general-purpose use and may be shared by other applications at the same time, avoid loading the default character when you want a character exclusively for your application.

To load the default character, create a new member/icon from your scripts without specifying a filename, or set the File member/icon property to an empty string. XtrAgent automatically loads the current character set as the default character. If the user has not yet selected a default character, XtrAgent will select the first character that supports the standard animation set. If none is available, the method will fail and the File member/icon property will be set to comma (","), indicating that no character file was loaded.

Although a client application can inquire as to the identity of the character, only a user can change its settings. You can use the ShowDefaultCharacterProperties member/icon method to display the Character Properties window.

XtrAgent will notify applications that have loaded the default character when a user changes a character selection, and pass the GUID of the new character. Agent automatically unloads the former character and reloads the new character. The queues of any clients that have loaded the default character are halted and flushed. However, the queues of clients that have loaded the character explicitly using the character's filename are not affected. If necessary, Agent also handles automatically resetting the text-to-speech (TTS) engine for the new character.

### Animating a Character

Once a character is loaded and placed on the screen, you can use several of XtrAgent's sprite functions for animating the character.

You can use the Play sprite method, specifying the name of an animation, to play that animation. Animation names are specific to a character definition. As an animation plays, the shape of its window changes to match the image in the frame. This results in a movable graphic image, or sprite, displayed on top of the desktop and all windows, or z-order.

The Say sprite method enables you to program the character to speak, automatically lip-syncing the output. Further details are covered in the Output section of this document.

You can use the MoveTo sprite method to position the character at a new location. When you call the MoveTo sprite method, XtrAgent automatically plays the appropriate animation based on the character's current location, then moves the character's frame. Similarly, when you call GestureAt, XtrAgent plays the appropriate gesturing animation based on the character's location and the location specified in the call.

To hide or show the character, call the Show sprite method. This automatically plays the animation associated with the character's Hiding/Showing state, then hides/shows the character's frame.

XtrAgent processes all animation calls, or requests, asynchronously. This enables your application's code to continue handling other events while the request is being processed. For example, calls to the Play sprite method place the animation in a queue for the character so that the animations can be played sequentially. However, this means you cannot assume that a call to other functions will necessarily execute after an animation it follows in your code. For example, typically, a statement following a call to Play or MoveTo will execute before the animation finishes.

You can synchronize your code with animations in a character's queue by storing a reference to the animation request, and, when the animation starts or completes, monitoring the Request events that XtrAgent uses to notify your application. For example, if you want a message box to appear when the character finishes an animation, you can put the message box call in your RequestComplete event handling subroutine, checking for the particular request ID.

When a character is hidden, XtrAgent does not play animations; however, it still queues and processes the animation request (plays the animation) and passes a request status back to the client. In the hidden state, the character cannot become input-active. However, if the user speaks the name of the character (when speech input is enabled), Agent automatically shows the character.

When your application loads multiple characters at the same time, XtrAgent's animation services enable you to animate characters independently or use the Wait, Interrupt or Stop sprite methods to synchronize their animation with each other.

Agent can also plays other animations automatically for you. For example, if the character's state has not changed for several seconds, Agent begins playing animations assigned to the character's Idling animations. Similarly, when speech input is enabled, Agent plays the character's Listening animations and then Hearing animations when an utterance is detected. These server-managed animations are called states, and are defined when a character is created.

Input Services

A client application provides the primary user interface for interaction with a character. You can program a character to respond to any form of input, from button-clicks to typed-in text. In addition, XtrAgent provides events so you can program what happens when the user clicks, double-clicks, or drags the character. The Xtra passes the coordinates of the pointer for these events.

### Input-Active Client

Because multiple client applications can share the same character and because multiple clients can use different characters at the same time, Agent designates one client as the input-active client and sends mouse and voice input only to that client application. This maintains the orderly management of user input, so that an appropriate client responds to the input.

Typically, user interaction determines which client application becomes input-active. For example, if the user clicks a character, that character's client application becomes input-active. Similarly, if a user speaks the name of a character, it becomes input-active. Also, when Agent processes a character's Show sprite method to show the character, the client of that character becomes input-active.

When a character is hidden, the client of that character will no longer be input-active for that character. Agent automatically makes the active client of any remaining character(s) input-active. When all characters are hidden, no client is input-active. However, in this situation, if the user presses the Listening hotkey, Agent will continue to listen for its commands (using the speech recognition engine matching the topmost character of the last input-active client).

If multiple clients are sharing the same character, Agent will designate its active client as input-active client. The active character is the topmost in the client order. You can set your client to be the active or not-active client using the Activate sprite method. You can also use the Activate sprite method to explicitly make your client input-active; but to avoid disrupting other clients of the character, you should do so only when your client application is active. For example, if the user clicks your application's window, activating your application, you can call the Activate sprite method to receive and process mouse and speech input directed to the character.

### Pop-up Menu Support

XtrAgent includes a pop-up menu (also known as a contextual menu) for each character. XtrAgent displays this pop-up menu automatically when a user right-clicks the character. You can add commands for your client application to the menu by defining a Commands collection. For each command in the collection that you define, you can specify CommandsCaption and CommandsVisible properties. The CommandsCaption is the text that appears in the menu when the CommandsVisible property is set to True. Define the access key for the menu text by including an ampersand (&) before the text character of the CommandsCaption text setting.

Agent automatically adds to the menu commands for opening the Voice Commands Window and hiding the character as well as the Commands captions of other clients of the character to enable users to switch between clients. It also automatically adds a separator to the menu between its menu entries and those defined by the client. Separators appear only when there are items in the menu to separate.

To remove commands from a menu, use the RemoveCommand member/icon method. Note that menu entries do not change while the menu displays. If you add or remove commands or change their properties, the menu displays the changes when the user redisplays the menu.

If you prefer to provide your own pop-up menu services for a character, you can use the AutoPopupMenu member/icon property to turn off Agent handling of the right-click action. You can then use the Click event notification to create your own menu handling behavior.

When the user selects a command from a character's pop-up menu or the Voice Commands Window, XtrAgent triggers the Command event of the associated client and passes back the parameters of the input.

Agent also provides a pop-up menu for the character's taskbar icon. When the character is visible, right-clicking this menu displays the same commands as those displayed by right-clicking the character. However, when the character is hidden, only the Agent-supplied commands are included.

### Speech Input Support

In addition to supporting mouse and keyboard interaction, Microsoft Agent includes direct support for speech input. Because Microsoft Agent's support for speech input is based on Microsoft SAPI (Speech Application Programming Interface), you can use Microsoft Agent with speech recognition command and control engines that include the SAPI-required support. For more information on speech engine requirements, see Speech Engine Support Requirements.

Microsoft provides a command-and-control speech recognition engine you can use with Microsoft Agent.

The user can initiate speech input by pressing and holding the push-to-talk Listening hotkey. In this Listening mode, if the speech engine receives the beginning of spoken input, it holds the audio channel open until it detects the end of the utterance. However, when not receiving input, it does not block audio output. This enables the user to issue multiple voice commands while holding down the key, and the character can respond when the user isn't speaking.

The Listening mode times out once the user releases the Listening key. The user can adjust the time-out for this mode using the Advanced Character Options. You cannot set this time-out from your client application code.

If a character attempts to speak while the user is speaking, the character's audible output fails though text may still be displayed in its word balloon. If the character has the audio channel while the Listening key is pressed, Agent automatically transfers control back to the user after processing the text in the Say sprite method. An optional MIDI tone is played to cue the user to begin speaking. This enables the user to provide input even if the application driving the character failed to provide logical pauses in its output.

You can also use the Listen sprite method to initiate speech input. Calling this method turns on the speech recognition for a predefined period of time. If there is no input during this interval, Microsoft Agent automatically turns off the speech recognition engine and frees up the audio channel. This avoids blocking input to or output from the audio device and minimizes the processor overhead the speech recognition uses when it is on. You can also use the Listen sprite method to turn off speech input. However, be aware that because the speech recognition engine operates asynchronously, the effect may not be immediate. As a result, it is possible to receive a Command event even after your code called Listen to turn off speech input.

To support speech input, you define a grammar, a set of words you want the speech recognition engine to listen and match for as the Voice setting for a Command in your Commands collection. You can include optional and alternative words and repeated sequences in your grammar. Note that Agent does not enable the Listening hotkey until one of its clients has successfully loaded a speech engine or has authored a Voice for one of its Command objects.

Whether the user presses the Listening hotkey or your client application calls the Listen sprite method to initiate speech input, the speech recognition engine attempts to match an utterance's input to the grammar for the commands that have been defined, and passes the information back to XtrAgent. The Xtra then notifies your application using the Command event.

XtrAgent also notifies your client application when it matches the speech input to one of its supplied commands. When in Listening mode, the Xtra automatically plays the animation assigned to the character's Listening state. Then, when an utterance is actually detected, Agent plays the character's Hearing state animation. Agent will keep the character in an attentive state until the utterance has ended. This provides the appropriate social feedback to cue the user for input.

If the user disables speech input in Advanced Character Options, the Listening hotkey will also be disabled. Similarly, attempting to call the Listen sprite method when speech input is disabled will cause the method to fail.

### Speech Engine Selection

A character's language ID setting determines its default speech input language; Microsoft Agent requests SAPI for an installed engine that matches that language. If a client application does not specify a language preference, Microsoft Agent will attempt to find a speech recognition engine that matches the user default language ID (using the major language ID, then the minor language ID). If no engine is available matching this language, speech is disabled for that character.

You can also request a specific speech recognition engine by specifying its mode ID (using the SRModeID member/icon property). However, if the language ID for that mode ID does not match the client's language setting, the call will fail. The speech recognition engine will then remain the last successfully set engine by the client, or if none, the engine that matches the current system language ID. If there is still no match, speech input is not available for that client.

Microsoft Agent automatically loads a speech recognition engine when speech input is initiated by a user pressing the Listening hotkey or the input-active client calls the Listen sprite method. However, an engine may also be loaded when setting or querying its mode ID, setting or querying the properties of the Voice Commands Window, querying SRStatus member/icon property, or when speech is enabled and the user displays the Speech Input page of the Advanced Character Options. However, Microsoft Agent only keeps loaded the speech engines that clients are using.

### Speech Input Events

In addition to the Command event notification, XtrAgent also notifies the input-active client when Agent turns the Listening mode on or off, using the ListeningState event. However, if the user presses the Listening mode key and there is no matching speech recognition engine available for the topmost character of the input-active client, Agent starts the Listening hotkey mode time-out, but does not generate a ListeningState event for the active client of the character. If, before the time-out completes, the user activates another character with speech recognition engine support, Agent attempts to activate speech input and generates the ListeningState event.

Similarly, if a client attempts to turn on the Listening mode using the Listen sprite method and there is no matching speech recognition engine available, the call fails and XtrAgent does not generate a ListeningState event.

When the Listening key mode is on and the user switches to a character that uses a different speech recognition engine, Agent switches to and activates that engine and triggers a ListeningState event. If the activated character does not have an available speech recognition engine (because one is not installed or none match the activated character's language ID setting), XtrAgent will trigger the ListeningState event for the previously activated character and passes back a value in the Cause parameter. However, the Xtra does not generate ListeningState events for the clients that do not have speech recognition support.

If a client successfully calls the Listen sprite method and a character without speech recognition engine support becomes input-active before the Listening mode time-out completes, and then the user switches back to the character of the original client, Agent will generate a ListeningState event for that client.

If the input-active client switches speech recognition engines by changing SRModeID member/icon property while in Listening mode, XtrAgent switches to and activates that engine without re-triggering the ListeningState event. However, if the specified engine is not available, the call fails and the Xtra also calls the ListeningState event, indicating that Listening mode has ended.

### The Listening Tip

The Listening Tip is another speech input service provided by Microsoft Agent. When speech input is installed, Agent includes a special tooltip window that appears when the user presses the Listening hotkey or calls the Listen sprite method. The Listening Tip appears only when the speech services are available. If no client has authored a voice command or successfully loads a speech engine, the Listening Tip does not appear. Further, both speech input and the Display Listening Tips option in the Advanced Character Options must be enabled for the tip to appear.

The Listening Tip automatically times out after being presented. If the "Heard" text time-out completes while the user is still holding down the hotkey, the tip reverts to the "listening" text unless the Agent receives another matching utterance. In this case, the tip displays the new "Heard" text and begins the time-out for that tip text. If the user releases the hotkey and the Agent is displaying the "Heard" text, the time-out continues and the Listening Tip window is hidden when the time-out interval elapses.

If the Agent has not yet attempted to load a speech recognition engine, the Listening Tip will not display. Similarly, if the user has disabled the display of the Listening Tip or disabled speech input in Advanced Character Options, the Listening Tip will not be displayed.

The Listening Tip does not appear when the pointer is over the character's taskbar icon. Instead, the standard notification tip window appears and displays the character's name.

Client applications cannot write directly to the Listening Tip.

The Listening Tip text appears in the language based on the input-active client's character language ID setting, regardless of whether there is a language-compatible speech recognition engine available.

Output Services

In addition to supporting the animation of a character, Microsoft Agent supports audio output for the character. This includes spoken output and sound effects. For spoken output, XtrAgent automatically lip-syncs the character's defined mouth images to the output. You can choose text-to-speech (TTS) synthesis, recorded audio, or only word balloon text output.

### Synthesized Speech Support

If you use synthesized speech, your character has the ability to say almost anything, which provides the greatest flexibility. With recorded audio, you can give the character a specific or unique voice. To specify output, provide the spoken text as a parameter of the Say method.

Because Microsoft Agent's architecture uses Microsoft SAPI for synthesized speech output, you can use any engine that conforms to this specification, and supports International Phonetic Alphabet (IPA) output using the Visual method of the ITTSNotifySinkW interface. For further information on the engine requires, see Speech Engine Requirements.

A character's language ID setting determines its TTS output. If a client does not specify a language ID for the character, the character's language ID is set to the user default language ID. If the character's definition includes a specific engine and that engine can be loaded and it matches the character's language setting, that engine will be used. Otherwise, Microsoft Agent enumerates the other available engines and requests a SAPI best match based on language, gender, and age (in that order). If there is no matching engine available, there is no TTS output for that client's use of the character. Agent attempts to load the TTS engine on the first Say call or when you query or successfully set its mode ID.

A client application can also specify a TTS engine for its character (using the TTSModeID property). This overrides the Agent's attempt to automatically find a matching engine based on the character's preferred TTS mode ID or the character's current language ID setting. However, if that engine is not installed (or cannot otherwise be loaded), the call will fail. XtrAgent then attempts to load another engine based on the language ID, compiled character TTS setting, and available TTS engines. If there is still no match, TTS is not available for that client, but the character can still speak into its word balloon.

Only the TTS engines in use by any client remain loaded. For example, if a character has a defined preference for a specific engine and that engine is available, but your client application has specified a different engine (by setting a character's language ID differently from the engine or specifying a different mode ID), only the engine specified by your application remains loaded. The engine matching the character's defined preference for a TTS setting is unloaded (unless another client is using the character's compiled engine setting).

### Audio Output Support

XtrAgent enables you to use audio files for a character's spoken output. You can record audio files and use the Say sprite method to play that data. XtrAgent animation services automatically support lip-syncing the character mouth by using the audio characteristics of the audio file. XtrAgent also supports a special format for audio files, which includes additional phoneme and word-break information for more enhanced lip-sync support. You can generate this special format using the Microsoft Linguistic Information Sound Editing Tool.

### Word Balloon Support

Spoken output can also appear as textual output in the form of a cartoon word balloon. This can be used to supplement the spoken output of a character or as an alternative to audio output when you use the Say sprite method.

You can also use a word balloon to communicate what a character is "thinking" using the Think sprite method. This displays the text you supply in a still "thought" balloon. The Think method also differs from the Say method in that it produces no audio output.

Word balloons support only captioned communication from the character, not user input. Therefore, the word balloon does not support input controls. However, you can easily provide user input for a character, using interfaces from your programming language or the other input services provided by Microsoft Agent, such as the pop-up menu.

When you define a character, you can specify whether to include word balloon support. If you use a character that includes word balloon support, you can temporarily disable the word balloon using the 'Map' speech tag. This tag enables you to use different spoken text than that displayed in the word balloon. If you pass an empty string for the text balloon, the text balloon will not appear.

### Animation Sound Effects

Microsoft Agent also enables you to include sound effects as a part of a character's animation. Using the Microsoft Agent Character Editor, you can specify the filename of standard Windows sound (.WAV) files to trigger on a given frame. Note that Microsoft Agent does not mix sound effects and spoken output, so spoken output does not begin until a sound effect completes. Therefore, avoid any long or looping sound effect as a part of a character's animation.

# XtrAgent Sprite Methods

All methods return request ID if succeeded, and void if not, except Listen(), Activate(), ShowPopupMenu(), Stop() and StopAll() which return the number 1 if succeeded and void if not.

# Say ( Sprite X, String Text, String FileName )

Converts a text string to speech using the character's text-to-speech (TTS) engine.

Parameters:

Text:

The text the character is to speak.

FileName: The path of a sound file to use for spoken output. This parameter is optional and can be a standard sound file (.WAV) or linguistically enhanced sound file (.LWV).

You can include vertical bar characters (|) in the Text parameter to designate alternative strings, so that each time the Xtra processes the method, it randomly choose a different string. Support of TTS output is defined when the character is compiled using the Microsoft Agent Character Editor.

If you want to use sound file output for the character, specify the location for the file in the FileName parameter. You can use the Text parameter to specify the words that appear in the character’s word balloon. If you specify a linguistically enhanced sound file (.LWV) for the FileName parameter and do not specify text, the Text parameter uses the text stored in the file.

This method uses the last animation played to determine which speaking animation to play. For example, if you precede the Say command with a Play "GestureRight", XtrAgent will play GestureRight and then the GestureRight speaking animation. If the last animation played has no speaking animation, then XtrAgent plays the animation assigned to the character’s Speaking state.

If you call Say and the audio channel is busy, the character’s audio output will not be heard, but the text will display in the word balloon.

Note: Set the character’s language ID before using this method to ensure appropriate text display within the word balloon.

See Also: Speech Output Tags

Play ( Sprite X, String Animation )

Plays a specified character animation.

Parameters:

Animation: The name of the animation to play.

An animation’s name is defined when the character is compiled with the Microsoft Agent Character Editor. Before playing the specified animation, XtrAgent attempts to play the Return animation for the previous animation (if one has been assigned).

See Also: Animations for Genie Character, Animations for Robby Character, Animations for Merlin Character

Wait ( Sprite X, Integer RequestID )

Holds the character’s animation queue at the specified animation until another request for another character completes.

Parameters:

RequestID: The ID of the request to wait for.

Use this method only when you support multiple (simultaneous) characters and want to sequence their interaction. (For a single character, each animation request is played sequentially--after the previous request completes.) If you have two characters and want one character’s animation request to wait until the other character’s animation completes, set the Wait method to the other character’s animation request ID.

MoveTo ( Sprite X, Integer X, Integer Y, Integer Speed )

Plays the associated Moving state animation and moves the character frame to the specified location.

Parameters:

X : The x-coordinate of the new position in pixels, relative to the stage origin (upper left). The location of a character is based on the upper left corner of its sprite rect.

Y : The y-coordinate of the new position in pixels, relative to the stage origin (upper left). The location of a character is based on the upper left corner of its sprite rect.

Speed : A parameter specifying in milliseconds how quickly the character’s frame moves. The recommended value is 1000. Specifying zero (0) moves the frame without playing an animation.

Stop ( Sprite X, Integer RequestID )

Stops the specified animation (request) and removes it from the character’s animation queue.

Parameters:

RequestID: The ID of the request to stop.

StopAll ( Sprite X, Integer Type )

Stops all animations (requests) and removes them from the character’s animation queue.

Parameters:

Type: The type of requests to stop (and remove from the character’s queue). Can be one of the following integers:

1 - Stops all animation requests.

2 - Stops all Play requests.

3 - Stops all Move requests.

4 - Stops all Say requests.

5 - Stops all Show requests.

Show ( Sprite X, Integer Visibility )

Displays or hides the character.

Parameters:

Visibility: FALSE hides the character and TRUE displays it.

XtrAgent queues the hide animation in the character’s queue. This allows you to use it to hide the character after a sequence of other animations. You can play the action immediately by using the StopAll method before calling the Show method. Hidden characters cannot access the audio channel.

Think ( Sprite X, String Text )

Displays the character’s thought word balloon with the specified text.

Parameters:

Text: The text to appear in the character’s thought balloon.

Like the Say method, the Think method is a queued request that displays text in a word balloon, except that thoughts display in a special thought balloon. The thought balloon supports only the Bookmark speech control tag (\Mrk) and ignores any other speech control tags. Unlike Say, the Think method does not change the character’s animation state.

Listen ( Sprite X, Integer OnOff )

Turns Listening mode (speech recognition input) on or off.

Parameter:

OnOff: Listening mode flag. If this parameter is True, the Listening mode is turned on; if False, Listening mode is turned off.

Setting this method to True enables the Listening mode (turns on speech recognition) for a fixed period of time. While you cannot set the value of the time-out, you can turn off Listening mode before the time-out expires. In addition, if the Listening mode is already on because you (or another client) successfully set the method to True before the time-out expires, the method succeeds and resets the time-out. However, if Listening mode is already on because the user is pressing the Listening key, the method succeeds, but the time-out is ignored and the Listening mode ends based on the user's interaction with the Listening key.

This method will succeed only when called by the input-active client. Therefore, the method will fail if your client is not the active client of the topmost character. The method will also fail if you attempt to set the method to False and the user is pressing the Listening key. It can also fail if there is no compatible speech engine available that matches the character's language ID setting or the user has disabled speech input using the Microsoft Agent property sheet. However, the method will not fail if the audio device is busy.

When you successfully set this method to True, XtrAgent triggers the ListeningState event. It also sends ListeningState when the Listening mode time-out completes or when you set Listen to False.

This method does not automatically call StopAll and play a Listening state animation of the character as occurs when the user presses the Listening key. This enables you to use the ListeningState event to determine whether you wish to stop the current animation and play your own appropriate animation. However, once a user utterance is detected, XtrAgent automatically calls StopAll and plays a Hearing state animation.

GestureAt ( Sprite X, Integer X, Integer Y )

Plays the associated Gesturing state animation based on the specified location.

Parameters:

X: The x-coordinate of the specified location in pixels, relative to the stage origin (upper left).

Y: The y-coordinate of the specified location in pixels, relative to the stage origin (upper left).

XtrAgent automatically determines and plays the appropriate gesturing animation based on the character's current position and the specified location.

Interrupt ( Sprite X, Integer RequestID )

Interrupts the specified animation (request) of another character.

Parameters:

RequestID: An ID of the request to interrupt.

If you load multiple characters, you can use this method to sync up animation between characters. For example, if another character is in a looping animation, this method will stop the looping animation and start the next animation in the character's queue.

Interrupt halts the existing animation, but does not flush the character's animation queue. It starts the next animation in the character's queue. To halt and flush a character's queue, use the Stop method.

You cannot use this method to have a character interrupt itself because the Microsoft Agent queues the Interrupt method in the character's animation queue. Therefore, you can only use Interrupt to halt the animation of another character you have loaded.

Activate ( Sprite X, Integer State )

Sets whether your application is active or a character is topmost.

Parameter:

State: You can specify the following values for this parameter:
0 - Set as not the active client.
1 - Set as the active client.
2 - Make the topmost character.

When multiple characters are visible, only one of the characters receives speech input at a time. Similarly, when multiple client applications share the same character, only one of the clients receives mouse input at a time. The character set to receive mouse and speech input is the topmost character and the client that receives input is the character's active client. (The topmost character's window also appears at the top of the character window's z-order.) Typically, the user determines which character is topmost by explicitly selecting it. However, topmost activation also changes when a character is shown or hidden (the character becomes or is no longer topmost, respectively.)

You can also use this method to explicitly manage when your client receives input directed to the character, such as when your application itself becomes active. For example, setting State to 2 makes the character topmost, and your client receives all mouse and speech input events generated from user interaction with the character. Therefore, it also makes your client the input-active client of the character. However, you can also set the active client for a character without making the character topmost, by setting State to 1. This enables your client to receive input directed to that character when the character becomes topmost. Similarly, you can set your client to not be the active client (to not receive input) when the character becomes topmost, by setting State to 0. You can determine if a character has other current clients using HasOtherClients member/icon property.

Avoid calling this method directly after a Show method. Show automatically sets the input-active client. When the character is hidden, the Activate call may fail, if it gets processed before the Show method completes.

Attempting to call this method with the State parameter set to 2 (when the specified character is hidden) will fail. Similarly, if you set State to 0, and your application is the only client, this call fails. A character must always have a topmost client.

Note: Calling this method with State set to 1 does not typically generate an ActivateInputState event unless there are no other characters loaded or your application is already input-active.

ShowPopupMenu ( Sprite X, Integer X, Integer Y )

Displays the pop-up menu for the character.

Parameters:

X: The x-coordinate of the character’s pop-up menu in pixels, relative to the stage origin (upper left).
Y: The y-coordinate of the character’s pop-up menu in pixels, relative to the stage origin (upper left).

When you set the XtrAgent member/icon property PopupMenu to False, the Xtra no longer automatically displays the menu when the character or its taskbar icon is right-clicked. You can use this method to display the menu.

The menu displays until the user selects a command or displays another menu. Only one pop-up menu can be displayed at a time; therefore, calls to this method will cancel (remove) the former menu.

This method should only be called when your client application is the active client of the character; otherwise it fails.

XtrAgent Sprite Events

ActivateInputState

Notifies a sprite when its character's input active state changed.

Parameter:

Activated: Input active flag. This Boolean value is True if the character became input active; and False if the character lost its input active state.

DragStart

Notifies a sprite when the user starts dragging its character.

Parameters:

X: The x-coordinate of the mouse pointer in pixels, relative to the stage origin (upper left).

Y: The y-coordinate of the mouse pointer in pixels, relative to the stage origin (upper left).

DragComplete

Notifies a sprite when the user stops dragging its character.

Parameters:

X: The x-coordinate of the mouse pointer in pixels, relative to the stage origin (upper left).

Y: The y-coordinate of the mouse pointer in pixels, relative to the stage origin (upper left).

Click

Notifies a sprite when the user clicks its character or character's taskbar icon..

Parameters:

X: The x-coordinate of the mouse pointer in pixels, relative to the stage origin (upper left).

Y: The y-coordinate of the mouse pointer in pixels, relative to the stage origin (upper left).

DoubleClick

Notifies a sprite when the user double-clicks its character.

Parameters:

X: The x-coordinate of the mouse pointer in pixels, relative to the stage origin (upper left).

Y: The y-coordinate of the mouse pointer in pixels, relative to the stage origin (upper left).

RequestStart

Notifies a sprite when a request begins. This event enables you to track when a queued request begins.

Parameter:

RequestID: Identifier of the request that started.

RequestComplete

Notifies a sprite when a request completes. This event enables you to track when a queued method completes.

Parameter:

RequestID: Identifier of the request that completed.

Command

Notifies a sprite that a Command was selected by the user.

Parameter:

CommandID: Identifier of the best match command alternative.

XtrAgent notifies the input-active client when the user chooses a command by voice or by selecting a command from the character's pop-up menu. The event occurs even when the user selects one of the Agent's commands. In this case XtrAgent returns a zero command ID.

Bookmark

Notifies a sprite when a bookmark completes.

Parameter:

BookmarkID: Identifier of the bookmark that resulted in triggering the event.

When you include bookmark tags in a Say sprite method, you can track when they occur with this event.

VisibleState

Notifies a sprite when the visibility state of its character changes.

Parameters:

Visible: Visibility flag. This Boolean value is True when character becomes visible and False when the character becomes hidden.

Cause: Cause of last change to the character's visibility state. The parameter may be one of the following:

0 - Character has not been shown.
1 - User hid the character with the character's taskbar icon pop-up menu or with speech input.
2 - User showed the character.
3 - Your application hid the character.
4 - Your application showed the character.
5 - Another application hid the character.
6 - Another application showed the character.
7 - User hid the character with the character's pop-up menu.
8 - User hid the character with the character's taskbar icon pop-up menu or using speech input.

Move

Notifies a sprite when its character has been moved.

Parameters:

X: The x-coordinate of the new position in pixels, relative to the stage origin (upper left). The location of a character is based on the upper left corner of its animation frame.

Y: The y-coordinate of the new position in pixels, relative to the stage origin (upper left). The location of a character is based on the upper left corner of its animation frame.

Cause: The cause of the character move. The parameter may be one of the following:

0 - Character has not been moved.
1 - User dragged the character.
2 - Your application moved the character.
3 - Another application moved the character.
4 - XtrAgent moved the character to keep it onscreen after a screen resolution change.

ActiveClientChange

Notifies a sprite when your application is no longer the active client of its character.

Parameter:

Status: Active state change of the client, which can be a combination of any of the following values:

0 - Your client is not the active client of the character.
1 - Your client is the active client of the character.
2 - Your client is input-active (active client of the topmost character).

When multiple client applications share the same character, the active client of the character receives mouse input. Similarly, when multiple characters are displayed, the active client of the topmost character (also known as the input-active client) receives Command events.

When the active client of a character changes, this event passes back True if your application has become the active client of the character or False if it is no longer the active client of the character.

A client application may receive this event when the user selects another client application's entry in character's pop-up menu or by voice command, the client application changes its active status, or another client application quits its connection to Microsoft Agent. Agent sends this event only to the client applications that are directly affected -- those that either become the active client or stop being the active client.

You can use the Activate sprite method to set whether your application is the active client of the character or to make your application the input-active client (which also makes the character topmost).

ListeningState

Notifies a sprite when the Listening mode changes.

Parameters:

Listening: The Listening mode state. True indicates that Listening mode has started; False, that Listening mode has ended.

Cause: The cause for the event, which may be one of the following values.

1 - Listening mode was turned off by program code.
2 - Listening mode (turned on by program code) timed out.
3 - Listening mode (turned on by the Listening key) timed out.
4 - Listening mode was turned off because the user released the Listening key.
5 - Listening mode was turned off because the user finished speaking.
6 - Listening mode was turned off because the input active client was deactivated.
7 - Listening mode was turned off because the default character was changed.
8 - Listening mode was turned off because the user disabled speech input.

This event is sent to all input-active sprites when the Listening mode begins after the user presses the Listening key or when its time-out ends, or when the input-active client calls the Listen sprite method with True or False.

DefaultCharacterChange

Notifies a sprite when the default character changes.

Parameter:

GUID: The unique identifier for the character.

When the user changes the character assigned as the user's default character, XtrAgent sends this event to clients that have loaded the default character. The event returns the character's unique identifier (GUID) formatted with braces and dashes, which is defined when the character is built with the Microsoft Agent Character Editor.

When the new character appears, it assumes the same size as any already loaded instance of the character or the previous default character (in that order).

# XtrAgent Member/Icon Properties

XtrAgent member properties are read/write unless otherwise specified. If a property cannot be retrieved the result value is zero.

File

The pathname of the linked character file, an empty string for the default character, or comma (",") for no character file.

This property is "*" if Microsoft Agent 2.0 or later is not installed.

When you load a movie that contains Agent member/icon, and its character file is not in the original location, XtrAgent uses Director's/Authorware's standard filename resolution algorithm to find it. This includes scanning the searchPaths and moviePath folders for the appropriate file. If after this process the file was still not found, XtrAgent searches the Agent's characters directory for it.

If the file could not be found in any of those locations, this property is being set to comma (","). If the file was found in the Agent's characters directory, this property is being set to the name of the character file, without the full path to it.
If you set this property from your script, XtrAgent first unloads the character associated with the member/icon (if any), and then try to load the new one.

You can load characters from the Microsoft Agent subdirectory by specifying a relative path (one that does not include a colon or leading slash character). This prefixes the path with Agent's characters directory (located in the localized %windows%\msagent directory). You can also use a relative address to specify your own directory in Agent's Chars directory.

Setting this property to an empty string will load the default character, if one is available.

TTSSpeed

This property returns the current speaking output speed setting for the character, in words per minute. For characters using TTS output, the property returns the actual TTS output for the character. If TTS is not enabled or the character does not support TTS output, the setting reflects the user setting for output speed.

This property is read-only, your application cannot set it, but you can include speed tags in your output text that will temporarily speed up the output for a particular utterance.

TTSPitch

This property returns the current speaking output pitch setting for the character, in Hertz. If the speech synthesis (TTS) engine is not enabled (or installed) or the character does not support TTS output, the result value is zero (0).

This property is read-only, your application cannot set it, but you can include pitch tags in your output text that will temporarily increase the pitch for a particular utterance.

SoundFX

This property is TRUE if the character's sound effects setting is enabled and FALSE if disabled.

The character's sound effects setting determines whether sound effects compiled as a part of the character it presents are played when you play an associated animation. The setting is subject to the user’s global sound effects setting.

OtherClients

The number of other connected clients to the character (total number of clients minus your client).

This property is read-only.

CharacterName

The name of the character. A character’s default name is defined when it is compiled with the Microsoft Agent Character Editor. A character’s name may vary based on the character’s language ID. Characters can be compiled with different names for different languages.

You can change the character’s name, however, this changes the character name for all current clients of the character. This property is not persistent (stored permanently). The character’s name reverts to its default name whenever the character is first loaded by a client.

Description

The character’s description. A character’s default description is defined when it is compiled with the Microsoft Agent Character Editor. The description setting is optional and may not be supplied for all characters.

You can change the character’s description, however, this value is not persistent (stored permanently). The character’s description reverts to its default setting whenever the character is first loaded by a client.

ExtraData

Additional data stored as part of the character. A character’s additional data is defined when it is compiled with the Microsoft Agent Character Editor. A character developer can supply this string by editing the .ACD file for a character. The setting is optional and may not be supplied for all characters, nor can the data be defined or changed at run time. In addition, the meaning of the data supplied is defined by the character developer.

AutoIdle

Automatic idle processing for a member/icon. If TRUE, XtrAgent automatically plays Idling state animations.

The Xtra automatically sets a time out after the last animation played for a character. When this timer’s interval is complete, the Xtra begins the Idling states for a character, playing its associated Idling animations at regular intervals. If you want to manage the Idling state animations yourself, set this property to FALSE.

PopupMenu

Automatic display of the character’s pop-up menu. True if XtrAgent automatically handles displaying the character’s pop-up menu and False if not.

This property applies only to your client application’s use of the character; the setting does not affect other clients of the character or other characters of your client application.

By setting this property to False, you can create your own menu-handling behavior. To display the menu after setting this property to False, use the ShowPopupMenu sprite method.

TTSModeID

The mode ID setting of the TTS (text-to-speech) engine for the character.

This setting determines the preferred engine mode for a character’s spoken TTS output. The mode ID for a TTS engine is the GUID defined by the speech vendor that uniquely identifies the mode of the engine (formatted with braces and dashes).

If you set a TTS mode ID, it overrides the XtrAgent attempt to match a speech engine based on the character’s compiled TTS mode ID, the current system language ID, and the character’s current language ID. However, if you attempt to set a mode ID when the user has disabled speech output in the Microsoft Agent property sheet or when the associated engine is not installed, such a call will fail.

If you do not set a TTS engine mode ID for the character, XtrAgent attempts to set an engine that matches the character’s compiled TTS setting and the character’s current language setting. If these are different, then the character’s language setting overrides its authored mode setting. If you have not set the character’s language setting, the character’s language is the user default language ID, and XtrAgent attempts the match based on that language ID.

This property applies to only your client application’s use of the character; the setting does not affect other clients of the character or other characters of your client application.

Microsoft Agent’s speech engine requirements are based on the Microsoft Speech API. Engines supporting Microsoft Agent’s SAPI requirements can be installed and used with Agent.

Note: Setting this property can fail if Speech.dll is not installed and the engine you specify does not match the character's compiled TTS mode setting.

SRModeID

The mode ID setting of the speech recognition engine for the character.

This setting determines the engine set for a character’s speech input. The mode ID for a speech recognition engine is a string representation of the GUID (formatted with braces and dashes) by the speech vendor uniquely identifying the engine.

If you specify a mode ID that does not match the character’s language setting, if the user has disabled speech recognition (in the Microsoft Agent property sheet), or the engine is not installed, such a call will fail.

If you do not set a speech recognition engine mode ID for the character, XtrAgent sets an engine that matches the character’s language setting. If there is no matching speech recognition engine available for the character the property is being set to an empty string.

When speech input is enabled (in the Advanced Character Options window), querying or setting this property will load the associated engine (if it is not already loaded), and start speech services. That is, the Listening key is available, and the Listening Tip is displayable. (The Listening key and Listening Tip are enabled only if they are also enabled in Advanced Character Options.) However, if you query the property when speech is disabled, XtrAgent does not start speech services and it returns an empty string.

This property applies to only your client application’s use of the character; the setting does not affect other clients of the character or other characters of your client application.

Microsoft Agent’s speech engine requirements are based on the Microsoft Speech API. Engines supporting Microsoft Agent’s SAPI requirements can be installed and used with Agent.

SRStatus

The status of the condition necessary to support speech input. Can be one of the following values:

0 - Conditions support speech input.
1 - There is no audio input device available on this system. (Note that this does not detect whether a microphone is installed; it can only detect whether the user has a properly installed input-enabled sound card with a working driver.)
2 - Another client is the active client of this character, or the current character is not topmost.
3 - The audio input or output channel is currently busy, some other application is using audio.
4 - An unspecified error occurred in the process of initializing the speech recognition subsystem. This includes the possibility that there is no speech engine available matching the character's language setting.
5 - The user has disabled speech input in the Advanced Character Options window.
6 - An error occurred in checking the audio status, but the cause of the error was not returned by the system.

This property enables you to query whether current conditions support speech recognition input, including the status of the audio device. If your application uses the Listen sprite method, you can use this function to better ensure that the call will succeed. Calling this method also loads the speech engine if it is not already loaded. However, it does not turn on Listening mode.

When speech input is enabled in the Agent property sheet (Advanced Character Options), querying the status will load the associated engine (if it is not already loaded), and start speech services. That is, the Listening key is available, and the Listening Tip is displayable. (The Listening key and Listening Tip are enabled only if they are also enabled in Advanced Character Options.) However, if you query the property when speech is disabled, Agent does not start speech services.

This function returns only the setting for your client application's use of the character; the setting does not reflect other clients of the character or other characters of your client application. Your application cannot set this property.

SRHotKey

The current hot key setting used to open the audio channel for speech input. This property is read-only.

CommandsCaption

The Caption text displayed for the character's Commands collection.

Setting this property for a character's Commands collection defines how it will appear on the character's pop-up menu when its CommandVisible property is set to True and your application is not the input-active client. To specify an access key (unlined mnemonic) for your CommandsCaption, include an ampersand (&) character before that character.

CommandsVoice

The Voice text setting for the character's Commands collection.

A Commands collection must have its CommandsVoice text property set to be voice-accessible. It also must have its CommandsCaption property set to appear in the Commands Window and its CommandsVisible property set to TRUE to appear on the character’s pop-up menu.

The string you supply to set this property can include square bracket characters ([ ]) to indicate optional words and vertical bar characters (|) to indicate alternative strings. Alternates must be enclosed in parentheses. For example, "(hello [there] | hi)" tells the speech engine to accept "hello," "hello there," or "hi" for the command. Remember to include appropriate spaces between words you include in brackets or parentheses as well as other text. Remember to include appropriate spaces between the text that's in brackets or parentheses and the text that's not in brackets or parentheses.

You can use the star (*) operator to specify zero or more instances of the words included in the group or the plus (+) operator to specify one or more instances. For example, the following results in a grammar that supports "try this", "please try this", and "please please try this", with unlimited iterations of "please":

"please* try this"

The following grammar format excludes "try this" because the + operator defines at least one instance of "please":

"please+ try this"

The repetition operators follow normal rules of precedence and apply to the immediately preceding text item. For example, the following grammar results in "New York" and "New York York", but not "New York New York":

"New York+"

Therefore, you typically want to use these operators with the grouping characters. For example, the following grammar includes both "New York" and "New York New York":

"(New York)+"

Repetition operators are useful when you want to compose a grammar that includes a repeated sequence such as a phone number or specification of a list of items:

"call (one|two|three|four|five|six|seven|eight|nine|zero|oh)*"
"I'd like (cheese|pepperoni|pineapple|canadian bacon|mushrooms|and)+"

Although the operators can also be used with square brackets (an optional grouping character), doing so may reduce the efficiency of Agent's processing of the grammar.

You can also use an ellipsis (…) to support word spotting, that is, telling the speech recognition engine to ignore words spoken in this position in the phrase (sometimes called garbage words). When you use ellipses, the speech engine recognizes only specific words in the string regardless of when spoken with adjacent words or phrases. For example, if you set this property to "…check mail…" the speech recognition engine will match phrases like "please check mail" or "check mail please" to this command. Ellipses can be used anywhere within a string. However, be careful using this technique as voice settings with ellipses may increase the potential of unwanted matches.

When defining the words and grammar for your command, always make sure that you include at least one word that is required; that is, avoid supplying only optional words. In addition, make sure that the word includes only pronounceable words and letters. For numbers, it is better to spell out the word rather than using the numeric representation. For example, "345" is not a good grammar form. Similarly, instead of "IEEE", use "I triple E". Also, omit any punctuation or symbols. For example, instead of "the #1 $10 pizza!", use "the number one ten dollar pizza". Including non-pronounceable characters or symbols for one command may cause the speech engine to fail to compile the grammar for all your commands. Finally, make your voice parameter as distinct as reasonably possible from other voice commands you define. The greater the similarity between the voice grammar for commands, the more likely the speech engine will make a recognition error. You can also use the confidence scores to better distinguish between two commands that may have similar or similar-sounding voice grammar.

You can include in your grammar words in the form of "text\pronunciation", where "text" is the text displayed and "pronunciation" is text that clarifies the pronunciation. For example, the grammar, "1st\first", would be recognized when the user says "first," but the Command event will return the text, "1st\first". You can also use IPA (International Phonetic Alphabet) to specify a pronunciation by beginning the pronunciation with a pound-sign character ("#"), then the text representing the IPA pronunciation.

For Japanese speech recognition engines, you can define grammar in the form "kana\kanji," reducing the alternative pronunciations and increasing the accuracy. (The ordering is reversed for backward compatibility.) This is particularly important for the pronunciation of proper names in Kanji. However, you can just pass in "kanji," without the Kana, in which case the engine should listen for all acceptable pronunciations for the Kanji. You can also pass in just Kana.

Except for errors using the grouping or repetition formatting characters, Microsoft Agent will not report errors in your grammar, unless the engine itself reports the error. If you pass text in your grammar that the engine fails to compile, but the engine does not handle and return as an error, Agent cannot report the error. Therefore, the client application must be careful defining the grammar for the this property.

Notes: The grammar features available may depend on the speech recognition engine. You may want to check with the engine's vendor to determine what grammar options are supported. Use the SRModeID to use a specific engine.

The operation of this property depends on the state of Microsoft Agent server's speech recognition state. For example, if speech recognition is disabled or not installed, this function has no immediate effect. If speech recognition is enabled during a session, however, the command will become accessible when its client application is input-active.

CommandsVisible

The Visible property for a Commands collection. TRUE sets the Commands collection’s Caption to be visible when the character’s pop-up menu is displayed; FALSE does not display it.

A Commands collection must have its CommandsCaption property set and its CommandsVisible property set to TRUE to appear on the character’s pop-up menu. The CommandsVisible property must also be set to TRUE for commands in the collection to appear when your client application is input-active.

XtrAgent Member/Icon Methods

AddCommand ( Member X, String Caption, String Voice, Integer Enabled, Integer Visible )

Adds a Command to a Commands collection. Returns the added Command ID if succeeded, void if not.

Parameters:

Caption: Specifies the Caption text displayed for a Command in a Commands collection.

Voice: Specifies the Voice text setting for a Command in a Commands collection. Refer to the CommandsVoice property for more information on how to specify this parameter.

Enabled: A Boolean expression that specifies the Enabled setting for a Command in a Commands collection. If the parameter is TRUE, the Command is enabled and can be selected; if FALSE, the Command is disabled.

Visible: A Boolean expression that specifies the Visible setting for a Command in a Commands collection. If the parameter is TRUE, the Command will be visible in the character’s pop-up menu (if the Caption property is also set).

RemoveCommand ( Member X, Integer CommandID )

Removes the specified Command from a Commands collection. Removing a Command from a Commands collection also removes it from the pop-up menu and the Commands Window when your application is input-active. Returns 1 if succeeded, void if not.

Parameters:

CommandID: The ID of a Command to remove from the Commands collection.

ShowDefaultCharacterProperties ( Member X, Integer X, Integer Y, Integer Default )

Displays default character properties window.

Parameters:

X: The x-coordinate of the window in pixels, relative to the screen origin (upper left).

Y: The y-coordinate of the window in pixels, relative to the screen origin (upper left).

Default: Default position flag. If this parameter is True, XtrAgent displays the property sheet window for the default character at the last location it appeared.

Creating Projectors

It's highly not recommended to embed XtrAgent with your projector(s)/package(s). Instead, place its run-time version in a folder named "Xtras", located in the directory where your projector/package file is.

Be sure not to embed the authoring version of XtrAgent in a projector/package as it cannot work and distributed with them.

To prevent problems with palettes in Director 5/6 you should include with each projector a copy of the modified DIRECTOR.INI file you created following the instructions in the Getting Started section. The .ini file should be renamed to match the name of the Projector file.

XtrAgent uses Director's/Authorware's standard filename resolution algorithm to locate linked character files. This includes scanning the searchPaths and the moviePath folders. If after this process the file still cannot be found, XtrAgent searches the Agent's characters directory for the character file.

Using XtrAgent with Shockwave movies on the Web

You can license the auto-downloadable Shockwave safe version of XtrAgent to provide it for automatic download from your Web site.

The auto-downloadable Shockwave safe versions are the files
XtrAgent.w32 (Windows) and XtrAgent.ppc (MacOS). Note that the Xtra is only available for Windows, but the package is available for both platforms. The MacOS package is empty and required by Macromedia when authoring movies. It will never be downloaded to an end user's machine.

In order provide the Shockwave versions for automatic download, you'll need to put them in a single location on a server. eg:
http://www.myserver.com/packs/XtrAgent.ppc
http://www.myserver.com/packs/XtrAgent.w32
Then modify the xtrainfo.txt file in the Director 7 folder to reference this location eg:
; DirectXtras
[#namePPC:"XtrAgent.ppc", #nameW32:"XtrAgent.X32",#package:"http://www.myserver.com/packs/XtrAgent"]
Finally, add a reference to the package in your movie.
Open a movie that uses XtrAgent. From the Modify\Movie\Xtras dialog in director,
select the xtra in the list of xtras. The "Download if needed" checkbox should
now be enabled. (If it's not enabled, make sure the filename in xtrainfo.txt matches
the actual filename for the xtra.) Click on the checkbox and director will load
information from the package file for each platform and add it to the current movie.

Licensing and Distribution

Application developers who want to freely distribute Microsoft Agent services and any of its components (including Microsoft Agent character files and speech engines) as part of their application or from their own server must complete a distribution license for Microsoft Agent. For more information on licensing requirements for Microsoft Agent, see the Licensing document at the Microsoft Agent Web site at http://msdn.microsoft.com/msagent/licensing.asp.

Important note on XtrAgent sprites :

Due to limitation in Microsoft Agent, you can not have more than one sprite in a frame, that's associate with the same character. To get around this limitation, you can use the character editor to compile two different files with different GUID, from the same character sources, import both of them to Director/Authorware and work with them as they were two different characters, although they will look and behave the same.

Important note on Director 6 and XtrAgent sound system:

The soundKeepDevice Lingo property in Director 6 tells Director whether or not to hold onto the sound device after a sound finishes playing. If it is set to true, and Director 6 uses DirectSound to mix sounds (when both DirectSound and Intel RSX drivers are installed), Director doesn't release the sound device. This is the default for Director 6, because it reduces the overhead of initializing the sound layers, grabbing the sound device, etc. each time a new sound plays.

Since XtrAgent needs the sound device to produce speech and to play WAV files, it's important that you set the soundKeepDevice to FALSE if you intend to play Director sounds and use XtrAgent in the same Director 6 movie.

The soundKeepDevice command does not affect whether Director uses RSX or not. If RSX is installed on a machine, it is always used.

Important note on trails in Director 5/6 :

When dragging a character outside of its sprite rectangle, trails are
sometimes being left on the Director 5/6 stage, until you click on it to refresh it. This is a result of the way Director 5/6 use to update its stage area.

The problem does not exist in Authorware and Director 7 or later.

To force Director to redraw the stage area and clear the trails, call
from lingo: "Set the stageColor to the stageColor" while the character
is being dragged.

Further information on Microsoft Agent technology can be found in the Microsoft Agent HomePage.

Copyright © 1996-1999 DirectXtras Inc. All Rights Reserved.

DirectXtras Inc. P.O Box 423417 San Francisco, CA 94142-3417 Voice: +1-415-5058249, Fax: +1-650-9384633 E-mail General information: info@directxtras.com E-mail Technical Support: supp@directxtras.com