Acapela TTS Multimedia 6 - narod.rutts-alenka.narod.ru/pdf/acamul-sdk-6.pdf · or perform in public the sound files generated by the ACAPELA Text-to-speech technologies for commercial

www.acapela-group.com, [email protected] > In Belgium: 33 boulevard Dolez, 7000 Mons. Tel +32(0)65 37 42 75 > In France: 3939 La Lauragaise, BP58309, 31683 Labège cedex. Tel + 33(0)5 62 24 71 00 > In Sweden : Englundavägen 7, PO Box 1328, 17126 Solna.

Acapela TTS Multimedia 6

Software Development Kit:

Developer Guide

Ref. : AcaMul-SDK-6

Date : 19/01/07

Page : 2/116

Acapela TTS Multimedia

SDK Developer Guide

AcaMul-SDK-6

www.acapela-group.com

Document revisions

Version Date Subject Author(s)

V 1.0 27/11/2002 First Version (BrightSpeech 1.0)

Laurent Hubaut Jean-Michel Reghem

V 1.1 Rev 23048

19/02/2003 Update (BrightSpeech 1.1) Francois Bataille Laurent Hubaut Jean-Michel Reghem

V 1.1

Rev 23076

17/03/2003 Update (BrightSpeech 1.1) Laurent Hubaut

Jean-Michel Reghem

V 1.2 19/05/2003 Update (BrightSpeech 1.2) Laurent Hubaut

Jean-Michel Reghem

V 1.3 05/07/2004 Update (BrightSpeech 1.3 and Babil 4.1)

Laurent Hubaut

Jean-Michel Reghem

Francois Bataille

V 1.4 05/09/2004 Update (BabTTS 1.4) Laurent Hubaut

V 1.5 29/08/2005 Update (BabTTS 1.5) François Bataille

V 6.000 21/12/2005 Acapela Multimedia v6.000 Laurent Hubaut

V 6.001 14/09/2006 Acapela Multimedia 6 for Mac OS X

Jean-Michel Reghem

V 6.002 18/10/2006 Update Jean-Michel Reghem

V 6.003 02/11/2006 Update Jean-Michel Reghem

V 6.010 19/01/2007 Update for Acapela Multimedia Windows 6.010

Jean-Michel Reghem

Date : 19/01/07

Page : 3/116


SDK Developer Guide

AcaMul-SDK-6


Terms and Conditions By using this software you agree to be bound by the terms and conditions below:

Software License Agreement

ACAPELA GROUP SA

Bvd Dolez 33 B 7000 MONS BE 0460.125.240 RPM MONS


IMPORTANT - READ BEFORE USING

Licence Agreement and Limited Warranty

Please read this license agreement ("license") carefully before pressing the "agree" button. By pressing "agree," you are agreeing to be bound by the terms of this license. If you do not agree to the terms of this license, press "disagree" and (if applicable) return the ACAPELA GROUP software to the dealer where you obtained it. Depending on the terms of delivery of your dealer you are eligible for a (partial) refund.

LICENSE

You may use the programs and manuals on a single computer and copy the programs for back up purposes in support of your use of the programs on a single computer, provided all copyright and other proprietary notices are included on such copy, and true and accurate records of such copy are kept.

The term "Use", used above, shall not include the right to replicate, redistribute, broadcast or perform in public the sound files generated by the ACAPELA Text-to-speech technologies for commercial purposes. This specific type of use of ACAPELA TTS technology is subject to a separate licensing agreement.

You may not decompile, disassemble or transfer the programs or manuals in whole or in part, except upon ACAPELA GROUP’s prior written approval, or your license and any express warranties granted herein will automatically terminate. In addition, you may not use or copy the programs or manuals, in whole or in part, except as expressly provided for in this license or upon ACAPELA GROUP's prior written approval, or your license will automatically terminate.

TERM

This license is effective until terminated. You may terminate it at any time by returning it to ACAPELA GROUP or destroying the programs and any copy you have made of them, and the manuals. This license will also terminate upon conditions set forth elsewhere in this Agreement or if you fail to comply with any term and condition of this Agreement. Unless otherwise stated in this Agreement, you agree upon such termination to return to ACAPELA GROUP or destroy the programs together with the copy, and the manuals.

Date : 19/01/07

Page : 4/116


SDK Developer Guide

AcaMul-SDK-6


DISK, PROGRAMS AND MANUALS

The programs and the manuals are provided "as is" without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the software is with you. Should the software prove defective, you (and not ACAPELA GROUP or any ACAPELA GROUP's representative or any ACAPELA GROUP's licensors) agree to assume the entire cost of all necessary servicing or repair to the computer you are using it on.

ACAPELA GROUP does not warrant that the functions contained in the program will meet your requirements or that the operation of the programs will be uninterrupted or error free. However, ACAPELA GROUP warrants the disk on which the programs are furnished, to be free from defects in materials and workmanship for a period of ninety (90) days from the date of delivery to you as evidenced by a copy of your receipt. ACAPELA GROUP's sole liability in the event of a defective disk shall be to give you a replacement disk. To obtain warranty service or replacement, you must take the disk, or deliver it prepaid, together with a copy of your receipt, to ACAPELA GROUP.

Except to the extent prohibited by applicable law, any implied warranty of merchantability or fitness for a particular purpose on the disk is limited in duration to the duration of this limited warranty.

LIMITATIONS OF REMEDIES

In no event will ACAPELA GROUP, ACAPELA GROUP's representatives or ACAPELA GROUP's licensors be liable to you for any damages in excess of the license fee paid by you including, without limitation, any lost profits, business goodwill or other special, incidental or consequential damages arising out of the use or inability to use the disk, the programs or the manuals, or for any claim by any party, even if ACAPELA GROUP, ACAPELA GROUP's representatives or ACAPELA GROUP's licensors have been advised of the possibility of such claims or damages.

GENERAL

Some jurisdictions may not allow the exclusion or limitation of incidental or consequential damages, or allow limitations on how long a limited warranty lasts, so the above limitations or exclusions may not apply to you. You may not sell, rent, sublicense, assign or otherwise transfer this agreement or the programs or manuals in any form except upon ACAPELA GROUP's prior written approval. ACAPELA GROUP or ACAPELA GROUP's licensors retain title to and ownership of the programs and manuals and all trade secrets therein at all times. If any part of this Agreement is held invalid or unenforceable, the other parts will remain valid.

You acknowledge that you have read this agreement, understand it and agree to be bound by it. You further agree that unless otherwise expressly agreed to in writing, it is the complete and exclusive statement of the agreement between us which supersedes any demonstration, advertisement, proposal, prior or contemporaneous agreement, oral or written, and any other communications between us or between us and the ACAPELA GROUP representative relating to the subject matter of this agreement.

Notes

You may use this software for a 30-day trial. If you wish to continue using the software beyond the

Date : 19/01/07

Page : 5/116


SDK Developer Guide

AcaMul-SDK-6


30-day trial, you should purchase it.

Acapela Multimedia and Acapela Multimedia documentation are copyright Acapela Group 2006. All rights reserved. Infovox iVox is a trademark of Acapela

Group. Macintosh, Power Macintosh, Mac, and Mac OS are trademarks of Apple Computer, Inc., registered in the U.S. and other countries. Microsoft and

Windows are trademarks of Microsoft Corporation.

Date : 19/01/07

Page : 2/116


SDK Developer Guide

AcaMul-SDK-6


Table of contents 1. Introduction _________________________________________5

1.1. Overview ________________________________________________ 5

1.2. Acapela’s Text-To-Speech product range ________________________ 5

1.3. HD and HQ voices _________________________________________ 5

1.4. Differences between operating systems ________________________ 5

1.5. Package content___________________________________________ 6

2. Getting Started _______________________________________8

2.1. Directory Structure ________________________________________ 8 2.1.1. Microsoft Windows __________________________________________________ 8 2.1.2. Apple Mac OS X ____________________________________________________ 8

2.2. Integrating the TTS in applications ____________________________ 9 2.2.1. Proprietary API_____________________________________________________ 9 2.2.2. NSCAPI__________________________________________________________ 10 2.2.3. SAPI 4.0a________________________________________________________ 10 2.2.4. SAPI 5.1_________________________________________________________ 10 2.2.5. ActiveX__________________________________________________________ 10 2.2.6. .NET Applications __________________________________________________ 10 2.2.7. Apple Speech Synthesis Manager _____________________________________ 10

3. Creating your first Application with the BabTts API __________11

3.1. Dynamic loading of the library_______________________________ 11

3.2. Initializing the library______________________________________ 11

3.3. Enumerating the installed voices_____________________________ 11

3.4. Opening a voice __________________________________________ 11

3.5. Adapting parameters ______________________________________ 11

3.6. Speaking the text ________________________________________ 11

3.7. Closing the voice _________________________________________ 12

3.8. Closing and unloading the Library ____________________________ 12

4. Using the Callbacks Mechanism _________________________13

4.1. Purpose ________________________________________________ 13

4.2. Using callbacks __________________________________________ 13

4.3. Messages _______________________________________________ 14

5. Changing Settings____________________________________15

5.1. Using the Property Box ____________________________________ 15

5.2. Using BabTTS_SetSettings/BabTTS_GetSettings_________________ 16 5.2.1. Callback Instance Value_____________________________________________ 16

Date : 19/01/07

Page : 3/116


SDK Developer Guide

AcaMul-SDK-6


5.2.2. Callback Message Mask _____________________________________________ 16 5.2.3. Coding Scheme ___________________________________________________ 16 5.2.4. Equalizer ________________________________________________________ 17 5.2.5. Leading Silence ___________________________________________________ 17 5.2.6. Pauses __________________________________________________________ 17 5.2.7. Pitch (HD voices ONLY) _____________________________________________ 19 5.2.8. Pitch – Maximum (HD voices ONLY) ___________________________________ 19 5.2.9. Pitch – Minimum (HD voices ONLY) ____________________________________ 19 5.2.10. Reading Mode___________________________________________________ 20 5.2.11. Sampling Rate __________________________________________________ 20 5.2.12. Speed Rate _____________________________________________________ 20 5.2.13. Volume ________________________________________________________ 21

6. Reference Guide _____________________________________22

6.1. Function list by topic ______________________________________ 22

6.2. Functions _______________________________________________ 23 6.2.1. BabTTS_Close ____________________________________________________ 24 6.2.2. BabTTS_Create ___________________________________________________ 25 6.2.3. BabTTS_Dialog____________________________________________________ 26 6.2.4. BabTTS_DictAddWord ______________________________________________ 27 6.2.5. BabTTS_DictDisable________________________________________________ 32 6.2.6. BabTTS_DictEnable ________________________________________________ 33 6.2.7. BabTTS_DictEnum _________________________________________________ 36 6.2.8. BabTTS_DictGetDefList _____________________________________________ 39 6.2.9. BabTTS_DictGetEntry_______________________________________________ 40 6.2.10. BabTTS_DictGetInfo ______________________________________________ 43 6.2.11. BabTTS_DictGetInfoFromFile _______________________________________ 45 6.2.12. BabTTS_DictGetMax ______________________________________________ 48 6.2.13. BabTTS_DictGetNumEntries ________________________________________ 49 6.2.14. BabTTS_DictGetNumLoaded________________________________________ 50 6.2.15. BabTTS_DictGetWordTrans ________________________________________ 51 6.2.16. BabTTS_DictIsModified____________________________________________ 53 6.2.17. BabTTS_DictLoad ________________________________________________ 54 6.2.18. BabTTS_DictRemoveWord _________________________________________ 57 6.2.19. BabTTS_DictSave ________________________________________________ 59 6.2.20. BabTTS_DictSaveAll ______________________________________________ 61 6.2.21. BabTTS_DictSetDefList____________________________________________ 62 6.2.22. BabTTS_DictSetInfo ______________________________________________ 63 6.2.23. BabTTS_DictSetPassword__________________________________________ 66 6.2.24. BabTTS_DictUnload ______________________________________________ 71 6.2.25. BabTTS_DictUnloadAll ____________________________________________ 72 6.2.26. BabTTS_EnumVoices _____________________________________________ 73 6.2.27. BabTTS_GetCallback______________________________________________ 74 6.2.28. BabTTS_GetFilterPreset ___________________________________________ 75 6.2.29. BabTTS_GetInstanceInfo __________________________________________ 76 6.2.30. BabTTS_GetNumVoices ___________________________________________ 78

Date : 19/01/07

Page : 4/116


SDK Developer Guide

AcaMul-SDK-6


6.2.31. BabTTS_GetSettings______________________________________________ 79 6.2.32. BabTTS_GetVoiceInfo_____________________________________________ 80 6.2.33. BabTTS_Init ____________________________________________________ 82 6.2.34. BabTtsInitDll____________________________________________________ 83 6.2.35. BabTtsInitDllEx__________________________________________________ 84 6.2.36. BabTTS_InsertText_______________________________________________ 85 6.2.37. BabTTS_Open___________________________________________________ 87 6.2.38. BabTTS_Pause __________________________________________________ 89 6.2.39. BabTTS_PhoGetDuration __________________________________________ 90 6.2.40. BabTTS_PhoGetMouth ____________________________________________ 91 6.2.41. BabTTS_ReadBuffer ______________________________________________ 92 6.2.42. BabTTS_Reset __________________________________________________ 94 6.2.43. BabTTS_Resume_________________________________________________ 95 6.2.44. BabTTS_SetCallback______________________________________________ 96 6.2.45. BabTTS_SetFilterPreset ___________________________________________ 98 6.2.46. BabTTS_SetSettings______________________________________________ 99 6.2.47. BabTTS_Speak _________________________________________________ 100 6.2.48. BabTTS_Uninit _________________________________________________ 103 6.2.49. BabTtsUninitDll _________________________________________________ 104 6.2.50. BabTTS_Write__________________________________________________ 105

6.3. Structure definitions _____________________________________ 109 6.3.1. BABTTSDICTINFO ________________________________________________ 109 6.3.2. BABTTSINFO ____________________________________________________ 109 6.3.3. BABTTSMOUTH __________________________________________________ 111 6.3.4. BABTTSUNITINFO ________________________________________________ 112

Date : 19/01/07

Page : 5/116


SDK Developer Guide

AcaMul-SDK-6


1. Introduction

1.1. Overview

For a complete overview of Acapela Multimedia product, please first read the document “Acapela Multimedia TTS 6 – User Guide” (AcaMul-User-6.pdf)

1.2. Acapela’s Text-To-Speech product range

Acapela Group is a global player on the speech market providing a wide range of multilingual Text-To-Speech (TTS) and Automatic Speech Recognition (ASR) solutions covering most of the market needs. Please visit our website http://www.acapela-group.com for more information on our wide range of products.

1.3. HD and HQ voices

While HD and HQ/HQM voices are based on different technologies, they are based on the same software architecture, called “BabTTS” in the sequel. Hence, the development of an application integrating HD or HQ/HQM voices is identical from the developer’s point of view. Only the selection of the voice will determine the underlying technology.

1.4. Differences between operating systems

Acapela Multimedia 6 contains some small differences between Microsoft Windows, linux based systems and Mac OS versions. In the following sections, such specificities are highlighted by 3 different icons:

• for Microsoft Windows family

• for Linux based systems

• for Apple Mac OS X

http://www.acapela-group.com/

Date : 19/01/07

Page : 6/116


SDK Developer Guide

AcaMul-SDK-6


1.5. Package content

The components of the Acapela TTS Multimedia Software Development Kit (AcaMulSDK) are the following:

Programming interfaces

o Proprietary BabTTS API in C/C++ that could be used with most of the compilers (VC++, Borland, gcc, …);

o NSCAPI wrapper library to BabTTS provided for compatibility purposes. (Read AcaMul-NSCAPI-6.pdf for more information)

o Microsoft SAPI 4.0a standard interface (Read AcaMul-Sapi4-6.pdf)

o Microsoft SAPI 5.1 standard interface (Read AcaMul-Sapi5-6.pdf)

o An ActiveX for projects in VB6 or Delphi.

o Speech Synthesis Manager components (Read AcaMul-SSM-OSX-6.pdf)

One or several engines (Voices) each composed of:

