acapela active speech control - narod.rutts-alenka.narod.ru/pdf/acamul-activex-6.pdf ·...

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



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



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



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.



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


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"



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



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).



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



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


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


or

EAS_NOT_CONNECTED

host application is not connected to a server




Reference manual

Date : 09/12/2005

Page : 12/35

AcaMul-ActiveX-6

not enough memory to perform the operation

EAS_SRV_NOTRUNNING


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


or

EAS_NOT_CONNECTED




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


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


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


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


Reference manual

Date : 09/12/2005

Page : 14/35

AcaMul-ActiveX-6

EAS_NOT_CONNECTED


EAS_TTSCHANNEL_NOT_ACTIVE

a TTS channel is not active

EAS_SRV_NOTRUNNING


EAS_INVALID_HANDLE


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


or



EAS_EMPTY_TEXT

text is empty


not enough memory to add text

EAS_EXEC_STARTED_ERROR

can’t execute speech output (internal error)

EAS_PROCESS_DATA_ERROR



Reference manual

Date : 09/12/2005

Page : 15/35

AcaMul-ActiveX-6

error during text to speech processing

EAS_INVALID_HANDLE


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




Reference manual

Date : 09/12/2005

Page : 16/35

AcaMul-ActiveX-6

or



EAS_INVALID_HANDLE


See Also

Speak, Pause, Resume

3.1.1.8Pause

Pause the current text play.

HRESULT Pause()

Parameters

none

Return Values


or



See Also

Resume, Speak, Stop

3.1.1.9Resume

Resume a previously paused text played.

HRESULT Resume()

Parameters

none

Return Values



Reference manual

Date : 09/12/2005

Page : 17/35

AcaMul-ActiveX-6


or



EAS_INVALID_HANDLE


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



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


or



TYPE_E_TYPEMISMATCH

unexpected variant type

TYPE_E_BUFFERTOOSMALL

buffer size too small

EAS_AUDIODATA_NOTAVAILABLE



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



Reference manual

Date : 09/12/2005

Page : 20/35

AcaMul-ActiveX-6

Return Values


or

EAS_SRV_NOTRUNNING


EAS_INVALID_HANDLE


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



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



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.



Reference manual

Date : 09/12/2005

Page : 23/35

AcaMul-ActiveX-6

3.1.2.6 Volume

Actual volume of the speech output.

Type


Value

0 to 65535

(default volume value at initialisation = 32767)

3.1.2.7Pitch

Actual pitch of the speech output.

Type


Value

10 to 500

(default pitch value at initialisation = 100)3.1.2.8Speed

Actual rate of the speech output.

Type


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



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)



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




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


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


3.1.3.4TextStop

Fired when end of text play is reached.

TextStop(lTextId)

Parameters




See Also

Speak,EventMask

Note


3.1.3.5WordPosition

Fired when a word is currently being played.



Reference manual

Date : 09/12/2005

Page : 27/35

AcaMul-ActiveX-6

WordPosition(lTextId, lWordPos, lByteCount)

Parameters




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




sEnginePhoneme1 [short integer]

1st char of engine phoneme




Reference manual

Date : 09/12/2005

Page : 28/35

AcaMul-ActiveX-6

2nd char of engine phoneme


1st char of engine phoneme


2nd char of engine phoneme

sIpaPhoneme1 [short integer]

1st IPA phoneme

lDuration [long integer]

duration of the phoneme in ms



See Also

EventMask, Speak

Note


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




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]



Reference manual

Date : 09/12/2005

Page : 29/35

AcaMul-ActiveX-6

duration of the phoneme in ms



See Also

EventMask, Speak

Note


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




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



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


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



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



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)






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)



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



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 active speech control - narod.rutts-alenka.narod.ru/pdf/acamul-activex-6.pdf ·...

Documents