Overzicht van alle functies

Hieronder geven we een overzicht van alle functies van de Fluency API, met een korte omschrijving. We gebruiken daarbij de volgende notatie:

Alle functies maken, net als de Windows API, gebruik van de stdcall (of WINAPI) manier van aanroepen.

De onderstaande tabel geeft een overzicht van de typen die in deze functies kunnen voorkomen, en hun (mogelijke) equivalenten in Delphi en C++:

type	bits	omschrijving	Delphi	C++
voice	32/64	adres van een voice-object, dat een stem representeert die in het geheugen is geladen	Pointer	void *
channel	32/64	adres van een channel-object, dat een kanaal representeert voor het synthetiseren van spraak, met een bepaalde stem en andere instellingen	Pointer	void *
sync	32/64	adres van een callback-functie, die het mogelijk maakt de voortgang van de spraaksynthese te volgen	Pointer	void *
audio	32/64	adres van een buffer met audio-samples, in 16-bits PCM, mono of stereo	Pointer	void *
string	32/64	adres van een zero-terminated string, Unicode of ANSI (zie de opmerking hieronder)	PAnsiChar PWideChar	char * wchar_t *
string8	32/64	adres van een zero-terminated string, uitsluitend ANSI	PAnsiChar	char *
boolean	8	TRUE (1) of FALSE (0)	Boolean	bool
unsigned	32	een positief getal	Cardinal	unsigned
integer	32	een positief of negatief getal	Integer	int
window	32	handle van een venster	HWND	HWND
*	32/64	pointer naar een output parameter	out	*

Unicode of Ansi?

Vanaf versie 8.0 werkt Fluency TTS intern met Unicode strings. Maar vanwege de compatibiliteit met eerdere versies worden ook ANSI-strings geaccepteerd. Elke functie die strings accepteert (met uitzondering van de functie fluencyGetPhone) heeft daarom twee versies, waarbij voor de Unicode-versie een hoofdletter W is toegevoegd aan de naam. Dus: fluencySetInputText veronderstelt een ANSI-string, en fluencySetInputTextW is de versie die een Unicode-string verwacht.

In het overzicht hieronder zijn de functies verdeeld in een aantal groepen van functies die min of meer bij elkaar horen.

Versie-informatie

Gebruik deze twee functies om het versienummer van Fluency TTS op te vragen. Deze functies kunnen aangeroepen worden voordat Fluency TTS geïnitialiseerd is.

resultaat

Het major of minor versienummer. Voor versie 5.0 dus respectievelijk 5 en 0.

Deze functie toont het About-venster, met versie-info en copyrights. Daarnaast wordt ook het volledige pad getoond van de applicatie die Fluency TTS in het geheugen heeft geladen, en het pad naar de map waar instellingen van de gebruiker en het user lexicon worden opgeslagen.

Win	Handle van het venster van de aanroepende applicatie. Mag de waarde 0 hebben als geen venster beschikbaar is; het About-venster wordt dan gecentreerd op de desktop.

Starten/stoppen

Met deze functie kunnen applicaties Fluency TTS uit de demo-stand halen, ook als de gebruiker niet over een licentie beschikt. Moet aangeroepen worden direct voorafgaand aan fluencyInitialize.

Key	Een licentiesleutel die gekoppeld is aan de applicatie die Fluency TTS in het geheugen laadt. Een dergelijke sleutel kan alleen verkregen worden na het afsluiten van een royalty-overeenkomst.
Extra	Eventuele extra informatie bij de licentiesleutel.

Deze functie moet aangeroepen worden voordat de overige functies kunnen worden gebruikt. De configuratie wordt gecontroleerd, lexica worden geopend, en instellingen van de gebruiker worden geladen. Ook wordt de licentie van de gebruiker gecontroleerd. Als geen geldige licentiesleutel aanwezig is, dan opereert Fluency TTS in de demo-stand.

resultaat

