kttsd Library API Documentation

PlugInProc Class Reference

pluginproc - the KDE Text-to-Speech Deamon Plugin API. More...

#include <pluginproc.h>

List of all members.

Signals

void synthFinished ()
void sayFinished ()
void stopped ()
void error (const bool keepGoing, const QString &msg)

Public Member Functions

 PlugInProc (QObject *parent=0, const char *name=0)
virtual ~PlugInProc ()
virtual bool init (KConfig *config, const QString &configGroup)
virtual void sayText (const QString &text)
virtual void synthText (const QString &text, const QString &suggestedFilename)
virtual QString getFilename ()
virtual void stopText ()
virtual pluginState getState ()
virtual void ackFinished ()
virtual bool supportsAsync ()
virtual bool supportsSynth ()
virtual QString getSsmlXsltFilename ()


Detailed Description

pluginproc - the KDE Text-to-Speech Deamon Plugin API.

Version:
1.0 Draft 1
This class defines the interface that plugins to KTTSD must implement.

Warning:
The pluginproc interface is still being developed and is likely to change in the future.
A KTTSD Plugin interfaces between KTTSD and a speech engine. It provides the methods used by KTTSD to synthesize and/or audibilize text into speech.

Goals

The ideal plugin has the following features (listed most important to least important):

As a plugin author, your goal is to provide all 3 of these features. However, the speech engine you are working with might not be able to support all three features.

If a plugin cannot do all 3 of the features above, the next best combinations are (from best to worst):

Notice that aynchronous support is not essential because KTTSD is able to provide aynchronous support by running the plugin in a separate thread. The ability to immediately stop audio output (or support separate synthesis only) is more important.

Implementations

All plugins should implement init in order to initialize the speech engine, set language codes, etc.

If supportsSynth return False, a plugin must implement sayText .

If supportsSynth returns True, a plugin must implement the following methods:

If supportsAsync returns True, the plugin must implement getState .

If supportsAsync returns True, and supportsSynth returns True, a plugin must emit synthFinished signal when synthesis is completed.

If supportsAsync returns True, and supportsSynth returns False, a plugin must emit sayFinished signal when saying is completed.

If supportsAsync returns False, do not emit signals sayFinished or synthFinished .

Guidelines

In no case, will a plugin need to perform more than one sayText or synthText at a time. In other words, in asynchronous mode, KTTSD will not call sayText or synthText again until returns psFinished.

If supportsAsync returns False, KTTSD will run the plugin in a separate QThread. As a consequence, the plugin must not make use of the KDE Library, when sayText or synthText is called, with the exception of KProcess and family (KProcIO, KShellProcess). This restriction comes about because the KDE Libraries make use of the main Qt event loop, which unfortunately, runs only in the main thread. This restriction will likely be lifted in Qt 4 and later.

Since the KDE library is not available from the sayText and synthText methods, it is best if the plugin reads configuration settings in the init method. The KConfig object is passed as an argument to init .

If the synthesis engine requires a long initialization time (more than a second), it is best if the plugin loads the speech engine from the init method. Otherwise, it will be more memory efficient to wait until sayText or synthText is called, because it is possible that the plugin will be created and initialized, but never used.

All plugins, whether supportsAsync returns True or not, should try to implement stopText . If a plugin returns False from supportsAsync, stopText will be called from the main thread, while sayText and/or synthText will be called from a separate thread. Hence, it will be possible for stopText to be called while sayText or synthText is running. Keep this in mind when implementing the code.

If the plugin returns True from supportsAsync, you will of course need to deal with similar issues. If you have to use QThreads to implement asynchronous support, do not be concerned about emitting the sayFinished or synthFinished signals from your threads, since KTTSD will convert the received signals into postEvents and return immediately.

If it is not possible for stopText to stop an in-progress operation, it must not wait for the operation to complete, since this would block KTTSD. Instead, simply return immediately. Usually, KTTSD will perform other operations while waiting for the plugin to complete its operation. (See threadedplugin.cpp.)