o A Language Module (i.e. English, French) able to transform a text into a phonetic string

o A Voice Module that converts this phonetic string into speech. Each voice is defined by the speaker name and the sampling rate allowing using the SDK in a wide range of applications.

Several development tools: (Read AcaMul-User-6.pdf for more information)

o AcaDemo ( AcaCocoaDemo ): Type-and-Talk application that allows users to quickly verify the correct installation of the software.

o The Lexicon Editor allows user to create “user dictionaries” in order to change the pronunciation of words according to their needs.

Date : 19/01/07

Page : 7/116


SDK Developer Guide

AcaMul-SDK-6


The voice Manager allows creating new voices, based on original ones but with some modified characteristics according to your specific needs.

o

o The License Manager is used for providing “License identities” to users

for generating purchase requests; Managing your installed licenses.

Date : 19/01/07

Page : 8/116


SDK Developer Guide

AcaMul-SDK-6


2. Getting Started This chapter presents the necessary steps for integrating Speech Synthesis into your application. See the User’s Guide for more information about the installation procedure.

2.1. Directory Structure

During the installation, the following directory structure is created:

2.1.1. Microsoft Windows

<TargetPath> : The main directory where are stored the different layers <TargetPath>\BabWizard: specific files for uninstalling purposes <TargetPath>\Bin: the binaries used by voices <TargetPath>\Doc: the help files (User Guide, Language manuals) <TargetPath>\Engines: data and modules for the installed voices. <TargetPath>\Sdk\Include: the include files for C/C++ programming <TargetPath>\Sdk\Samples: source code of the sample programs Note: According to what you’ve purchased, the directory structure can be slightly different.

2.1.2. Apple Mac OS X

The main directory is /Applications/AcapelaMultimedia/

Relative to this directory, you will have ./ : Engine and synthesizer libraries, configuration file and executable tools ./Documentation/ :User and Developer Guide (including this), language manuals … ./Voices/ : Data and modules for the installed voices ./SDK/Include/: Include files for C/C++/Objective-C programming ./SDK/Examples/: Source code for the examples programs

In /System/Library/Speech/Synthesizers/ ./AcapelaSynth.SpeechSynthesizer : The Apple Speech Synthesis Manager synthesizer bundle

In /Library/Speech/Voices/ ./AGmm-XXXX.SpeechVoice : The Apple Speech Synthesis Manager voices bundles

In /Library/Application\ Support/AcapelaMultimedia/ ./BabTTS.conf : BabTTS configuration file ./License/ : The License directory

In /usr/lib/ ./libnscube.dylib : Install path for the NSCAPI compatibility wrapper library

Date : 19/01/07

Page : 9/116


SDK Developer Guide

AcaMul-SDK-6


2.2. Integrating the TTS in applications

2.2.1. Proprietary API

2.2.1.1 Include Files

The software development kit is provided with two kind of include files (.h):

Object definitions: ioBabTts.h defines the structures, enums and macro of the

SDK Function definitions: ifBabTtsDyn.h

2.2.1.2 Dynamic link to the library

In order to use the SDK, you have to explicitly tell to your application where to find the AcaTts library :

Include the windows definition file (windows.h or stdafx.h) Include ioBabTts.h and ifBabTtsDyn.h in all source files (except one) you expect

to use the TTS

In order to implement the dynamic loading, insert in only one source file:

// #include “windows.h” or #include ”stdafx.h” for windows // #include ”stdlib.h” or ”stdio.h” for linux or Mac OS X #include "ioBabTTS.h" #define _BABTTSDYN_IMPL_ #include "ifBabTTSDyn.h" #undef _BABTTSDYN_IMPL_

And, in all other files which need the sdk:

// #include “windows.h” or #include ”stdafx.h” for windows // #include ”stdlib.h” or ”stdio.h” for linux or Mac OS X #include "ioBabTTS.h" #include "ifBabTTSDyn.h"

Then, in your application and, at least, before the use of any functions of the SDK, call either : BabTtsInitDll() : if the dll AcaTTS.dll is in the executable path (or the current directory). BabTtsInitDllEx() : if you want to provide the absolute path where looking to AcaTTS.dll

Date : 19/01/07

Page : 10/116


SDK Developer Guide

AcaMul-SDK-6


2.2.2. NSCAPI

Acapela Multimedia comes with a NSCAPI wrapper library to BabTTS. This implementation is for compatibility purposes with old applications and don’t work with a speech synthesis server as in Acapela Telecom. Refer to the NSCAPI documentation (AcaMul-NscApi-6.pdf)

2.2.3. SAPI 4.0a

The Sapi4 module is called AcaTtsSapi4.dll, it must be in the same directory as AcaTts.dll Refer to the Microsoft SAPI 4.0a documentation for more information about this interface.

2.2.4. SAPI 5.1

The Sapi5 module is called AcaTtsSapi5.dll, it must be in the same directory as AcaTts.dll Refer to the Microsoft SAPI 5.1 documentation for more information about this interface.

2.2.5. ActiveX

Refer to the ActiveX documentation (AcaMul-ActiveX-6.pdf)

2.2.6. .NET Applications

Use SpeechLib Assembly provided with the SAPI 5.1 SDK (see provided samples)

2.2.7. Apple Speech Synthesis Manager

You can use the Carbon speech synthesis API (also called Speech Synthesis Manager) in the ApplicationServices Framework (C/C++/Objective-C) You can also use the NSSpeechSynthesize Object of the Cocoa Speech Synthesis API in the AppKit Framework (Objective-C and Java) For more information, read the Apple documentation and AcaMul-SSM-OSX-6.pdf document.

Date : 19/01/07

Page : 11/116


SDK Developer Guide

AcaMul-SDK-6


3. Creating your first Application with the BabTts API In this chapter, you will learn the different tasks to create very simple application. See samples in the SDK directory.

3.1. Dynamic loading of the library

See 2.2.1.2 for the use of BabTtsInitDll or BabTtsInitDllEx (and chapter 6 for a more detailed description of both functions)

3.2. Initializing the library

Just after the successful loading of the modules, you must make a call to BabTTS_Init() in order to initialize the library. This function must be called before any other functions

3.3. Enumerating the installed voices

The Acapela TTS Multimedia SDK has an enumerator feature that allows you to easily find the voices installed on your system. (see BabTTS_GetNumVoices, BabTTS_EnumVoices, BabTTS_GetVoiceInfo)

3.4. Opening a voice

Opening a new voice is really easy: You have first to create the instance (LPBABTTS) that will be used as a container (BabTTS_Create). Then, initialize it with the voice name you want to use. (BabTTS_Open) The BabTTS Api convention for voice name is to append the sampling rate to the name of the speaker for the voice. For example, the French voice Julie at 22kHz (multimedia purpose) is called Julie22k, for the 8kHz telecom optimized: Julie8k, Julie at 22kHz but with reduced size (overall quality is slightly lower than the standard 22kHz version but this versions helps to reduces space requirements constrains) : Julie22kM, …

3.5. Adapting parameters

You can of course retrieve/modify several parameters (like speech rate …). This will be done by calling BabTTS_SetSettings functions.

3.6. Speaking the text

There are several ways to use the Text-to-speech system depending on the application you are targeting. For Multimedia application, you can simply use the BabTTS_SpeakText function that will send the output of the Text-to-speech to your sound card. For telecom, (dependant of your license file), you will have to put the text in a queue (BabTTS_InsertText) and then you will retrieve the output in buffers (BabTTS_ReadBuffer). In other applications, you can directly put the produced speech into a file by using the BabTTS_Write function.

Date : 19/01/07

Page : 12/116


SDK Developer Guide

AcaMul-SDK-6


3.7. Closing the voice

Like usual, when you have completed using the engine, you will call some closing functions to free the resources (BabTTS_Close).

3.8. Closing and unloading the Library

A call to the function BabTTS_Uninit allows to safely releasing all resources acquired by the library. Then, calling BabTtsUnitDll will release the Acatts.dll library

Date : 19/01/07

Page : 13/116


SDK Developer Guide

AcaMul-SDK-6


4. Using the Callbacks Mechanism

4.1. Purpose

When using Acapela TTS Multimedia with sound card (using BabTTS_Speak), you can synchronize some events with the produced sounds. You can, for example highlight word as soon as they are played (as in AcaDemo)

4.2. Using callbacks

Acapela TTS Multimedia accepts two kind of callback: function or window.

Acapela TTS Multimedia accepts one kind of callback: function. See BabTTS_SetCallback to know how you can define and handle a callback. Each event is associated with a message that contains different side information according to its type.

dwCallbackInstance : by default this parameter is filled with the calling LPBABTTS. You can change it thanks to the setting BABTTS_PARAM_CBINSTANCE with the function BabTTS_SetSetting.

dwMsgInfo : Event specific information. See below

If you don’t want specific events, or if you want to add some, you can use the BabTTS_SetSettings with the BABTTS_PARAM_MSGMASK parameter, using a bit field. See related event for which bit enable/disable each message

Date : 19/01/07

Page : 14/116


SDK Developer Guide

AcaMul-SDK-6


4.3. Messages

Message Meaning dwMsgInfo Related Bit for

enable/disable BABTTS_MSG_END Indicates the

end of the processing

BABTTS_MSG_PHONE Sent each time a phoneme is encountered

Handle to the current phoneme, user can retrieve visual information for animation purposes

BABTTS_EVENT_PHONE

BABTTS_MSG_SENTENCE Sent each time the engine begins a new sentence

Pointer to a BABTTSUNITINFO structure filled with information about the sentence

BABTTS_EVENT_SENTENCE

BABTTS_MSG_SPEAK The engine starts processing

BABTTS_MSG_TEXTBEGIN Sent each time the engine begins a new text

Pointer to a BABTTSUNITINFO structure filled with information about the text

BABTTS_EVENT_TEXTBEGIN

BABTTS_MSG_TEXTEND Sent when engine finished a text

BABTTS_EVENT_TEXTEND

BABTTS_MSG_USERMRK The engine encountered a user mark

the numerical data associated with the marker (see Sapi tags)

BABTTS_EVENT_USERMRK

BABTTS_MSG_WORD Sent each time the engine begins a new word

Pointer to a BABTTSUNITINFO structure filled with information about the word

BABTTS_EVENT_WORD

Date : 19/01/07

Page : 15/116


SDK Developer Guide

AcaMul-SDK-6


5. Changing Settings Acapela TTS Multimedia, depending of the technology used (HD or HQ) allows you to adapt some settings.

5.1. Using the Property Box

Acapela TTS Multimedia provides you a graphical dialog box allowing the change of most of the parameters. This Dialog Box is similar to the Voice Manager (see “User Guide, chapter 7) but doesn’t allow the modification of the voice. Depending of the type of voice you currently use (custom or original), you can make the changes you made persistent or not.

This Property Box can be called by several methods:

• Proprietary API : The BabTTS_Dialog function (see Reference Guide) • SAPI 4.0a : ITTSDialogs.GeneralDlg method

Date : 19/01/07

Page : 16/116


SDK Developer Guide

AcaMul-SDK-6


5.2. Using BabTTS_SetSettings/BabTTS_GetSettings

This paragraph explains the different parameters you can use with these functions. For each parameter, you will find:

• A Description of the parameter • The BabTtsParam type to use with functions (see reference guide) • The valid range • Remarks, if any

5.2.1. Callback Instance Value

Description:

Change the value of the dwCallbackInstance used with callbacks. Changing this value allows user to have a better control on callback.

BabTtsParam:

BABTTS_PARAM_ CBINSTANCE

Range:

Any 32 bits value

Remark:

By default, this value is the same as the LPBABTTS object.

5.2.2. Callback Message Mask

Description:

Allows selecting the messages sent with the callback mechanism

BabTtsParam:

BABTTS_PARAM_ MSGMASK

Range:

Any combination of : • BABTTS_EVENT_PHONE • BABTTS_EVENT_SENTENCE • BABTTS_EVENT_TEXTBEGIN • BABTTS_EVENT_TEXTEND • BABTTS_EVENT_USERMRK • BABTTS_EVENT_WORD

5.2.3. Coding Scheme

Description:

Sets the coding scheme applied to the output

BabTtsParam:

BABTTS_PARAM_WAVEFORMAT

Date : 19/01/07

Page : 17/116


SDK Developer Guide

AcaMul-SDK-6


Range:

One of the following values: • BABTTS_FORMAT_PCM8 : 8 bits linear PCM • BABTTS_FORMAT_PCM : 16 bits linear PCM • BABTTS_FORMAT_ALAW : CCITT A-Law (8 bits) • BABTTS_FORMAT_MULAW : CCITT µ law (8 bits) • BABTTS_FORMAT_OKI_ADPCM : Oki Data ADPCM 4 bits (Dialogic)

Remarks:

When used with BabTTS_Write, all possibilities are not allowed,depending of the output format chosen(raw, wav, aiff …). Refer to the BabTTS_Write function for possibilities

5.2.4. Equalizer

Description:

Allows to control the Equalizer from your application.

BabTtsParam:

• BABTTS_PARAM_USEFILTER : Enable/disable the use of the equalizer

• BABTTS_PARAM_FILTERVALUEn (n=1-4): a value corresponding to the attenuation/amplification for the nth band.

Range:

• BABTTS_PARAM_USEFILTER : 0 / 1 • BABTTS_PARAM_FILTERVALUEn (n=1-4)

o 0(-10dB, attenuation)<Value<200 (+10dB, amplification) o 100 (0dB) left unchanged

5.2.5. Leading Silence

Description:

Changes the value (in ms) of the pause at the beginning of a sentence. Changing this value allows faster response of the TTS.

BabTtsParam:

BABTTS_PARAM_ LEADINGSILENCE

Range:

> 20 ms, < 10sec

Remark:

By default, this value is 50 ms.

5.2.6. Pauses

Description:

Allows changing the duration of several type of pauses

Date : 19/01/07

Page : 18/116


SDK Developer Guide

AcaMul-SDK-6


BabTtsParam:

• BABTTS_PARAM_PAUSEPUNCT (Pause for .!? - default: 500 ms)

• BABTTS_PARAM_PAUSESEMICOLON (Pause for ; - default: 500 ms)

• BABTTS_PARAM_PAUSECOMMA(Pause for ,: - default: 250 ms)

• BABTTS_PARAM_PAUSEBRACKET(Pause for ([{}]) - default:100 ms) 1• BABTTS_PARAM_PAUSESPELL (Pause between words or letters

in spell mode - default: 500 ms)

Range:

One of the following values: • BABTTS_PAUSE_DEFAULT (to use the default value for the

selected param) • BABTTS_PAUSE_VERYSHORT (100 ms) • BABTTS_PAUSE_SHORT(250 ms) • BABTTS_PAUSE_MEDIUM (500 ms) • BABTTS_PAUSE_LONG (1000 ms) • BABTTS_PAUSE_VERYLONG (2000 ms)

Advanced

It is possible to change the default values of a BABTTS_PARAM_PAUSExxx for a language or a specific voice. If you change the default values for a language, these new default values will be applied to all voices depending of this language. . If you change the default values for a specific voice (or custom voice), these new default values will be applied only to the voice.

To do this, open regedit and go to “HKLM\Software\Acapela Group\Acapela Multimedia 6\Languages\xxxxxxxx” to modify the values for the language xxxxxxxx or go to “HKLM\Software\ Acapela Group\Acapela Multimedia 6\Speechfonts\yyyyyyyy” to modify the values for the voice yyyyyyyy. Add the following entries (values in REG_SZ type and in ms):

• PAUSE_PUNCT • PAUSE_SEMICOLON • PAUSE_COMMA • PAUSE_BRACKET • PAUSE_SPELL

It is also possible to modify the values of BABTTS_PAUSE_zzzzzz by the same way. Add the following entries (values in REG_SZ type and in ms):

• PAUSE_VALUE_VERYSHORT • PAUSE_VALUE_SHORT • PAUSE_VALUE_MEDIUM • PAUSE_VALUE_LONG

1 1 For the following HD voices, you can only modify BABTTS_PARAM_PAUSEPUNCT and not the other pauses: Roger and Kate, Poul, Rik, Matti, Pierre, Helga and Gerhard, Snorri, Trygve and Vegard, Juan, AnnMarie and Ingmar, Lucy and Larry. All HQ voices and others HD voices can use the other punct settings.

