. DirectXtras Home
        Home

DirectCommunication Xtra
DirectConnection Xtra
DirectControl Xtra
DirectEmail Xtra
DirectFTP Xtra
DirectImage Xtra
DirectInteraction Xtra
DirectOS Xtra
DirectSMS Xtra
DirectSound Xtra
DirectTransition Xtra
DirectTransition3D Xtra Set I
DirectTransition3D Xtra Set II
DirectTransition3D Xtra Set III
DirectTTS Xtra
Documentation
License Agreement
Licensing Fees
Order Form
XtrAgent
DirectXport Xtra

SpeechPlugin

Special Discounted Bundles

The Gallery
How To Order
Order Form
Check for Upgrades

Sign in
Change Your Profile

Contact Us
















    .
DirectXtras
Xtra Power for Director & Authorware



DirectTTS Xtra
 Provide your applications with the ability to talk…

Authorware 4.x Compatible Authorware 5.x CompatibleAuthorware 6.x CompatibleAuthorware 7.x CompatibleDirector 5.x Compatible Director 6.x CompatibleDirector 7.x Compatible Director 8.x CompatibleDirector MX CompatibleDirector MX 2004 Compatible Director Shockwave Compatible and Safe     MacOS 8.x and 9.x CompatibleWindows Compatible   


DirectTTS Xtra™ Version 1.0 Documentation

 

Developed by Tomer Berda, DirectXtras Inc.
(C) Copyright 2004.
Last updated:
August 31, 2004.

DirectTTS is a cross-platform, easy to use Scripting Xtra for Macromedia Director, Authorware and Shockwave that provides applications with the ability to talk by transforming text to speech.

DirectTTS Xtra includes support for high-quality lip-synching, allowing the creation of guides, coaches, entertainers, and other types of assistants or specialists.

On Windows, the Xtra can use any Microsoft SAPI compliant TTS (Text-To-Speech) engine that is installed on the system, at any language, to produce speech, such as the Microsoft English TTS engine that is pre installed with Windows 2000, and which can be freely distributed along with applications developed with DirectTTS Xtra.

DirectTTS Xtra is available for Director 5 and above, Authorware 4 and above, and is compatible with Windows 9X and newer (including 2000, ME, NT, XP) as well as MacOS 8 and 9.

DirectTTS Xtra is Shockwave safe, so it can also be used with Shockwave 7 or later and when safety features in Director are turned on.

An auto downloadable Shockwave safe package of DirectTTS Xtra is also available. It is a compressed, small sized (about 20K) version of the Xtra, that can be downloaded automatically from a web site to the user's local machine whenever needed, and once installed provides Shockwave applications on the web with the ability to talk.

Installation

Registration

Overview

Using DirectTTS Xtra

Distributing Speech Engines and Components

Functions Reference

Child Functions:

New()
Forget()

ttsSpeak()

ttsStop()

ttsPause()

ttsResume()

ttsIsSpeaking()

ttsInject()

ttsSetSpeed()

ttsGetSpeed()

ttsSetVolume()

ttsGetVolume()

ttsSetPitch()

ttsGetPitch()

ttsSetVoice()

ttsGetVoice()

Global Functions:

ttsGetNumOfVoices()

ttsGetVoiceAge()

ttsGetVoiceGender()

ttsGetVoiceName()

ttsGetVoiceStyle()

ttsGetVoiceDescription()

ttsGetVoiceLanguageID()

ttsGetVoiceSubLanguageID()

ttsGetVersion()

Events Reference

on SpeechStart
on SpeechStop

on SpeechVisual

Error Codes

 

Installation

DirectTTS Xtra has an authoring version, a run time version, a Shockwave version, and an auto downloadable Shockwave safe package. The trial version only includes the authoring version.
The authoring version should be placed in your Director and/or
Authorware "Xtras" folder. It will be used by Director and/or Authorware
when creating and testing your movie/presentation. 

The run time version should be placed in a folder named "Xtras" that is
inside the folder that contains the host projector/package. Alternatively, you
can bundle it in your projectors/packages. It is used when running your movie/presentation as a stand-alone application.

