kttsd/filters/sbd/sbdproc.h

   1 /***************************************************** vim:set ts=4 sw=4 sts=4:
   2   Sentence Boundary Detection (SBD) Filter class.
   3   -------------------
   4   Copyright:
   5   (C) 2005 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 /******************************************************************************
  25
  26   This class performs three kinds of SBD:
  27     1.  If the text is SSML, generates new SSML where the prosody and voice
  28         tags are fully specified for each sentence.  This allows user to
  29         advance or rewind by sentence without losing SSML context.
  30         Input is considered to be SSML if the top-level element is a
  31         <speak> tag.
  32     2.  If the text is code, each line is considered to be a sentence.
  33         Input is considered to be code if any of the following strings are
  34         detected:
  35             slash asterisk
  36             if left-paren
  37             pound include
  38     3.  If the text is plain text, performs SBD using specified Regular
  39         Expression.
  40
  41   Text is output with tab characters (\t) separating sentences.
  42
  43  ******************************************************************************/
  44
  45 #ifndef SBDPROC_H
  46 #define SBDPROC_H
  47
  48 // Qt includes.
  49 #include <QtCore/QObject>
  50 #include <QtCore/QThread>
  51 #include <QtCore/QEvent>
  52 #include <QtCore/QStack>
  53 #include <QtCore/QStringList>
  54
  55 // KTTS includes.
  56 #include "filterproc.h"
  57
  58 class TalkerCode;
  59 class KConfig;
  60 class QDomElement;
  61 class QDomNode;
  62
  63 class SbdThread: public QThread
  64 {
  65     Q_OBJECT
  66
  67     public:
  68         /**
  69          * Constructor.
  70          */
  71         SbdThread( QObject *parent = 0);
  72
  73         /**
  74          * Destructor.
  75          */
  76         virtual ~SbdThread();
  77
  78         /**
  79          * Get/Set text being processed.
  80          */
  81         void setText( const QString& text );
  82         QString text();
  83
  84         /**
  85          * Set/Get TalkerCode.
  86          */
  87         void setTalkerCode( TalkerCode* talkerCode );
  88         TalkerCode* talkerCode();
  89
  90         /**
  91          * Set Sentence Boundary Regular Expression.
  92          * This method will only be called if the application overrode the default.
  93          *
  94          * @param re            The sentence delimiter regular expression.
  95          */
  96         void setSbRegExp( const QString& re );
  97
  98         /**
  99          * The configured Sentence Boundary Regular Expression.
 100          *
 101          * @param re            The sentence delimiter regular expression.
 102          */
 103         void setConfiguredSbRegExp( const QString& re );
 104
 105         /**
 106          * The configured Sentence Boundary that replaces SB regular expression.
 107          *
 108          * @param sb            The sentence boundary replacement.
 109          *
 110          */
 111         void setConfiguredSentenceBoundary( const QString& sb );
 112
 113         /**
 114          * Did this filter do anything?  If the filter returns the input as output
 115          * unmolested, it should return False when this method is called.
 116          */
 117         void setWasModified(bool wasModified);
 118         bool wasModified();
 119
 120     signals:
 121         void filteringFinished();
 122
 123     protected:
 124         virtual void run();
 125         virtual bool event ( QEvent * e );
 126
 127     private:
 128         enum TextType {
 129             ttSsml,             // SSML
 130             ttCode,             // Code
 131             ttPlain             // Plain text
 132         };
 133
 134         enum SsmlElemType {
 135             etSpeak,
 136             etVoice,
 137             etProsody,
 138             etEmphasis,
 139             etPS,               // Paragraph or sentence (we don't care).
 140             etBreak,
 141             etNotSsml
 142         };
 143
 144         // Speak Element.
 145         struct SpeakElem {
 146             QString lang;               // xml:lang="en".
 147         };
 148
 149         // Voice Element.
 150         struct VoiceElem {
 151             QString lang;               // xml:lang="en".
 152             QString gender;             // "male", "female", or "neutral".
 153             uint age;                   // Age in years.
 154             QString name;               // Synth-specific voice name.
 155             QString variant;            // Ignored.
 156         };
 157
 158         // Prosody Element.
 159         struct ProsodyElem {
 160             QString pitch;              // "x-low", "low", "medium", "high", "x-high", "default".
 161             QString contour;            // Pitch contour (ignored).
 162             QString range;              // "x-low", "low", "medium", "high", "x-high", "default".
 163             QString rate;               // "x-slow", "slow", "medium", "fast", "x-fast", "default".
 164             QString duration;           // Ignored.
 165             QString volume;             // "silent", "x-soft", "soft", "medium", "load", "x-load", "default".
 166         };
 167
 168         // Emphasis Element.
 169         struct EmphasisElem {
 170             QString level;              // "strong", "moderate", "none" and "reduced"
 171         };
 172
 173         // Break Element.
 174         struct BreakElem {
 175             QString strength;           // "x-weak", "weak", "medium" (default value), "strong",
 176                                         // or "x-strong", "none"
 177             QString time;               // Ignored.
 178         };
 179
 180         // Paragraph and Sentence Elements.
 181         struct PSElem {
 182             QString lang;               // xml:lang="en".
 183         };
 184
 185         // Given a tag name, returns SsmlElemType.
 186         SsmlElemType tagToSsmlElemType(const QString tagName);
 187         // Parses an SSML element, pushing current settings onto the context stack.
 188         void pushSsmlElem( SsmlElemType et, const QDomElement& elem );
 189         // Given an attribute name and value, constructs an XML representation of the attribute,
 190         // i.e., name="value".
 191         QString makeAttr( const QString& name, const QString& value );
 192         // Returns an XML representation of an SSML tag from the top of the context stack.
 193         QString makeSsmlElem( SsmlElemType et );
 194         // Pops element from the indicated context stack.
 195         void popSsmlElem( SsmlElemType et );
 196         QString makeBreakElem( const QDomElement& e );
 197         // Converts a text fragment into a CDATA section.
 198         QString makeCDATA( const QString& text );
 199         // Returns an XML representation of an utterance node consisting of voice,
 200         // prosody, and emphasis elements.
 201         QString makeSentence( const QString& text );
 202         // Starts a sentence by returning a speak tag.
 203         QString startSentence();
 204         // Ends a sentence and appends a Tab.
 205         QString endSentence();
 206         // Parses a node of the SSML tree and recursively parses its children.
 207         // Returns the filtered text with each sentence a complete ssml tree.
 208         QString parseSsmlNode( QDomNode& n, const QString& re );
 209
 210         // Parses Ssml.
 211         QString parseSsml( const QString& inputText, const QString& re );
 212         // Parses code.  Each newline is converted into a tab character (\t).
 213         QString parseCode( const QString& inputText );
 214         // Parses plain text.
 215         QString parsePlainText( const QString& inputText, const QString& re );
 216
 217         // Context stacks.
 218         QStack<SpeakElem> m_speakStack;
 219         QStack<VoiceElem> m_voiceStack;
 220         QStack<ProsodyElem> m_prosodyStack;
 221         QStack<EmphasisElem> m_emphasisStack;
 222         QStack<PSElem> m_psStack;
 223
 224         // The text being processed.
 225         QString m_text;
 226         // Talker Code.
 227         TalkerCode* m_talkerCode;
 228         // Configured default Sentence Delimiter regular expression.
 229         QString m_configuredRe;
 230         // Configured Sentence Boundary replacement expression.
 231         QString m_configuredSentenceBoundary;
 232         // Application-specified Sentence Delimiter regular expression (if any).
 233         QString m_re;
 234         // False if input was not modified.
 235         bool m_wasModified;
 236         // True when a sentence has been started.
 237         bool m_sentenceStarted;
 238 };
 239
 240 class SbdProc : virtual public KttsFilterProc
 241 {
 242     Q_OBJECT
 243
 244     public:
 245         /**
 246          * Constructor.
 247          */
 248         explicit SbdProc( QObject *parent, const QVariantList &args);
 249
 250         /**
 251          * Destructor.
 252          */
 253         virtual ~SbdProc();
 254
 255         /**
 256          * Initialize the filter.
 257          * @param config          Settings object.
 258          * @param configGroup     Settings Group.
 259          * @return                False if filter is not ready to filter.
 260          *
 261          * Note: The parameters are for reading from kttsdrc file.  Plugins may wish to maintain
 262          * separate configuration files of their own.
 263          */
 264         virtual bool init( KConfig *config, const QString &configGroup );
 265
 266         /**
 267          * Returns True if this filter is a Sentence Boundary Detector.
 268          * If so, the filter should implement @ref setSbRegExp() .
 269          * @return          True if this filter is a SBD.
 270          */
 271         virtual bool isSBD();
 272
 273         /**
 274          * Returns True if the plugin supports asynchronous processing,
 275          * i.e., supports asyncConvert method.
 276          * @return                        True if this plugin supports asynchronous processing.
 277          *
 278          * If the plugin returns True, it must also implement @ref getState .
 279          * It must also emit @ref filteringFinished when filtering is completed.
 280          * If the plugin returns True, it must also implement @ref stopFiltering .
 281          * It must also emit @ref filteringStopped when filtering has been stopped.
 282          */
 283         virtual bool supportsAsync();
 284
 285         /**
 286          * Convert input, returning output.  Runs synchronously.
 287          * @param inputText         Input text.
 288          * @param talkerCode        TalkerCode structure for the talker that KTTSD intends to
 289          *                          use for synthing the text.  Useful for extracting hints about
 290          *                          how to filter the text.  For example, languageCode.
 291          * @param appId             The DCOP appId of the application that queued the text.
 292          *                          Also useful for hints about how to do the filtering.
 293          */
 294         virtual QString convert( const QString& inputText, TalkerCode* talkerCode, const QString& appId );
 295
 296         /**
 297          * Convert input.  Runs asynchronously.
 298          * @param inputText         Input text.
 299          * @param talkerCode        TalkerCode structure for the talker that KTTSD intends to
 300          *                          use for synthing the text.  Useful for extracting hints about
 301          *                          how to filter the text.  For example, languageCode.
 302          * @param appId             The DCOP appId of the application that queued the text.
 303          *                          Also useful for hints about how to do the filtering.
 304          * @return                  False if the filter cannot perform the conversion.
 305          *
 306          * When conversion is completed, emits signal @ref filteringFinished.  Calling
 307          * program may then call @ref getOutput to retrieve converted text.  Calling
 308          * program must call @ref ackFinished to acknowledge the conversion.
 309          */
 310         virtual bool asyncConvert( const QString& inputText, TalkerCode* talkerCode, const QString& appId );
 311
 312         /**
 313          * Waits for a previous call to asyncConvert to finish.
 314          */
 315         virtual void waitForFinished();
 316
 317         /**
 318          * Returns the state of the Filter.
 319          */
 320         virtual int getState();
 321
 322         /**
 323          * Returns the filtered output.
 324          */
 325         virtual QString getOutput();
 326
 327         /**
 328          * Acknowledges the finished filtering.
 329          */
 330         virtual void ackFinished();
 331
 332         /**
 333          * Stops filtering.  The filteringStopped signal will emit when filtering
 334          * has in fact stopped and state returns to fsIdle;
 335          */
 336         virtual void stopFiltering();
 337
 338         /**
 339          * Did this filter do anything?  If the filter returns the input as output
 340          * unmolested, it should return False when this method is called.
 341          */
 342         virtual bool wasModified();
 343
 344         /**
 345          * Set Sentence Boundary Regular Expression.
 346          */
 347         virtual void setSbRegExp( const QString& re );
 348
 349     private slots:
 350         // Received when SBD Thread finishes.
 351         void slotSbdThreadFilteringFinished();
 352
 353     private:
 354         // If not empty, apply filters only to apps using talkers speaking these language codes.
 355         QStringList m_languageCodeList;
 356         // If not empty, apply filter only to apps containing this string.
 357         QStringList m_appIdList;
 358         // SBD Thread Object.
 359         SbdThread* m_sbdThread;
 360         // State.
 361         int m_state;
 362         // Configured default Sentence Delimiter regular expression.
 363         QString m_configuredRe;
 364 };
 365
 366 #endif      // SBDPROC_H