TRUE (1) als de initialisatie zonder fouten is verlopen. Als deze functie FALSE (0) teruggeeft, dan is Fluency TTS niet correct geïnstalleerd.

Deze functie maakt het mogelijk Fluency TTS te draaien vanaf een USB-stick, en wordt dan gebruikt in plaats van fluencyInitialize.

TTSPath	Het volledige pad naar de map waar FLUENCY.DLL en de overige bestanden gevonden kunnen worden.
UserPath	Het pad naar een map waar instellingen en user lexicon kunnen worden opgeslagen. Dit moet een locatie zijn waar ook een gebruiker met beperkte rechten schrijfrechten heeft!
resultaat	TRUE (1) als de initialisatie zonder fouten is verlopen. Als deze functie FALSE (0) teruggeeft, dan is Fluency TTS niet correct geïnstalleerd.

Sluit alle geopende bestanden. Aanroepen voordat FLUENCY.DLL vrijgegeven wordt.

Stemmen inventariseren

resultaat

Het aantal stemmen dat geïnstalleerd is.

Gebruik deze functie in combinatie met fluencyGetVoiceCount om een lijst van stemmen aan te maken, waaruit de gebruiker kan kiezen.

VoiceIndex	Index van de stem. De eerste stem heeft index 1
Name	Buffer waarin de naam van de stem wordt gezet.
MaxLen	Het maximale aantal tekens dat de buffer kan bevatten.
resultaat	Het aantal tekens dat in de buffer is gezet.

Het voice-object

Laadt een stem in het geheugen. Elke stem neemt ongeveer 1,5 MB geheugenruimte in beslag. Als een stem reeds in het geheugen geladen is, wordt zijn reference count opgehoogd.

Name	De naam van de stem. Gebruik fluencyGetVoiceName om een lijst van geïnstalleerde stemmen aan te maken, of vraag met fluencyGetPreferredVoiceName de naam op van de stem die door de gebruiker als favoriet geselecteerd is.
resultaat	Het adres van het voice-object. Als de gevraagde stem niet aanwezig is, geeft deze functie 0 (nil) als resultaat.

Verlaagt de reference count van de stem. Als deze op 0 komt, wordt de stem vrijgegeven.

Voice

Adres van het voice-object. Als Voice de waarde 0 (nil) heeft, dan heeft deze functie geen effect.

Het channel-object

Maakt een kanaal aan voor spraaksynthese. Elk kanaal heeft zijn eigen instellingen (stem, tempo, volume, tekst, etc.). Deze kunnen tijdens het spreken gewijzigd worden.

Voice	Het adres van een voice-object.
SamplingRate	De sampling rate in aantal samples per seconde (Hz). Geef 0 op om de standaard sampling rate van 22KHz (= 22050 samples per seconde) te kiezen. De minimumwaarde is 4000 (4 KHz), het maximum is 96000 (96 KHz). Een hogere waarde dan 22 KHz geeft echter geen hogere geluidskwaliteit!
Stereo	Geef FALSE (0) voor een mono-kanaal, TRUE (1) voor een stereo-kanaal.
resultaat	Adres van een nieuw channel-object.

Geeft het kanaal weer vrij.

Channel

Het adres van het vrij te geven channel-object. Dit kan daarna niet meer gebruikt worden.

Wijzigt de stem van een kanaal. Deze functie kan gebruikt worden terwijl Fluency TTS aan het spreken is, maar let op dat het kanaal op geen enkel moment zonder stem zit.

Channel	Het adres van een channel-object.
Voice	Het adres van een voice-object.

Het effect van deze functie kan ook bereikt worden met een tag in de invoertekst.

Wijzigt het spreektempo van een kanaal. Kan tijdens het spreken gebruikt worden.

Channel	Het adres van een channel-object.
Tempo	Minimumwaarde -10 (zeer traag), maximumwaarde 10 (zeer snel). Het normale spreektempo heeft de waarde 0.

Het effect van deze functie kan ook bereikt worden met een tag in de invoertekst.

