CyberBuddy Command Reference
This document is intended for advanced users.
CyberBuddy can read standard text and Web documents. But CyberBuddy can do much more when a document is written or converted to a format that is designed specifically for CyberBuddy. This is done by adding "tags" or text commands to tell CyberBuddy to do various things.
CyberBuddy Formatted Documents
When the document is saved with an extension of .cbb, Windows will recognize it as a CyberBuddy document and will "hand" the document to CyberBuddy to be read.
A CyberBuddy text document can be viewed or edited in something as simple as Windows Notepad. The format of the document is simply a text document with some "command tags" that direct the Activities of the Agent character. The CyberBuddy Story Builder simplifies the task of adding the command tags and provides a way to test the document as it is created.
The CyberBuddy Story Builder will generate most of the following commands for you. Using the Story Builder, you can create documents to be read by CyberBuddy without having to worry about the syntax of the commands.
Microsoft Agent Imbedded commands
The following tags are imbedded speech commands that are recognized by the Microsoft agent server. They are common agent commands that will work with most agent programs.
The emphasize tag
You can emphasize a word by putting \emp\ before the word. For example: This is an \emp\important word.
The Pause tag
A pause can provide emphasis. To add a pause use the tag \pau=xxx\, where xxx is the time to pause in milliseconds (1/1000 of a second). For example: Knock! Knock! \pau=1000\ Whose there? This would put a 1 second pause after Knock! Knock! Remember, the time is in milliseconds so 500 = 1/2 second, 1000 = 1 second and so forth.
The whisper tag
You can make the character whisper by putting \chr="whisper"\ before the text to be whispered. All text after this, to the end of the line, will be whispered. For example: \chr="whisper"\ This line will be whispered.
The Monotone tag
This causes the character to speak in a monotone. Place the tag \chr="monotone"\ before text to be spoken. All text after that command, on that line, will be spoken in monotone.
Sometimes, a word must be misspelled in order for it to be pronounced correctly. The Microsoft agent server contains a tag that allows a word to be spelled differently for pronouncing the word and for showing the word in the word balloon. This is called the "map" tag. The format is as follows:
\map="spoken"="written"\ - This tag statement allows words to be seen in the message balloon differently than they will be spoken. For example:
The \map="whinnd"="wind"\ is blowing.
Gives the correct pronunciation for the word "wind".
CyberBuddy Specific Tags
The remaining tags are specific to CyberBuddy. Unless otherwise noted, these commands must appear at the start of a text line, and may be the only item on that line.
The "Gesture" tag
Making the character animate with certain gestures will enhance your message. If you put '&&' at the start of a line immediately followed by an Agent standard gesture, the character will perform the gesture. For example: &&Explain will cause the character to assume the "explain" pose. The Gesture command must be alone on a line. Some other common gestures are: &&Gestureleft (&&Gestureright, &&Gestureup, &&Gesturedown) &&Pleased &&Sad &&Greet &&read &&write &&confused &&getattention &&decline &&lookright (&&lookleft, &&lookup, &&lookdown);
List of Some Agent
included at the end of this section.
There are a few gesture commands that are not a standard Agent gestures. These gestures will only work with CyberBuddy:
The "fly" gesture. &&fly will cause the character to move to a random position on the screen.
The "wait" gesture. &&wait inserted in the text will cause the agent to wait until the text has been read to that point before continuing. Normally, when text and gestures are sent to the character's Agent Server, they are queued by the Agent server and delivered sequentially. This frees the program up to continue with it's other tasks. There are times when it is desirable to have the program wait until the Agent server finishes speaking the queued text. This command accomplishes that. Use it sparingly as the program will keep from doing other things when these tags are imbedded in the document being read.
The "Move to" and "Appear" tags. These tags will cause the character to move to, or appear at a position on the screen. The format of the tag is &&moveto or &&appear followed by a position. The standard positions are: topright, topleft, bottomright, bottomleft, center. Example: &&movetobottomright will move the character to the bottom right corner of the screen.
In addition, the character can be moved, or appear at a position relative to it's current position. This is accomplished with a "delta" command taking the place of the position statement. The format for this command is &&movetodelta10&&15 where the 10 is the number of pixels to move in the X axis (horizontal) and the 15 is the number of pixels to move in the Y axis (vertical). Note that these numbers can be negative numbers as well such as: &&appeardelta-10&&-15.
The name tag
If you put in ## a line of text, the ## will be replaced by the name of the CyberBuddy user. For example: Hello ##, how are you today? The ## tag may appear anywhere in text.
The Raise Pitch tag
If you put a "^+" at the start of a line, that line will be read with a higher pitch. This is especially effective when there is quoted text from a child or woman. For example: ^+"How was work today Honey?"
said the wife.
"Just great" said the husband.
Wait time tag
The wait time tag can be used to cause the character to wait a specific amount of time before continuing. The format for this tag is %% followed by the desired wait time in milliseconds. For example:
%%8000 would wait 8 seconds.
Sound effects tag
To play a sound effect in the CyberBuddy text place a &&SFX command followed by the filename of the sound effect. The file is assumed to be a wav or mid in the same folder as CyberBuddy. Example: &&SFXmysound.wav
Background Sound tag
This tag is similar to the Sound Effects tag as shown above. The difference is that it specifies a midi file instead of a wave sound file. Due to the way sound cards operate, midi files (.mid) can be played at the same time as the agent is speaking while wave sound files (.wav) may not be played at the same time as speaking. This makes midi files perfect for background music. Since the midi file will be normally used as background music, the tag for this type of file also includes a volume command. This sets the volume of the midi music file as a percentage of total volume. A volume change may be issued again later to change the volume of the music as it is playing. The format of the background music tag is: &&SFXmymusic.mid=volume=50 where mymusic.mid is the midi music file and 50 means volume of the midi music at 50%.
If you want the music to start at a specific point, or change volume at a certain point, you need to have a "wait" animation command (&&wait) on the line before the midi command. This will tell the Agent to wait until the speech has caught up to that point before changing the background music. To stop background music at a point, change the volume level to 0.
Try the "Take a Tour" on the "About" tab of CyberBuddy for an example of sound effects and background music.
Background Volume tag
This tag can be used to change the volume of a background midi music file that is playing. The format for the tag is: &&SFX=volume=50 where 50 means volume of the midi music at 50%. Note that this volume tag will only change the volume of the background music. A value of 100 will be full volume. A value of 0 will stop the current music.
See the note above. A "Wait" animation command (&&wait) should appear on the line above this volume change command.
The comment / special command tag
A $$ at the start of a line indicates a comment or special command. The text on this line will not be spoken by the character. You can use it to add comments to yourself in the text. Some special commands using the comment identifier are:
Character Change command
This is a complex command that is best generated by the CyberBuddy Story Builder. It is documented here for information purposes. The character change command is $$CC followed by the character information. A typical command looks like:
The command contains; the name of the character, the text to speech Voice ID, voice pitch(1-400), voice speed(50-230), character size (1-20 10 is normal size).
When CyberBuddy sees this command, it checks to see if the character is available on the user's computer. If so, the character is loaded. If not, this command is ignored. It next checks to see if the indicated voice ID is available. If so, it is loaded. If not, the default voice for the character is used.
Tells CyberBuddy to load sound effects etc. from a web site before reading the document.
If you are creating a web document that has sound effects, CyberBuddy has to know where to find the sound files. This is handled by the preload statement. This statement must be the first line in a CyberBuddy document. The statement contains the preload statement followed by the URL of the web site containing the sound files. Example:
When this statement is seen by CyberBuddy, as the first line in the document, CyberBuddy will scan the document looking for any required sound files. It will then check to see if it already has the desired sound file. If not, it will download these files to the CyberBuddy folder. This is done so that when the document is read, there will be no interruption when a sound effect is encountered.
The following tags are specialized tags primarily used by CyberBuddy for instruction or a tour of the program. As such, it is rare that you will need to use them. To see an example of how these tags are used, look at the file tour.ahf or tour.cbb in the CyberBuddy folder. This is a text file that can be opened with Notepad.
Show Tab tag
The ^^ tag is used to display a particular Tab page of the CyberBuddy program. The ^^ is followed by the name of the Tab. Valid tab names are: about, general, time(news tab), reminder, read, send, icq(buddies tab), email, stocks, www.
Show at control tag
This command is a @@ followed by text, followed by && followed by a component name in CyberBuddy. This causes CyberBuddy to point to a specific control in the CyberBuddy program and speak the text. An intimate knowledge of the various controls within CyberBuddy is necessary and this command is only used in the "tour of the program". To see how this tag is used, look at the tour.ahf file in the CyberBuddy folder. A variation of this tag is shown next. It can be used to load web pages while CyberBuddy is speaking.
Load web page command.
If the user is online, this command can be used to load a specific web page in the user's browser as CyberBuddy speaks. The format for this command is @@ followed by any text to be spoken, followed by &&www, followed by the full URL of the desired web page. For example:
@@ Here is the CyberBuddy homepage &&wwwhttp://thecyberbuddy.com
[#=GestureList]List of Some Agent Character Gestures
The following gesture commands, preceeded on a line by &&, will cause the Agent Character to perform the gesture. For example: &&explain