If the stopText implementation returns before the operation has actually completed, it must emit the stopped() signal when it is actually completed.

If a plugin returns True from supportsAsync, and stopText is called, when the plugin has stopped or completed the operation, it must return psIdle on the next call to getState ; not psFinished. The following state diagram might be helpful to understand this:

          psIdle <<----------------------------------------------------------
         /      \                                                           ^
  psSaying      psSynthing --- stopText called and operation completed -->> ^
         \      /                                                           ^
        psFinished --- ackFinished called ------------------------------->> ^
 

If your plugin can't immediately stop an in-progress operation, the easiest way to handle this is to set a flag when stopText is called, and then in your getState() implementation, if the operation has completed, change the psFinished state to psIdle, if the flag is set. See the flite plugin for example code.

If a plugin returns True from supportsSynth, KTTSD will pass a suggested filename in the synthText call. The plugin should synthesize the text into an audio file with the suggested name. If the synthesis engine does not permit this, i.e., it will pick a filename of its own, that is OK. In either case, the actual filename produced should be returned in getFilename . In no case may the plugin re-use this filename once getFilename has been called. If for some reason the synthesis engine cannot support this, the plugin should copy the file to the suggested filename. The file must not be locked when getFilename is called. The file will be deleted when KTTSD is finished using it.

The preferred audio file format is wave, since this is the only format guaranteed to be supported by KDE (aRts). Other formats may or may not be supported on a user's machine.

The plugin destructor should take care of terminating the speech engine.

Error Handling

Plugins may emit the error signal when an error occurs.

When an error occurs, plugins should attempt to recover as best they can and continue accepting sayText or synthText calls. For example, if a speech engine emits an error in response to certain characters embedded in synthesizing text, the plugin should discard the text and emit signal error with True as the first argument and the speech engine's error message as the second argument. The plugin should then treat the operation as a completed operation, i.e., return psFinished when getState is called.

If the speech engine crashes, the plugin should emit signal error with True as the first argument and then attempt to restart the speech engine. The plugin will need to implement some protection against an infinite restart loop and emit the error signal with False as the first argument if this occurs.

If a plugin emits the error signal with False as the first argument, KTTSD will no longer call the plugin.

PlugInConf

The plugin should implement a configuration dialog where the user can specify options specific to the speech engine. This dialog is displayed in the KDE Control Center and also in the KTTS Manager (kttsmgr). See pluginconf.h.

If the user changes any of the settings while the plugin is created, the plugin will be destroyed and re-created.

Definition at line 228 of file pluginproc.h.


Constructor & Destructor Documentation

PlugInProc::PlugInProc QObject *  parent = 0,
const char *  name = 0
 

Constructor.

Definition at line 33 of file pluginproc.cpp.

PlugInProc::~PlugInProc  )  [virtual]
 

Destructor.

Plugin must terminate the speech engine.

Definition at line 40 of file pluginproc.cpp.


Member Function Documentation

bool PlugInProc::init KConfig *  config,
const QString &  configGroup
[virtual]
 

Initializate the speech engine.

Parameters:
config Settings object.
configGroup Settings Group.
Sample code for reading configuration:

            config->setGroup(configGroup);
            m_fliteExePath = config->readPathEntry("FliteExePath", "flite");
            kdDebug() << "FliteProc::init: path to flite: " << m_fliteExePath << endl;
            config->setGroup(configGroup);
          

Definition at line 47 of file pluginproc.cpp.

void PlugInProc::sayText const QString &  text  )  [virtual]
 

Say a text.

Synthesize and audibilize it.

Parameters:
text The text to be spoken.
If the plugin supports asynchronous operation, it should return immediately and emit sayFinished signal when synthesis and audibilizing is finished. It must also implement the getState method, which must return psFinished, when saying is completed.

Definition at line 58 of file pluginproc.cpp.

void PlugInProc::synthText const QString &  text,
const QString &  suggestedFilename
[virtual]
 

Synthesize text into an audio file, but do not send to the audio device.