Date : 19/01/07

Page : 19/116


SDK Developer Guide

AcaMul-SDK-6


• PAUSE_VALUE_VERYLONG

You can do this by modifying the BabTts.conf xml file and adding an attribute to the NLP XML element corresponding to the voice you want to modify. For example, add PAUSE_PUNCT=”PAUSE_VALUE_SHORT” as attribute to the element German_Sarah22k to change the pause punct of sarah. BE CAREFULL!!! If you broke the xml format, Acapela Multimedia will not work. Do a backup of your BabTts.conf file before modifying it.

5.2.7. Pitch (HD voices ONLY)

Description :

Sets the baseline pitch (in Hz) of the voice. (Man: usually about 110 Hz. Woman: usually about 180 Hz)

BabTtsParam :

BABTTS_PARAM_PITCH

Range

30Hz <–-> 500Hz

Remark

This parameter cannot be changed with a HQ voice.

5.2.8. Pitch – Maximum (HD voices ONLY)

Description :

Determine the maximum pitch allowed (in Hz).

BabTtsParam :

BABTTS_PARAM_ MAXPITCH

Range

Pitch <–-> (Pitch*2.5)

Remark


5.2.9. Pitch – Minimum (HD voices ONLY)

Description :

Determine the minimum pitch allowed (in Hz).

BabTtsParam :

BABTTS_PARAM_ MINPITCH

Range

Pitch/5 <–-> Pitch

Date : 19/01/07

Page : 20/116


SDK Developer Guide

AcaMul-SDK-6


Remark


5.2.10. Reading Mode

Description:

Allows selecting the way texts are spoken

BabTtsParam:

BABTTS_PARAM_ READINGMODE

Range:

One of the following values: • BABTTS_READ_TEXT : normal mode • BABTTS_READ_WORD : words are spoken with a pause between

them • BABTTS_READ_LETTER : each word is pronounced letter by letter

(spelling mode)

Remark:

BABTTS_READ_TEXT is the default reading mode, for custom voices, you can change the default with the Voice Manager. You can adapt the pause used for letter and word mode with the BABTTS_PARAM_PAUSESPELL parameter. (Default: 500 ms)

5.2.11. Sampling Rate

Description :

Gives the actual sampling rate of the voice.

BabTtsParam :

BABTTS_PARAM_VOICE

Range

One of the following values : 8000, 11025, 16000, 22050

Remarks

Read-only

5.2.12. Speed Rate

Description:

Determines the reading speed of the text-to-speech engine. Values are in percent of the default speed rate.

BabTtsParam:

BABTTS_PARAM_SPEED

Range

30% <–-> 300%

Date : 19/01/07

Page : 21/116


SDK Developer Guide

AcaMul-SDK-6


5.2.13. Volume

Description:

Applies a ratio (in %) to the output of the TTS in order to change the volume.

BabTtsParam:

BABTTS_PARAM_VOLUMERATIO

Range

0%-150%

Date : 19/01/07

Page : 22/116


SDK Developer Guide

AcaMul-SDK-6


6. Reference Guide

The reference guide is intended to provide a complete reference of the functionalities offered in the Acapela TTS Multimedia Software Development Kit.

6.1. Function list by topic

Library Loading, unloading

BabTtsInitDll, BabTtsInitDllEx,BabTtsUninitDll

Library initialization, unitialization BabTTS_Init, BabTTS_Unit

Engine creation and destruction

BabTTS_Open, BabTTS_Close, BabTTS_Create

Engine Use BabTTS_Speak, BabTTS_Write, BabTTS_Pause, BabTTS_Resume, BabTTS_InsertText, BabTTS_ReadBuffer

Engine configuration BabTTS_SetCallback, BabTTS_Reset, BabTTS_SetSettings, BabTTS_GetSettings, BabTTS_GetCallback, BabTTS_Dialog, BabTTS_SetFilterPreset, BabTTS_GetFilterPreset

Voice enumeration BabTTS_GetNumVoices, BabTTS_EnumVoices, BabTTS_GetVoiceInfo, BabTTS_GetInstanceInfo

User Dictionary BabTTS_DictXXXX functions

Date : 19/01/07

Page : 23/116


SDK Developer Guide

AcaMul-SDK-6


6.2. Functions

Each function is described with the following details:

Synopsis :

Prototype in C language of the function.

Description :

Describes the functionality provided by the function.

Parameters :

Gives the list and details about the parameters to be specified to the function.

Return value(s) :

A return value is often used to control the result provided by the function.

Example :

If needed, a short example shows how to use the function. All examples are implemented in the example program BabTTS_DocExample (see the SDK directory in your installation path). Note : the symbol indicates that the function needs a specific license before being used.

Date : 19/01/07

Page : 24/116


SDK Developer Guide

AcaMul-SDK-6


6.2.1. BabTTS_Close

Synopsis

BabTtsError BabTTS_Close(LPBABTTS lpBabTTS);

Description

Releases the memory allocated for lpBabTTS. After a call to BabTTS_Close, the handle is no more valid and you must use BabTTS_Create and BabTTS_Open for creating a new one.

Parameters

LpBabTTS [IN] The LPBABTTS object to delete.

Return Value

BabTTS_Close returns:

E_BABTTS_NOERROR The memory has been correctly released

E_BABTTS_NOTVALIDPARAMETER The lpBabTTS handle is not valid

E_BABTTS_PROCESSERROR Unexpected error

Remarks

None

Example

See BabTTS_Open

Date : 19/01/07

Page : 25/116


SDK Developer Guide

AcaMul-SDK-6


6.2.2. BabTTS_Create

Synopsis

LPBABTTS BabTTS_Create(void)

Description

This function creates a new LPBABTTS in memory. The return value (if not NULL) must be used for each call to other functions.

Parameters

none

Return Value

BabTTS_Create returns a handle to a newly opened instance. NULL if initialization failed.

Remarks

The created instance cannot be used before initialisation, use BabTTS_Open before using the instance

Example

See BabTTS_Open

Date : 19/01/07

Page : 26/116


SDK Developer Guide

AcaMul-SDK-6


6.2.3. BabTTS_Dialog

Synopsis

BabTtsError BabTTS_Dialog ( LPBABTTS lpBabTTS, HWND hWnd, BabTtsDlg dlgType);

Description

This function opens a Windows dialog boxes to configure an opened object or a voice in general.

Parameters

lpBabTTS : [IN] A BabTTS object to use. Can be NULL, in this case the dialog allows to manage any voice. hWnd: [IN] Handle of the parent window. If this parameter is NULL, the engine returns E_BABTTS_NOERROR if it supports the requested dialog box. dlgType : [IN] The type of Dialog. Can be:

• BABTTS_DLG_LEXICON : The Lexicon Editor • BABTTS_DLG_PROPERTIES : The properties Editor (Or voice

manager if lpBabTTS is NULL)

Return Value

E_BABTTS_NOERROR No error E_BABTTS_REGISTRYERROR The Dialog Module of BabTTS has

not been found E_BABTTS_PROCESSERROR Unexpected Error E_BABTTS_NOTVALIDPARAMETER Invalid Parameter

Date : 19/01/07

Page : 27/116


SDK Developer Guide

AcaMul-SDK-6


6.2.4. BabTTS_DictAddWord

Synopsis

BabTtsError BabTTS_DictAddWord( LPBABTTS lpBabTTS, LPBABTTSDICT lpDict, const char* lpszWord, const char* lpszTrans, BabTtsWordType Type);

Description

This function appends (changes) a word transcription to the user dictionary.

Parameters

lpBabTTS : [IN] A BabTTS object to use lpDict : [IN] A previously loaded dictionary handle lpszWord: [IN] The word for which the user wants to adjust the pronunciation. Max. 511 characters + '\0'. lpszTrans: [IN] The phonetic transcription or a word that has the wanted pronunciation (See remarks). Max. 1023 characters + '\0'. Type: [IN] The grammatical type of the word.

Date : 19/01/07

Page : 28/116


SDK Developer Guide

AcaMul-SDK-6


Return Value

W_BABTTS_NOTPROCESSED warning informing that the operation cannot be processed (See Remarks).

E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS, invalid lpDict

(NULL or not equal to a loaded dictionary), invalid Type, lpszWord is NULL or lpszTrans is NULL..

E_BABTTS_DICT_READ Error while adding the word into the loaded dictionary (reading phase).

E_BABTTS_DICT_WRITE Error while adding the word into the loaded dictionary (writing phase).

E_BABTTS_BADPHO A wrong phoneme was introduced into lpszTrans

E_BABTTS_NOTIMPLEMENTED The NLP does not support user dictionaries

Remarks

If lpszWord is in lower case, the user transcription will replace the word in both lower and upper case. If lpszWord contains characters in upper case, the transcription will replace only a word with the same case. lpszTrans can be either a word having the new pronunciation ("say as") or a phonetic transcription. To differentiate the phonetic transcription, a phonetic string must begin with # and have a space between each phoneme. Example for the French word "Bonjour" that we want be pronounced like "hello": lpszTrans can be "hello" or, using the phonetic transcription, "# E l o" Possible cause of W_BABTTS_NOTPROCESSED: 1) The dictionary has not the "write" property (See BabTTS_SetInfo). 2) lpszTrans contains more than 1023 characters. 3)lpszWord is an empty string or contains more than 511 characters.

Date : 19/01/07

Page : 29/116


SDK Developer Guide

AcaMul-SDK-6


Valid BabTtsWordType: BABTTS_WORDTYPE_UNKNOWN, BABTTS_WORDTYPE_NOUN, BABTTS_WORDTYPE_VERB, BABTTS_WORDTYPE_ADVERB, BABTTS_WORDTYPE_ADJECTIVE, BABTTS_WORDTYPE_PROPERNOUN, BABTTS_WORDTYPE_PRONOUN, BABTTS_WORDTYPE_CONJUNCTION, BABTTS_WORDTYPE_CARDINAL, BABTTS_WORDTYPE_ORDINAL, BABTTS_WORDTYPE_DETERMINER, BABTTS_WORDTYPE_QUANTIFIER, BABTTS_WORDTYPE_PUNCTUATION, BABTTS_WORDTYPE_CONTRACTION, BABTTS_WORDTYPE_INTERJECTION, BABTTS_WORDTYPE_ABBREVIATION, BABTTS_WORDTYPE_PREPOSITION

Date : 19/01/07

Page : 30/116


SDK Developer Guide

AcaMul-SDK-6


Example /* IMPORTANT NOTE :

Please do not forget to call the BabTtsInitDll/BabTtsInitDllEx + BabTTS_Init and BabTTS_Uninit + BabTtsUninitDll functions, respectively at the very beginning and at the end of your source code. Those functions need to be called only once for the whole program.*/ LPBABTTS babtts=NULL;

