summaryrefslogtreecommitdiffstats
path: root/kttsd/libkttsd/pluginproc.h
blob: c271ad3d2b9ff4846ec9c0397d9df178b66bcbda (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
/***************************************************** vim:set ts=4 sw=4 sts=4:
  This file is the template for the processing plug ins.
  -------------------
  Copyright : (C) 2002-2003 by José Pablo Ezequiel "Pupeno" Fernández
  Copyright : (C) 2004 by Gary Cramblitt <garycramblitt@comcast.net>
  -------------------
  Original author: José Pablo Ezequiel "Pupeno" Fernández <pupeno@kde.org>
  Current Maintainer: Gary Cramblitt <garycramblitt@comcast.net>
 ******************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; version 2 of the License.               *
 *                                                                         *
 ***************************************************************************/

#ifndef _PLUGINPROC_H_
#define _PLUGINPROC_H_

#include <qobject.h>
#include <qstring.h>
#include <kdemacros.h>
#include "kdeexportfix.h"
#include <kconfig.h>

/**
* @interface PlugInProc
*
* 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.
*
* @section 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 @ref supportsSynth function
*   should return True.
* - When @ref 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
*   @ref sayText or @ref synthText call and emits signals @ref sayFinished or
*   @ref synthFinished when completed.  If the plugin can do this, the @ref 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):
*
* - @ref supportsSynth returns True, @ref supportsAsync returns False, and
*   @stopText is able to immediately stop synthesis.
* - @ref supportsSynth returns True, @ref supportsAsync returns False, and
*   @stopText returns immediately without stopping synthesis.
* - @ref supportsAsync returns True, @ref supportsSynth returns False, and
*   @ref stopText is able to immediately stop saying.
* - Both @ref supportsSynth and @ref supportsAsync both return False, and
*   @ref stopText is able to immediately stop saying.
* - @ref supportsAsync returns True, @ref supportsSynth returns False, and
*   @ref stopText returns immediately without stopping saying.
* - Both @ref supportsSynth and @ref supportsAsync both return False, and
*   @ref 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.
*
* @section Minimum Implementations
*
* All plugins should implement @ref init in order to initialize the speech engine,
* set language codes, etc.
*
* If @ref supportsSynth return False, a plugin must implement @ref sayText .
*
* If @ref supportsSynth returns True, a plugin must implement the following methods:
* - @ref synthText
* - @ref getFilename
* - @ref ackFinished
* The plugin need not implement @ref sayText .
*
* If @ref supportsAsync returns True, the plugin must implement @ref getState .
*
* If @ref supportsAsync returns True, and @ref supportsSynth returns True, 
* a plugin must emit @ref synthFinished signal when synthesis is completed.
*
* If @ref supportsAsync returns True, and @ref supportsSynth returns False, 
* a plugin must emit @ref sayFinished signal when saying is completed.
*
* If @ref supportsAsync returns False, do not emit signals @ref sayFinished
* or @ref synthFinished .
*
* @section Implementation Guidelines
*
* In no case, will a plugin need to perform more than one @ref sayText or
* @ref synthText at a time.  In other words, in asynchronous mode, KTTSD will
* not call @ref sayText or @ref synthText again until @ref @getState returns
* psFinished.
*
* If @ref 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 @ref sayText or @ref 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 @ref sayText and @ref synthText methods,
* it is best if the plugin reads configuration settings in the @ref init method.
* The KConfig object is passed as an argument to @ref 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 @ref init method.
* Otherwise, it will be more memory efficient to wait until @ref sayText or 
* @ref synthText is called, because it is possible that the plugin will be created
* and initialized, but never used.
*
* All plugins, whether @ref supportsAsync returns True or not, should try to
* implement @ref stopText .  If a plugin returns False from @ref supportsAsync,
* @ref stopText will be called from the main thread, while @ref sayText and/or
* @ref synthText will be called from a separate thread.  Hence, it will be
* possible for @ref stopText to be called while @ref sayText or @ref synthText is
* running.  Keep this in mind when implementing the code.
*
* If the plugin returns True from @ref 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 @ref sayFinished or @ref synthFinished signals from your threads, since
* KTTSD will convert the received signals into postEvents and
* return immediately.
*
* If it is not possible for @ref 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 @ref stopText implementation returns before the operation has actually
* completed, it must emit the @ref stopped() signal when it is actually completed.
*
* If a plugin returns True from @ref supportsAsync, and @ref stopText is called,
* when the plugin has stopped or completed the operation, it must return psIdle
* on the next call to @ref getState ; not psFinished.  The following state diagram
* might be helpful to understand this:
*
 @verbatim
          psIdle <<----------------------------------------------------------
         /      \                                                           ^
  psSaying      psSynthing --- stopText called and operation completed -->> ^
         \      /                                                           ^
        psFinished --- ackFinished called ------------------------------->> ^
 @endverbatim
*
* 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 @ref supportsSynth, KTTSD will pass a suggested
* filename in the @ref 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 @ref getFilename .
* In no case may the plugin re-use this filename once @ref 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 @ref 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.
*
* @section Error-handling Error Handling
*
* Plugins may emit the @ref error signal when an error occurs.
*
* When an error occurs, plugins should attempt to recover as best they can and
* continue accepting @ref sayText or @ref 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 @ref 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
* @ref getState is called.
*
* If the speech engine crashes, the plugin should emit signal @ref 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 @ref error signal with False as the first argument
* if this occurs.
*
* If a plugin emits the @ref error signal with False as the first argument,
* KTTSD will no longer call the plugin.
*
* @section 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.
*/

class QTextCodec;

enum pluginState
{
    psIdle = 0,                  /**< Plugin is not doing anything. */
    psSaying = 1,                /**< Plugin is synthesizing and audibilizing. */
    psSynthing = 2,              /**< Plugin is synthesizing. */
    psFinished = 3               /**< Plugin has finished synthesizing.  Audio file is ready. */
};

class KDE_EXPORT PlugInProc : virtual public QObject{
    Q_OBJECT

    public:
        enum CharacterCodec {
            Local    = 0,
            Latin1   = 1,
            Unicode  = 2,
            UseCodec = 3
        };

        /**
        * Constructor.
        */
        PlugInProc( QObject *parent = 0, const char *name = 0);

        /**
        * Destructor.
        * Plugin must terminate the speech engine.
        */
        virtual ~PlugInProc();

        /**
        * Initialize the speech engine.
        * @param config          Settings object.
        * @param configGroup     Settings Group.
        *
        * Sample code for reading configuration:
        *
          @verbatim
            config->setGroup(configGroup);
            m_fliteExePath = config->readEntry("FliteExePath", "flite");
            kdDebug() << "FliteProc::init: path to flite: " << m_fliteExePath << endl;
            config->setGroup(configGroup);
          @endverbatim
        */
        virtual bool init(KConfig *config, const QString &configGroup);

        /** 
        * Say a text.  Synthesize and audibilize it.
        * @param 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 @ref getState method, which must return
        * psFinished, when saying is completed.
        */
        virtual void sayText(const QString &text);

        /**
        * Synthesize text into an audio file, but do not send to the audio device.
        * @param text                    The text to be synthesized.
        * @param 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 @ref synthFinished signal when synthesis is completed.
        * It must also implement the @ref getState method, which must return
        * psFinished, when synthesis is completed.
        */
        virtual void synthText(const QString &text, const QString &suggestedFilename);

        /**
        * Get the generated audio filename from call to @ref synthText.
        * @return                        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.
        */
        virtual QString getFilename();

        /**
        * 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 @ref sayText or
        * @ref 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 @ref stopped signal when the operation has
        * actually stopped.
        *
        * The plugin should change to the psIdle state after stopping the
        * operation.
        */
        virtual void stopText();

        /**
        * Return the current state of the plugin.
        * This function only makes sense in asynchronous mode.
        * @return                        The pluginState of the plugin.
        *
        * @see pluginState
        */
        virtual pluginState getState();

        /**
        * 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.
        */
        virtual void ackFinished();

        /**
        * Returns True if the plugin supports asynchronous processing,
        * i.e., returns immediately from sayText or synthText.
        * @return                        True if this plugin supports asynchronous processing.
        *
        * If the plugin returns True, it must also implement @ref getState .
        * It must also emit @ref sayFinished or @ref synthFinished signals when
        * saying or synthesis is completed.
        */
        virtual bool supportsAsync();

        /**
        * Returns True if the plugin supports synthText method,
        * i.e., is able to synthesize text to a sound file without
        * audibilizing the text.
        * @return                        True if this plugin supports synthText method.
        *
        * If the plugin returns True, it must also implement the following methods:
        * - @ref synthText
        * - @ref getFilename
        * - @ref ackFinished
        *
        * If the plugin returns True, it need not implement @ref sayText .
        */
        virtual bool supportsSynth();

        /**
        * 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.
        * @return            Name of the XSLT file.
        */
        virtual QString getSsmlXsltFilename();

        /**
        * Given the name of a codec, returns the QTextCodec for the name.
        * Handles the following "special" codec names:
        *   Local               The user's current Locale codec.
        *   Latin1              Latin1 (ISO 8859-1)
        *   Unicode             UTF-16
        * @param codecName      Name of desired codec.
        * @return               The codec object.  Calling program must not delete this object
        *                       as it is a reference to an existing QTextCodec object.
        *
        * Caution: Do not pass translated codec names to this routine.
        */
        static QTextCodec* codecNameToCodec(const QString &codecName);

        /**
        * Builds a list of codec names, suitable for display in a QComboBox.
        * The list includes the 3 special codec names (translated) at the top:
        *   Local               The user's current Locale codec.
        *   Latin1              Latin1 (ISO 8859-1)
        *   Unicode             UTF-16
        */
        static QStringList buildCodecList();

        /**
        * Given the name of a codec, returns index into the codec list.
        * Handles the following "special" codec names:
        *   Local               The user's current Locale codec.
        *   Latin1              Latin1 (ISO 8859-1)
        *   Unicode             UTF-16
        * @param codecName      Name of the codec.
        * @param codecList      List of codec names. The first 3 entries may be translated names.
        * @return               QTextCodec object.  Caller must not delete this object.
        *
        * Caution: Do not pass translated codec names to this routine in codecName parameter.
        */
        static int codecNameToListIndex(const QString &codecName, const QStringList &codecList);

        /**
        * Given index into codec list, returns the codec object.
        * @param codecNum       Index of the codec.
        * @param codecList      List of codec names. The first 3 entries may be translated names.
        * @return               QTextCodec object.  Caller must not delete this object.
        */
        static QTextCodec* codecIndexToCodec(int codecNum, const QStringList &codecList);

        /**
        * Given index into codec list, returns the codec Name.
        * Handles the following "special" codec names:
        *   Local               The user's current Locale codec.
        *   Latin1              Latin1 (ISO 8859-1)
        *   Unicode             UTF-16
        * @param codecNum       Index of the codec.
        * @param codecList      List of codec names. The first 3 entries may be translated names.
        * @return               Untranslated name of the codec.
        */
        static QString codecIndexToCodecName(int codecNum, const QStringList &codecList);

    signals:
        /**
        * Emitted when synthText() finishes and plugin supports asynchronous mode.
        */
        void synthFinished();
        /**
        * Emitted when sayText() finishes and plugin supports asynchronous mode.
        */
        void sayFinished();
        /**
        * Emitted when stopText() has been called and plugin stops asynchronously.
        */
        void stopped();
        /**
        * Emitted if an error occurs.
        * @param keepGoing               True if the plugin can continue processing.
        *                                False if the plugin cannot continue, for example,
        *                                the speech engine could not be started.
        * @param msg                     Error message.
        *
        * When an error occurs, plugins should attempt to recover as best they can
        * and continue accepting @ref sayText or @ref synthText calls.  For example,
        * if the speech engine emits an error while synthesizing text, the plugin
        * should return True along with error message.
        *
        * @see Error-handling
        *
        */
        void error(bool keepGoing, const QString &msg);
};

#endif // _PLUGINPROC_H_