Wijzigt het volume van een kanaal. Kan tijdens het spreken gebruikt worden.

Channel	Het adres van een channel-object.
Volume	0 - 100 procent. Standaardwaarde: 70.

Het effect van deze functie kan ook bereikt worden met een tag in de invoertekst.

Wijzigt het stereo-balans van een kanaal. Kan tijdens het spreken gebruikt worden. Bij een mono-kanaal heeft deze functie geen effect.

Channel	Het adres van een channel-object.
Balance	Geheel links: -100, midden: 0, geheel rechts: 100.

Het effect van deze functie kan ook bereikt worden met een tag in de invoertekst.

Stuurt tekst naar Fluency TTS. Deze functie werkt tevens als een reset van het kanaal.

Channel	Het adres van een channel-object.
Text	De uit te spreken tekst in ANSI-codering (dus geen Unicode of ASCII).

Synthetiseert de eerstvolgende spraakklank. Deze functie biedt een low-level interface naar de spraaksynthese, voor die gevallen waar fluencySpeak of fluencySpeakToFile niet volstaat.

Alle parameters behalve Channel zijn output-parameters!

Channel	Het adres van een channel-object.
Phone	De spraakklank in Fluency allofoonnotatie. Bestaat uit één of twee tekens. Voorbeelden: "e" voor de klinker in beet; "Ei" voor de tweeklank in bijt.
Samples	Het aantal samples in de audio-buffer.
Wav	Adres van een buffer met audio-samples, in 16-bits PCM, mono of stereo. Voor een mono-kanaal is het aantal bytes in de buffer 2 * Samples, voor een stereo-kanaal 4 * Samples.
TextIndex	Als de spraakklank het begin van een woord markeert, dan geeft deze variable de positie van het woord in de invoertekst. Het begin van de tekst is positie 0. Let op: als de spraakklank niet het begin van een woord markeert, dan wordt ook de waarde 0 gegeven!
WordLength	Als de spraakklank het begin van een woord markeert, dan geeft deze variable de lengte van het woord. Dus: als WordLength > 0 dan TextIndex = positie in de tekst.
resultaat	TRUE (1) als de functie succesvol was, FALSE (0) als het einde van de tekst bereikt is.

Het benodigde geheugen voor de audio-samples wordt door Fluency TTS beheerd. De data zijn toegankelijk totdat je opnieuw deze functie aanroept.

Deze functie is met name bedoeld om in een while-loop te draaien: while fluencyGetPhone(...) ...

Start de spraaksynthese, en speelt de spraak af via de geluidskaart.

Channel	Het adres van een channel-object.
Sync	Het adres van een callback-functie, die het mogelijk maakt de voortgang van de spraaksynthese te volgen. Deze parameter mag 0 (nil) zijn, als geen gebruik wordt gemaakt van een callback.
User	Deze parameter wordt meegegeven aan de callback, en kan gebruikt worden om eventuele extra informatie door te geven.
resultaat	TRUE (1) als de functie succesvol was, FALSE (0) als de geluidskaart niet beschikbaar is.

Het is mogelijk verschillende kanalen tegelijk af te spelen, mits de geluidskaart dit ondersteunt.

Stopt het afspelen via de geluidskaart.

Channel

Het adres van een channel-object.

Pauzeert het afspelen via de geluidskaart, of gaat verder met afspelen.

Channel

Het adres van een channel-object.

Start de spraaksynthese, en schrijft de audio naar een .wav-bestand (Windows PCM, 16 bits).

Channel	Het adres van een channel-object.
Filename	Pad + naam van het te schrijven .wav-bestand.
Sync	Het adres van een callback-functie, die het mogelijk maakt de voortgang van de spraaksynthese te volgen. Deze parameter mag 0 (nil) zijn, als geen gebruik wordt gemaakt van een callback.
User	Deze parameter wordt meegegeven aan de callback, en kan gebruikt worden om eventuele extra informatie door te geven.