Parameters:
text The text to be synthesized.
suggestedFilename Full pathname of file to create. The plugin may ignore this parameter and choose its own filename. KTTSD will query the generated filename using getFilename().
If the plugin supports asynchronous operation, it should return immediately and emit synthFinished signal when synthesis is completed. It must also implement the getState method, which must return psFinished, when synthesis is completed.

Definition at line 72 of file pluginproc.cpp.

QString PlugInProc::getFilename  )  [virtual]
 

Get the generated audio filename from call to synthText.

Returns:
Name of the audio file the plugin generated. Null if no such file.
The plugin must not re-use or delete the filename. The file may not be locked when this method is called. The file will be deleted when KTTSD is finished using it.

Definition at line 81 of file pluginproc.cpp.

void PlugInProc::stopText  )  [virtual]
 

Stop current operation (saying or synthesizing text).

Important: This function may be called from a thread different from the one that called sayText or synthText. If the plugin cannot stop an in-progress sayText or synthText operation, it must not block waiting for it to complete. Instead, return immediately.

If a plugin returns before the operation has actually been stopped, the plugin must emit the stopped signal when the operation has actually stopped.

The plugin should change to the psIdle state after stopping the operation.

Definition at line 88 of file pluginproc.cpp.

pluginState PlugInProc::getState  )  [virtual]
 

Return the current state of the plugin.

This function only makes sense in asynchronous mode.

Returns:
The pluginState of the plugin.
See also:
pluginState

Definition at line 99 of file pluginproc.cpp.

void PlugInProc::ackFinished  )  [virtual]
 

Acknowledges a finished state and resets the plugin state to psIdle.

If the plugin is not in state psFinished, nothing happens. The plugin may use this call to do any post-processing cleanup, for example, blanking the stored filename (but do not delete the file). Calling program should call getFilename prior to ackFinished.

Definition at line 109 of file pluginproc.cpp.

bool PlugInProc::supportsAsync  )  [virtual]
 

Returns True if the plugin supports asynchronous processing, i.e., returns immediately from sayText or synthText.

Returns:
True if this plugin supports asynchronous processing.
If the plugin returns True, it must also implement getState . It must also emit sayFinished or synthFinished signals when saying or synthesis is completed.

Definition at line 116 of file pluginproc.cpp.

bool PlugInProc::supportsSynth  )  [virtual]
 

Returns True if the plugin supports synthText method, i.e., is able to synthesize text to a sound file without audibilizing the text.

Returns:
True if this plugin supports synthText method.
If the plugin returns True, it must also implement the following methods:

If the plugin returns True, it need not implement sayText .

Definition at line 124 of file pluginproc.cpp.

QString PlugInProc::getSsmlXsltFilename  )  [virtual]
 

Returns the name of an XSLT stylesheet that will convert a valid SSML file into a format that can be processed by the synth.

For example, The Festival plugin returns a stylesheet that will convert SSML into SABLE. Any tags the synth cannot handle should be stripped (leaving their text contents though). The default stylesheet strips all tags and converts the file to plain text.

Returns:
Name of the XSLT file.

Definition at line 135 of file pluginproc.cpp.

void PlugInProc::synthFinished  )  [signal]
 

Emitted when synthText() finishes and plugin supports asynchronous mode.

void PlugInProc::sayFinished  )  [signal]
 

Emitted when sayText() finishes and plugin supports asynchronous mode.

void PlugInProc::stopped  )  [signal]
 

Emitted when stopText() has been called and plugin stops asynchronously.

void PlugInProc::error const bool  keepGoing,
const QString &  msg
[signal]
 

Emitted if an error occurs.

Parameters:
keepGoing True if the plugin can continue processing. False if the plugin cannot continue, for example, the speech engine could not be started.
msg Error message.
When an error occurs, plugins should attempt to recover as best they can and continue accepting sayText or synthText calls. For example, if the speech engine emits an error while synthesizing text, the plugin should return True along with error message.

See also:
Error-handling


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kttsd Library Version 3.3.90.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sun Dec 12 14:37:19 2004 by doxygen 1.3.9.1 written by Dimitri van Heesch, © 1997-2003