LPBABTTSDICT lpDict=NULL; BabTtsError babError=E_BABTTS_NOERROR; printf("BabTTS_Create\n"); babtts = BabTTS_Create(); printf("BabTTS_Open with Julie22k\n"); babError=BabTTS_Open(babtts,"Julie22k",0); if(babError!=E_BABTTS_NOERROR) { printf("Error while opening voice: %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictLoad\n"); babError=BabTTS_DictLoad(babtts,&lpDict,"user_fr.dic"); if(babError!=E_BABTTS_NOERROR) { printf("Error while loading dictionary: %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictAddWord \"bonjour\"\n"); babError=BabTTS_DictAddWord(babtts,lpDict,"bonjour", "# E l o", BABTTS_WORDTYPE_NOUN); if(babError!=E_BABTTS_NOERROR) { printf("Error while adding word \"bonjour\" : %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictAddWord \"café\"\n"); babError=BabTTS_DictAddWord(babtts,lpDict,"café","cacao", BABTTS_WORDTYPE_NOUN); if(babError!=E_BABTTS_NOERROR) { printf("Error while adding word \"café\" : %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictSave\n"); babError=BabTTS_DictSave(babtts,lpDict,NULL); if(babError!=E_BABTTS_NOERROR) { printf("Error while saving dictionary: %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictUnload\n");

Date : 19/01/07

Page : 31/116


SDK Developer Guide

AcaMul-SDK-6


babError=BabTTS_DictUnload(babtts,lpDict); if(babError!=E_BABTTS_NOERROR) { printf("Error while unloading dictionary : %d\n",babError); } BabTTS_Close(babtts);

Date : 19/01/07

Page : 32/116


SDK Developer Guide

AcaMul-SDK-6


6.2.5. BabTTS_DictDisable

Synopsis

BabTtsError BabTTS_DictDisable(LPBABTTS lpBabTTS, LPBABTTSDICT lpDict);

Description

This function disables a loaded dictionary.

Parameters

lpBabTTS : [IN] A BabTTS object to use lpDict: [IN] A valid dictionary handle.

Return Value

BabTTS_DictDisable returns an error type: W_BABTTS_NOTPROCESSED user dictionary is already

disabled E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS, invalid lpDict

(NULL or not equal to a loaded dictionary).


Remarks

A newly loaded dictionary is enabled by default. If user disables a dictionary by calling BabTTS_DictDisable, then the dictionary is not used for the phonetisation. But it is still loaded in memory. Call BabTTS_DictEnable to enable the dictionary. To know the enable/disable status of a dictionary, user can call BabTTS_DictGetInfo and examine dwProperties member or check the return value of BabTTS_DictEnable / DictDisable (W_BABTTS_NOTPROCESSED)

Example

See BabTTS_DictEnable

Date : 19/01/07

Page : 33/116


SDK Developer Guide

AcaMul-SDK-6


6.2.6. BabTTS_DictEnable

Synopsis

BabTtsError BabTTS_DictEnable(LPBABTTS lpBabTTS, LPBABTTSDICT lpDict);

Description

This function enables a loaded dictionary.

Parameters

lpBabTTS : [IN] A BabTTS object to use lpDict: [IN] A valid dictionary handle.

Return Value

BabTTS_DictEnable returns an error type: W_BABTTS_NOTPROCESSED user dictionary is already

enabled E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER Invalid lpDict (NULL or not

equal to a loaded dictionary). E_BABTTS_NOTIMPLEMENTED The NLP does not support user

dictionaries

Remarks

A newly loaded dictionary is enabled by default. If user enables a dictionary by calling BabTTS_DictEnable, then the dictionary is used for the phonetisation. Call BabTTS_DictDisable to disable the dictionary. To know the enable/disable status of a dictionary, user has to call BabTTS_DictGetInfo and examine dwProperties member or check the return value of BabTTS_DictEnable / DictDisable (W_BABTTS_NOTPROCESSED)

Date : 19/01/07

Page : 34/116


SDK Developer Guide

AcaMul-SDK-6



Please do not forget to call the BabTtsInitDll/BabTtsInitDllEx + BabTTS_Init and BabTTS_Uninit + BabTtsUninitDll functions, respectively at the very beginning and at the end of your source code. Those functions need to be called only once for the whole program.*/ LPBABTTS babtts=NULL; LPBABTTSDICT lpDict1, lpDict2, lpDict3, lpDict4=NULL; BabTtsError babError, babError1, babError2, babError3, babError4=E_BABTTS_NOERROR; printf("BabTTS_Create\n"); babtts = BabTTS_Create(); printf("BabTTS_Open with John22k\n"); babError=BabTTS_Open(babtts,"John22k",0); if(babError!=E_BABTTS_NOERROR) { printf("Error while opening voice: %d\n",babError); BabTTS_Close(babtts); return; } printf("Loading dictionaries\n"); babError1=BabTTS_DictLoad(babtts,&lpDict1,"user1_us.dic"); babError2=BabTTS_DictLoad(babtts,&lpDict2,"user2_us.dic"); babError3=BabTTS_DictLoad(babtts,&lpDict3,"user3_us.dic"); babError4=BabTTS_DictLoad(babtts,&lpDict4,"user4_us.dic"); if(babError1||babError2||babError3||babError4) { printf("Error while loading dictionary: %d %d %d %d\n" ,babError1,babError2,babError3,babError4); BabTTS_Close(babtts); return; } printf("all dictionaries are enabled\n"); //... //code, using all dictionaries… //... BabTTS_DictDisable(babtts, lpDict1);//lpDict1 disabled BabTTS_DictDisable(babtts, lpDict2);//lpDict2 disabled printf("user1.dic and user2.dic disabled\n"); //... //code, using only lpDict3 and lpDict4 //... BabTTS_DictEnable(babtts, lpDict1); //lpDict1 enabled BabTTS_DictDisable(babtts, lpDict3); //lpDict3 disabled BabTTS_DictDisable(babtts, lpDict4); //lpDict4 disabled printf("user1.dic enabled, other dictionaries disabled\n"); //... //code, using only lpDict1 //... BABTTSDICTINFO Dict1Info; printf("BabTTS_DictGetInfo\n"); BabTTS_DictGetInfo(babtts, lpDict1,&Dict1Info); if(Dict1Info.dwProperties&&BABTTS_DICT_ENABLED) { printf("lpDict1 is enabled\n"); }

Date : 19/01/07

Page : 35/116


SDK Developer Guide

AcaMul-SDK-6


printf("BabTTS_DictUnloadAll\n"); babError=BabTTS_DictUnloadAll(babtts); if(babError!=E_BABTTS_NOERROR) { printf("Error while unloading dictionary: %d\n",babError); } BabTTS_Close(babtts); babtts=NULL;

Date : 19/01/07

Page : 36/116


SDK Developer Guide

AcaMul-SDK-6


6.2.7. BabTTS_DictEnum

Synopsis

BabTtsError BabTTS_DictEnum( LPBABTTS lpBabTTS, LPBABTTSDICT* lppDict, unsigned long dwIndex);

Description

This function enumerates the loaded dictionaries.

Parameters

lpBabTTS : [IN] A BabTTS object to use lppDict: [OUT] Pointer to the loaded dictionary handle (same as returned by BabTTS_DictLoad). The user shouldn't delete manually this handle because it is used by BabTTS object. Use BabTTS_DictUnload to delete the dictionary. dwIndex: [IN] The index of the requested dictionary.(first dictionary has index 1)

Return Value

BabTTS_DictEnum returns an error type: E_BABTTS_NOERROR No error E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS, lppDict is

NULL E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NODICT No dictionary found at given

index E_BABTTS_NOTIMPLEMENTED The NLP does not support user

dictionaries

Remarks

Index are in the range from 1 to BabTTS_DictGetNumLoaded(). If you unload a dictionary, index of other dictionaries will decrease if they were loaded after the unloaded dictionary. This function is useful to retrieve dictionaries handles automatically loads by a babtts object open with BABTTS_USEDEFDICT mode.

Date : 19/01/07

Page : 37/116


SDK Developer Guide

AcaMul-SDK-6




LPBABTTSDICT lpDict1, lpDict2, lpDict3, lpDict4=NULL; BabTtsError babError, babError1, babError2, babError3, babError4=E_BABTTS_NOERROR; printf("BabTTS_Create\n"); babtts = BabTTS_Create(); printf("BabTTS_Open with Heather22k\n"); babError=BabTTS_Open(babtts,"Heather22k",0); if(babError!=E_BABTTS_NOERROR) { printf("Error while opening voice: %d\n",babError); BabTTS_Close(babtts); return; } printf("Loading dictionaries\n"); babError1=BabTTS_DictLoad(babtts,&lpDict1,"user1_us.dic"); babError2=BabTTS_DictLoad(babtts,&lpDict2,"user2_us.dic"); babError3=BabTTS_DictLoad(babtts,&lpDict3,"user3_us.dic"); babError4=BabTTS_DictLoad(babtts,&lpDict4,"user4_us.dic"); if(babError1||babError2||babError3||babError4) { printf("Error while loading dictionary: %d %d %d %d\n",babError1,babError2,babError3,babError4); BabTTS_Close(babtts); return; } //... //code with dictionaries… //... printf("BabTTS_DictGetNumLoaded\n"); long numberdico=BabTTS_DictGetNumLoaded(babtts); printf("Number of loaded dictionaries: %d\n",numberdico); if(numberdico>0) { for(int i=1;i<=numberdico;i++) { LPBABTTSDICT dico=NULL; printf("BabTTS_DictEnum for dictionaries number %d\n",i); babError=BabTTS_DictEnum(babtts,&dico,i); if(babError!=E_BABTTS_NOERROR) { printf("Error while enumerating dictionary number %d: %d\n",i,babError); BabTTS_Close(babtts); return; }

Date : 19/01/07

Page : 38/116


SDK Developer Guide

AcaMul-SDK-6


else { //code with dictionaries… }

} } printf("BabTTS_DictSaveAll\n"); babError=BabTTS_DictSaveAll(babtts); if(babError!=E_BABTTS_NOERROR) { printf("Error while saving dictionary: %d\n",babError); } printf("BabTTS_DictUnloadAll\n"); babError=BabTTS_DictUnloadAll(babtts); if(babError!=E_BABTTS_NOERROR) { printf("Error while unloading dictionary: %d\n",babError); } BabTTS_Close(babtts);

Date : 19/01/07

Page : 39/116


SDK Developer Guide

AcaMul-SDK-6


6.2.8. BabTTS_DictGetDefList

Synopsis

BabTtsError BabTTS_DictGetDefList(LPBABTTS lpBabTTS, char* lpszFileList, unsigned long* lpdwSize);

Description

This function retrieves the list of user lexicons loaded when using BABTTS_USEDEFDICT

Parameters

lpBabTTS : [IN] A BabTTS object to use lpszFileList: [OUT] The needed list (user allocated array of size *lpdwSize or NULL if we want only the minimum size needed for lpszFileList string) lpdwSize: [IN] The size of the lpszFileList array / [OUT] The number of bytes copied ( or needed ) to lpszFileList

Remark

Lexicon file names are separated by a ‘;’, first ones have higher priority

Date : 19/01/07

Page : 40/116


SDK Developer Guide

AcaMul-SDK-6


6.2.9. BabTTS_DictGetEntry

Synopsis

BabTtsError BabTTS_DictGetEntry(LPBABTTS lpBabTTS, LPBABTTSDICT lpDict, unsigned long dwIndex, char* lpszEntry, unsigned long* lpdwEntrySize);

Description

This function retrieves the word number "dwIndex" in the user lexicon

Parameters

lpBabTTS : [IN] A BabTTS object to use lpDict : [IN] A valid dictionary handle dwIndex: [IN] The zero-based index of the word to retrieve lpszEntry: [OUT] The needed word (user allocated array of size *lpdwEntrySize or NULL if we want only the minimum size needed for lpszEntry string) lpdwEntrySize: [IN] The size of the lpszEntry array / [OUT] The number of bytes copied ( or needed ) to lpszEntry

Return Value

BabTTS_DictGetEntry returns an error type: W_BABTTS_NOTPROCESSED warning informing that the

operation cannot be processed (See "Remarks").


(NULL or not equal to a loaded dictionary), or lpdwEntrySize is NULL.

E_BABTTS_DICT_READ Error while reading the dictionary

E_BABTTS_DICT_NOENTRY There is no entry at dwIndex. Call BabTTS_DictGetNumEntries to know the upper boundary


Remarks

The way the NLP manages the index order is free, this function can only be used when "dumping" all the dictionary. Two words with consecutive indexes are not related together. Possible cause of W_BABTTS_NOTPROCESSED: The dictionary has not the "read" property (See

Date : 19/01/07

Page : 41/116


SDK Developer Guide

AcaMul-SDK-6


BabTTS_DictSetInfo) The size of lpszEntry is too short. Allocate a new lpszEntry with a minimum of (*lpdwEntrySize) bytes. If lpszEntry is NULL, lpdwEntrySize will contain the minimum size of lpszEntry needed to copy the word. The function returns E_BABTTS_NOERROR if success. The value returned by *lpdwEntrySize is the length of the word + '\0'



LPBABTTSDICT lpDict=NULL; unsigned long size=0; char lpszEntry[512]; char lpszTrans[1024]; BabTtsWordType typ; BabTtsError err; lpszEntry[0]='\0'; lpszTrans[0]='\0'; printf("BabTTS_Create\n"); babtts = BabTTS_Create(); printf("BabTTS_Open with voice Julie22k\n"); err=BabTTS_Open(babtts,"Caroline22k",0); if(err!=E_BABTTS_NOERROR) { printf("Error while opening voice: %d\n",err); BabTTS_Close(babtts); return; } printf("BabTTS_DictLoad\n"); err=BabTTS_DictLoad(babtts,&lpDict,"user_fr.dic"); if(err) { printf("Error while loading dictionary: %d\n",err); BabTTS_Close(babtts); return; } long numentries=BabTTS_DictGetNumEntries(babtts,lpDict); printf("Number of entries in dictionary: %d\n",numentries); for(int i=0;i<numentries;i++) { size=512; printf("BabTTS_DictGetEntry on entry %d\n",i);

Date : 19/01/07

Page : 42/116


SDK Developer Guide

AcaMul-SDK-6


err=BabTTS_DictGetEntry(babtts,lpDict,i,lpszEntry,&size); printf("Entry: %s Size: %d\n",lpszEntry,size); if((err==E_BABTTS_NOERROR)&&(size>0)) { size=1024; printf("BabTTS_DictGetWordTrans on entry \"%s\"\n",lpszEntry); err=BabTTS_DictGetWordTrans(babtts,lpDict, lpszEntry,lpszTrans,&size,&typ); printf("Entry: \"%s\" Transcription: \"%s\" WordType: %d\n",lpszEntry,lpszTrans,typ); } } printf("BabTTS_DictUnload\n");

err=BabTTS_DictUnload(babtts,lpDict); if(err!=E_BABTTS_NOERROR) { printf("Error while unloading dictionary: %d\n",err); } BabTTS_Close(babtts);

Date : 19/01/07

Page : 43/116


SDK Developer Guide

AcaMul-SDK-6


6.2.10. BabTTS_DictGetInfo

Synopsis

BabTtsError BabTTS_DictGetInfo(LPBABTTS lpBabTTS, LPBABTTSDICT lpDict, LPBABTTSDICTINFO lpDictinfo);

Description

This function returns information about a loaded dictionary.

Parameters

lpBabTTS : [IN] A BabTTS object to use lpDict : [IN] A previously loaded dictionary handle lpDictinfo: [OUT] The (user-allocated) structure designed to receive the information about the dictionary.

Return Value

BabTTS_DictGetInfo returns an error type: E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS, invalid lpDict

(NULL or not equal to a loaded dictionary) or lpDictinfo is NULL.


Date : 19/01/07

Page : 44/116


SDK Developer Guide

AcaMul-SDK-6


Remarks

The user-allocated BABTTSDICTINFO structure contains the following information:

The absolute filename of the dictionary The language The dictionary version The number of entries The revision of the dictionary The creation date The last modification date The properties of the dictionary (enabled/disabled, read

protection, write protection, password protection, modified/not modified, user/system dictionary)

The description of the dictionary The user-defined name of the dictionary

See BABTTSDICTINFO in chapter "Structures definitions" for more information.

Example

See BabTTS_DictSetInfo

Date : 19/01/07

Page : 45/116


SDK Developer Guide

AcaMul-SDK-6


6.2.11. BabTTS_DictGetInfoFromFile

Synopsis

BabTtsError BabTTS_DictGetInfoFromFile(LPBABTTS lpBabTTS, const char* lpszFileName, LPBABTTSDICTINFO lpDictinfo);

Description

This function returns information about a dictionary stored in a file.

Parameters

lpBabTTS : [IN] A BabTTS object to use lpszFileName : [IN] A dictionary filename lpDictinfo: [OUT] The (user-allocated) structure designed to receive the information about the dictionary.

Return Value

BabTTS_DictGetInfo returns an error type: W_BABTTS_NOTPROCESSED Informations not available in

this dictionary: This is not a BabTTS user dictionary.

E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS, lpszFileName

is NULL or empty string. E_BABTTS_DICT_READ Error while reading dictionary

information. E_BABTTS_DICT_OPEN lpszFileName doesn't exist E_BABTTS_NOTIMPLEMENTED The NLP does not support user

dictionaries

Date : 19/01/07

Page : 46/116


SDK Developer Guide

AcaMul-SDK-6


Remarks





See BABTTSDICTINFO in chapter "Structures definitions" for more information.

Date : 19/01/07

Page : 47/116


SDK Developer Guide

AcaMul-SDK-6



Please do not forget to call the BabTtsInitDll/BabTtsInitDllEx + BabTTS_Init and BabTTS_Uninit + BabTtsUninitDll functions, respectively at the very beginning and at the end of your source code. Those functions need to be called only once for the whole program.*/ LPBABTTS babtts=NULL; LPBABTTSDICT lpDict=NULL; BabTtsError babError=E_BABTTS_NOERROR; printf("BabTTS_Create\n"); babtts = BabTTS_Create(); printf("BabTTS_Open with voice Heather22k\n"); babError=BabTTS_Open(babtts,"Heather22k",0); if(babError!=E_BABTTS_NOERROR) { printf("Error while opening voice: %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictGetInfoFromFile\n"); BABTTSDICTINFO dictInfo; babError=BabTTS_DictGetInfoFromFile(babtts, "user_us.dic",&dictInfo); if(babError!=E_BABTTS_NOERROR) { printf("Error in BabTTS_DictGetInfoFromFile: %d\n",babError); BabTTS_Close(babtts); return; } printf("\tNum entries: %d\n\tProperties: 0x%x\n\t Num revision: %d\n\tDescription: %s\n\tDiconame: %s\n\tLanguage: %s\n\tVersion:%s\n\ttime_t creation: %d\n\ttime_t last modification:%d\n",dictInfo.dwNumEntries ,dictInfo.dwProperties, dictInfo.dwRevision, dictInfo.szDescription, dictInfo.szDiconame, dictInfo.szLanguage, dictInfo.szVersion, dictInfo.tCreated, dictInfo.tModified); BabTTS_Close(babtts);

Date : 19/01/07

Page : 48/116


SDK Developer Guide

AcaMul-SDK-6


6.2.12. BabTTS_DictGetMax

Synopsis

long BabTTS_DictGetMax(LPBABTTS lpBabTTS);

Description

This function returns the maximum number of loaded dictionary accepted by the engine.

Parameters

lpBabTTS : [IN] A BabTTS object to use

Return Value

BabTTS_DictGerMax returns Positive value The max number of dictionaries E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTIMPLEMENTED The language module does not

support user dictionaries

Remarks

This function is used to know if the language module has multi user dictionaries ability. Some module cannot manage more than one (or zero) user dictionary.

Date : 19/01/07

Page : 49/116


SDK Developer Guide

AcaMul-SDK-6


6.2.13. BabTTS_DictGetNumEntries

Synopsis

long BabTTS_DictGetNumEntries(LPBABTTS lpBabTTS, LPBABTTSDICT lpDict);

Description

This function retrieves the number of words in the user lexicon.

Parameters

lpBabTTS : [IN] A BabTTS object to use lpDict : [IN] A valid dictionary handle

Return Value

BabTTS_DictGetNumEntries returns: Positive value number of word in the dictionary E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS, invalid lpDict



Example

See BabTTS_DictGetEntry

Date : 19/01/07

Page : 50/116


SDK Developer Guide

AcaMul-SDK-6


6.2.14. BabTTS_DictGetNumLoaded

Synopsis

long BabTTS_DictGetNumLoaded(LPBABTTS lpBabTTS);

Description

This function returns the actual number of loaded dictionary.

Parameters


Return Value

BabTTS_DictGetNumLoaded returns: Positive value Actual number of loaded user

dictionaries E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTIMPLEMENTED The NLP does not support user

dictionaries

Remarks

This function returns the number of user dictionaries. Thus, the system dictionary is not included into the account. Use this function to know the upper boundary before using BABTTS_DictEnum to enum the actual loaded dictionaries.

Example

See BabTTS_DictEnum

Date : 19/01/07

Page : 51/116


SDK Developer Guide

AcaMul-SDK-6


6.2.15. BabTTS_DictGetWordTrans

Synopsis

BabTtsError BabTTS_DictGetWordTrans(LPBABTTS lpBabTTS, LPBABTTSDICT lpDict, const char* lpszWord, char* lpszTrans, unsigned long* lpdwSize, BabTtsWordType* lpWordType);

Description

This function gets the actual transcription of a word.

Parameters

lpBabTTS : [IN] A BabTTS object to use lpDict : [IN] A valid dictionary handle lpszWord: [IN] The word for which the user wants the pronunciation lpszTrans: [OUT] The needed transcription (user allocated array of size *lpdwSize or NULL if we want only the minimum size needed for lpszTrans string) lpdwSize: [IN] The size of the lpszTrans array [OUT] The number of bytes copied ( or needed ) to lpszTrans lpWordType: [OUT] The grammatical type of the word (see the list of BabTtsWordType in the Remarks section.)

Return Value

BabTTS_DictGetWordTrans returns an error type: W_BABTTS_NOTPROCESSED Warning informing that the

operation cannot be processed (See "Remarks").


(NULL or not equal to a loaded dictionary), lpdwSize is NULL or lpszWord is NULL.

E_BABTTS_DICT_NOENTRY lpszWord does not exist in the dictionary

E_BABTTS_DICT_READ Error while reading the dictionary.


Date : 19/01/07

Page : 52/116


SDK Developer Guide

AcaMul-SDK-6


Remarks

lpszTrans can be a word having the new pronounciation ("say as") or an other phonetic transcription. To differentiate the phonetic transcription, the phonetic string begins with # and have a space between each phoneme. Possible cause of W_BABTTS_NOTPROCESSED: 1) The dictionary has not the "read" property (See BabTTS_DictSetInfo). 2) The size of lpszTrans is too short. Allocate a new lpszTrans with a minimum of (*lpdwSize) bytes. 3) lpszWord is an empty string. If lpszTrans is NULL, lpdwSize will contain the minimum size of lpszTrans needed to copy the transcription. The function returns E_BABTTS_NOERROR if success. The value returned by *lpdwSize is the length of the transcription + '\0' (thus: real size of the transcription string+ 1) Valid BabTtsWordType: BABTTS_WORDTYPE_UNKNOWN, BABTTS_WORDTYPE_NOUN, BABTTS_WORDTYPE_VERB, BABTTS_WORDTYPE_ADVERB, BABTTS_WORDTYPE_ADJECTIVE, BABTTS_WORDTYPE_PROPERNOUN, BABTTS_WORDTYPE_PRONOUN, BABTTS_WORDTYPE_CONJUNCTION, BABTTS_WORDTYPE_CARDINAL, BABTTS_WORDTYPE_ORDINAL, BABTTS_WORDTYPE_DETERMINER, BABTTS_WORDTYPE_QUANTIFIER, BABTTS_WORDTYPE_PUNCTUATION, BABTTS_WORDTYPE_CONTRACTION, BABTTS_WORDTYPE_INTERJECTION, BABTTS_WORDTYPE_ABBREVIATION, BABTTS_WORDTYPE_PREPOSITION

Example

See BabTTS_DictGetEntry

Date : 19/01/07

Page : 53/116


SDK Developer Guide

AcaMul-SDK-6


6.2.16. BabTTS_DictIsModified

Synopsis

long BabTTS_DictIsModified( LPBABTTS lpBabTTS, LPBABTTSDICT lpDict);

Description

This function informs if the dictionary has been modified (and not yet saved).

Parameters

lpBabTTS : [IN] A BabTTS object to use. lpDict : [IN] A valid dictionary handle.

Return Value

BabTTS_DictIsModified returns: 1 The dictionary has been modified 0 The dictionary has not been

modified E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS, invalid lpDict

(NULL or not equal to a loaded dictionary


Example

See BabTTS_DictSave

Date : 19/01/07

Page : 54/116


SDK Developer Guide

AcaMul-SDK-6


6.2.17. BabTTS_DictLoad

Synopsis

BabTtsError BabTTS_DictLoad(LPBABTTS lpBabTTS, LPBABTTSDICT* lppDict, const char* lpszFileName)

Description

This function loads a dictionary into the BABTTS object and returns a BABTTSDICT handle.

Parameters

lpBabTTS : [IN] A BabTTS object to use lppDict : [OUT] Pointer to the loaded dictionary handle. The user shouldn't delete manually this handle because it is used by BabTTS object. Use BabTTS_DictUnload to delete the dictionary. lpszFileName : [IN] Name of the dictionary file (must be an absolute path).

Return Value

BabTTS_DictLoad returns an error type: E_BABTTS_NOERROR No error E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS, lppDict is

NULL E_BABTTS_DICT_READ The dictionary cannot be read

and/or loaded E_BABTTS_DICT_OPEN The specified dictionary cannot

be opened E_BABTTS_NOMEM Error during memory allocation E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTIMPLEMENTED The NLP does not support user

dictionaries

Date : 19/01/07

Page : 55/116


SDK Developer Guide

AcaMul-SDK-6


Remarks

If several dictionaries are loaded and contain a same word entry, the last loaded dictionary has the priority. Example: A first user dictionary is loaded and contains the entry: hello bye. A second user dictionary is loaded and contains the entry: hello hi. Then, the word "hello" will be pronounced "hi" and not "bye". if lpszFileName == NULL memory-only dictionary if lpszFileName doesn't exist --> the dictionary is created and will be saved with this filename after calling BabTTS_DictSave or BabTTS_DictSaveAll. The function will return E_BABTTS_DICT_READ if user tries to load a system dictionary (see BabTTS_DictGetInfo) or if a version incompatibility occurs.


Please do not forget to call the BabTtsInitDll/BabTtsInitDllEx + BabTTS_Init and BabTTS_Uninit + BabTtsUninitDll functions, respectively at the very beginning and at the end of your source code. Those functions need to be called only once for the whole program.*/ LPBABTTS babtts=NULL; LPBABTTSDICT lpDict=NULL; BabTtsError babError=E_BABTTS_NOERROR; printf("BabTTS_Create\n"); babtts = BabTTS_Create(); printf("BabTTS_Open with Heather22k\n"); babError=BabTTS_Open(babtts,"Heather22k",0); if(babError!=E_BABTTS_NOERROR) { printf("Error while opening voice: %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictLoad\n"); babError=BabTTS_DictLoad(babtts,&lpDict,"user_us.dic"); if(babError!=E_BABTTS_NOERROR) { printf("Error while loading dictionary: %d\n",babError); BabTTS_Close(babtts); return; } else { //Add words, open other dictionaries, use TTS functions, etc… }

Date : 19/01/07

Page : 56/116


SDK Developer Guide

AcaMul-SDK-6


printf("BabTTS_DictUnload\n"); babError=BabTTS_DictUnload(babtts,lpDict); if(babError!=E_BABTTS_NOERROR) { printf("Error while unloading dictionary: %d\n",babError); } lpDict=NULL; printf("BabTTS_Close\n"); BabTTS_Close(babtts); babtts=NULL;

Date : 19/01/07

Page : 57/116


SDK Developer Guide

AcaMul-SDK-6


6.2.18. BabTTS_DictRemoveWord

Synopsis

BabTtsError BabTTS_DictRemoveWord( LPBABTTS lpBabTTS, LPBABTTSDICT lpDict, const char* lpszWord);

Description

This function deletes a word from a dictionary.

Parameters

lpBabTTS : [IN] A BabTTS object to use lpDict : [IN] A previously loaded dictionary handle lpszWord: [IN] The word to delete (case sensitive if the word exists in upper case in the dictionary).

Return Value

BabTTS_DictRemoveWord returns an error type: W_BABTTS_NOTPROCESSED warning informing that the

operation cannot be processed (The dictionary has not the "write" property: See BabTTS_DictSetInfo).


(NULL or not equal to a loaded dictionary) or lpszWord is NULL.

E_BABTTS_DICT_READ Error while removing the word from the loaded dictionary (reading phase).

E_BABTTS_DICT_WRITE Error while removing the word from the loaded dictionary (writing phase).

E_BABTTS_DICT_NOENTRY lpszWord does not exist in the dictionary


Date : 19/01/07

Page : 58/116


SDK Developer Guide

AcaMul-SDK-6




LPBABTTSDICT lpDict=NULL; BabTtsError babError=E_BABTTS_NOERROR; printf("BabTTS_Create\n"); babtts = BabTTS_Create(); printf("BabTTS_Open with Julie22k\n"); babError=BabTTS_Open(babtts,"Julie22k",0); if(babError!=E_BABTTS_NOERROR) { printf("Error while opening voice: %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictLoad\n"); babError=BabTTS_DictLoad(babtts,&lpDict,"user_fr.dic"); if(babError!=E_BABTTS_NOERROR) { printf("Error while loading dictionary: %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictRemoveWord \"hi\"\n"); babError=BabTTS_DictRemoveWord(babtts,lpDict,"hi"); if(babError!=E_BABTTS_NOERROR) { if(babError==E_BABTTS_DICT_NOENTRY) { printf("BabTTS_DictRemoveWord return E_BABTTS_DICT_NOENTRY because word \"hi\" is not in dictionary\n"); } else { printf("Error while removing word \"hi\": %d\n",babError); BabTTS_Close(babtts); return; } } printf("BabTTS_DictSave\n"); babError=BabTTS_DictSave(babtts, lpDict,NULL); if(babError!=E_BABTTS_NOERROR) { printf("Error while saving dictionary: %d\n",babError); } babError=BabTTS_DictUnload(babtts,lpDict); if(babError!=E_BABTTS_NOERROR) { printf("Error while unloadinf dictionary: %d\n",babError); } BabTTS_Close(babtts); babtts=NULL;

Date : 19/01/07

Page : 59/116


SDK Developer Guide

AcaMul-SDK-6


6.2.19. BabTTS_DictSave

Synopsis

BabTtsError BabTTS_DictSave( LPBABTTS lpBabTTS, LPBABTTSDICT lpDict, const char* lpszFileName);

Description

This function saves the content of a dictionary to a file.

Parameters

lpBabTTS : [IN] A BabTTS object to use lpDict : [IN] A valid dictionary handle lpszFileName: [IN] The new name used to save the dictionary. NULL to use the same lpszFileName than at loading.

Return Value

BabTTS_DictIsModified returns an error type: E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS, invalid lpDict


E_BABTTS_NOMEM Error during memory allocation E_BABTTS_NODICT Error when attempting to dump

the dictionary before writing it to file.

E_BABTTS_DICT_WRITE Error when attempting to write the dictionary on disk.


Date : 19/01/07

Page : 60/116


SDK Developer Guide

AcaMul-SDK-6



Please do not forget to call the BabTtsInitDll/BabTtsInitDllEx + BabTTS_Init and BabTTS_Uninit + BabTtsUninitDll functions, respectively at the very beginning and at the end of your source code. Those functions need to be called only once for the whole program.*/

LPBABTTS babtts=NULL; LPBABTTSDICT lpDict=NULL; BabTtsError babError=E_BABTTS_NOERROR; printf("BabTTS_Create\n"); babtts = BabTTS_Create(); printf("BabTTS_Open with Julie22k\n"); babError=BabTTS_Open(babtts,"Julie22k",0); if(babError!=E_BABTTS_NOERROR) { printf("Error while opening voice: %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictLoad\n"); babError=BabTTS_DictLoad(babtts,&lpDict,"user_fr.dic"); if(babError!=E_BABTTS_NOERROR) { printf("Error while loading dictionary: %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictAddWord \"hi\"\n"); babError=BabTTS_DictAddWord(babtts,lpDict,"hi","# a j", BABTTS_WORDTYPE_NOUN); if(babError!=E_BABTTS_NOERROR) { printf("Error while adding word \"hi\": %d\n",babError); BabTTS_Close(babtts); return; } if(BabTTS_DictIsModified(babtts,lpDict)==1) { printf("Dictionary is modified\n"); printf("BabTTS_DictSave\n"); babError=BabTTS_DictSave(babtts, lpDict,NULL); if(babError!=E_BABTTS_NOERROR) printf("Error while saving dictionary: %d\n",babError); } else { printf("Dictionary is NOT modified\n"); } babError=BabTTS_DictUnload(babtts,lpDict); if(babError!=E_BABTTS_NOERROR) { printf("Error while unloading dictionary: %d\n",babError); } BabTTS_Close(babtts);

Date : 19/01/07

Page : 61/116


SDK Developer Guide

AcaMul-SDK-6


6.2.20. BabTTS_DictSaveAll

Synopsis

BabTtsError BabTTS_DictSaveAll(LPBABTTS lpBabTTS);

Description

This function saves the content of all dictionaries using original filenames.

Parameters


Return Value

BabTTS_DictSaveAll returns an error type: E_BABTTS_NOERROR No error E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTIMPLEMENTED The NLP does not support user

dictionaries

Remarks

A memory-only dictionary (open with BabTTS_DictLoad with lpszFileName=NULL) cannot be saved with BabTTS_DictSaveAll. Use BabTTS_DictSave with a filename to save such a dictionary. This function does not return error value if a dictionary cannot be saved. To verify if each dictionary is well saved, use BabTTS_DictSave instead.

Example

See BabTTS_DictEnum

Date : 19/01/07

Page : 62/116


SDK Developer Guide

AcaMul-SDK-6


6.2.21. BabTTS_DictSetDefList

Synopsis

BabTtsError BabTTS_DictSetDefList(LPBABTTS lpBabTTS, const char* lpszFileList);

Description

This function sets the list of user lexicons automatically loaded when using BABTTS_USEDEFDICT.

Parameters

lpBabTTS : [IN] A BabTTS object to use lpszFileList: [IN] The list of user lexicon, each filename must be separated with a ‘;’

Return Value

BabTTS_DictSetDefList returns an error type: E_BABTTS_NOERROR No error E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS or invalid

value in lpszFileList

Remarks This function doesn't work on Mac OS X. You have to use the LexiconEditor.app or modify the BabTts.conf by adding the DefDict="/path/to/your/first/defaultDic1;/path/to/your/second/defaultDic2" attribute in a speechfont tag (for example <Ryan22kM …/>

Date : 19/01/07

Page : 63/116


SDK Developer Guide

AcaMul-SDK-6


6.2.22. BabTTS_DictSetInfo

Synopsis

BabTtsError BabTTS_DictSetInfo(LPBABTTS lpBabTTS, LPBABTTSDICT lpDict, BABTTSDICTINFO Dictinfo);

Description

This function sets information for a loaded dictionary.

Parameters

lpBabTTS : [IN] A BabTTS object to use lpDict : [IN] A previously loaded dictionary handle Dictinfo: [IN] A (user-allocated) structure where info must be copied

Return Value

BabTTS_DictSetInfo returns an error type: E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS, invalid lpDict



Remarks





See BABTTSDICTINFO in chapter "Structures definitions" for more information. Only the following information of BABTTSDICTINFO can be set by the user: szVersion, dwProperties (read and write, only if user has the rights: see BabTTS_DictSetPassword), szDescription and szDiconame. Other information are automatically completed by BabTTS and will not be used with function BabTTS_DictSetInfo..

Date : 19/01/07

Page : 64/116


SDK Developer Guide

AcaMul-SDK-6


Don't forget to initialize your structure before calling BabTTS_DictSetInfo. If you want to change the description but you didn't fill the old diconame, version and properties field, you will erase that information. It is better to call BabTTS_DictGetInfo before using BabTTS_DictSetInfo. If the dictionary is protected by password, you have to call BabTTS_DictSetPassword before changing "read" or "write" property.


Please do not forget to call the BabTtsInitDll/BabTtsInitDllEx + BabTTS_Init and BabTTS_Uninit + BabTtsUninitDll functions, respectively at the very beginning and at the end of your source code. Those functions need to be called only once for the whole program.*/ LPBABTTS babtts=NULL; LPBABTTSDICT lpDict=NULL; BabTtsError babError=E_BABTTS_NOERROR; printf("BabTTS_Create\n"); babtts = BabTTS_Create(); printf("BabTTS_Open with voice Heather22k\n"); babError=BabTTS_Open(babtts,"Heather22k",0); if(babError!=E_BABTTS_NOERROR) { printf("Error while opening voice: %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictLoad\n"); babError=BabTTS_DictLoad(babtts,&lpDict,"user_us.dic"); if(babError!=E_BABTTS_NOERROR) { printf("Error while loading dictionary: %d\n",babError); BabTTS_Close(babtts); return; } BABTTSDICTINFO dictInfo; printf("BabTTS_DictGetInfo\n"); //initialisation of dictInfo; babError=BabTTS_DictGetInfo(babtts,lpDict,&dictInfo); if(babError!=E_BABTTS_NOERROR) { printf("Error in BabTTS_DictGetInfo: %d\n",babError); BabTTS_Close(babtts); return; } printf("\tNum entries: %d\n\tProperties: 0x%x\n\t Num revision: %d\n\tDescription: %s\n\tDiconame: %s\n\tLanguage: %s\n\tVersion:%s\n\ttime_t creation: %d\n\ttime_t last modification:%d\n",dictInfo.dwNumEntries ,dictInfo.dwProperties, dictInfo.dwRevision, dictInfo.szDescription, dictInfo.szDiconame, dictInfo.szLanguage, dictInfo.szVersion, dictInfo.tCreated, dictInfo.tModified); printf("Setting description, version and diconame with

Date : 19/01/07

Page : 65/116


SDK Developer Guide

AcaMul-SDK-6


BabTTS_DictSetInfo\n"); strcpy(dictInfo.szDescription,"my usenglish user dic"); strcpy(dictInfo.szVersion,"ver_1_0"); strcpy(dictInfo.szDiconame,"test userdic"); babError=BabTTS_DictSetInfo(babtts,lpDict,dictInfo); if(babError!=E_BABTTS_NOERROR) { printf("Error in BabTTS_DictSetInfo: %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictSave\n"); babError=BabTTS_DictSave(babtts, lpDict,NULL); if(babError!=E_BABTTS_NOERROR) { printf("Error in BabTTS_DictSave: %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictGetInfo\n"); babError=BabTTS_DictGetInfo(babtts,lpDict,&dictInfo); if(babError!=E_BABTTS_NOERROR) { printf("Error in BabTTS_DictGetInfo: %d\n",babError); BabTTS_Close(babtts); return; } printf("\tNum entries: %d\n\tProperties: 0x%x\n\t

Num revision: %d\n\tDescription: %s\n\tDiconame: %s\n\tLanguage: %s\n\tVersion:%s\n\ttime_t creation: %d\n\ttime_t last modification:%d\n",dictInfo.dwNumEntries ,dictInfo.dwProperties, dictInfo.dwRevision, dictInfo.szDescription, dictInfo.szDiconame, dictInfo.szLanguage, dictInfo.szVersion, dictInfo.tCreated, dictInfo.tModified); printf("BabTTS_DictUnload\n"); babError=BabTTS_DictUnload(babtts, lpDict); if(babError!=E_BABTTS_NOERROR) { printf("Error in BabTTS_DictUnload: %d\n",babError); BabTTS_Close(babtts); return; } BabTTS_Close(babtts);

Date : 19/01/07

Page : 66/116


SDK Developer Guide

AcaMul-SDK-6


6.2.23. BabTTS_DictSetPassword

Synopsis

BabTtsError BabTTS_DictSetPassword(LPBABTTS lpBabTTS, LPBABTTSDICT lpDict, const char* lpszStr1, const char* lpszStr2);

Description

This function sets a new password, verifies a password or changes a password of a loaded user dictionary

Parameters

lpBabTTS : [IN] A BabTTS object to use lpDict : [IN] A previously loaded dictionary handle lpszStr1 and lpszStr2: [IN] 8-char strings, empty strings or NULL (see "Remarks")

Return Value

BabTTS_DictSetPassword returns: W_BABTTS_NOTPROCESSED wrong syntax or bad password:

operation not completed. E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS, invalid

lpDict, lpszStr1 is NULL or strlen(lpszStr2) != 8 (in cas of lpszStr2!= NULL or empty string).


Date : 19/01/07

Page : 67/116


SDK Developer Guide

AcaMul-SDK-6


Remarks

This function has 3 different goals: Set a new password, change (or remove) an existing password, enter a password to be able to change read/write properties. In fact, user cannot change read or write properties of a password protected dictionary. lpszStr1 cannot be NULL if dictionary has no password, set a new password with an empty string in lpszStr1 and a 8-char string into lpszStr2. To unlock a password-protected dictionary, enter the 8-char string into lpszStr1 and leave lpsrStr2 NULL To change the password of a dictionary, enter the old password into lpszStr1 and fill lpszStr2 with the new password. To remove the password of a dictionary, enter the old password into lpszStr1 and fill lpszStr2 with an empty string An 8-char string means 9 character (8 for the password and 1 for \0). Don't forget to save your dictionary to apply the password change. When you unlock a password-protected dictionary, you can change the read/write properties of the dictionary as you want until the unloading of the dictionary. If you change successfully a password, you don't need to unlock the dictionary. The table in the next pages shows the different possibilities for this function and the corresponding returned values.


Please do not forget to call the BabTtsInitDll/BabTtsInitDllEx + BabTTS_Init and BabTTS_Uninit + BabTtsUninitDll functions, respectively at the very beginning and at the end of your source code. Those functions need to be called only once for the whole program.*/ LPBABTTS babtts=NULL; LPBABTTSDICT lpDict=NULL; BabTtsError babError=E_BABTTS_NOERROR; printf("BabTTS_Create\n"); babtts = BabTTS_Create(); printf("BabTTS_Open with voice Heather22k\n"); babError=BabTTS_Open(babtts,"Heather22k",0); if(babError!=E_BABTTS_NOERROR) { printf("Error while opening voice: %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictLoad\n"); babError=BabTTS_DictLoad(babtts,&lpDict,"user_passw_us.dic"); if(babError!=E_BABTTS_NOERROR) { printf("Error while loading dictionary: %d\n",babError); BabTTS_Close(babtts); return; }

Date : 19/01/07

Page : 68/116


SDK Developer Guide

AcaMul-SDK-6


/* If user_passw_us has no password --> setting a new password, removing the read property and save if user_passw_us has a password --> verify the password, setting the read property and enumerate the entry */ BABTTSDICTINFO dictInfo; BabTTS_DictGetInfo(babtts,lpDict,&dictInfo); babError=BabTTS_DictGetInfo(babtts,lpDict,&dictInfo); if(babError!=E_BABTTS_NOERROR) { printf("Error in BabTTS_DictGetInfo: %d\n",babError); BabTTS_Close(babtts); return; } if((dictInfo.dwProperties&BABTTS_DICT_PASSWORD)!=BABTTS_DICT_PASSWORD) { //Dictionary has no password printf("Dictionary has not a password\n"); printf("Removing read property\n"); unsigned long NotRead=BABTTS_DICT_READ^0xFFFF; dictInfo.dwProperties&=NotRead; babError=BabTTS_DictSetInfo(babtts,lpDict,dictInfo); if(babError!=E_BABTTS_NOERROR) { printf("Error in BabTTS_DictSetInfo: %d\n",babError); BabTTS_Close(babtts); return; } //setting a new password: 12345678 babError=BabTTS_DictSetPassword(babtts,lpDict,"","12345678"); if(babError!=E_BABTTS_NOERROR) printf("BabTTS_DictSetPassword: error %d\n",babError); else printf("Password 12345678 correctly set\n"); printf("BabTTS_DictAddWord: \"hello\"\n"); babError=BabTTS_DictAddWord(babtts,lpDict,"hello","bye", BABTTS_WORDTYPE_NOUN); if(babError!=E_BABTTS_NOERROR) { printf("Error while adding word \"hello\": %d\n",babError); BabTTS_Close(babtts); return; } printf("BabTTS_DictSave\n"); babError=BabTTS_DictSave(babtts, lpDict,NULL); if(babError!=E_BABTTS_NOERROR) { printf("Error in BabTTS_DictSave: %d\n",babError); BabTTS_Close(babtts); return; } }

Date : 19/01/07

Page : 69/116


SDK Developer Guide

AcaMul-SDK-6


else { //Dictionary has a password printf("Dictionary has already a password\n"); printf("Password verification\n"); babError=BabTTS_DictSetPassword(babtts,lpDict, "12345678",NULL); if(babError!=E_BABTTS_NOERROR) { if(babError==W_BABTTS_NOTPROCESSED) printf("\"12345678\" is not the correct password for this dictionary ... aborting\n"); else printf("BabTTS_DictSetPassword: error %d\n",babError); BabTTS_Close(babtts); return; } else printf("Password 12345678 correctly verified\n"); printf("Setting read property\n"); dictInfo.dwProperties|=BABTTS_DICT_READ; babError=BabTTS_DictSetInfo(babtts,lpDict,dictInfo); if(babError!=E_BABTTS_NOERROR) { printf("Error in BabTTS_DictSetInfo: %d\n",babError); BabTTS_Close(babtts); return; } long numentries=BabTTS_DictGetNumEntries(babtts,lpDict); printf("Number of entries in dictionary: %d\n",numentries); for(int i=0;i<numentries;i++) { char lpszEntry[512]; unsigned long size=512; printf("BabTTS_DictGetEntry on entry %d\n",i); babError=BabTTS_DictGetEntry(babtts,lpDict,i, lpszEntry,&size); if(babError!=E_BABTTS_NOERROR) { printf("Error in BabTTS_DictGetEntry: %d\n",babError); BabTTS_Close(babtts); return; } printf("Entry: %s\n",lpszEntry); } } babError=BabTTS_DictUnload(babtts, lpDict); if(babError!=E_BABTTS_NOERROR) { printf("Error in BabTTS_DictUnload: %d\n",babError); BabTTS_Close(babtts); return; } BabTTS_Close(babtts); babtts=NULL;

Date : 19/01/07

Page : 70/116


SDK Developer Guide

AcaMul-SDK-6


Table for the function BabTTS_DictSetPassword(LPBABTTS lpBabTTS, LPBABTTSDICT lpDict, LPCSTR lpszStr1, LPCSTR lpszStr2);)

Comments dico password lpszStr1 lpszStr2 returned value result R/W propertieslpszStr1 cannot never be NULL

,,, NULL ,,, E_BABTTS_NOTVALIDPARAMETER nothing change ,,,Dictionary without password:

setting a passwordcorrect use (lpszStr1 is empty string) "" "" 12345678 E_BABTTS_NOERROR password 12345678 set not locked

strlen(lpszStr2)!=8 "" "" 12345 E_BABTTS_NOTVALIDPARAMETER password not set not lockedlpszStr2 is NULL "" "" NULL E_BABTTS_NOTVALIDPARAMETER password not set not locked

Dictionary with password:verifying password to change r/w properties

correct use 12345678 12345678 NULL E_BABTTS_NOERROR password verified unlockedbad password 12345678 abcdefgh NULL W_BABTTS_NOTPROCESSED password not verified locked

strlen(lpszStr1)!=8 12345678 12345 NULL E_BABTTS_NOTVALIDPARAMETER password not verified lockedDictionary with password:

changing the passwordcorrect use 12345678 12345678 abcdefgh E_BABTTS_NOERROR password changed to abcdefgh unlocked

bad password 12345678 mnopqrst abcdefgh W_BABTTS_NOTPROCESSED password not changed lockedgood password but strlen(lpszStr2)!=8 12345678 12345678 abcde E_BABTTS_NOTVALIDPARAMETER password not changed unlocked

strlen(lpszStr1)!=8 12345678 12345 abcdefgh E_BABTTS_NOTVALIDPARAMETER password not changed lockedDictionary with password:

removing the passwordcorrect use (lpszStr2 is empty string) 12345678 12345678 "" E_BABTTS_NOERROR password removed unlocked

bad password 12345678 abcdefgh "" W_BABTTS_NOTPROCESSED password not removed lockedstrlen(lpszStr1)!=8 12345678 12345 "" E_BABTTS_NOTVALIDPARAMETER password not removed locked

Date : 8/29/05

Page : 71/116

BabTTS

Software Development Kit

BabTTS-SDK


6.2.24. BabTTS_DictUnload

Synopsis

BabTtsError BabTTS_DictUnload( LPBABTTS lpBabTTS, LPBABTTSDICT lpDict);

Description

This function unloads a dictionary unconditionally from memory.

Parameters

lpBabTTS : [IN] A BabTTS object to use. lpDict: [IN] A valid dictionary handle.

Return Value

BabTTS_DictUnload returns an error type: E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS, invalid lpDict



Remarks

This function doesn't save a modified dictionary. If you have modified a dictionary, use BabTTS_DictSave before calling BabTTS_DictUnload.

Example

See BabTTS_DictLoad

Date : 19/01/07

Page : 72/116


SDK Developer Guide

AcaMul-SDK-6


6.2.25. BabTTS_DictUnloadAll

Synopsis

BabTtsError BabTTS_DictUnloadAll(LPBABTTS lpBabTTS);

Description

This function unloads all dictionaries from memory.

Parameters


Return Value

BabTTS_DictEnum returns an error type: E_BABTTS_NOERROR No error E_BABTTS_NOTVALIDPARAMETER Invalid lpBabTTS E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTIMPLEMENTED The NLP does not support user

dictionaries

Remarks

This function doesn't save a modified dictionary. If you have modified a dictionary, use BabTTS_DictSaveAll before calling BabTTS_DictUnloadAll.

Example

See BabTTS_DictEnum

Date : 19/01/07

Page : 73/116


SDK Developer Guide

AcaMul-SDK-6


6.2.26. BabTTS_EnumVoices

Synopsis

BabTtsError BabTTS_EnumVoices(unsigned long dwIndex, char szVoice[50]);

Description

This function returns with the name of the voice number dwIndex.

Parameters

dwIndex [IN] : zero index based of the voice you want the name szVoice [OUT] : Filled with the name of the voice

Return Value

E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER dwIndex is out of the number of

installed voices

Example

See BabTTS_GetVoiceInfo

Date : 19/01/07

Page : 74/116


SDK Developer Guide

AcaMul-SDK-6


6.2.27. BabTTS_GetCallback

Synopsis

BabTtsError BabTTS_GetCallback(LPBABTTS lpBabTTS, void** lppCallback, unsigned long* lpdwCallbackType);

Description

Retrieve the current callback parameters.

Parameters

lpBabTTS [IN] : The LPBABTTS object to use. lppCallback [OUT] : Address of a callback (according to lpdwCallbackType, see below) lpdwCallbackType [OUT] : The actual type of callback

Return Value

E_BABTTS_NOERROR The callback has been correctly set



Remarks

• See BabTTS_SetCallback and Using callbacks:

Date : 19/01/07

Page : 75/116


SDK Developer Guide

AcaMul-SDK-6


6.2.28. BabTTS_GetFilterPreset

Synopsis

BabTtsError BabTTS_GetFilterPreset(LPBABTTS lpBabTTS, char szPreset[50]);

Description

Return the actual used preset for the equalizer.

Parameters

lpBabTTS: [IN] The BabTTS object to use szPreset: [OUT] Null terminating string filled with the name of the actual preset. Empty string if no preset is actually used.

Return Value

E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER lpBabTTS is not valid

Date : 19/01/07

Page : 76/116


SDK Developer Guide

AcaMul-SDK-6


6.2.29. BabTTS_GetInstanceInfo

Synopsis

BabTtsError BabTTS_GetInstanceInfo(LPBABTTS lpBabTTS, BABTTSINFO* lpInfo);

Description

Gives information about an instance

Parameters

lpBabTTS: [IN] The BabTTS object to use lpInfo : [OUT] Structure filled with information

Return Value




BABTTSINFO voiceInfo; BabTtsError error; printf("BabTTS_Create\n"); babtts = BabTTS_Create(); printf("BabTTS_Open with Julie22k\n"); error = BabTTS_Open(babtts,"Julie22k",BABTTS_USEDEFDICT); if(error != E_BABTTS_NOERROR) { printf("Error while opening voice: %d\n",error); } else { memset(&voiceInfo,0,sizeof(BABTTSINFO)); printf("BabTTS_GetInstanceInfo\n"); error=BabTTS_GetInstanceInfo(babtts,&voiceInfo); if(error!=E_BABTTS_NOERROR) { printf("BabTTS_GetVoiceInfo error: %d\n",error); return; } printf("Voice: %s Speaker: %s Language: %s Version:%s\n",\ voiceInfo.szName,voiceInfo.szSpeaker, voiceInfo.szLanguage, voiceInfo.szVersion); }

Date : 19/01/07

Page : 77/116


SDK Developer Guide

AcaMul-SDK-6


printf("BabTTS_Close\n"); BabTTS_Close(babtts);

Date : 19/01/07

Page : 78/116


SDK Developer Guide

AcaMul-SDK-6


6.2.30. BabTTS_GetNumVoices

Synopsis

long WINAPI BabTTS_GetNumVoices(void);

Description

Returns the number of installed voices

Parameters

none

Return Value

The number of voices installed in the system

Example

See BabTTS_GetVoiceInfo

Date : 19/01/07

Page : 79/116


SDK Developer Guide

AcaMul-SDK-6


6.2.31. BabTTS_GetSettings

Synopsis

BabTtsError BabTTS_GetSettings(LPBABTTS lpBabTTS, BabTtsParam ParamType, unsigned long* pdwParamValue);

Description

Retrieves the value of the setting given as parameter

Parameters

lpBabTTS: [IN] The BabTTS object to use ParamType : [IN] indicates which parameter to retrieve pdwParamValue [OUT] Filled with actual value of the parameter

Return Value

E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER One (or more) parameter is not

valid

Remarks

See Changing Settings for information about possible parameters

Date : 19/01/07

Page : 80/116


SDK Developer Guide

AcaMul-SDK-6


6.2.32. BabTTS_GetVoiceInfo

Synopsis

BabTtsError BabTTS_GetVoiceInfo(const char* lpszVoice, BABTTSINFO* lpInfo);

Description

Gives useful information about a voice

Parameters

lpszVoice : [IN] The name of the voice lpInfo [OUT] Structure filled with information

Return Value

E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER The voice doesn’t exist

Date : 19/01/07

Page : 81/116


SDK Developer Guide

AcaMul-SDK-6



Please do not forget to call the BabTtsInitDll/BabTtsInitDllEx + BabTTS_Init and BabTTS_Uninit + BabTtsUninitDll functions, respectively at the very beginning and at the end of your source code. Those functions need to be called only once for the whole program.*/ BabTtsError babError=E_BABTTS_NOERROR;

BABTTSINFO voiceInfo; long tempnumber=BabTTS_GetNumVoices(); printf("Number of voice: %d\n",tempnumber); for(int j=0;j<tempnumber;j++) { char szVoice[50]; szVoice[0]='\0'; memset(&voiceInfo,0,sizeof(BABTTSINFO)); babError=BabTTS_EnumVoices(j,szVoice); if(babError!=E_BABTTS_NOERROR) { printf("BabTTS_EnumVoices error: %d\n",babError); return; } babError=BabTTS_GetVoiceInfo(szVoice,&voiceInfo); if(babError!=E_BABTTS_NOERROR) { printf("BabTTS_GetVoiceInfo error: %d\n",babError); return; } printf("Voice: %s Speaker: %s Language: %s Version: %s\n",voiceInfo.szName,voiceInfo.szSpeaker, voiceInfo.szLanguage, voiceInfo.szVersion); }

Date : 19/01/07

Page : 82/116


SDK Developer Guide

AcaMul-SDK-6


6.2.33. BabTTS_Init

Synopsis

bool BabTTS_Init();

Description

BabTTS_Init initializes the library. Starting from BabTTS version 1.3, this function MUST be called before any other function.

Return Value

BabTTS_Init returns true if correctly initialized.

Date : 19/01/07

Page : 83/116


SDK Developer Guide

AcaMul-SDK-6


6.2.34. BabTtsInitDll

Synopsis

HMODULE BabTtsInitDll();

Description

BabTtsInitDll loads the library. The AcaTts.dll/libacatts.so/libacatts.dylib is expected to be in the executable search path or the current (working) directory. See 2.2.1.2 for information about how to integrate the library in your application

Return Value

BabTtsInitDll returns the handle of the AcaTts.dll/ libacatts.so/ libacatts.dylib library or NULL if failed.

Remarks

This function has the responsibility to load the library and to retrieve the symbols of all functions. In case of failure (NULL return value), a call to a function of the API will cause an access violation exception. It is the responsibility of the developer to be sure about the availability of acatts.dll.

To avoid working directory problems (For example with Mac OS X Application Bundle scheme where the real executable is located in MyApp.app/Contents/MacOS) it is recommended to use the function BabTtsInitDllEx() instead of BabTtsInitDll().

Date : 19/01/07

Page : 84/116


SDK Developer Guide

AcaMul-SDK-6


6.2.35. BabTtsInitDllEx

Synopsis

HMODULE BabTtsInitDllEx(const char* lpszAcaTtsPath);

Description

BabTtsInitDllEx loads the library given the exact (absolute) location of the AcaTts.dll/libacatts.so/libacatts.dylib. See 2.2.1.2 for information about how to integrate the library in your application

Return Value

BabTtsInitDll returns the handle of the AcaTts.dll /libacatts.so/ libacatts.dylib library or NULL if failed.

Parameters

lpszAcaTtsPath: [IN] The location of AcaTts.dll/libacatts.so/libacatts.dylib including the filename and extension. i.e. “c:\program files\acapela group\acapela multimedia\acatts.dll” for windows, “/Applications/AcapelaMultimedia/libacatts.dylib for Mac OS X …

Remarks

This function has the responsibility to load the library and to retrieve the symbols of all functions. In case of failure (NULL return value), a call to a function of the API will cause an access violation exception. . It is the responsibility of the application to be sure about the availability of acatts.dll in the provided path.

To avoid working directory problems (For example with Mac OS X Application Bundle scheme where the real executable is located in MyApp.app/Contents/MacOS) it is recommended to use the function BabTtsInitDllEx() instead of BabTtsInitDll().

Date : 19/01/07

Page : 85/116


SDK Developer Guide

AcaMul-SDK-6


6.2.36. BabTTS_InsertText

Synopsis

BabTtsError BabTTS_InsertText ( LPBABTTS lpBabTTS, const char* lpszText, unsigned long dwTextFlag );

Description

BabTTS_InsertText adds the text given as parameter to the Processing Queue. This Queue stores all the text sent to the synthesizer but not yet processed by the function BabTTS_ReadBuffer.

Parameters

lpBabTTS : [IN] The BabTTS object to use lpText : [IN] The text to process (can be a buffer or a file location) dwTextFlag : [IN] A process mask indicating how the function must interpret the input text : BABTTS_TEXT lpText is a buffer

stored in memory (either Char* or

Default: BABTTS_TEXT

wchar*) BABTTS_FILE lpText is the

location (relative or absolute) of a file containing the text to be

processed BABTTS_TXT_ANSI The encoding of

the text is windows standard

Default: BABTTS_TXT_ANSI

ansi. (8bits)

BABTTS_TXT_UC2 The encoding of the text is

UNICODE 16 bits BABTTS_TXT_MACROMAN

The encoding of the text is Apple

Mac Roman (8 bits)

BABTTS_READ_DEFAULT Use the default reading mode of

Default: BABTTS_READ_DEFAULT

the voice BABTTS_READ_TEXT Use the normal,

text based,

reading mode. BABTTS_READ_WORD Read words

separated by

pauses. BABTTS_READ_LETTER Read word letter

Date : 19/01/07

Page : 86/116


SDK Developer Guide

AcaMul-SDK-6


by letter BABTTS_TAG_NO Standard text, Default:

without tag BABTTS_TAG_NO BABTTS_TAG_SAPI The text is tagged

using the SAPI 4

tagging standard

Return Value

BabTTS_InsertText returns an error: E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error E_BABTTS_NOTVALIDPARAMETER One (or more) parameter is not

valid or there is nothing to be processed (the text is empty)

Remark

When using BABTTS_TAG_SAPI, a single ‘\’ is considered as the beginning (end) of a Sapi tag. If you want to use it, you must use ‘\\’ : i.e. : “c:\\program file\\”.

Unicode (BABTTS_TXT_UC2) is only available in windows.

You can use either BABTTS_TXT_ANSI or BABTTS_TXT_MACROMAN, depending of your application. Other codage are not available. If your text is Unicode, convert it to Mac Roman or Ansi (Windows Latin 1 charset) by using CreateTextEncoding, TECCreateConverter and TECConvertText from the Text Encoding Conversion Manager (CoreServices framework)

Example

See BabTTS_ReadBuffer

Date : 19/01/07

Page : 87/116


SDK Developer Guide

AcaMul-SDK-6


6.2.37. BabTTS_Open

Synopsis

BabTtsError BabTTS_Open(LPBABTTS lpBabTTS, const char* lpszVoice, unsigned long dwOpenFlag )

Description

This function fills a voice handle with the data corresponding to the requested voice.

Parameters

lpBabTTS [IN] : The object to fill. lpszVoice [IN] : The Voice Name to open (i.e. Julie8k, Julie16k…) dwOpenFlag [IN] : A mask that specifies the desired opening modes for the voice.

Return Value

E_BABTTS_NOERROR Normal initialization E_BABTTS_NOTVALIDPARAMETER The lpBabTTS handle is

not valid E_BABTTS_NOTVALIDLICENSE you don’t have a valid

licence key for this voice


Remarks

• Voice installed on the system can be found using the enumerator’s functions.

• As the same voice (speaker) can be present in several sampling

rate, the sampling rate is appended to the name of the voice :

o Julie22k is the multimedia HQ version (22kHz) of the French

voice Julie. o Julie22kM is the Multimedia HQM version (22kHz medium

size) of the French voice Julie o Julie8k is the telephony version (8kHz) of the French voice

Julie.

Date : 19/01/07

Page : 88/116


SDK Developer Guide

AcaMul-SDK-6


• dwOpenFlag can be:

BABTTS_USEDEFDICT Loads a list of default

user dictionaries. See BabTTS_DictSetDefList and BabTTS_DictGetDefList for more information.

Default:none


Please do not forget to call the BabTtsInitDll/BabTtsInitDllEx + BabTTS_Init and BabTTS_Uninit + BabTtsUninitDll functions, respectively at the very beginning and at the end of your source code. Those functions need to be called only once for the whole program.*/ LPBABTTS babtts=NULL; BabTtsError error; printf("BabTTS_Create\n"); babtts = BabTTS_Create(); printf("BabTTS_Open with Julie22k\n"); error = BabTTS_Open(babtts,"Julie22k",BABTTS_USEDEFDICT); if(error != E_BABTTS_NOERROR) { printf("Error while opening voice: %d\n",error); } else { //some work with babtts… //… // Then, we delete it } printf("BabTTS_Close\n"); BabTTS_Close(babtts);

Date : 19/01/07

Page : 89/116


SDK Developer Guide

AcaMul-SDK-6


6.2.38. BabTTS_Pause

Synopsis

BabTtsError BabTTS_Pause(LPBABTTS lpBabTTS);

Description

BabTTS_Pause forces TTS to pause while speaking using BabTTS_Speak in BABTTS_ASYNC mode

Parameters

lpBabTTS : [IN] The BabTTS object to use

Return Value

BabTTS_Pause returns an error: E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error

Date : 19/01/07

Page : 90/116


SDK Developer Guide

AcaMul-SDK-6


6.2.39. BabTTS_PhoGetDuration

Synopsis

BabTtsError BabTTS_PhoGetDuration(LPBABTTS lpBabTTS, unsigned long dwPhoneme, unsigned long* lpdwDuration);

Description

Retrieve the duration of a phoneme

Parameters

lpBabTTS : [IN] The BabTTS object to use dwPhoneme : [IN] Handle of the played phoneme, correspond to the side information (dwMsgInfo) you receive with the BABTTS_MSG_PHONE message in the callback lpdwDuration : [out] Filled with the duration (in ms) of the phoneme

Return Value

E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error

Remark

dwPhoneme is only valid inside the callback, using it outside the callback scope can produce unpredictable results

Date : 19/01/07

Page : 91/116


SDK Developer Guide

AcaMul-SDK-6


6.2.40. BabTTS_PhoGetMouth

Synopsis

BabTtsError BabTTS_PhoGetMouth(LPBABTTS lpBabTTS, unsigned long dwPhoneme, BABTTSMOUTH* lpMouth);

Description

Retrieve the mouth information of a phoneme (as defined in MS-SAPI 4.0a)

Parameters

lpBabTTS : [IN] The BabTTS object to use dwPhoneme : [IN] Handle of the played phoneme, correspond to the side information (dwMsgInfo) you receive with the BABTTS_MSG_PHONE message in the callback lpMouth : [out] Filled with the mouth information of the phoneme

Return Value

E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error

Remark

dwPhoneme is only valid inside the callback, using it outside the callback scope can produce unpredictable results

Date : 19/01/07

Page : 92/116


SDK Developer Guide

AcaMul-SDK-6


6.2.41. BabTTS_ReadBuffer

Synopsis

BabTtsError BabTTS_ReadBuffer(LPBABTTS lpBabTTS, void* lpBuffer, unsigned long dwBufSize, unsigned long* lpdwGen);

Description

BabTTS_ReadBuffer processes the text stored in the Queue (with BabTTS_InsertText) and produces speech samples in the buffer provided to the function. It asks the synthesizer for generating dwBufSize samples. When all the text has been retrieved, BabTTS_ReadBuffer returns W_BABTTS_NOMOREDATA.

Parameters

lpBabTTS: [IN] The BabTTS object to use lpBuffer : [OUT] An user-allocated buffer of size greater than dwBufSize*sizeof(sample) bytes. dwBufSize :[IN] the size (in samples) of lpBuffer (the actual size in byte depends of the selected coding scheme. lpdwGen : [OUT] filled with the number of generated samples

Return Value


valid W_BABTTS_NOMOREDATA All data have been generated


Please do not forget to call the BabTtsInitDll/BabTtsInitDllEx + BabTTS_Init and BabTTS_Uninit + BabTtsUninitDll functions, respectively at the very beginning and at the end of your source code. Those functions need to be called only once for the whole program.*/

LPBABTTS babtts=NULL; BabTtsError error; char lpszMyText[]="Ceci est un test."; FILE* hOut=fopen("test.pcm","wb"); printf("BabTTS_Create\n"); babtts = BabTTS_Create();

Date : 19/01/07

Page : 93/116


SDK Developer Guide

AcaMul-SDK-6


printf("BabTTS_Open\n"); error = BabTTS_Open(babtts,"Julie22k",0); if(error != E_BABTTS_NOERROR) { printf("Error while opening voice: %d\n",error); BabTTS_Close(babtts); return; } printf("BabTTS_InsertText\n"); error=BabTTS_InsertText(babtts,lpszMyText,BABTTS_TEXT|BABTTS_TXT_ANSI); if(error!=E_BABTTS_NOERROR) { printf("Error BabTTS_InsertText: %d\n",error); BabTTS_Close(babtts); fclose(hOut); return; } //read samples (by default 16 bits PCM we need "short") //if BABTTS_PARAM_WAVEFORMAT refers to a 8 bits format //use "char" (See BabTTS_SetSettings) short buffer[1024]; unsigned long size; printf("BabTTS_ReadBuffer\n"); error=BabTTS_ReadBuffer(babtts,buffer,1024,&size); while(W_BABTTS_NOMOREDATA!=error) { if(error<0) { printf("Error BabTTS_ReadBuffer: %d\n",error); BabTTS_Close(babtts); fclose(hOut); return; } printf("Writing %d samples to file\n",size); fwrite(buffer,sizeof(short),size,hOut); printf("BabTTS_ReadBuffer\n"); error=BabTTS_ReadBuffer(babtts,buffer,1024,&size); } printf("Writing %d bytes to file\n",size); fwrite(buffer,sizeof(short),size,hOut); fclose (hOut); BabTTS_Close(babtts);

Date : 19/01/07

Page : 94/116


SDK Developer Guide

AcaMul-SDK-6


6.2.42. BabTTS_Reset

Synopsis

BabTtsError BabTTS_Reset(LPBABTTS lpBabTTS);

Description

This function resets the internal state of the object and returns to an IDLE state. Useful when you want to stop the engine after a call to BabTTS_Speak function in asynchronous mode.

Parameters

lpBabTTS : [IN] The BabTTS object to reset

Return Value

BabTTS_Reset returns an error: E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error

Date : 19/01/07

Page : 95/116


SDK Developer Guide

AcaMul-SDK-6


6.2.43. BabTTS_Resume

Synopsis

BabTtsError BabTTS_Resume(LPBABTTS lpBabTTS);

Description

BabTTS_Resume asks the TTS to resume the processing of the text where it was previously paused.

Parameters

lpBabTTS : [IN] The BabTTS object to use

Return Value

BabTTS_Resume returns an error: E_BABTTS_NOERROR No error E_BABTTS_PROCESSERROR Unexpected error

Date : 19/01/07

Page : 96/116


SDK Developer Guide

AcaMul-SDK-6


6.2.44. BabTTS_SetCallback

Synopsis

BabTtsError BabTTS_SetCallback(LPBABTTS lpBabTTS, void* lpCallback, unsigned long dwCallbackType);

Description

Tell a TTS object to use a specific callback mechanism.

Parameters

lpBabTTS [IN] : The LPBABTTS object to use. lpCallback [IN]: Address of a callback (according to dwCallbackType, see below) dwCallbackType [IN] : The actual type of callback

Return Value

BabTTS_Close returns:

The callback has been correctly set

E_BABTTS_NOERROR



Remarks

• Valid values for dwCallbackType are: BABTTS_CB_NONE Reset the callback,

no messages are sent lpCallback is not used

to user BABTTS_CB_WINDOW Use standard windows lpCallback is a HWND

messages handle

BABTTS_CB_FUNCTION Use a specific lpCallback is a callback function BabTTSProc function

• Events are used only when working with a sound card

Date : 19/01/07

Page : 97/116


SDK Developer Guide

AcaMul-SDK-6


• For BABTTS_CB_WINDOW, the messages are sent using a standard window message mechanism. In order to retrieve the different events, the window must provide a WndProc function with the traditional window prototype:

BOOL CALLBACK WndProc( HWND hWnd, UINT Msg, WPARAM dwCallbackInstance, LPARAM dwMsgInfo); In this case, the meaning of each parameter is as follow : Msg : the message sent by the object dwCallbackInstance: the Callback instance(default : lpBabTTS)

designed by user dwMsgInfo: the Message specific information (see Event)

• For BAB_TTS_FUNCTION, the callback function must have the BabTTSProc prototype

BabTtsError WINAPI BabTTSProc (LPBABTTS lpBabTTS, unsigned long Msg, unsigned long dwCallbackInstance, unsigned long dwMsgInfo);

• By default, the dwCallbackInstance (or wParam) is equals to the LPBABTTS object used. You can change its value by changing the BABTTS_PARAM_CBINSTANCE parameter.

Date : 19/01/07

Page : 98/116


SDK Developer Guide

AcaMul-SDK-6


6.2.45. BabTTS_SetFilterPreset

Synopsis

BabTtsError BabTTS_SetFilterPreset(LPBABTTS lpBabTTS, const char* lpszPreset);

Description

Use the equalizer with the requested Preset

Parameters

lpBabTTS: [IN] The BabTTS object to use lpszPreset: [IN] Null terminating string filled with the name of the preset. NULL string if you want to disable the equalizer.

Return Value


Remarks

Setting a valid Preset is similar to enable the filter with BABTTS_PARAM_USEFILTER. This function is not available on Mac OS X

Date : 19/01/07

Page : 99/116


SDK Developer Guide

AcaMul-SDK-6


6.2.46. BabTTS_SetSettings

Synopsis

BabTtsError WINAPI BabTTS_SetSettings(LPBABTTS lpBabTTS, BabTtsParam ParamType, unsigned long dwParamValue)

Description

BabTTS_SetSettings allows users to change some parameters (i.e. volume, instance callback,…)

Parameters

lpBabTTS: [IN] The BabTTS object to use ParamType : [IN] indicates which parameter to change dwParamValue [IN] the value to give to the parameter

Return Value


valid

Remarks

See Changing Settings (Section 5 of this document) for information about possible parameters

Date : 19/01/07

Page : 100/116


SDK Developer Guide

AcaMul-SDK-6


6.2.47. BabTTS_Speak

Synopsis BabTtsError BabTTS_Speak

(LPBABTTS lpBabTTS, void* lpText, unsigned long dwSpeakFlag);

Description

BabTTS_Speak process the text given as parameter and sends the generated samples to the default sound card of the system (For multimedia purposes).

Parameters

lpBabTTS: [IN] The BabTTS object to use lpText : [IN] The text to pronounce (can be a buffer or a file location) dwSpeakFlag : [IN] A process mask indicating how the function must interpret the input text : BABTTS_SYNC

Synchronous mode: Function returns only once the whole text has been spoken.

Default: BABTTS_SYNC

BABTTS_ASYNC Asynchronous mode: Function returns directly, use events for synchronizing

BABTTS_TEXT lpText is a buffer stored in memory (either Char* or wchar*)


BABTTS_FILE lpText is the location (relative or absolute) of a file containing the text to be processed

Date : 19/01/07

Page : 101/116


SDK Developer Guide

AcaMul-SDK-6


BABTTS_TXT_ANSI The encoding of the

text is windows standard ansi.


(8bits)

BABTTS_TXT_UC2 The encoding of the text is UNICODE 16

bits BABTTS_TXT_MACROMAN

The encoding of the text is Apple Mac

Roman (8 bits)

BABTTS_READ_DEFAULT Default: Use the default BABTTS_READ_DEFAULT

reading mode of the voice

BABTTS_READ_TEXT Use the normal, text based, reading mode.

BABTTS_READ_WORD Read words separated by pauses.

BABTTS_READ_LETTER Read word letter by letter

BABTTS_TAG_NO Standard text,

Default: BABTTS_TAG_NO

without tag BABTTS_TAG_SAPI

The text is tagged using the SAPI 4

tagging standard

Return Value

BabTTS_Speak returns an error: E_BABTTS_NOERROR No error E_BABTTS_WAVEOUTNOTFREE Cannot open the sound card for

output E_BABTTS_NOTVALIDPARAMETER One (or more parameter) is not



Remark

When using BABTTS_TAG_SAPI, a single ‘\’ is considered as the beginning (end) of a Sapi tag. If you want to use it, you must use ‘\\’ : i.e. : “c:\\program file\\”

Date : 19/01/07

Page : 102/116


SDK Developer Guide

AcaMul-SDK-6






BabTtsError error; char lpszMyText[]="Ceci est un test."; printf("BabTTS_Create\n"); babtts = BabTTS_Create(); printf("BabTTS_Open with Julie22k\n"); error = BabTTS_Open(babtts,"Julie22k",BABTTS_USEDEFDICT); if(error != E_BABTTS_NOERROR) { printf("Error while opening voice: %d\n",error); } else { printf("BabTTS_Speak\n"); error=BabTTS_Speak(babtts,lpszMyText, BABTTS_TEXT|BABTTS_SYNC|BABTTS_TXT_ANSI); if(error!=E_BABTTS_NOERROR) { printf("Error BabTTS_Speak: %d\n",error); } } printf("BabTTS_Close\n"); BabTTS_Close(babtts); babtts=NULL;

Date : 19/01/07

Page : 103/116


SDK Developer Guide

AcaMul-SDK-6


6.2.48. BabTTS_Uninit

Synopsis

bool BabTTS_Uninit();

Description

BabTTS_Uninit frees all resources allocated by the babtts library. Calling another BabTTS functions after can produce unpredictable errors.

Return Value

BabTTS_Uninit returns true if correctly uninitialized.

Date : 19/01/07

Page : 104/116


SDK Developer Guide

AcaMul-SDK-6


6.2.49. BabTtsUninitDll

Synopsis

bool BabTtsUninitDll();

Description

BabTtsUninitDll unloads the AcaTts.dll library Calling another BabTTS functions after can produce unpredictable errors.

Return Value

BabTtsUninitDll always returns 0.

Date : 19/01/07

Page : 105/116


SDK Developer Guide

AcaMul-SDK-6


6.2.50. BabTTS_Write

Synopsis BabTtsError BabTTS_Write

(LPBABTTS lpBabTTS, void* lpText, const char* lpszFileName, unsigned long dwWriteFlag);

Description

BabTTS_Write converts an input text to a sound file according to input options.

Parameters

lpBabTTS: [IN] The BabTTS object to use lpText : [IN] The text to process (can be a buffer or a file location) lpszFileName : [IN] : Name of the output file (Must be absolute) dwWriteFlag : [IN] A process mask indicating how the function must interpret the input text and how the output must be handled (format)

Date : 19/01/07

Page : 106/116


SDK Developer Guide

AcaMul-SDK-6


BABTTS_TEXT lpText is a buffer

stored in memory (either Char* or


wchar*) BABTTS_FILE lpText is the

location (relative or absolute) of a file containing the

text to be processed BABTTS_TXT_ANSI The encoding of the

text is windows standard ansi.


(8bits)

BABTTS_TXT_UC2 The encoding of the text is UNICODE 16

bits BABTTS_TXT_MACROMAN

The encoding of the text is Apple Mac

Roman (8 bits)

BABTTS_READ_DEFAULT Use the default reading mode of the

Default: BABTTS_READ_DEFAULT

voice BABTTS_READ_TEXT Use the normal, text

based, reading mode. BABTTS_READ_WORD Read words separated

by pauses. BABTTS_READ_LETTER Read word letter by

letter BABTTS_TAG_NO Standard text, Default:

without tag BABTTS_TAG_NO BABTTS_TAG_SAPI The text is tagged

using the SAPI 4

tagging standard BABTTS_FILE_RAW The requested output

format for the file is raw data (without

Default: BABTTS_FILE_RAW

any header) BABTTS_FILE_WAV The requested output

format for the file is wav (windows)

file

Date : 19/01/07

Page : 107/116


SDK Developer Guide

AcaMul-SDK-6


BABTTS_FILE_AU The requested output

format for the file

is au (sun) file BABTTS_FILE_AIFF The requested output

format for the file

is aiff (apple) file

NB: BABTTS_FILE_AIFF only available on Mac OS X.

Return Value

BabTTS_Write returns an error: E_BABTTS_NOERROR No error E_BABTTS_WAVEOUTNOTFREE Cannot open the sound card for

output E_BABTTS_NOTVALIDPARAMETER One (or more parameter) is not


Remarks

• When using BABTTS_TAG_SAPI, a single ‘\’ is considered as the beginning (end) of a Sapi tag. If you want to use it, you must use ‘\\’ : i.e. : “c:\\program file\\”

• The format (coding scheme) of the output is dependant of the

parameter BABTTS_PARAM_WAVEFORMAT (voir Coding Scheme). All combinations are not possible :

File Type Allowed coding schemes • BABTTS_FORMAT_PCM8 BABTTS_FILE_RA

W • BABTTS_FORMAT_PCM • BABTTS_FORMAT_ALAW • BABTTS_FORMAT_MULAW • BABTTS_FORMAT_OKI_ADPCM

• BABTTS_FORMAT_PCM8 BABTTS_FILE_WAV • BABTTS_FORMAT_PCM • BABTTS_FORMAT_ALAW • BABTTS_FORMAT_MULAW • BABTTS_FORMAT_PCM8 BABTTS_FILE_AU • BABTTS_FORMAT_PCM • BABTTS_FORMAT_ALAW • BABTTS_FORMAT_MULAW • BABTTS_FORMAT_PCM BABTTS_FILE_AIFF

Date : 19/01/07

Page : 108/116


SDK Developer Guide

AcaMul-SDK-6






BabTtsError error; char lpszMyText[]="Ceci est un test."; printf("BabTTS_Create\n"); babtts = BabTTS_Create(); printf("BabTTS_Open with Julie22k\n"); error = BabTTS_Open(babtts,"Julie22k",BABTTS_USEDEFDICT); if(error != E_BABTTS_NOERROR) { printf("Error while opening voice: %d\n",error); } else { printf("BabTTS_Write\n"); error=BabTTS_Write(babtts,lpszMyText,"output.wav", BABTTS_FILE|BABTTS_FILE_WAV|BABTTS_TXT_ANSI); if(error!=E_BABTTS_NOERROR) { printf("Error BabTTS_Write: %d\n",error); } } printf("BabTTS_Close\n"); BabTTS_Close(babtts); babtts=NULL;

Date : 19/01/07

Page : 109/116


SDK Developer Guide

AcaMul-SDK-6


6.3. Structure definitions

6.3.1. BABTTSDICTINFO

This structure gives information about a loaded user dictionary

szFilename The corresponding filename szLanguage The language szVersion User defined version dwNumEntries The number of entries dwRevision The revision of the dictionary (number of

"save" made by user) tcreated Creation date tmodified Last modification date dwProperties Associated properties of the dictionary

can be a combination of : BABTTS_DICT_ENABLED (0x01): The dictionary is enabled BABTTS_DICT_READ (0x02): The dictionary is readable BABTTS_DICT_WRITE (0x04): The dictionary is writable BABTTS_DICT_PASSWORD (0x10): The dictionary is protected by password. BABTTS_DICT_MODIFIED (0x20): The dictionary has been modified since the last save/load

szDescription User defined description szDiconame Name for the dictionary

see BabTTS_DictGetInfo, BabTTS_GetInfoFromFile, BabTTS_SetInfo

6.3.2. BABTTSINFO

Give specific information about a voice

The name of the selected voice(as used in BabTTS_Open)

szName

The name of the speaker szSpeaker The Language szLanguage The Version of the Engine (Major, Minor, Revision)

szVersion

The sampling rate can be : BABTTS_SAMP_8KHZ BABTTS_SAMP_11KHZ BABTTS_SAMP_16KHZ

Freq

Date : 19/01/07

Page : 110/116


SDK Developer Guide

AcaMul-SDK-6


BABTTS_SAMP_22KHZ Type The type of application (Multimedia

or telecom) Synth The technology used (HD or HQ)

Gender The Gender can be : BABTTS_GENDER_NEUTRAL BABTTS_GENDER_FEMALE BABTTS_GENDER_MALE

Age The age

see BabTTS_GetVoiceInfo, BabTTS_GetInstanceInfo

Date : 19/01/07

Page : 111/116


SDK Developer Guide

AcaMul-SDK-6


6.3.3. BABTTSMOUTH

This structure describes mouth position (similar as the SAPI MOUTH struct)

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

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

bMouthUpturn Extent to which the mouth turns up at the corners (that is, how much it smiles). This is a linear range from 0xFF for the maximum upturn (that is, the mouth is fully smiling) to 0x00 if the corners of the mouth turn down. If this member is 0x80, the mouth is neutral.

bJawOpen Angle to which the jaw is open. This is a linear range from 0xFF for completely open to 0x00 for completely closed.

bTeethUpperVisible Extent to which the upper teeth are visible. This is a linear range from 0xFF for the maximum extent (that is, the upper teeth and gums are completely exposed) to 0x00 for the minimum (the upper teeth are completely hidden). If this member is 0x80, only the teeth are visible.

bTeethLowerVisible Extent to which the lower teeth are visible. This is a linear range from 0xFF for the maximum extent (that is, the lower teeth and gums are completely exposed) to 0x00 for the minimum (the lower teeth are completely hidden.) If this member is 0x80, only the teeth are visible.

bTonguePosn Tongue position. This a linear range from 0xFF if the tongue is against the upper teeth, to 0x00 if it is relaxed. If this member is 0x80, the tongue is visible.

bLipTension Lip tension. This is a linear range from 0xFF if the lips are very tense to 0x00 if they are completely relaxed.

Date : 19/01/07

Page : 112/116


SDK Developer Guide

AcaMul-SDK-6


6.3.4. BABTTSUNITINFO

Side information sent with word and sentence events

dwPos The position of the event in the text (in byte)

dwLength The length (in byte) of the event. dwTimeStamp The time when event occurs (from the

beginning of the text) dwDuration The length (in ms) of the event

Documents

Acapela TTS Multimedia 6 - narod.rutts-alenka.narod.ru/pdf/acamul-sdk-6.pdf · or perform in public the sound files generated by the ACAPELA Text-to-speech technologies for commercial