Deze functie geeft een waarschuwing als het .wav-bestand niet geopend kan worden, door gebrek aan schrijfrechten of doordat het bestand gebruikt wordt door een andere applicatie.

Het is mogelijk om gelijktijdig meerdere kanalen naar verschillende audio-bestanden te schrijven. Het is echter niet mogelijk deze functie te gebruiken terwijl spraak via de geluidskaart wordt afgespeeld.

Stopt het schrijven naar een audio-bestand. Het bestand wordt netjes afgesloten, inclusief header-informatie. Het wordt niet verwijderd.

Channel

Het adres van een channel-object.

Scant een tekst op woorden die mogelijk problemen geven. Deze functie simuleert de spraaksynthese zonder audio te genereren.

Channel	Het adres van een channel-object.
Sensitivity	Minimumwaarde = 0. Maximumwaarde = 5. Aanbevolen waarde = 3.
Sync	Het adres van een callback-functie, die het mogelijk maakt de voortgang van de spraaksynthese te volgen. De mogelijk problematische woorden worden aangegeven via de SYNC_SCAN-event.
User	Deze parameter wordt meegegeven aan de callback, en kan gebruikt worden om eventuele extra informatie door te geven.

De minimumwaarde voor de parameter Sensitivity (0) geeft alle woorden die in een tekst voorkomen. De maximumwaarde (5) geeft alleen woorden die uitgespeld worden, en die niet als "bekende afkorting" in het lexicon voorkomen. De aanbevolen waarde (3) geeft alle woorden die niet in het lexicon of het gebruikerslexicon voorkomen, en waarvan de uitspraak via regels tot stand komt.

Deze functie vereist een geldige licentie of het gebruik van fluencyUnLock. In de demo-stand geeft deze functie een foutmelding.

Je kunt deze functie niet gebruiken als Fluency TTS bezig is met spreken, of met het genereren van een audio-bestand.

Stopt het scannen van een tekst.

Channel

Het adres van een channel-object.

Lexicon

Geeft de fonetische transcriptie van een woord in Fluency-notatie. Als een woord niet gevonden wordt in het lexicon of het gebruikerslexicon, dan wordt de transcriptie met regels gegenereerd.

Word	Het op te zoeken woord. Deze string mag geen spaties bevatten.
Transcription	Buffer waarin de transcriptie wordt gezet.
MaxLen	Het maximale aantal tekens dat de buffer kan bevatten.
resultaat	Het aantal tekens dat in de buffer is gezet.

Deze functie vereist een geldige licentie of het gebruik van fluencyUnLock. In de demo-stand wordt altijd de lege string teruggegeven.

Voegt een woord toe aan het gebruikerslexicon. Als het woord reeds in het gebruikerslexicon voorkomt, en de transcriptie is de lege string, dan wordt het woord verwijderd.

Word	Het woord dat wordt toegevoegd of verwijderd. Deze string mag geen spaties bevatten.
Transcription	De fonetische transcriptie van het woord in Fluency-notatie.

Geeft het eerstvolgende woord in het gebruikerslexicon.

Word	Het voorafgaande woord. Geef de lege string om het eerste woord te vinden.
NextWord	Buffer waarin het eerstvolgende woord wordt gezet.
MaxLen	Het maximale aantal tekens dat de buffer kan bevatten.
resultaat	Het aantal tekens dat in de buffer is gezet.

Na het laatste woord geeft deze functie 0 als resultaat.

Extra lexicon functies vanaf versie 8.0

Verwijdert alle woorden uit het gebruikerslexicon.

Importeert woorden uit een tekstbestand. Elke regel moet bestaan uit het woord, gevolgd door een TAB-teken, gevolgd door de transcriptie in Fluency-notatie.

Exporteert woorden naar een tekstbestand dat met Notepad bewerkt kan worden.

Instellingen opvragen / wijzigen

Geeft de naam van de stem die door de gebruiker als favoriet is geselecteerd.

