PlugInProc Class Reference
pluginproc - the KDE Text-to-Speech Deamon Plugin API. More...
#include <pluginproc.h>
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
- Warning:
- The pluginproc interface is still being developed and is likely to change in the future.
Goals
The ideal plugin has the following features (listed most important to least important):- It can synthesize text into an audio file without sending the audio to the audio device. If the plugin can do this, the supportsSynth function should return True.
- When stopText is called, is able to immediately stop an in-progress synthesis or saying operation.
- It can operate asynchronously, i.e., returns immediately from a sayText or synthText call and emits signals sayFinished or synthFinished when completed. If the plugin can do this, the supportsAsync function should return True.
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):
- supportsSynth returns True, supportsAsync returns False, and is able to immediately stop synthesis.
- supportsSynth returns True, supportsAsync returns False, and returns immediately without stopping synthesis.
- supportsAsync returns True, supportsSynth returns False, and stopText is able to immediately stop saying.
- Both supportsSynth and supportsAsync both return False, and stopText is able to immediately stop saying.
- supportsAsync returns True, supportsSynth returns False, and stopText returns immediately without stopping saying.
- Both supportsSynth and supportsAsync both return False, and stopText returns immediately without stopping saying.
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:
- synthText
- getFilename
- ackFinished The plugin need not implement sayText .
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
|
Constructor.
Definition at line 33 of file pluginproc.cpp. |
|
Destructor. Plugin must terminate the speech engine. Definition at line 40 of file pluginproc.cpp. |
Member Function Documentation
|
Initializate the speech engine.
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. |
|
Say a text. Synthesize and audibilize it.
Definition at line 58 of file pluginproc.cpp. |
|
Synthesize text into an audio file, but do not send to the audio device.
Definition at line 72 of file pluginproc.cpp. |
|
Get the generated audio filename from call to synthText.
Definition at line 81 of file pluginproc.cpp. |
|
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. |
|
Return the current state of the plugin. This function only makes sense in asynchronous mode.
Definition at line 99 of file pluginproc.cpp. |
|
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. |
|
Returns True if the plugin supports asynchronous processing, i.e., returns immediately from sayText or synthText.
Definition at line 116 of file pluginproc.cpp. |
|
Returns True if the plugin supports synthText method, i.e., is able to synthesize text to a sound file without audibilizing the text.
If the plugin returns True, it need not implement sayText . Definition at line 124 of file pluginproc.cpp. |
|
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.
Definition at line 135 of file pluginproc.cpp. |
|
Emitted when synthText() finishes and plugin supports asynchronous mode.
|
|
Emitted when sayText() finishes and plugin supports asynchronous mode.
|
|
Emitted when stopText() has been called and plugin stops asynchronously.
|
|
Emitted if an error occurs.
|
The documentation for this class was generated from the following files: