kttsd/plugins/festivalint/festivalintproc.h

   1 /***************************************************** vim:set ts=4 sw=4 sts=4:
   2   Main speaking functions for the Festival (Interactive) Plug in
   3   -------------------
   4   Copyright:
   5   (C) 2004 by Gary Cramblitt <garycramblitt@comcast.net>
   6   -------------------
   7   Original author: Gary Cramblitt <garycramblitt@comcast.net>
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; either version 2 of the License, or
  12   (at your option) any later version.
  13
  14   This program is distributed in the hope that it will be useful,
  15   but WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17   GNU General Public License for more details.
  18
  19   You should have received a copy of the GNU General Public License
  20   along with this program; if not, write to the Free Software
  21   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  22  ******************************************************************************/
  23
  24 #ifndef _FESTIVALINTPROC_H_
  25 #define _FESTIVALINTPROC_H_
  26
  27 #include <QMutex>
  28
  29 #include <k3process.h>
  30
  31 #include <pluginproc.h>
  32
  33 class QTextCodec;
  34
  35 class FestivalIntProc : public PlugInProc{
  36     Q_OBJECT
  37
  38     public:
  39         enum SupportsSSML {
  40             ssUnknown,
  41             ssYes,
  42             ssNo
  43         };
  44
  45         /**
  46          * Constructor
  47          */
  48         FestivalIntProc( QObject* parent = 0, const QStringList &args = QStringList());
  49
  50         /**
  51          * Destructor
  52          */
  53         virtual ~FestivalIntProc();
  54
  55         /**
  56          * Initializate the speech engine.
  57          * @param config          Settings object.
  58          * @param configGroup     Settings group.
  59          */
  60         virtual bool init(KConfig *config, const QString &configGroup);
  61
  62         /**
  63          * Returns true when festival is ready to speak a sentence.
  64          */
  65         bool isReady();
  66
  67         /**
  68          * Say a text string.
  69          * @param text            The text to speak.
  70          */
  71         virtual void sayText(const QString &text);
  72
  73         /**
  74         * Synthesize text into an audio file, but do not send to the audio device.
  75         * @param text                    The text to be synthesized.
  76         * @param suggestedFilename       Full pathname of file to create.  The plugin
  77         *                                may ignore this parameter and choose its own
  78         *                                filename.  KTTSD will query the generated
  79         *                                filename using getFilename().
  80         *
  81         * If the plugin supports asynchronous operation, it should return immediately
  82         * and emit @ref synthFinished signal when synthesis is completed.
  83         * It must also implement the @ref getState method, which must return
  84         * psFinished, when synthesis is completed.
  85         */
  86         virtual void synthText(const QString &text, const QString &suggestedFilename);
  87
  88         /**
  89         * Get the generated audio filename from call to @ref synthText.
  90         * @return                        Name of the audio file the plugin generated.
  91         *                                Null if no such file.
  92         *
  93         * The plugin must not re-use or delete the filename.  The file may not
  94         * be locked when this method is called.  The file will be deleted when
  95         * KTTSD is finished using it.
  96         */
  97         virtual QString getFilename();
  98
  99         /**
 100         * Stop current operation (saying or synthesizing text).
 101         * Important: This function may be called from a thread different from the
 102         * one that called sayText or synthText.
 103         * If the plugin cannot stop an in-progress @ref sayText or
 104         * @ref synthText operation, it must not block waiting for it to complete.
 105         * Instead, return immediately.
 106         *
 107         * If a plugin returns before the operation has actually been stopped,
 108         * the plugin must emit the @ref stopped signal when the operation has
 109         * actually stopped.
 110         *
 111         * The plugin should change to the psIdle state after stopping the
 112         * operation.
 113         */
 114         virtual void stopText();
 115
 116         /**
 117         * Return the current state of the plugin.
 118         * This function only makes sense in asynchronous mode.
 119         * @return                        The pluginState of the plugin.
 120         *
 121         * @see pluginState
 122         */
 123         virtual pluginState getState();
 124
 125         /**
 126         * Acknowledges a finished state and resets the plugin state to psIdle.
 127         *
 128         * If the plugin is not in state psFinished, nothing happens.
 129         * The plugin may use this call to do any post-processing cleanup,
 130         * for example, blanking the stored filename (but do not delete the file).
 131         * Calling program should call getFilename prior to ackFinished.
 132         */
 133         virtual void ackFinished();
 134
 135         /**
 136         * Returns True if the plugin supports asynchronous processing,
 137         * i.e., returns immediately from sayText or synthText.
 138         * @return                        True if this plugin supports asynchronous processing.
 139         *
 140         * If the plugin returns True, it must also implement @ref getState .
 141         * It must also emit @ref sayFinished or @ref synthFinished signals when
 142         * saying or synthesis is completed.
 143         */
 144         virtual bool supportsAsync();
 145
 146         /**
 147         * Returns True if the plugin supports synthText method,
 148         * i.e., is able to synthesize text to a sound file without
 149         * audibilizing the text.
 150         * @return                        True if this plugin supports synthText method.
 151         *
 152         * If the plugin returns True, it must also implement the following methods:
 153         * - @ref synthText
 154         * - @ref getFilename
 155         * - @ref ackFinished
 156         *
 157         * If the plugin returns True, it need not implement @ref sayText .
 158         */
 159         virtual bool supportsSynth();
 160
 161         /**
 162         * Say or Synthesize text with the given voice code.
 163         * @param festivalExePath         Path to the Festival executable, or just "festival".
 164         * @param text                    The text to be synthesized.
 165         * @param suggestedFilename       If not Null, synthesize only to this filename, otherwise
 166         *                                synthesize and audibilize the text.
 167         * @param voiceCode               Voice code.
 168         * @param time                    Speed percentage. 50 to 200. 200% = 2x normal.
 169         * @param pitch                   Pitch persentage.  50 to 200.
 170         * @param volume                  Volume percentage.  50 to 200.
 171         * @param languageCode            Language code, for example, "en".
 172         */
 173         void synth(const QString &festivalExePath, const QString &text,
 174             const QString &synthFilename, const QString& voiceCode,
 175             int time, int pitch, int volume, const QString &languageCode,
 176             QTextCodec* codec);
 177
 178         /**
 179         * Sends commands to Festival to query for a list of supported voice codes.
 180         * Fires queryVoicesFinished when completed.
 181         * @return                       False if busy doing something else and therefore cannot
 182         *                               do the query.
 183         */
 184         bool queryVoices(const QString &festivalExePath);
 185
 186         /**
 187         * Returns the name of an XSLT stylesheet that will convert a valid SSML file
 188         * into a format that can be processed by the synth.  For example,
 189         * The Festival plugin returns a stylesheet that will convert SSML into
 190         * SABLE.  Any tags the synth cannot handle should be stripped (leaving
 191         * their text contents though).  The default stylesheet strips all
 192         * tags and converts the file to plain text.
 193         * @return            Name of the XSLT file.
 194         */
 195         QString getSsmlXsltFilename();
 196
 197         /**
 198         * Whether Festival supports SSML or not.
 199         * 0 = Unknown
 200         * 1 = Yes
 201         * 2 = No
 202         */
 203         SupportsSSML supportsSSML() { return m_supportsSSML; }
 204
 205     signals:
 206         /**
 207         * This signal fires upon completion of a queryVoices operation.
 208         * The list of voice codes do not have "voice_" prefix.
 209         */
 210         void queryVoicesFinished(const QStringList &voiceCodes);
 211
 212     private slots:
 213         void slotProcessExited(K3Process* proc);
 214         void slotReceivedStdout(K3Process* proc, char* buffer, int buflen);
 215         void slotReceivedStderr(K3Process* proc, char* buffer, int buflen);
 216         void slotWroteStdin(K3Process* proc);
 217
 218     private:
 219         /**
 220         * Start Festival engine.
 221         * @param festivalExePath         Path to the Festival executable, or just "festival".
 222         * @param voiceCode               Voice code in which to speak text.
 223         * @param languageCode            Language code, for example, "en".
 224         */
 225         void startEngine(const QString &festivalExePath, const QString &voiceCode,
 226             const QString &languageCode, QTextCodec* codec);
 227
 228         /**
 229         * If ready for more output, sends the given text to Festival process, otherwise,
 230         * puts it in the queue.
 231         * @param text                    Text to send or queue.
 232         */
 233         void sendToFestival(const QString& text);
 234
 235         /**
 236         * If Festival is ready for more input and there is more output to send, send it.
 237         * To be ready for more input, the Stdin buffer must be empty and the "festival>"
 238         * prompt must have been received (m_ready = true).
 239         * @return                        False when Festival is ready for more input
 240         *                                but there is nothing to be sent, or if Festival
 241         *                                has exited.
 242         */
 243         bool sendIfReady();
 244
 245         /**
 246         * Determine if the text has SABLE tags.  If so, we will have to use a different
 247         * synthesis method.
 248         */
 249         bool isSable(const QString &text);
 250
 251         /**
 252         * We attempt to shorten sentences longer than this by replacing commas with periods.
 253         */
 254         static const int c_tooLong = 600;
 255
 256         /**
 257         * Path to the Festival executable.
 258         */
 259         QString m_festivalExePath;
 260
 261         /**
 262         * Selected voice (from config).
 263         */
 264         QString m_voiceCode;
 265
 266         /**
 267         * True if the voice is preloaded.  Also used as a flag to suppress killing
 268         * Festival, since startup time will be excessive.
 269         */
 270         bool m_preload;
 271
 272         /**
 273         * Selected speed (from config).
 274         */
 275         int m_time;
 276
 277         /**
 278         * Selected pitch (frequency) (from config).
 279         */
 280         int m_pitch;
 281
 282         /**
 283          * Selected volume (from config).
 284          */
 285         int m_volume;
 286
 287         /**
 288         * Running voice.
 289         */
 290         QString m_runningVoiceCode;
 291
 292         /**
 293         * Running time (speed).
 294         */
 295         int m_runningTime;
 296
 297         /**
 298         * Running pitch (frequency).
 299         */
 300         int m_runningPitch;
 301
 302         /**
 303          * Festival process
 304          */
 305         K3Process* m_festProc;
 306
 307         /**
 308         * Synthesis filename.
 309         */
 310         QString m_synthFilename;
 311
 312         /**
 313          * True when festival is ready for another input.
 314          */
 315         volatile bool m_ready;
 316
 317         /**
 318         * Plugin state.
 319         */
 320         pluginState m_state;
 321
 322         /**
 323         * True when stopText has been called.  Used to force transition to psIdle when
 324         * Festival exits.
 325         */
 326         bool m_waitingStop;
 327
 328         /**
 329         * True when queryVoices has been called.
 330         */
 331         bool m_waitingQueryVoices;
 332
 333         /**
 334         * A queue of outputs to be sent to the Festival process.
 335         * Since Festival requires us to wait until the "festival>" prompt before
 336         * sending the next command, this queue allows us to queue up multiple
 337         * commands and send each one when the ReceivedStdOut signal fires.
 338         */
 339         QStringList m_outputQueue;
 340
 341         bool m_writingStdin;
 342
 343         /**
 344         * Language code.
 345         */
 346         QString m_languageCode;
 347
 348         /**
 349         * Codec.
 350         */
 351         QTextCodec* m_codec;
 352
 353         /**
 354         * Flag if SSML is supported.  Festival cannot support SABLE (and therefore SSML)
 355         * unless rab_diphone (British male) is installed. Gawd, I hope Festival folks fix this!
 356         */
 357         SupportsSSML m_supportsSSML;
 358 };
 359
 360 #endif // _FESTIVALINTPROC_H_