Name	Buffer waarin de naam van de stem wordt gezet.
MaxLen	Het maximale aantal tekens dat de buffer kan bevatten.
resultaat	Het aantal tekens dat in de buffer is gezet.

Wijzigt de favoriete stem van de gebruiker.

Name	De naam van de stem.

Vraagt de door de gebruiker gekozen waarde op voor tempo, volume of stereo-balans.

resultaat

De door de gebruiker gekozen waarde. Tempo = -10 .. 10 (standaardwaarde = 0); Volume = 0 .. 100 (standaardwaarde = 70); Balance = -100 .. 100 (standaardwaarde = 0).

Wijzigt de door de gebruiker gekozen waarde voor tempo, volume of stereo-balans.

Tempo	-10 .. 10 (standaardwaarde = 0).
Volume	0 .. 100 (standaardwaarde = 70).
Balance	-100 .. 100 (standaardwaarde = 0).

Geeft de ingestelde waarde voor de manier van voorlezen. Dit is een globale parameter die geldt voor alle kanalen die door een applicatie aangemaakt worden.

resultaat

0 = normaal; 1 = woord-voor-woord; 2 = lettergreep-voor-lettergreep.

Wijzigt de ingestelde waarde voor de manier van voorlezen. Dit is een globale parameter die geldt voor alle kanalen die door een applicatie aangemaakt worden.

Mode	0 = normaal; 1 = woord-voor-woord; 2 = lettergreep-voor-lettergreep.

Geeft de ingestelde waarde voor het uitspellen van onbekende woorden. Dit is een globale parameter die geldt voor alle kanalen die door een applicatie aangemaakt worden.

resultaat

0 = alleen losse letters worden uitgespeld, woorden worden -zo goed en zo kwaad als dat gaat- altijd uitgesproken. 1 = onbekende woorden zonder klinker worden uitgespeld. 2 = woorden worden uitgespeld als het begin/eind van het woord niet overeenkomt met de fonotactische restricties van het Nederlands.

De standaardwaarde van deze parameter is 2. Een woord als kzmodika wordt bij deze instelling uitgespeld, want geen enkel Nederlands woord begint met kzm.

Wijzigt de ingestelde waarde voor het uitspellen van onbekende woorden. Dit is een globale parameter die geldt voor alle kanalen die door een applicatie aangemaakt worden.

Mode

0 = alleen losse letters worden uitgespeld, woorden worden -zo goed en zo kwaad als dat gaat- altijd uitgesproken. 1 = onbekende woorden zonder klinker worden uitgespeld. 2 = woorden worden uitgespeld als het begin/eind van het woord niet overeenkomt met de fonotactische restricties van het Nederlands. (Standaardwaarde)

Geeft de ingestelde waarde voor het uitspreken van interpunctie. Dit is een globale parameter die geldt voor alle kanalen die door een applicatie aangemaakt worden.

resultaat

FALSE (0) = interpunctie wordt niet uitgesproken; TRUE (1) = interpunctie wordt eveneens uitgesproken. Standaardwaarde: FALSE.

Wijzigt de ingestelde waarde voor het uitspreken van interpunctie. Dit is een globale parameter die geldt voor alle kanalen die door een applicatie aangemaakt worden.

Mode	FALSE (0) = interpunctie wordt niet uitgesproken; TRUE (1) = interpunctie wordt eveneens uitgesproken. Standaardwaarde: FALSE.

Zorgt ervoor dat Fluency TTS de instellingen opslaat in het bestand FLUENCY.INI. Dit gebeurt automatisch als je fluencyClose aanroept.

Als de instellingen niet gewijzigd zijn (bijvoorbeeld met fluencySetPreferredVoiceName), dan heeft het aanroepen van deze functie geen effect.

Zorgt ervoor dat Fluency TTS opnieuw het bestand FLUENCY.INI inleest, dat alle instellingen bevat.