The Shockwave safe version can be used with Shockwave for Director or Authorware, and should be placed in the appropriate Shockwave 'Xtras' folder.


The auto downloadable Shockwave safe package should be
uploaded to your server. It is used when running your movie in a web
browser via Shockwave for Director 7 or above. 

Once you have decided the location on your server where the auto
downloadable packages will be placed, you should modify the "xtrainfo.txt"
file in the Director 7 or above folder accordingly. For example if you uploaded
the downloadable package to "http://www.myserver.com/packs" you
should add the following lines to "xtrainfo.txt". 

[#namePPC:"DirectTTS", #nameW32:"DirectTTS.x32",
#package:"http://www.myserver.com/packs/DirectTTS"] 


Finally, add a reference to the auto downloadable package in your movie.
Open a movie that uses the DirectTTS Xtra. From the
Modify->Movie->Xtras dialog in Director, select the DirectTTS Xtra in the
list of Xtras. The "Download if needed" check box should now be enabled. (If
it's not enabled, make sure the filename in "xtrainfo.txt" matches the actual
filename of the Xtra.) Click on the check box and Director will load information
from the package file for each platform and add it to the current movie. 

IMPORTANT: The authoring, run time and Shockwave versions can not
coexist in the same "Xtras" folder, so be sure to place the appropriate version
in the appropriate folder. 

 

Registration

DirectTTS Xtra is a commercial product. 

Basically, there are 3 types of licenses: Single, Site and Corporate.

Single License: Entitles an organization to receive one copy of the licensed
Xtra(s) which can only be used by a single developer on a single computer at
any one time.

Site License: Entitles an organization to receive one copy of the licensed
Xtra(s) which can be used by any number of developers on any number of
workstations within one site.

Corporate License: Entitles an organization to receive one copy of the
licensed Xtra(s) which can be used by any number of developers on any
number of workstations within the entire corporation (multiple sites).

Important Notes:

  • A copy of the licensed Xtra includes the Authoring and freely distributable Runtime versions.
  • If you intend to distribute your application on both platforms (Windows and MacOS), or if you author your application on one platform and intend to deliver it on the other platform, you'd have to license both the Windows and MacOS versions of the Xtra.
  • Qualification for free and discounted upgrades and updates will be provided based on the registered e-mail address.
  • All licenses now include the Shockwave safe version of the Xtra along with an auto-downloadable Shockwave safe package which can be used with Shockwave movies on the web.
  • Single and Site licenses include free future upgrades and updates for minor revisions of the licensed Xtra(s), while Corporate license includes free future upgrades and updates for both major and minor revisions of the licensed Xtra(s).

Once you have licensed DirectTTS Xtra, you will be given a serial number that should be passed to the New() function when creating the DirectTTS Xtra instance in order to unlock the Xtra. Once the Xtra is unlocked,
trial warnings will no longer be presented, there will be no other limitations and the run-time and Shockwave versions of the Xtra will become activated.

Be sure to protect the call to New() so that the serial number does not become exposed. This method should be called before any other methods are called. 

You can freely distribute the run time version and Shockwave safe package of DirectTTS Xtra with any application developed by you, and you alone. You can not redistribute the authoring version. Please refer to the license agreement for further information.

Note that if your Shockwave movie needs to run on both Windows and MacOS, you'd need to obtain a license for both the Windows and MacOS versions of the Xtra, in order to obtain both the Windows and MacOS Shockwave safe versions and their auto-downloadable Shockwave safe packages, along with serial numbers to activate them.

 

Overview

DirectTTS Xtra functions are divided into two categories, global and child.

Global functions can be called from anywhere in your scripts and do not require a DirectTTS Xtra instance to be passed to them. They can be used to retrieve information about the installed voices, the Xtra version, etc.

Child functions can be called from anywhere in your scripts but require a DirectTTS Xtra instance to be passed to them. Those are the functions that actually transform text into speech and control the way the speech is being produced through the specified instance.

Each instance of DirectTTS Xtra can present one voice at a time. In order to use multiple voices at the same time, create multiple instances of DirectTTS Xtra and work with them simultaneously. 

 

Using DirectTTS Xtra

 

Step 1 - Create a new instance of DirectTTS Xtra and store it for a later use. You will have to pass it as the first parameter to the other DirectTTS Xtra child functions.

Lingo Sample Code for Director :

Set TTS = new (Xtra "DirectTTS",0)

Sample Code for Authorware :

TTS:=NewObject("DirectTTS",0)

JavaScript Sample Code for Director :

Set TTS = new (Xtra "DirectTTS",0)

Step 2 - Select the default voice (assuming that at least one is installed).

Lingo Sample Code for Director :

ttsSetVoice (TTS, 0)

Sample Code for Authorware :

CallObject (TTS, "ttsSetVoice", 0)

JavaScript Sample Code for Director :

TTS.ttsSetVoice(0)

Step 3 - Transform text to speech using the selected voice.

Lingo Sample Code for Director :

ttsSpeak (TTS, "Hello Director")

Sample Code for Authorware :

CallObject (TTS, "ttsSpeak", "Hello Authorware")

JavaScript Sample Code for Director :

TTS.ttsSpeak ("Hello Director")

Note that the above example is using the default voice. The Xtra provides functions to query for installed voices and change the current voice.

Step 4 - Once you're done using the Xtra, delete the DirectTTS instance that you've created in step 1.

Lingo Sample Code for Director : Set TTS=0

Sample Code for Authorware : DeleteObject(TTS)

JavaScript Sample Code for Director : var TTS=0

Distributing Speech Engines and Components

On Windows, the Xtra can use any Microsoft SAPI compliant TTS (Text-To-Speech) engine that is installed on the system, at any language, to produce speech, such as the Microsoft English TTS engine that is pre installed with Windows 2000.

For the Xtra to work properly, your application should ensure that Microsoft SAPI 4 is installed on the client machine using the ttsGetVersion() function. If Microsoft SAPI 4 is not already installed, your application should install it prior to using the Xtra.

Microsoft SAPI 4 comes pre installed with Windows 2000, and might be installed on Windows NT/9X machines if one or more speech related and SAPI compliant products were previously installed on them.

Microsoft SAPI installation file can be freely distributed along with your applications.

The Microsoft TTS engines can also be freely distributed along with your applications (subject to Microsoft's terms and conditions). Other non free multilingual SAPI compliant TTS engines are also available on the market from various TTS vendors, including:

Microsoft Agent Text-To-Speech Engines

Digalo

IBM ViaVoice

Eloquent

Elan

Infovox

Lucent


On MacOS, the Xtra can use any Speech Manager compatible TTS engine that is installed on the system, at any language, to produce speech, such as Apple PlainTalk TTS engines that are distributed along with the MacOS.

For the Xtra to work properly, your application should ensure that Apple Speech manager is installed and activated on the client machine using the ttsGetVersion() function. The Speech manager comes preinstalled along with the MacOS and if necessary can be activated from the Extensions Manager.

 

 

Functions Reference

 

Director: New ( Xtra "DirectTTS", integer SerialNumber )

Authorware: NewObject ("DirectTTS", integer SerialNumber)

Creates a new DirectTTS Xtra instance.

The returned value is a new instance of DirectTTS Xtra.

Parameter :

SerialNumber : DirectTTS Xtra Serial Number. If you are using the trial version, pass the number 0.

Returns : DirectTTS instance.

 

Director: Forget ( object me )

Authorware: DeleteObject ( object me )

Deletes a DirectTTS Xtra instance.

Parameter :

object me : DirectTTS Instance.

Returns : None.

In Director, you can also delete the DirectTTS Xtra instance by setting it to zero.

 

ttsSpeak ( object me, string TTS )

Converts a text string to speech and send the speech data to the
audio output device. 

Parameters :

object me : DirectTTS Instance.

TTS : Text string to be spoken.

Returns : Error Code.

Remarks : The text string to be spoken can contain tags. The tags syntax may vary among platforms and TTS engines. 

Microsoft SAPI complaint engines should accept tags embedded between a pair of back slashes in the format "\Tag=Value\", where 'Tag' is the name of the tag and 'Value' is a numeric or string value for the tag. Multiple tags are supported and should be separated by spaces. For example, "\Spd=360\" will set the speech speed to 360 words per minute.

Following are Microsoft SAPI compliant tags. The range of values for the parameter of each tag may vary depending on the installed TTS engine.

Vol Tag - Sets the baseline speaking volume of the speech output.

Syntax: \Vol=number\

Where 'number' is the baseline speaking volume: 0 is silence and 65535 is maximum volume. 

The volume setting affects both left and right channels. You cannot set the volume of each channel separately.

Spd Tag - Sets the baseline average talking speed of the speech output.

Syntax: \Spd=number\

Where 'number' is the baseline average talking speed, in words per minute. 

Rst Tag - Resets all tags to the default settings.

Syntax: \Rst\

Pit Tag - Sets the baseline pitch of the output to the specified value in hertz.

Syntax: \Pit=number\

Where 'number' is the pitch in hertz. 

Pau Tag - Pauses speech for the specified number of milliseconds.

Syntax: \Pau=number\

Where 'number' is the number of milliseconds to pause. 

Emp Tag - Emphasizes the next word spoken. This tag must immediately precede the word.

Syntax: \Emp\

 

ttsStop ( object me )

Stops playback on the audio output device.
Any unspoken text will be cleared from memory. 

Parameter :

object me : DirectTTS Instance.

Returns : Error Code.

 

ttsPause ( object me )

Pauses playback on the audio output device.

Parameter :

object me : DirectTTS Instance.

Returns : Error Code.

 

ttsResume ( object me )

Resumes playback on the paused audio output device. 

Parameter :

object me : DirectTTS Instance.

Returns : Error Code.

 

ttsIsSpeaking ( object me )

Checks whether a speech is being produced.

Parameter :

object me : DirectTTS Instance. 

Returns : True if speech is being produced by the specified instance and false otherwise.

 

ttsInject ( object me, string Tag )

Injects text-to-speech control tags into the text currently being
spoken. 

This function can be used to control speaking parameters on the fly
without having to reconstruct the text-to-speech buffers. If the
engine understands a tag, it should act on the tag as soon as possible
after receiving it.

Parameters :

object me : DirectTTS Instance.

Tag : A string that contains the tag to inject. A string can contain
multiple tags, separated by spaces. The tags in the string should be in
the same format as tags embedded in text passed to the ttsSpeak() function -- for example, "\Spd=360\". 

Returns : Error Code.

Remarks : Do not use this function to inject bookmark tags.

This function is not available in the MacOS version of the Xtra, and
will fail silently if called under MacOS.

 

ttsSetSpeed ( object me, integer Speed )

Sets the average speaking speed of the current voice. 

Parameters :

object me : DirectTTS Instance.

Speed : An integer specifying the new average speaking speed, in
words per minute. If the value is out of range for the engine, an error is
returned and the speed is not changed. 

Returns : Error Code.

 

ttsGetSpeed ( object me )

Retrieves the current average speaking speed of the current voice. 

Parameter :

object me : DirectTTS Instance.

Returns : An integer indicating the average speaking speed of
the current voice, in words per minute. 

 

ttsSetVolume ( object me, integer Volume )

Sets the speaking volume of the current voice. 

Parameters :

object me : DirectTTS Instance.

Volume : An integer specifying the new speaking volume, in percent.
The volume level ranges from 0 (absolute silence) to 100 (maximum
volume). If the value is out of range for the engine, the function
returns an error and the speaking volume is not changed. 

Returns : Error Code.

 

ttsGetVolume ( object me )

Retrieves the current speaking volume of the current voice. 

Parameter :

object me : DirectTTS Instance.

Returns : An integer indicating the speaking volume of the
current voice, in percent. The volume level ranges from 0 (absolute
silence) to 100 (maximum volume). 

 

ttsSetPitch ( object me, integer Pitch )

Sets the speaking pitch of the current voice. 

Parameters :

object me : DirectTTS Instance.

Pitch : An integer specifying the new pitch, in hertz. If the value is out
of range for the engine, an error is returned and the pitch is not
changed. 

Returns : Error Code.

 

ttsGetPitch ( object me )

Retrieves the current speaking pitch of the current voice.

Parameter :

object me : DirectTTS Instance.

Returns : An integer indicating the speaking pitch, in hertz. 

 

ttsSetVoice ( object me, integer VoiceID )

Changes the current voice to one of the available voices and its
preprogrammed default settings. 

Parameters :

object me : DirectTTS Instance.

VoiceID : An integer specifying the ID of the voice setting. Can be 0 (zero) for the default voice at the default language or any number between 1 (first available voice) and the number returned by the ttsGetNumOfVoices() function (last available voice).

Returns : Error Code.

 

ttsGetVoice ( object me )

Retrieves the ID of the current voice. 

Parameter :

object me : DirectTTS Instance.

Returns : An integer indicating the ID of the current voice.

 

ttsGetNumOfVoices ( )

Retrieves the total number of available voices on the client machine.

Returns : An integer indicating the number of available voices on
the client machine.

 

ttsGetVoiceAge ( integer VoiceID )

Retrieves the age of the specified voice. 

Parameters :

VoiceID : An integer specifying the ID of the voice setting. Can be any
number between 1 (first available voice) and the number returned by
the ttsGetNumOfVoices() function (last available voice). 

Returns : An integer indicating the age of the specified voice.
Possible values: 1, 3, 6, 14, 30 or 70. 

 

ttsGetVoiceGender ( integer VoiceID )

Retrieves the gender of the specified voice. 

Parameter :

VoiceID : An integer specifying the ID of the voice setting. Can be any
number between 1 (first available voice) and the number returned by
the ttsGetNumOfVoices() function (last available voice). 

Returns : An integer indicating the gender of the specified voice.
Possible values: 1 for female, 2 for male and 0 for not perceptibly male
or female. 

 

ttsGetVoiceName ( integer VoiceID )

Retrieves the name of the specified voice. 

Parameter :

VoiceID : An integer specifying the ID of the voice setting. Can be any
number between 1 (first available voice) and the number returned by
the ttsGetNumOfVoices() function (last available voice). 

Returns : A string containing the name of the specified voice. 

 

ttsGetVoiceStyle ( integer VoiceID )

Retrieves the personality of the specified voice. 

Parameter :

VoiceID : An integer specifying the ID of the voice setting. Can be any
number between 1 (first available voice) and the number returned by
the ttsGetNumOfVoices() function (last available voice). 

Returns : A string containing the personality of the specified
voice. For example: "Business", "Casual", "Computer", "Excited",
"Singsong". 

Remarks : This function is not available in the MacOS version of the Xtra, and
will fail silently if called under MacOS.

 

ttsGetVoiceDescription ( integer VoiceID )

Retrieves the description of the specified voice.

Parameter :

VoiceID : An integer specifying the ID of the voice setting. Can be any
number between 1 (first available voice) and the number returned by
the ttsGetNumOfVoices() function (last available voice). 

Returns : A string containing the description of the specified
voice. 

Remarks : On MacOS, the returned string is the same as the one returned
by the ttsGetVoiceName() function. On Windows, the returned string
should be of the form: "Voice Description (Age, gender, etc.),
Language, [Optional Sampling Rate,] Manufacturer EngineName[,
Optional Version Number]". 

 

ttsGetVoiceLanguageID ( integer VoiceID )

Retrieves the language ID of the specified voice. 

Parameter :

VoiceID : An integer specifying the ID of the voice setting. Can be any
number between 1 (first available voice) and the number returned by
the ttsGetNumOfVoices() function (last available voice). 

Returns : An integer indicating the language ID of the specified
voice. Possible values:

6: Danish 
7: German
9: English (US) (Sub language ID is 1)
9: English (British) (Sub language ID is 2)
10: Spanish
11: Finnish
12: French
16: Italian
17: Japanese
19: Dutch
20: Norwegian
22: Portuguese (Brazilian)
25: Russian
29: Swedish

 

ttsGetVoiceSubLanguageID ( integer VoiceID )

Retrieves the sub language ID of the specified voice. 

Parameter :

VoiceID : An integer specifying the ID of the voice setting. Can be any
number between 1 (first available voice) and the number returned by
the ttsGetNumOfVoices() function (last available voice). 

Returns : An integer indicating the sub language ID of the
specified voice. The sub language ID is essentially a locale setting. For
example, Portuguese has two sub languages, Brazilian and Standard. 

 

ttsGetVersion ( integer SoftID )

Retrieves the Xtra version and checks whether Microsoft SAPI (on Windows) or Apple Speech Manager (on MacOS) are installed.

Parameter :

SoftID :  Pass the number 1 to retrieve the Xtra version or the number 2 to check whether Microsoft SAPI or Apple Speech Manager are installed.

Returns : When SoftID parameter is set to 1, the returned value is an integer indicating the Xtra version multiple by 1000. For example: 1000 for version 1.00, 4500 for version 4.5, etc. When SoftID parameter is set to 2, the returned value is true if Microsoft SAPI (on Windows) or Apple Speech Manager (on MacOS) are installed on the client machine, and false otherwise.

 

Events Reference

DirectTTS Xtra will call the following functions to notify your application on the speech playback status. Your application can implement one or more of those functions to retrieve the speech playback status.

Please refer to the DirectTTS Xtra sample Director movie for a sample code.

Events are not available in Authorware.

 

on SpeechStart ( object me )

Being called when a speech starts. 

Parameter :

object me : The DirectTTS instance associated with the event.

 

on SpeechStop ( object me )

Being called when a speech stops. 

Parameter :

object me : The DirectTTS instance associated with the event.

 

on SpeechVisual ( object me, integer MouthHeight, integer MouthWidth, integer MouthUpturn, integer JawOpen, integer TeethUpperVisible, integer TeethLowerVisible, integer TonguePosn, integer LipTension )

Being called while DirectTTS Xtra produces speech, describing which
phoneme is being used in the current digital-audio stream.

Parameters :

object me : The DirectTTS instance associated with the event.

MouthHeight : Height of the mouth or lips. This is a linear range from
255 for the maximum possible height for the mouth to 0 for the
minimum height (that is, the mouth or lips are closed). 

MouthWidth : Width of the mouth or lips. This is a linear range from
255 for the maximum possible width for the face to 0 for the minimum
width (that is, the mouth or lips are puckered). 

MouthUpturn : Extent to which the mouth turns up at the corners
(that is, how much it smiles). This is a linear range from 255 for the
maximum upturn (that is, the mouth is fully smiling) to 0 if the corners
of the mouth turn down. If this parameter is 128, the mouth is neutral. 

JawOpen : Angle to which the jaw is open. This is a linear range from
255 for completely open to 0 for completely closed. 

TeethUpperVisible : Extent to which the upper teeth are visible. This
is a linear range from 255 for the maximum extent (that is, the upper
teeth and gums are completely exposed) to 0 for the minimum (the
upper teeth are completely hidden). If this parameter is 128, only the
teeth are visible. 

TeethLowerVisible : Extent to which the lower teeth are visible. This
is a linear range from 255 for the maximum extent (that is, the lower
teeth and gums are completely exposed) to 0 for the minimum (the
lower teeth are completely hidden.) If this parameter is 128, only the
teeth are visible. 

TonguePosn : Tongue position. This a linear range from 255 if the
tongue is against the upper teeth, to 0 if it is relaxed. If this parameter
is 128, the tongue is visible. 

LipTension : Lip tension. This is a linear range from 255 if the lips are
very tense to 0 if they are completely relaxed. 

Remarks : This event is not available in the MacOS version of the Xtra and
will not be fired on MacOS.

 

Error Codes

 

0: Success (no error).

-1: The Xtra has failed to initialize due to insufficient memory or missing components.

-2: Invalid voice ID.

-2147024882: Not enough memory.
-2147418113:
Value out of range.

The DirectTTS Xtra functions might return additional platform specific error codes that are not listed above.



DirectXtras Inc.
P.O Box 2645, Menlo Park, CA, 94026, U.S.A
Voice: +1-415-5058249, Fax: +1-801-8585841
Toll Free: 1-800-4453093
E-mail General Information: info@directxtras.com
E-mail Technical Support: support@directxtras.com

Copyright © 1996-2004 DirectXtras Inc. All Rights Reserved.
WebMaster: tamar@directxtras.com
Last Updated: 9/18/2004 8:35:46 AM.