Acapela Active Speech Control
Reference manual
Ref. : AcaMul-ActiveX-6
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 2/35
AcaMul-ActiveX-6
Document revisions
Version Date Subject Author(s)
A 12/26/2002 Preliminary version (first external review)
SB
B 08/15/2003 First version RD
C 10/09/2003 Add OEMKey property RD
D 12/23/2005 Add ServerShutdown method
MAJOR CHANGE :
Component, interfaces, type libraries & classes names
RD
E 09/09/2005 Add voice : YoussefRemove voice : AnaVoice identification changes for voice Laura, Lucy, Maria, Chiara
RD
F 09/12/2005 First version for Acapela Multimedia 6.0
MPB
G 21/12/2005 Added remark about BabTTS-style OEMKey and location of AcaTTS.dll
LZ
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 3/35
AcaMul-ActiveX-6
Table of contents1. Introduction_____________________________________________5
2. Overview_______________________________________________6
2.1. Package contents______________________________________________62.1.1. ActiveX component.....................................................................................................62.1.2. Documentation..........................................................................................................62.1.3. C/C++ language header file........................................................................................62.1.4. C/C++ Sample application..........................................................................................62.1.5. VB6 Sample application.............................................................................................6
2.2. Installation___________________________________________________6
2.3. Programming overview__________________________________________8
3. API Reference____________________________________________10
3.1. IAASpeechCtrl interface_________________________________________103.1.1. Methods..................................................................................................................10
3.1.1.1 ConnectEngine....................................................................................................103.1.1.2 DisconnectEngine................................................................................................113.1.1.3 Enumerate.........................................................................................................113.1.1.4 Load..................................................................................................................123.1.1.5 Unload...............................................................................................................133.1.1.6 Speak................................................................................................................143.1.1.7 Stop..................................................................................................................153.1.1.8 Pause................................................................................................................163.1.1.9 Resume.............................................................................................................163.1.1.10 EventMask........................................................................................................173.1.1.11 GetVarAudioData,GetAudioData...........................................................................183.1.1.12 ServerShutdown................................................................................................19
3.1.2. Properties...............................................................................................................203.1.2.1 Voice(n).............................................................................................................203.1.2.2 CurrentVoice......................................................................................................203.1.2.3 VoiceCount........................................................................................................213.1.2.4 Output...............................................................................................................213.1.2.5 Filename............................................................................................................223.1.2.6 Volume.............................................................................................................233.1.2.7 Pitch..................................................................................................................233.1.2.8 Speed................................................................................................................233.1.2.9 OEMKey.............................................................................................................233.1.2.10 Status..............................................................................................................243.1.2.11 LastError..........................................................................................................24
3.1.3. Events....................................................................................................................253.1.3.1 AudioOpen.........................................................................................................253.1.3.2 AudioClose.........................................................................................................25
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 4/35
AcaMul-ActiveX-6
3.1.3.3 TextStart...........................................................................................................263.1.3.4 TextStop............................................................................................................263.1.3.5 WordPosition......................................................................................................263.1.3.6 AcaPhoneme.......................................................................................................273.1.3.7 MouthPosition.....................................................................................................283.1.3.8 AudioData..........................................................................................................293.1.3.9 LastError............................................................................................................30
3.2. IAAVoiceCtrl interface___________________________________________303.2.1. Properties...............................................................................................................30
3.2.1.1 Cmd..................................................................................................................303.2.1.2 Gender..............................................................................................................313.2.1.3 Language...........................................................................................................313.2.1.4 Speaker.............................................................................................................313.2.1.5 Index................................................................................................................313.2.1.6 Frequency..........................................................................................................32
4. Appendix A______________________________________________33
4.1. Language identifiers____________________________________________33
4.2. Constants____________________________________________________34
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 5/5
AcaMul-ActiveX-6
1. Introduction
Acapela Active Speech Control is an ActiveX control that allows any Windows application to integrate and use the Acapela TTS.
It provides 2 interfaces (IAASpeechCtrl, IAAVoiceCtrl) providing the methods, properties and events needed to easily use the text-to-speech technology.
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 6/6
AcaMul-ActiveX-6
2. Overview2.1.Package contents
2.1.1.ActiveX component
These files contain the implementation of the API and must be linked to the application.
<Program files>\Acapela Group\Acapela Multimedia
2.1.2.Documentation
AcaMul-ActiveX-6.doc (this file) is located in:
<Program files>\Acapela Group\Acapela Multimedia\Doc
2.1.3.C/C++ language header file
c_aaspeechctrl.h is located in:
<Program files>\Acapela Group\Acapela Multimedia\sdk\include
This file contains the constants definitions and values (see also Constants) used by Acapela
Active Speech Control.
2.1.4.C/C++ Sample application
A C/C++ sample application (project, sources) located in :
<Program files>\Acapela Group\Acapela Multimedia\sdk\samples\ActiveX\VC++
2.1.5. VB6 Sample application
A VB6 sample application (project, sources) located in :
<Program files>\Acapela Group\Acapela Multimedia\sdk\samples\ActiveX\VB
2.2.Installation
After succesfull installation, the following entries are created in the registry :
[HKEY_CLASSES_ROOT\CLSID\{62D734B4-3A0A-484A-BA71-ABF084F0EA2E}]@="AASpeechCtrl Class"
[HKEY_CLASSES_ROOT\CLSID\{62D734B4-3A0A-484A-BA71-ABF084F0EA2E}\Control]
[HKEY_CLASSES_ROOT\CLSID\{62D734B4-3A0A-484A-BA71-ABF084F0EA2E}\InprocServer32]Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 7/35
AcaMul-ActiveX-6
@="<path>\AGASpeechCtrl.dll"
[HKEY_CLASSES_ROOT\CLSID\{62D734B4-3A0A-484A-BA71-ABF084F0EA2E}\Insertable]
[HKEY_CLASSES_ROOT\CLSID\{62D734B4-3A0A-484A-BA71-ABF084F0EA2E}\MiscStatus]@="0"
[HKEY_CLASSES_ROOT\CLSID\{62D734B4-3A0A-484A-BA71-ABF084F0EA2E}\MiscStatus\1]@="131473"
[HKEY_CLASSES_ROOT\CLSID\{62D734B4-3A0A-484A-BA71-ABF084F0EA2E}\ProgID]@="AGASpeechCtrl.AASpeechCtrl.1"
[HKEY_CLASSES_ROOT\CLSID\{62D734B4-3A0A-484A-BA71-ABF084F0EA2E}\Programmable]
[HKEY_CLASSES_ROOT\CLSID\{62D734B4-3A0A-484A-BA71-ABF084F0EA2E}\ToolboxBitmap32]@="<path>\AGASpeechCtrl.dll, 101"
[HKEY_CLASSES_ROOT\CLSID\{62D734B4-3A0A-484A-BA71-ABF084F0EA2E}\TypeLib]@="{2DE7D51F-E0EF-44D3-9BB8-D3E836CE55C9}"
[HKEY_CLASSES_ROOT\CLSID\{62D734B4-3A0A-484A-BA71-ABF084F0EA2E}\Version]@="1.0"
[HKEY_CLASSES_ROOT\CLSID\{62D734B4-3A0A-484A-BA71-ABF084F0EA2E}\VersionIndependentProgID]@="AGASpeechCtrl.AASpeechCtrl"
[HKEY_CLASSES_ROOT\CLSID\{C95CC651-9E6A-4508-A5FD-BF9C474695A6}]@="AAVoiceCtrl Class"
[HKEY_CLASSES_ROOT\CLSID\{C95CC651-9E6A-4508-A5FD-BF9C474695A6}\InprocServer32]@="<path>\AGASpeechCtrl.dll""ThreadingModel"="Apartment"
[HKEY_CLASSES_ROOT\CLSID\{C95CC651-9E6A-4508-A5FD-BF9C474695A6}\ProgID]@="AGASpeechCtrl.AAVoiceCtrl.1"
[HKEY_CLASSES_ROOT\CLSID\{C95CC651-9E6A-4508-A5FD-BF9C474695A6}\Programmable]
[HKEY_CLASSES_ROOT\CLSID\{C95CC651-9E6A-4508-A5FD-BF9C474695A6}\TypeLib]@="{2DE7D51F-E0EF-44D3-9BB8-D3E836CE55C9}"
[HKEY_CLASSES_ROOT\CLSID\{C95CC651-9E6A-4508-A5FD-BF9C474695A6}\VersionIndependentProgID]@="AGASpeechCtrl.AAVoiceCtrl"
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 8/35
AcaMul-ActiveX-6
[HKEY_CLASSES_ROOT\TypeLib\{2DE7D51F-E0EF-44D3-9BB8-D3E836CE55C9}]
[HKEY_CLASSES_ROOT\TypeLib\{2DE7D51F-E0EF-44D3-9BB8-D3E836CE55C9}\1.0]@="AGASpeechCtrl 1.0 Type Library"
[HKEY_CLASSES_ROOT\TypeLib\{2DE7D51F-E0EF-44D3-9BB8-D3E836CE55C9}\1.0\0]
[HKEY_CLASSES_ROOT\TypeLib\{2DE7D51F-E0EF-44D3-9BB8-D3E836CE55C9}\1.0\0\win32]@="<path>\AGASpeechCtrl.dll"
[HKEY_CLASSES_ROOT\TypeLib\{2DE7D51F-E0EF-44D3-9BB8-D3E836CE55C9}\1.0\FLAGS]@="0"
[HKEY_CLASSES_ROOT\TypeLib\{2DE7D51F-E0EF-44D3-9BB8-D3E836CE55C9}\1.0\HELPDIR]@="<path>"
Acapela Active Speech Control is a self-registered component and can be manually registered by the following command:
regsvr32 <path>AGASpeechCtrl.dll
where <path> is the directory that contains the component.
Important remark: the files AcaTTS.dll and AcaTTS.ini are expected to be found in the “Current” directory of the Application using the ActiveX. This way it allows to have different set of voices and settings for different products using the same ActiveX.
2.3.Programming overview
The general flow of typical application using Acapela Active Speech Control is as following:
1. Create an instance (aka object) of IAASpeechCtrl interface
2. Connect the TTS server (Acapela Multimedia) to be used.
object.ConnectEngine
3. Unlock the TTS engine (only needed if no computer locked licence is available)
Set OEMKey property to a proper value
4. Enumerate the voices available on the TTS Server
object.Enumerate
5. Start a TTS channel by loading the required voice
object.Load
6. Perform speech operations
object.Speakobject.Resume
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 9/35
AcaMul-ActiveX-6
object.Pauseobject.Stop
7. Stop the current TTS channel by unloading the voice
object.Unload
8. Disconnect from the TTS server
object.DisconnectEngine
NOTE
You must create an instance of IAASpeechCtrl interface for each TTS channel/voice you plan to use (one object per voice).
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 10/35
AcaMul-ActiveX-6
3. API Reference3.1. IAASpeechCtrl interface
IAASpeechCtrl is the TTS control interface that controls speech operations. To use more
than one voice at a time, you needs to create one instance (aka object) of this interface.
In the following, the term “TTS channel” refers to an instance of the interface with a
loaded voice.
3.1.1.Methods3.1.1.1ConnectEngine
Connect the host application to an Acapela tts engine.
HRESULT ConnectEngine(nConnectionMode, nPort, SrvAddress)
Parameters
nConnectionMode [integer]
[in] Connection mode to TTS engine server
EAS_AF_LOCAL (1) means local . This is the only relevant value
. local tts server (same computer as client)
. applies to Acapela Multimedia TTS servers
nPort [integer]
[in] Irrelevant, should be set to 0
pSrvAddress [string]
[in] Irrelevant, should be set to empty string.
Return Values
EAS_SUCCESS in case of success
or
EAS_ALREADY_CONNECTED
host application is already connected to a server
EAS_NOT_ENOUGH_MEMORY
not enough memory to perform the connection
EAS_SRV_NOTRUNNING
server is not running
See Also
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 11/35
AcaMul-ActiveX-6
DisconnectEngine, LastError
3.1.1.2DisconnectEngine
Release the current connection to the server. Disconnection can’t be performed if a TTS channel is still active (Unload method must be called before disconnection).
HRESULT DisconnectEngine()
Parameters
none
Return Values
EAS_SUCCESS in case of success
or
EAS_TTSCHANNEL_STILL_ACTIVE
a TTS channel is still active
EAS_INVALID_HANDLE
invalid dispatch handle (internal error)
See Also
ConnectEngine, Load, Unload, LastError
3.1.1.3Enumerate
Enumerates all available voices on the TTS server and fills in VoiceCount and voice list array Voice.
HRESULT Enumerate()
Parameters
none
Return Values
EAS_SUCCESS in case of success
or
EAS_NOT_CONNECTED
host application is not connected to a server
EAS_NOT_ENOUGH_MEMORY
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 12/35
AcaMul-ActiveX-6
not enough memory to perform the operation
EAS_SRV_NOTRUNNING
server is not running
EAS_INVALID_HANDLE
invalid dispatch handle (internal error)
EAS_NO_VOICE
no voice found
See Also
OEMKey,Voice,VoiceCount, IAAVoiceCtrl,LastError
Note
Once the voice enumeration is done, VoiceCount property contains the number of enumerated voices, each enumerated voice is stored in an IAAVoiceCtrl object and the whole voice list (and voice properties) can be accessed thru Voice(n) property that represents an array of IAAVoiceCtrl objects.
Remark: the files AcaTTS.dll and AcaTTS.ini are expected to be found in the “Current” directory of the Application. This way it allows to have different set of voices for different products using the same ActiveX.
3.1.1.4Load
Loads a voice, start a TTS channel.
HRESULT Load(bstrCmd)
Parameters
bstrCmd [string]
[in] Null terminated string that contains the identifier of the voice to
load. The voice identifier for a given voice is given by the Cmd property
of the IAAVoiceCtrl object (in Voice array) corresponding to the given
voice.
Return Values
EAS_SUCCESS in case of success
or
EAS_NOT_CONNECTED
host application is not connected to a server
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 13/35
AcaMul-ActiveX-6
EAS_TTSCHANNEL_STILL_ACTIVE
a TTS channel is already active (call Unload before)
EAS_SRV_NOTRUNNING
server is not running
EAS_CONNECT_ERROR
unable to connect to server
EAS_CONNREJECT
server rejects the connection (maximum channels number reached)
EAS_VOICE_LIST_ERROR
given voice doesn’t match a voice enumerated by the server
EAS_INVALID_HANDLE
invalid server handle (internal error)
EAS_VOICE_INIT_ERROR
error during initialization of given voice
EAS_NOT_ENOUGH_MEMORY
not enough memory to perform the operation
EAS_CHANNEL_LOCKED
channel already used by another user
See Also
Unload
Remark
Only one voice can be loaded at a time by an object. To use more than one voice, you should create an instance (object) of Acapela Active Speech Control per needed voice.
3.1.1.5Unload
Unload a previously loaded voice.
HRESULT UnLoad()
Parameters
none
Return Values
EAS_SUCCESS in case of success
orAcapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 14/35
AcaMul-ActiveX-6
EAS_NOT_CONNECTED
host application is not connected to a server
EAS_TTSCHANNEL_NOT_ACTIVE
a TTS channel is not active
EAS_SRV_NOTRUNNING
server is not running
EAS_INVALID_HANDLE
invalid server handle (internal error)
See Also
Load
3.1.1.6Speak
Play the provided text on the selected output.
HRESULT Speak(bstrText, long lTextId)
Parameters
bstrText [string]
[in] Pointer to a null terminated string that contains the text to be
played.
lTextId [long integer]
[in] text identifier
Return Values
EAS_SUCCESS in case of success
or
EAS_TTSCHANNEL_NOT_ACTIVE
a TTS channel is not active
EAS_EMPTY_TEXT
text is empty
EAS_NOT_ENOUGH_MEMORY
not enough memory to add text
EAS_EXEC_STARTED_ERROR
can’t execute speech output (internal error)
EAS_PROCESS_DATA_ERROR
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 15/35
AcaMul-ActiveX-6
error during text to speech processing
EAS_INVALID_HANDLE
invalid server handle (internal error)
See Also
Stop, Pause, Resume, Output
Note
The behaviour of text played depends on the Output type chosen by host application.
If Output is set audio output (i.e. output to an audio card device), the audio signal is
produced by TTS server at 1x real time.
If Output is set to file output or callback output, the audio signal is produced by the TTS
server at N x real time according to the capability of the TTS server.
Producing audio signal at N x real time means that the host application receives the audio
signal in a time corresponding to the real duration of the audio signal divided by N :
for ex. with a 4 x real-time tts engine, the audio signal for a text which duration is 1min is
produced in 15s.
Acapela Multimedia is a real-time only (1X) TTS engine, Acapela Telecom is a N x real time (Nx) TTS engine, N is equivalent to the channel number stored in the (hardware or software) protection key.
TTS Events are fired (if enabled) to host application during text play.
Events are sent synchronously with the audio signal play to allow word or phoneme
synchronization with audio signal output.
3.1.1.7Stop
Stop the current text played.
HRESULT Stop()
Parameters
none
Return Values
EAS_SUCCESS in case of success
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 16/35
AcaMul-ActiveX-6
or
EAS_TTSCHANNEL_NOT_ACTIVE
a TTS channel is not active
EAS_INVALID_HANDLE
invalid server handle (internal error)
See Also
Speak, Pause, Resume
3.1.1.8Pause
Pause the current text play.
HRESULT Pause()
Parameters
none
Return Values
EAS_SUCCESS in case of success
or
EAS_TTSCHANNEL_NOT_ACTIVE
a TTS channel is not active
See Also
Resume, Speak, Stop
3.1.1.9Resume
Resume a previously paused text played.
HRESULT Resume()
Parameters
none
Return Values
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 17/35
AcaMul-ActiveX-6
EAS_SUCCESS in case of success
or
EAS_TTSCHANNEL_NOT_ACTIVE
a TTS channel is not active
EAS_INVALID_HANDLE
invalid server handle (internal error)
EAS_CHANNEL_NOTREADY
problem with the channel execution
EAS_PROCESS_DATA_ERROR
error during text to speech processing
See Also
Pause, Speak, Pause
3.1.1.10EventMask
Control the TTS events fired to host application during a text played.
HRESULT EventMask(ulEvtMask)
Parameters
UlEvtMask [unsigned long integer]
[in] a bit field that control enabling/disabling of TTS events;
each bit correspond to a given event :
bit 0 n/a
bit 1 enable(1)/disable(0) word position event
(event mask = EVT_WORD_POSITION)
bit 2 enable(1)/disable(0) phoneme event
(event mask = EVT_PHONEME)
bit 3-5 n/a
bit 6 enable(1)/disable(0) mouth position event
(event mask = EVT_MOUTH_POS)
Return values
EAS_SUCCESS
See Also
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 18/35
AcaMul-ActiveX-6
Events,Speak
Note
Some events can’t be disabled and are always fired (see Events).
WordPosition, Phoneme and Mouth Position are automatically disabled when Output is set to file output.
3.1.1.11GetVarAudioData,GetAudioData
Get the next available audio signal data in callback output.
HRESULT GetVarAudioData(vData) HRESULT GetAudioData(pData, lDataSize);
Parameters
vData [variant]
[in] variant type buffer that will be filled in with audio data,
must have the following characteristics :
type : safearray of byte (VT_ARRAY|VT_UI1)
safearray dim : 1
safearray bounds : [0, lDataSize]
pData [byte pointer]
[in] pointer to buffer that will be filled in with audio data : buffer must be
large enough to receive the data
lDataSize [long integer]
[in] buffer size
Return Values
EAS_SUCCESS in case of success
or
EAS_TTSCHANNEL_NOT_ACTIVE
a TTS channel is not active
TYPE_E_TYPEMISMATCH
unexpected variant type
TYPE_E_BUFFERTOOSMALL
buffer size too small
EAS_AUDIODATA_NOTAVAILABLE
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 19/35
AcaMul-ActiveX-6
no available data
See Also
Output
Note
Calling this method has only a meaning when Output is set to callback output. In this case
host application received an AudioData event each time an audio signal data is available.
The application must then call GetAudioData or GetVarAudioData to get the next available
data. The data is destroyed immediately after a call to the method, so the application must
insure to copy the data before using it.
Note for developers
Applications written with programming languages that can handle memory pointers may use
GetAudioData method to get access to audio buffer in control.
GetVarAudioData is useful for other programming languages (like Visual Basic) that can only
handle data via Automation.
3.1.1.12ServerShutdown
Performs a shutdown of the TTS server.
HRESULT ServerShutdown(nState)
Parameters
nState [integer]
[in] shutdown state
2 forces server shutdown though there is still an active channel
(all active TTS channels are stopped and closed)
1 requests server shutdown, the behaviour depends on the currentserver state : if no TTS channel is active, server shutdowns itself
immediately, else server waits for all TTS channels to be closed
before shutdown itself (shutdown can so be cancelled)
0 cancels shutdown request
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 20/35
AcaMul-ActiveX-6
Return Values
EAS_SUCCESS in case of success
or
EAS_SRV_NOTRUNNING
server is not running
EAS_INVALID_HANDLE
invalid server handle (internal error)
See Also
DisconnectEngine
Note
After calling this method, you must call DisconnectEngine to release the connection to the server.
3.1.2.Properties3.1.2.1Voice(n)
Access to a given enumerated voice list array.
Parameters
nIndex [integer]
[in] index of voice in array
Type
[readonly] IAAVoiceCtrl object
See Also
Enumerate
Note
This property is filled in only after a call to Enumerate method.
3.1.2.2CurrentVoice
Access to the current loaded voice.
Type
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 21/35
AcaMul-ActiveX-6
[readonly] IAAVoiceCtrl object
See Also
Enumerate
Note
This property is filled in only after a call to Load method.
3.1.2.3 VoiceCount
Description
Enumerated voices count.
Type
[readonly] short integer
See Also
Enumerate, Voice
Note
This property is filled in only after a call to Enumerate method.
3.1.2.4Output
Description
Speech output mode.
Type
[read/write] short integer
Value
low byte contains the output type :
AUDIO_OUTPUT 0
FILE_OUTPUT 1
CALLBACK_OUTPUT 2
high byte contains when low byte is set to FILE_OUTPUT, the format of output file :
PCM_FORMAT 0
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 22/35
AcaMul-ActiveX-6
WAV_FORMAT 1
See Also
Filename, Speak,
Constants,GetVarAudioData,GetAudioData,Events
Note
The format of the audio signal produced by TTS server is : PCM 16bits and frequency depending on the selected voice.
Note
In audio output mode, the audio signal produced by the TTS server is played by the control on the audio device (sound card) at 1 x realtime.
In file output mode, the audio signal produced by the TTS server is written by the control in the file which name is set by Filename property at N x realtime (see Speak): the format of output file is set by high byte of the property value.
In callback output mode, the audio signal produced by the TTS server is sent back to the host application to allow application to handle itself the audio signal: each time a data (audio signal chunk) is available, control fires an AudioData event to the host application that must call GetVarAudioData or GetAudioData to get the data.
According to the selected output mode and the event mask (see EventMask), Events are fired to the host application to allow it to perform text synchronization with audio signal play.
3.1.2.5Filename
Description
Name of output file in file output mode.
Type
[read/write] null terminated string
See Also
Output, Speak
Note
By default, at initialization the filename is set to AcapelaTTS.wav.
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 23/35
AcaMul-ActiveX-6
3.1.2.6 Volume
Actual volume of the speech output.
Type
[read/write] short integer
Value
0 to 65535
(default volume value at initialisation = 32767)
3.1.2.7Pitch
Actual pitch of the speech output.
Type
[read/write] short integer
Value
10 to 500
(default pitch value at initialisation = 100)3.1.2.8Speed
Actual rate of the speech output.
Type
[read/write] short integer
Value
30 to 1000
(default speed value at initialisation = 100)
3.1.2.9OEMKey
Software protection key.
Type
[write] string
Value
43 characters long string
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 24/35
AcaMul-ActiveX-6
or the BabTTS API license key (much longer)
Note
Enumeration depends closely on protection mode. If host application uses software protection instead of hardware protection, software protection must be sent before calling Enumerate method.
3.1.2.10Status
Actual control status.
Type
[readonly] short integer – bit field
Value
bit 0 connection to server status 0 : not connected 1 : connected
bit 1 tts channel status0 : not active 1 : active
bit 2 idle state0 : idle 1 : busy (speech operation in progress)
bit 3 play status0 : not playing 1 : play in progress
bit 4 pause status0 : not paused 1 : paused
bit 5 audio status0 : audio device not opend 1 : audio device opened
3.1.2.11LastError
Last error code produced by a failed call to a method.
Type
[readonly] long integer
Value
see Constants
See Also
LastError (event)
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 25/35
AcaMul-ActiveX-6
Note
Some calls to methods or properties don’t directly return error codes. To know if the call has or not produced an error, host application must read this property.
Error codes are also fired by LastError event.
3.1.3.Events
Some events are fired during a text play. Some of these events can be enabled/disabled thru EventMask method.
3.1.3.1AudioOpen
Fired when audio output device is opened.
AudioOpen()
Parameters
none
See Also
EventMask
Note
This event is always enabled.
3.1.3.2AudioClose
Fired when audio output device is closed
AudioClose
Parameters
none
See Also
EventMask
Note
This event is always enabled.
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 26/35
AcaMul-ActiveX-6
3.1.3.3TextStart
Fired when text play is started.
TextStart(lTextId)
Parameters
lTextId [long integer]
text identifier : the value passed in parameter lTextId of Speak method
that identifies the text that refers to the event.
See Also
Speak,EventMask
Note
This event is always enabled.
3.1.3.4TextStop
Fired when end of text play is reached.
TextStop(lTextId)
Parameters
lTextId [long integer]
text identifier : the value passed in parameter lTextId of Speak method
that identifies the text that refers to the event.
See Also
Speak,EventMask
Note
This event is always enabled.
3.1.3.5WordPosition
Fired when a word is currently being played.
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 27/35
AcaMul-ActiveX-6
WordPosition(lTextId, lWordPos, lByteCount)
Parameters
lTextId [long integer]
text identifier : the value passed in parameter lTextId of Speak method
that identifies the text that refers to the event.
lWordPos [long integer]
word position in text identified by lTextId
(rank of the first character of word from the beginning of text)
lByteCount [long integer]
position in bytes in the audio signal from the beginning
See Also
EventMask, Speak
Note
This event is enabled/disabled by EventMask method. It is disabled when output type is set
to file output.
3.1.3.6AcaPhoneme
Fired when a phoneme is currently being played.
WARNING : AcaPhoneme is a new event which replaces the previous Phoneme, with new parameters which correspond to the new technology of the TTS.
AcaPhoneme(lTextId, sEnginePhoneme1, sEnginePhoneme2, sEnginePhoneme3, sEnginePhoneme4, sIPAPhoneme1, lDuration, lByteCount)
Parameters
lTextId [long integer]
text identifier : the value passed in parameter lTextId of Speak method
that identifies the text that refers to the event.
sEnginePhoneme1 [short integer]
1st char of engine phoneme
sEnginePhoneme2 [short integer]
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 28/35
AcaMul-ActiveX-6
2nd char of engine phoneme
sEnginePhoneme3 [short integer]
1st char of engine phoneme
sEnginePhoneme4 [short integer]
2nd char of engine phoneme
sIpaPhoneme1 [short integer]
1st IPA phoneme
lDuration [long integer]
duration of the phoneme in ms
lByteCount [long integer]
position in bytes in the audio signal from the beginning
See Also
EventMask, Speak
Note
This event is enabled/disabled by EventMask method. It is disabled when output type is set
to file output.
3.1.3.7MouthPosition
Fired when a phoneme is currently being played and mouth positions have been enabled by the EventMask method.
MouthPosition(lTextId, sIPAPhoneme1, sMouthPos1, sMouthPos2, sMouthPos3, sMouthPos4, sMouthPos5, sMouthPos6, sMouthPos7, sMouthPos8, lDuration, lByteCount)
Parameters
lTextId [long integer]
text identifier : the value passed in parameter lTextId of Speak method
that identifies the text that refers to the event.
sIpaPhoneme1 [short integer]
1st IPA phoneme
sMouthPos1 [short integer] to sMouthPos8 [short integer]
8 members of the structure which describes the mouth position (similar as in the SAPI MOUTH structure
lDuration [long integer]
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 29/35
AcaMul-ActiveX-6
duration of the phoneme in ms
lByteCount [long integer]
position in bytes in the audio signal from the beginning
See Also
EventMask, Speak
Note
This event is enabled/disabled by EventMask method. It is disabled when output type is set
to file output.3.1.3.8AudioData
Fired when an audio data is available. This event is only fired when Output is set to
callback output. It notices the host application that one or more audio signal data is
available.
AudioData(lTextId, lDataCount, lDataSize)
Parameters
lTextId [long integer]
text identifier : the value passed in parameter lTextId of Speak method
that identifies the text that refers to the event.
lDataCount [long integer]
number of available data – can be > 1 if the host application doesn’t call
GetVarAudioData or GetAudioData method each the event is fired.
lDataSize [long integer]
size of current notified available data
See Also
Speak
Note
This event is always enabled. The host application is in charge to react as fast as possible to
audio data event by calling GetVarAudioData or GetAudioData method to get the
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 30/35
AcaMul-ActiveX-6
available data.
WordPosition and Phoneme event provides each a parameter (lByteCount) that allows the
host application to easily synchronize audio signal data with word position and phonemes.
3.1.3.9LastError
Fired when a call to a method or proprety produces an error.
LastError(lErrorCode)
Parameters
lErrorCode [long integer]
error value (see Constants)
See Also
LastError (property)
Note
This event is always enabled.
3.2.IAAVoiceCtrl interface
IAAVoiceCtrl is an interface that gives access to description of a given voice.
IEASpeechCtrl interface contains an array of IAAVoiceCtrl objects, that store the
description for all enumerated voices (this array is filled in after a call to Enumerate
method).
Each voice description can be accessed thru Voice(n) property where n is the index of the
voice in the array.
3.2.1.Properties3.2.1.1Cmd
Voice identifier.
Type
[readonly]string
Note
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 31/35
AcaMul-ActiveX-6
The property’s value must be used as parameter of Load method.
See Acapela TTS Telecom voices, Acapela TTS Multimedia voices.
3.2.1.2Gender
Voice’s gender
Type
[readonly] short integer
Value
1 : woman
2 : man
3.2.1.3Language
Voice’s language identifier
Type
[readonly] integer
Value
See Language identifiers
3.2.1.4Speaker
Voice speaker’s name.
Type
[readonly]string
3.2.1.5Index
Voice’s index in array
Type
[readonly]short integer
Value
1 to VoiceCount
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 32/35
AcaMul-ActiveX-6
3.2.1.6Frequency
Voice’s frequency in Hz (sampling rate)
Type
[readonly]long integer
Value
8000 (8000 samples/sec)
11025 (11025 samples/sec)
16000 (16000 samples/sec)
22050 (22050 samples/sec)
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 33/35
AcaMul-ActiveX-6
4. Appendix A4.1.Language identifiers
Here is a list of identifiers that can be returned in Language property of
This list corresponds to languages currently supported by Acapela speech products.
Identifier Language
5121 Arabic (Algeria)
1025 Arabic (Saudia Arabia)
1029 Czech (Standard)
1030 Danish (Standard)
1043 Dutch (Netherlands)
2067 Dutch (Belgium)
1033 English (United States)
2057 English (United Kingdom)
1036 French (Standard)
1035 Finnish (Standard)
1031 German (Standard)
1039 Icelandic (Standard)
1040 Italian (Standard)
1044 Norwegian (Standard)
1045 Polish (Standard)
1046 Portuguese (Brazil)
2070 Portuguese (Standard)
1049 Russian
1034 Spanish (Standard)
8202 Spanish (Venezuela)
1053 Swedish (Standard)
1055 Turkish (Standard)
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 34/35
AcaMul-ActiveX-6
4.2.Constants
TTS engine identifiers
ACAPELA_TELECOM_ENGINE 0
ACAPELA_MULTIMEDIA_ENGINE 1
Connection modes
EAS_AF_LOCAL 1
EAS_AF_INET 2
Output types
AUDIO_OUTPUT 0
FILE_OUTPUT 1
CALLBACK_OUTPUT 2
File format
PCM_FORMAT 0
WAV_FORMAT 1
TTS event masks
EVT_TEXT 1
EVT_WORD_POSITION 2
EVT_PHONEME 4
Min/max values for TTS params
MIN_PITCH 10
MAX_PITCH 500
MIN_SPEED 30
MAX_SPEED 1000
MIN_VOLUME 0
MAX_VOLUME FFFFh
Return/error codes
EAS_SUCCESS 0
EAS_NOT_CONNECTED 800a0258h
EAS_ALREADY_CONNECTED 800a0259h
EAS_TTSCHANNEL_NOT_ACTIVE 800a025ah
EAS_TTSCHANNEL_STILL_ACTIVE 800a025bh
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01
Acapela Active SpeechControl
Reference manual
Date : 09/12/2005
Page : 35/35
AcaMul-ActiveX-6
EAS_EMPTY_TEXT 800a025ch
EAS_UNSUPPORTED_FORMAT 800a025dh
EAS_AUDIODATA_NOTAVAILABLE 800a025eh
EAS_INVALID_ARRAY 800a025fh
EAS_NOT_ENOUGH_MEMORY 800a0260h
EAS_INVALID_HANDLE 800a0261h
EAS_INVALID_CHANNEL 800a0262h
EAS_INVALID_SERVER 800a0263h
EAS_NO_VOICE 800a0264h
EAS_VOICE_LIST_ERROR 800a0265h
EAS_IDVOICE_ERROR 800a0266h
EAS_VOICE_INIT_ERROR 800a0267h
EAS_PROCESS_DATA_ERROR 800a0268h
EAS_EXEC_STARTED_ERROR 800a0269h
EAS_INVALID_PARAM 800a026ah
EAS_RANGE_PARAM 800a026bh
EAS_CHANNEL_LOCKED 800a026ch
EAS_CHANNEL_NOTREADY 800a026dh
EAS_CONNECT_ERROR 800a026eh
EAS_TIMEOUT_INIT 800a026fh
EAS_CONNRESET 800a0270h
EAS_CONNREJECT 800a0271h
EAS_TOOMANY_VOICES 800a0272h
EAS_SRV_NOTRUNNING 800a0273h
EAS_NOT_IMPLEMENTED_YET 800a0274h
Acapela Group3939 la Lauragaise, BP 758, 31683 Labège Cedex, France. T. : +33 (0)562 24 71 00 F. : +33 (0)562 24 71 01