NAME
Win32::MSAgent - Interface module for the Microsoft Agent
SYNOPSIS
use Win32::MSAgent;
my $agent = Win32::MSAgent->new('Genie');
my $char = $agent->Characters('Genie');
$char->Voice('Dutch', 'Alexander');
$char->SoundEffectsOn(1);
$char->Show();
$char->MoveTo(300,300);
sleep(5);
foreach my $animation ($char->AnimationNames)
{
my $request = $char->Play($animation);
$char->Speak($animation);
my $i = 0;
while (($request->Status == 2) || ($request->Status == 4))
{ $char->Stop($request) if $i >10; sleep(1); $i++}
}DESCRIPTION
Win32::MSAgent allows you to use the Microsoft Agent 2.0 OLE control in your perl scripts. From the Microsoft Website: "With the Microsoft Agent set of software services, developers can easily enhance the user interface of their applications and Web pages with interactive personalities in the form of animated characters. These characters can move freely within the computer display, speak aloud (and by displaying text onscreen), and even listen for spoken voice commands."
Since the MS Agent itself is only available on MS Windows platforms, this module will only work on those.
See the included demo.pl for some sample code.
PREREQUISITES
In order to use the MSAgent in your scripts, you need to download and install some components. They can all be downloaded for free from http://www.microsoft.com/msagent/devdownloads.htm for more information on installation of the neccesary components, visit http://www.pvoice.org/msagent.htm
- 1. Microsoft Agent Core Components
- 2. Localized Language Components
- 3. MS Agent Character files (.acs files)
- 4. Text To Speech engine for your language
- 5. SAPI 4.0 runtime
Optionally you can install the Speech Recognition Engines and the Speech Control Panel. The Speech Recognition part of MS Agent is not supported in this version of Win32::MSAgent
USAGE
The POD documentation here is not complete. I will continue to write more documentation in upcoming versions. In this version the Agent control and the Characters object are implemented. No events are implemented yet, nor any of the Speech Recognition stuff.
$agent = Win32::MSAgent->new([charactername])
The constructor optionally takes the name of the character to load. It loads the MS Agent OLE control, connects to it, and if the character name is supplied, it loads that character in the Characters object already. It returns the Win32::MSAgent object itself.
$agent->ShowDefaultCharacterProperties([X,Y])
Calling this method displays the default character properties window (not the Microsoft Agent property sheet). If you do not specify the X and Y coordinates, the window appears at the last location it was displayed
$agent->Connected(boolean)
Returns or sets whether the current object is connected to the Microsoft Agent server.
$agent->RaiseRequestErrors(boolean)
This method enables you to determine whether the server raises errors that occur with methods that support Request objects. For example, if you specify an animation name that does not exist in a Play method, the server raises an error (displaying the error message) unless you set this property to False.
$char = $agent->Characters(character)
This method returns the character object for the character you specify. If you don't specify a charactername, it returns the object for the character you previously 'Load'-ed.
$agent->Characters->ListVoices(languagename)
This method can be called on a Character object. It lists all possible voices for a certain language. It does not list voices nor languages that are installed on your system! Just the ones that you could install and use with MS Agent. You can query the correct id for a language from ListLanguages
$agent->Characters->ListLanguages
This method can be called on a Character object. It lists all possible languages you could use with MS Agent. Again, these are not the installed languages, just the ones MS Agent could recognize.
$agent->Characters->Load(id, acsfile)
You can load characters from the 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). For example, specifying the following would load Genie.acs from Agent's Chars directory:
$agent->Characters->Load("genie", "genie.acs")You can also specify your own directory in Agent's Chars directory.
$agent->Characters->Load("genie", "MyCharacters\\genie.acs")$char->Show
This method shows the character on whose object it is called
$char->Hide
This method hides the character on whose object it is called
$char->Play(animation)
This method lets the character do the animation you tell it to. You can get a list of all animations that a certain character supports by calling AnimationNames
$char->Interrupt(request)
The Play, Speak, Move, and other 'animation' methods return request objects. If you want to interrupt the animation, call this method on the character with the returned request object from the action you want to interrupt.
$char->Stop(request)
Like the Interrupt method, this does not only interrupt the action, it completely stops it. The author of this module does not completely see the difference between the two, since there is no 'Resume' method to call on an interrupted action. With $request->Status however you can find out _why_ an action is stopped... See below for more info on the Request object.
$char->StopAll([type])
If you call this method without any parameters, it stops every action for this character. You can however supply a 'type' parameter, indicating which types of actions should be stopped:
(You can also specify multiple types by separating them with commas. )
- "Get"
-
To stop all queued Get requests.
- "NonQueuedGet"
-
To stop all non-queued Get requests (Get method with Queue parameter set to False).
- "Move"
-
To stop all queued MoveTo requests.
- "Play"
-
To stop all queued Play requests.
- "Speak"
-
To stop all queued Speak requests.
Activate
GestureAt
Get
Listen
MoveTo
ShowPopupMenu
Wait
Think
Speak
@animations = $char->AnimationNames()
Voice
Active
AutoPopupMenu
Visible
Speed
Pitch
LanguageID
This method accepts a Microsoft LanguageID like 0x0409 for US English
TTSModeID
This method accepts a speech engine identifier like {c5c35d60-da44-11d1-B1F1-0000F803E456} for Microsoft Sam
Height
Width
HelpModeOn
SoundEffectsOn
Please take the MS Agent Platform SDK helpfile (download from http://www.microsoft.com/msagent/devdownloads.htm) for more documentation on the various methods and properties.
The Request object
yadayadayada
BUGS
None AFAIK...
SUPPORT
The MS Agent itself is supported on MS' public newsgroup news://microsoft.public.msagent You can email the author for support on this module.
AUTHOR
Jouke Visser
jouke@cpan.org
http://jouke.pvoice.orgCOPYRIGHT
Copyright (c) 2002-2003 Jouke Visser. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
SEE ALSO
perl(1).