Dit is nuttig als de gebruiker via het Instellingen-programma wijzigingen heeft aangebracht in zijn voorkeursstem, tempo en andere parameters. Het Instellingen-programma geeft dit aan door een speciale message te sturen naar alle top-level windows. Je programma kan deze message ontvangen door bij aanvang de Windows-functie RegisterWindowMessage aan te roepen, met als argument de string FLUENCY_SETTINGS_CHANGE.

Als je de message ontvangt roep je fluencyUpdateSettings aan, en vervolgens kun je de nieuwe settings opvragen. Zie de broncode van het programma AudioWizard voor een uitgewerkt voorbeeld.

Geeft het pad naar de map waar het gebruikerslexicon user.lex wordt opgeslagen, alsmede de instellingen van de gebruiker (FLUENCY.INI).

Path	Buffer waarin het pad wordt gezet.
MaxLen	Het maximale aantal tekens dat de buffer kan bevatten.
resultaat	Het aantal tekens dat in de buffer is gezet.

Ongedocumenteerde functies

Enkele functies zijn uitsluitend bedoeld voor gebruik in Fluency-applicaties, en worden niet verder toegelicht.

Synchronisatie

Bij de functies fluencySpeak en fluencySpeakToFile kan optioneel het adres worden opgegeven van een callback-functie die het mogelijk maakt de voortgang van de spraaksynthese te volgen. De meest voor de hand liggende toepassing is het highlighten van het woord dat uitgesproken wordt. De functie fluencyScanText maakt eveneens gebruikt van deze callback.

De callback-functie moet gedeclareerd zijn met de stdcall (of WINAPI) manier van aanroepen, en heeft de volgende argumenten:

Event	Synchronisatie-event. Zie de tabel hieronder.
Param1	De eerste parameter.
Param2	De tweede parameter.
User	De waarde die meegegeven is bij het aanroepen van fluencySpeak, fluencySpeakToFile of fluencyScanText.

De onderstaande tabel geeft een overzicht van de synchronisatie-events waarvoor de callback-functie wordt aangeroepen.

event	waarde	omschrijving
SYNC_START	0	De spraaksynthese is gestart.
SYNC_PROGRESS	1	De spraaksynthese is aanbeland bij het begin van een woord. Param1 geeft de positie in de invoertekst (het begin van de tekst is positie 0). Param2 geeft de lengte van het woord.
SYNC_FINISH	2	De spraaksynthese is gestopt.
SYNC_PHONEME	3	Deze event wordt voor elke spraakklank gegenereerd. Param1 geeft een representatie van het foneem, waarbij deze parameter als een 16-bits waarde behandeld wordt: het low-order byte bevat de eerste letter van het foneem, het high-order byte de eventuele tweede letter. Param2 geeft de duur van het foneem in aantal samples.
SYNC_SCAN	4	Deze event wordt gegenereerd door de functie fluencyScanText. Param1 geeft de positie in de invoertekst (het begin van de tekst is positie 0). Param2 geeft de lengte van het woord.

Zorg ervoor dat de callback-functie bliksemsnel is, om vastlopers te voorkomen. Het is met name geen goed idee om de events in een MessageBox te laten zien!

Tags in de invoertekst

Het effect van de functies fluencySetVoice, fluencySetTempo, fluencySetVolume en fluencySetBalance kan ook bereikt worden met tags in de invoertekst. Zie het voorbeeld hieronder:

\stem=Arthur;balans=-50\ Zo, ik zit op het linkerkanaal, en jij zit rechts. \stem=Fiona;balans=50\ Nee hoor, ik zit gewoon op mijn stoel!

In dergelijke tags kunnen behalve de (Nederlandse) termen stem, tempo, volume en balans ook de Engelse equivalenten voice en balance gebruikt worden.

\voice=Arthur;balance=0\ Hoe heten jullie? \voice=Davíd;balance=-100\ Kwik, \voice=Fiona;balance=30\ Kwek, \voice=Marco;balance=100\ en Kwak.