/***************************************************** vim:set ts=4 sw=4 sts=4: kspeech.h KTTSD DCOP Interface -------------------- Copyright: (C) 2002-2003 by José Pablo Ezequiel "Pupeno" Fernández (C) 2003-2004 by Olaf Schmidt (C) 2004-2005 by Gary Cramblitt ------------------- Original author: José Pablo Ezequiel "Pupeno" Fernández ******************************************************************************/ /*************************************************************************** * * * 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 _KSPEECH_H_ #define _KSPEECH_H_ #include #include /** * @interface KSpeech * * kspeech - the KDE Text-to-Speech API. * * @version 1.0 Draft 10 * * @since KDE 3.4 * * This class defines the DCOP interface for applications desiring to speak text. * Applications may speak text by sending DCOP messages to application "kttsd" object "KSpeech". * * %KTTSD -- the KDE Text-to-Speech Deamon -- is the program that supplies the services * in the KDE Text-to-Speech API. * * @warning The KSpeech interface is still being developed and is likely to change in the future. * * @section Features * * - Priority system for Screen Readers, warnings and messages, while still playing * regular texts. * - Long text is parsed into sentences. User may backup by sentence or part, * replay, pause, and stop playing. * - Handles multiple speaking applications. Text messages are treated like print jobs. * Jobs may be created, started, stopped, paused, resumed, and deleted. * - Speak contents of clipboard. * - Speak KDE notifications. * - Plugin-based text job filtering permits substitution for misspoken words, * abbreviations, etc., transformation of XML or XHTML to SSML, and automatic * choice of appropriate synthesis engine. * * @section Requirements * * You may build any KDE application to use KSpeech, since the interface is in kdelibs, but * the kdeaccessibility package must be installed for KTTS to function. * * You will need a speech synthesis engine, such as Festival. See the KTTS Handbook * for the latest information on installing and configuring speech engines and voices * with KTTS. * * @section goals Design Goals * * The KDE Text-to-Speech API is designed with the following goals: * * - Support the features enumerated above. * - Plugin-based architecture for support of a wide variety of speech synthesis * engines and drivers. * - Permit generation of speech from the command line (or via shell scripts) * using the KDE DCOP utilities. * - Provide a lightweight and easily usable interface for applications to * generate speech output. * - Applications need not be concerned about contention over the speech device. * - Provide limited support for speech markup languages, such as Sable, * Java %Speech Markup Language (JSML), and %Speech Markup Meta-language (SMML). * - Provide limited support for embedded speech markers. * - Asynchronous to prevent system blocking. * - Plugin-based audio architecture. Currently supports aRts but will support * additional audio engines in the future, such as gstreamer. * - Compatible with original %KTTSD API as developed by José Pablo Ezequiel * "Pupeno" Fernández (avoid breaking existing applications). * * Architecturally, applications interface with %KTTSD, which performs queueing, * speech job managment, plugin management and sentence parsing. %KTTSD interfaces with a * %KTTSD speech plugin(s), which then interfaces with the speech engine(s) or driver(s). * @verbatim application ^ | via DCOP (the KDE Text-to-Speech API) v kttsd ^ | KTTSD plugin API v kttsd plugin ^ | v speech engine @endverbatim * * The %KTTSD Plugin API is documented in PluginConf in the kdeaccessibility module. * * There is a separate GUI application, called kttsmgr, for providing %KTTSD * configuration and job management. * * kttsd maintains 4 types of speech output: * - Screen Reader Output * - Warnings * - Messages * - Text Jobs * * Method sayScreenReaderOutput speaks Screen Reader output. * It pre-empts any other speech in progress, * including other Screen Reader outputs, i.e., it is not a queue. * This method is reserved for use by Screen Readers. * * Methods sayWarning and sayMessage place messages into the Warnings and * Messages queues respectively. Warnings take priority over messages, which take priority * over text jobs. Warnings and messages are spoken when the currently-speaking * sentence of a text job is finished. * * setText places text into the text job queue. startText begins speaking jobs. * When one job finishes, the next job begins. Method appendText adds * additional parts to a text job. Within a text job, the application (and user * via the kttsmgr GUI), may back up or advance by sentence or part, or rewind * to the beginning. * See jumpToTextPart and moveRelTextSentence. * Text jobs may be paused, stopped, and resumed or deleted from the queue. * See pauseText, stopText, resumeText, and removeText. * * @section cmdline DCOP Command-line Interface * * To create a text job to be spoken * @verbatim dcop kttsd KSpeech setText @endverbatim * * where \ is the text to be spoken, and \ is usually a language code * such as "en", "cy", etc. * * Example. * @verbatim dcop kttsd KSpeech setText "This is a test." "en" @endverbatim * * To start speaking the text. * @verbatim dcop kttsd KSpeech startText 0 @endverbatim * * You can combine the setText and startText commands into a single command. * @verbatim dcop kttsd KSpeech sayText @endverbatim * * @since KDE 3.5 * * To stop speaking and rewind to the beginning of the text. * @verbatim dcop kttsd KSpeech stopText 0 @endverbatim * * Depending upon the speech plugin used, speaking may not immediately stop. * * To stop and remove a text job. * @verbatim dcop kttsd KSpeech removeText 0 @endverbatim * * Note: For more information about talker codes, see talkers below. * * @section programming Calling KTTSD from a Program * * There are two methods of making DCOP calls from your application to %KTTSD. * * - Manually code them using dcopClient object. See kdebase/konqueror/kttsplugin/khtmlkttsd.cpp * for an example. This method is recommended if you want to make a few simple calls to KTTSD. * - Use kspeech_stub as described below. This method generates the marshalling code for you * and is recommended for a more complex speech-enabled applications. kcmkttsmgr in the * kdeaccessibility module is an example that uses this method. * * To make DCOP calls from your program using kspeech_stub, follow these steps: * * 1. Include kspeech_stub.h in your code. Derive an object from the KSpeech_stub interface. * For example, suppose you are developing a KPart and want to call %KTTSD. * Your class declaration might look like this: * @verbatim #include class MyPart: public KParts::ReadOnlyPart, public KSpeech_stub { @endverbatim * * 2. In your class constructor, initialize DCOPStub, giving it the sender * "kttsd", object "KSpeech". * @verbatim MyPart::MyPart(TQWidget *tqparent, const char *name) : KParts::ReadOnlyPart(tqparent, name), DCOPStub("kttsd", "KSpeech") { @endverbatim * * 3. See if KTTSD is running, and if not, start it. * @verbatim DCOPClient *client = dcopClient(); client->attach(); if (!client->isApplicationRegistered("kttsd")) { TQString error; if (KApplication::startServiceByDesktopName("kttsd", TQStringList(), &error)) cout << "Starting KTTSD failed with message " << error << endl; } @endverbatim * * If you want to detect if KTTSD is installed without starting it, use this code. * @verbatim KTrader::OfferList offers = KTrader::self()->query("DCOP/Text-to-Speech", "Name == 'KTTSD'"); if (offers.count() > 0) { // KTTSD is installed. } @endverbatim * * Typically, you would do this to hide a menu item or button if KTTSD is not installed. * * 4. Make calls to KTTSD in your code. * @verbatim uint jobNum = setText("Hello World", "en"); startText(jobNum); @endverbatim * * 4. Add kspeech_DIR and kspeech.stub to your Makefile.am. Example: * @verbatim kspeech_DIR = $(kde_includes) libmypart_la_SOURCES = kspeech.stub @endverbatim * * @section signals Signals Emitted by KTTSD * * %KTTSD emits a number of DCOP signals, which provide information about sentences spoken, * text jobs started, stopped, paused, resumed, finished, or deleted and markers seen. * In general, these signals are broadcast to any application that connects to them. * Applications should check the appId argument to determine whether the signal belongs to * them or not. * * To receive %KTTSD DCOP signals, follow these steps: * * 1. Include kspeechsink.h in your code. Derive an object from the KSpeechSink interface * and declare a method for each signal you'd like to receive. For example, * if you were coding a KPart and wanted to receive the KTTSD signal sentenceStarted: * @verbatim #include class MyPart: public KParts::ReadOnlyPart, virtual public KSpeechSink { protected: ASYNC sentenceStarted(const TQCString& appId, const uint jobNum, const uint seq); @endverbatim * * You can combine sending and receiving in one object. * @verbatim #include class MyPart: public KParts::ReadOnlyPart, public KSpeech_stub, virtual public KSpeechSink { protected: ASYNC sentenceStarted(const TQCString& appId, const uint jobNum, const uint seq); @endverbatim * * See below for the signals you can declare. * * 2. In your class constructor, initialize DCOPObject with the name of your DCOP * receiving object. * @verbatim MyPart::MyPart(TQWidget *tqparent, const char *name) : KParts::ReadOnlyPart(tqparent, name), DCOPObject("mypart_kspeechsink") { @endverbatim * * Use any name you like. * * 3. Where appropriate (usually in your constructor), make sure your DCOPClient * is registered and connect the %KTTSD DCOP signals to your declared receiving * methods. * @verbatim // Register DCOP client. DCOPClient *client = kapp->dcopClient(); if (!client->isRegistered()) { client->attach(); client->registerAs(kapp->name()); } // Connect KTTSD DCOP signals to our slots. connectDCOPSignal("kttsd", "KSpeech", "sentenceStarted(TQCString,uint,uint)", "sentenceStarted(TQCString,uint,uint)", false); @endverbatim * * Notice that the argument signatures differ slightly from the actual declarations. For * example * @verbatim ASYNC sentenceStarted(const TQCString& appId, const uint jobNum, const uint seq); @endverbatim * * becomes * @verbatim "sentenceStarted(TQCString,uint,uint)", @endverbatim * * in the connectDCOPSignal call. * * 4. Write the definition for the received signal. Be sure to check whether the signal * is intended for your application. * @verbatim ASYNC MyPart::sentenceStarted(const TQCString& appId, const uint jobNum, const uint seq) { // Check appId to determine if this is our signal. if (appId != dcopClient()->appId()) return; // Do something here. } @endverbatim * * 5. Add kspeechsink_DIR and kspeechsink.skel to your Makefile.am. Example for an app * both sending and receiving. * @verbatim kspeech_DIR = $(kde_includes) kspeechsink_DIR = $(kde_includes) libmypart_la_SOURCES = kspeech.stub kspeechsink.skel @endverbatim * * @section talkers Talkers, Talker Codes, and Plugins * * Many of the methods permit you to specify a desired "talker". This * may be a simple language code, such as "en" for English, "es" for Spanish, etc. * Code as NULL to use the default configured talker. * * Within KTTSMGR, the user has the ability to configure more than one talker for each language, * with different voices, genders, volumes, and talking speeds. * * Talker codes serve two functions: * - They identify configured plugins, and * - They provide a way for applications to specify the desired speaking attributes * that influence the choice of plugin to speak text. * * A Talker Code consists of a series of XML tags and attributes. * An example of a full Talker Code with all attributes specified is * * * * * * (The @e voice and @e prosody tags are adapted from the W3C Speech Synthesis * Markup Language (SSML) and Java Speech Markup Language (JSML). * The @e kttsd tag is an extension to the SMML and JSML languages to support * named synthesizers and text encodings.) * %KTTS doesn't really care about the @e voice, @e prosody, and @e kttsd tags. In fact, * they may be omitted and just the attributes specified. The example above then * becomes * * lang="en" name="kal" gender="male" volume="soft" rate="fast" * synthesizer="Festival" * * The attributes may be specified in any order. * * For clarity, the rest of the discussion * will omit the @e voice, @e prosody, and @e kttsd tags. * * The attributes that make up a talker code are: * * - @e lang. Language code and optional country code. * Examples: en, es, en_US, en_GB. Codes * are case in-sensitive and hyphen (-) or underscore (_) may be * used to separate the country code from the language code. * - @e synthesizer. The name of the synthesizer (plugin) used to produce the speech. * - @e gender. May be either "male", "female", or "neutral". * - @e name. The name of the voice code. * The choice of voice codes is synthesizer-specific. * - @e volume. May be "loud", "medium", or "quiet". A synonym for "quiet" is * "soft". * - @e rate. May be "fast", "medium", or "slow". * * Each plugin, once it has been configured by a user in kttsmgr, returns a * fully-specified talker code to identify itself. If the plugin supports it, * the user may configure another instance of the plugin with a different set * of attributes. This is the difference between a "plugin" and a "talker". * A talker is a configured instance of a plugin. Each plugin (if it supports it) * may be configured as multiple talkers. * * When the user configures %KTTSD, she configures one or more talkers and then * places them in preferred order, top to bottom in kttsmgr. In effect, * she specifies her preferences for each of the talkers. * * When applications specify a talker code, they need not (and typically do not) * give a full specification. An example of a talker code with only some of the * attributes specified might be * * lang="en" gender="female" * * If the talker code is not in XML attribute format, it assumed to be a @e lang * attribute. So the talker code * * en * * is interpreted as * * lang="en" * * When a program requests a talker code in calls to setText, appendText, * sayMessage, sayWarning, and sayScreenReaderOutput, * %KTTSD tries to match the requested talker code to the closest matching * configured talker. * * The @e lang attribute has highest priority (attempting to speak English with * a Spanish synthesizer would likely be unintelligible). So the language * attribute is said to have "priority". * If an application does not specify a language attribute, a default one will be assumed. * The rest of the attributes are said to be "preferred". If %KTTSD cannot find * a talker with the exact preferred attributes requested, the closest matching * talker will likely still be understandable. * * An application may specify that one or more of the attributes it gives in a talker * code have priority by preceeding each priority attribute with an asterisk. * For example, the following talker code * * lang="en" gender="*female" volume="soft" * * means that the application wants to use a talker that supports American English language * and Female gender. If there is more than one such talker, one that supports * Soft volume would be preferred. Notice that a talker configured as English, Male, * and Soft volume would not be picked as long as an English Female talker is * available. * * The algorithm used by %KTTSD to find a matching talker is as follows: * * - If language code is not specified by the application, assume default configured * by user. The primary language code automatically has priority. * - (Note: This is not yet implemented.) * If there are no talkers configured in the language, %KTTSD will attempt * to automatically configure one (see automatic configuraton discussion below) * - The talker that matches on the most priority attributes wins. * - If a tie, the one that matches on the most preferred attributes wins. * - If there is still a tie, the one nearest the top of the kttsmgr display * (first configured) will be chosen. * * Language codes actually consist of two parts, a language code and an optional * country code. For example, en_GB is English (United Kingdom). The language code is * treated as a priority attribute, but the country code (if specified) is treated * as preferred. So for example, if an application requests the following * talker code * * lang="en_GB" gender="male" volume="medium" * * then a talker configured as lang="en" gender="male" volume="medium" would be * picked over one configured as lang="en_GB" gender="female" volume="soft", * since the former matches on two preferred attributes and the latter only on the * preferred attribute GB. An application can override this and make the country * code priority with an asterisk. For example, * * lang="*en_GB" gender="male" volume="medium" * * To specify that American English is priority, put an asterisk in front of * en_US, like this. * * lang="*en_US" gender="male" volume="medium" * * Here the application is indicating that a talker that speaks American English * has priorty over one that speaks a different form of English. * * (Note: Not yet implemented). * If a language code is specified, and no plugin is currently configured * with a matching language code, %KTTSD will attempt to automatically * load and configure a plugin to support the requested language. If * there is no such plugin, or there is a plugin but it cannot automatically * configure itself, %KTTSD will pick one of the configured plugins using the * algorithm given above. * * Notice that %KTTSD will always pick a talker, even if it is a terrible match. * (The principle is that something heard is better than nothing at all. If * it sounds terrible, user will change his configuration.) * If an attribute is absolutely mandatory -- in other words the application * must speak with the attribute or not at all -- the application can determine if * there are any talkers configured with the attribute by calling getTalkers, * and if there are none, display an error message to the user. * * Applications can implement their own talker-matching algorithm by * calling getTalkers, then finding the desired talker from the returned * list. When the full talker code is passed in, %KKTSD will find an exact * match and use the specified talker. * * If an application requires a configuration that user has not created, * it should display a message to user instructing them to run kttsmgr and * configure the desired talker. (This must be done interactively because * plugins often need user assistance locating voice files, etc.) * * The above scheme is designed to balance the needs * of applications against user preferences. Applications are given the control * they @e might need, without unnecessarily burdening the application author. * If you are an application author, the above discussion might seem overly * complicated. It isn't really all that complicated. Here are rules of thumb: * * - It is legitimate to give a NULL (0) talker code, in which case, the user's default * talker will be used. * - If you know the language code, give that in the talker code, otherwise * leave it out. * - If there is an attribute your application @e requires for proper functioning, * specify that with an asterisk in front of it. For example, your app might * speak in two different voices, Male and Female. (Since your * app requires both genders, call getTalkers to determine if both genders * are available, and if not, advise user to configure them. Better yet, * give the user a choice of available distinquishing attributes * (loud/soft, fast/slow, etc.) * - If there are other attributes you would prefer, specify those without an * asterisk, but leave them out if it doesn't really make any difference * to proper functioning of your application. Let the user decide them * when they configure %KTTS. * * One final note about talkers. %KTTSD does talker matching for each sentence * spoken, just before the sentence is sent to a plugin for synthesis. Therefore, * the user can change the effective talker in mid processing of a text job by * changing his preferences, or even deleting or adding new talkers to the configuration. * * @section markup Speech Markup * * Note: %Speech Markup is not yet fully implemented in %KTTSD. * * Each of the five methods for queueing text to be spoken -- sayScreenReaderOutput, * setText, appendText, sayMessage, and sayWarning -- may contain speech markup, * provided that the plugin the user has configured supports that markup. The markup * languages and plugins currently supported are: * * - %Speech Synthesis Markup language (SSML): Festival and Hadifix. * * This may change in the future as synthesizers improve. * * Before including markup in the text sent to kttsd, the application should * query whether the currently-configured plugin * supports the markup language by calling supportsMarkup. * * It it does not support the markup, it will be stripped out of the text. * * @section markers Support for Markers * * Note: Markers are not yet implemented in %KTTSD. * * When using a speech markup language, such as Sable, JSML, or SSML, the application may embed * named markers into the text. If the user's chosen speech plugin supports markers, %KTTSD * will emit DCOP signal markerSeen when the speech engine encounters the marker. * Depending upon the speech engine and plugin, this may occur either when the speech engine * encounters the marker during synthesis from text to speech, or when the speech is actually * spoken on the audio device. The calling application can call the supportsMarkers * method to determine if the currently configured plugin supports markers or not. * * @section sentenceparsing Sentence Parsing * * Not all speech engines provide robust capabilities for stopping synthesis that is in progress. * To compensate for this, %KTTSD parses text jobs given to it by the setText and * appendText methods into sentences and sends the sentences to the speech * plugin one at a time. In this way, should the user wish to stop the speech * output, they can do so, and the worst that will happen is that the last sentence * will be completed. This is called Sentence Boundary Detection (SBD). * * Sentence Boundary Detection also permits the user to rewind by sentences. * * The default sentence delimiter used for plain text is as follows: * * - A period (.), question mark (?), exclamation mark (!), colon (:), or * semi-colon (;) followed by whitespace (including newline), or * - Two newlines in a row separated by optional whitespace, or * - The end of the text. * * When given text containing speech markup, %KTTSD automatically determines the markup type * and parses based on the sentence semantics of the markup language. * * An application may change the sentence delimiter by calling setSentenceDelimiter * prior to calling setText. Changing the delimiter does not affect other * applications. * * Text given to %KTTSD via the sayWarning, sayMessage, and sayScreenReaderOutput * methods is @e not parsed into sentences. For this reason, applications * should @e not send long messages with these methods. * * Sentence Boundary Detection is implemented as a plugin SBD filter. See * filters for more information. * * @section filters Filters * * Users may specify filters in the kttsmgr GUI. Filters are plugins that modify the text * to be spoken or change other characteristics of jobs. Currently, the following filter plugins * are available: * * - String Replacer. Permits users to substitute for mispoken words, or vocalize chat * emoticons. * - XML Transformer. Given a particular XML or XHTML format, permits conversion of the * XML to SSML (Speech Synthesis Markup Language) using XSLT (XML Style Language - Transforms) * stylesheets. * - Talker Chooser. Permits users to redirect jobs from one configured Talker to another * based on the contents of the job or application that sent it. * * Additional plugins may be available in the future. * * In additional to these regular filters, KTTS also implements Sentence Boundary Detection (SBD) * as a plugin filter. See sentenceparsing for more information. * * Regular filters are applied to Warnings, Messages, and Text jobs. SBD filters are * only applied to regular Text jobs; they are not applied to Warnings and Messages. Screen * Reader Outputs are never filtered. * * @section authors Authors * * @author José Pablo Ezequiel "Pupeno" Fernández * @author Gary Cramblitt * @author Olaf Schmidt * @author Gunnar Schmi Dt */ // NOTE: kspeech class is now obsolete. Please use KSpeech instead. class KSpeech : virtual public DCOPObject { K_DCOP public: /** * @enum kttsdJobState * Job states returned by method getTextJobState. */ enum kttsdJobState { jsQueued = 0, /**< Job has been queued but is not yet speakable. */ jsSpeakable = 1, /**< Job is speakable, but is not speaking. */ jsSpeaking = 2, /**< Job is currently speaking. */ jsPaused = 3, /**< Job has been paused. */ jsFinished = 4 /**< Job is finished and is deleteable. */ }; /** * @enum kttsdMarkupType * %Speech markup language types. */ enum kttsdMarkupType { mtPlain = 0, /**< Plain text */ mtJsml = 1, /**< Java %Speech Markup Language */ mtSsml = 2, /**< %Speech Synthesis Markup Language */ mtSable = 3, /**< Sable 2.0 */ mtHtml = 4 /**< HTML @since 3.5 */ }; k_dcop: /** @name DCOP Methods */ //@{ /** * Determine whether the currently-configured speech plugin supports a speech markup language. * @param talker Code for the talker to do the speaking. Example "en". * If NULL, defaults to the user's default talker. * @param markupType The kttsd code for the desired speech markup language. * @return True if the plugin currently configured for the indicated * talker supports the indicated speech markup language. * @see kttsdMarkupType */ virtual bool supportsMarkup(const TQString &talker, uint markupType = 0) const = 0; /** * Determine whether the currently-configured speech plugin supports markers in speech markup. * @param talker Code for the talker to do the speaking. Example "en". * If NULL, defaults to the user's default talker. * @return True if the plugin currently configured for the indicated * talker supports markers. */ virtual bool supportsMarkers(const TQString &talker) const = 0; /** * Say a message as soon as possible, interrupting any other speech in progress. * IMPORTANT: This method is reserved for use by Screen Readers and should not be used * by any other applications. * @param msg The message to be spoken. * @param talker Code for the talker to do the speaking. Example "en". * If NULL, defaults to the user's default talker. * If no plugin has been configured for the specified Talker code, * defaults to the closest matching talker. * * If an existing Screen Reader output is in progress, it is stopped and discarded and * replaced with this new message. */ virtual ASYNC sayScreenReaderOutput(const TQString &msg, const TQString &talker) = 0; /** * Say a warning. The warning will be spoken when the current sentence * stops speaking and takes precedence over Messages and regular text. Warnings should only * be used for high-priority messages requiring immediate user attention, such as * "WARNING. CPU is overheating." * @param warning The warning to be spoken. * @param talker Code for the talker to do the speaking. Example "en". * If NULL, defaults to the user's default talker. * If no plugin has been configured for the specified Talker code, * defaults to the closest matching talker. */ virtual ASYNC sayWarning(const TQString &warning, const TQString &talker) = 0; /** * Say a message. The message will be spoken when the current sentence stops speaking * but after any warnings have been spoken. * Messages should be used for one-shot messages that can't wait for * normal text messages to stop speaking, such as "You have mail.". * @param message The message to be spoken. * @param talker Code for the talker to do the speaking. Example "en". * If NULL, defaults to the user's default talker. * If no talker has been configured for the specified talker code, * defaults to the closest matching talker. */ virtual ASYNC sayMessage(const TQString &message, const TQString &talker) = 0; /** * Sets the GREP pattern that will be used as the sentence delimiter. * @param delimiter A valid GREP pattern. * * The default sentence delimiter is @verbatim ([\\.\\?\\!\\:\\;])(\\s|$|(\\n *\\n)) @endverbatim * * Note that backward slashes must be escaped. * When %KTTSD parses the text, it replaces all tabs, spaces, and formfeeds * with a single space, and then replaces the sentence delimiters using * the following statement: @verbatim TQString::replace(sentenceDelimiter, "\\1\t"); @endverbatim * * which replaces all sentence delimiters with a tab, but * preserving the first capture text (first parenthesis). In other * words, the sentence punctuation is preserved. * The tab is later used to separate the text into sentences. * * Changing the sentence delimiter does not affect other applications. * * @see sentenceparsing */ virtual ASYNC setSentenceDelimiter(const TQString &delimiter) = 0; /** * Queue a text job. Does not start speaking the text. * @param text The message to be spoken. * @param talker Code for the talker to do the speaking. Example "en". * If NULL, defaults to the user's default plugin. * If no plugin has been configured for the specified Talker code, * defaults to the closest matching talker. * @return Job number. * * Plain text is parsed into individual sentences using the current sentence delimiter. * Call setSentenceDelimiter to change the sentence delimiter prior to * calling setText. * Call getTextCount to retrieve the sentence count after calling setText. * * The text may contain speech mark language, such as Sable, JSML, or SSML, * provided that the speech plugin/engine support it. In this case, * sentence parsing follows the semantics of the markup language. * * Call startText to mark the job as speakable and if the * job is the first speakable job in the queue, speaking will begin. * * @see getTextCount * @see startText */ virtual uint setText(const TQString &text, const TQString &talker) = 0; /** * Say a plain text job. This is a convenience method that * combines setText and startText into a single call. * @param text The message to be spoken. * @param talker Code for the talker to do the speaking. Example "en". * If NULL, defaults to the user's default plugin. * If no plugin has been configured for the specified Talker code, * defaults to the closest matching talker. * @return Job number. * * Plain text is parsed into individual sentences using the current sentence delimiter. * Call setSentenceDelimiter to change the sentence delimiter prior to * calling setText. * Call getTextCount to retrieve the sentence count after calling setText. * * The text may contain speech mark language, such as Sable, JSML, or SSML, * provided that the speech plugin/engine support it. In this case, * sentence parsing follows the semantics of the markup language. * * The job is marked speakable. * If there are other speakable jobs preceeding this one in the queue, * those jobs continue speaking and when finished, this job will begin speaking. * If there are no other speakable jobs preceeding this one, it begins speaking. * * @see getTextCount * * @since KDE 3.5 */ virtual uint sayText(const TQString &text, const TQString &talker) = 0; /** * Adds another part to a text job. Does not start speaking the text. * @param text The message to be spoken. * @param jobNum Job number of the text job. * If zero, applies to the last job queued by the application, * but if no such job, applies to the current job (if any). * @return Part number for the added part. Parts are numbered starting at 1. * * The text is parsed into individual sentences. Call getTextCount to retrieve * the sentence count. Call startText to mark the job as speakable and if the * job is the first speakable job in the queue, speaking will begin. * * @see setText. * @see startText. */ virtual int appendText(const TQString &text, uint jobNum=0) = 0; /** * Queue a text job from the contents of a file. Does not start speaking the text. * @param filename Full path to the file to be spoken. May be a URL. * @param talker Code for the talker to do the speaking. Example "en". * If NULL, defaults to the user's default talker. * If no plugin has been configured for the specified Talker code, * defaults to the closest matching talker. * @param encoding Name of the encoding to use when reading the file. If * NULL or Empty, uses default stream encoding. * @return Job number. 0 if an error occurs. * * Plain text is parsed into individual sentences using the current sentence delimiter. * Call setSentenceDelimiter to change the sentence delimiter prior to calling setText. * Call getTextCount to retrieve the sentence count after calling setText. * * The text may contain speech mark language, such as Sable, JSML, or SSML, * provided that the speech plugin/engine support it. In this case, * sentence parsing follows the semantics of the markup language. * * Call startText to mark the job as speakable and if the * job is the first speakable job in the queue, speaking will begin. * * @see getTextCount * @see startText */ virtual uint setFile(const TQString &filename, const TQString &talker, const TQString& encoding) = 0; /** * Get the number of sentences in a text job. * @param jobNum Job number of the text job. * If zero, applies to the last job queued by the application, * but if no such job, applies to the current job (if any). * @return The number of sentences in the job. -1 if no such job. * * The sentences of a job are given sequence numbers from 1 to the number returned by this * method. The sequence numbers are emitted in the sentenceStarted and * sentenceFinished signals. */ virtual int getTextCount(uint jobNum=0) = 0; /** * Get the job number of the current text job. * @return Job number of the current text job. 0 if no jobs. * * Note that the current job may not be speaking. See isSpeakingText. * * @see getTextJobState. * @see isSpeakingText */ virtual uint getCurrentTextJob() = 0; /** * Get the number of jobs in the text job queue. * @return Number of text jobs in the queue. 0 if none. */ virtual uint getTextJobCount() = 0; /** * Get a comma-separated list of text job numbers in the queue. * @return Comma-separated list of text job numbers in the queue. */ virtual TQString getTextJobNumbers() = 0; /** * Get the state of a text job. * @param jobNum Job number of the text job. * If zero, applies to the last job queued by the application, * but if no such job, applies to the current job (if any). * @return State of the job. -1 if invalid job number. * * @see kttsdJobState */ virtual int getTextJobState(uint jobNum=0) = 0; /** * Get information about a text job. * @param jobNum Job number of the text job. * If zero, applies to the last job queued by the application, * but if no such job, applies to the current job (if any). * @return A TQDataStream containing information about the job. * Blank if no such job. * * The stream contains the following elements: * - int state - Job state. * - TQCString appId - DCOP senderId of the application that requested the speech job. * - TQString talker - Talker Code requested by application. * - int seq - Current sentence being spoken. Sentences are numbered starting at 1. * - int sentenceCount - Total number of sentences in the job. * - int partNum - Current part of the job begin spoken. Parts are numbered starting at 1. * - int partCount - Total number of parts in the job. * * Note that sequence numbers apply to the entire job. They do not start from 1 at the beginning of * each part. * * The following sample code will decode the stream: @code TQByteArray jobInfo = getTextJobInfo(jobNum); TQDataStream stream(jobInfo, IO_ReadOnly); int state; TQCString appId; TQString talker; int seq; int sentenceCount; int partNum; int partCount; stream >> state; stream >> appId; stream >> talker; stream >> seq; stream >> sentenceCount; stream >> partNum; stream >> partCount; @endcode */ virtual TQByteArray getTextJobInfo(uint jobNum=0) = 0; /** * Given a Talker Code, returns the Talker ID of the talker that would speak * a text job with that Talker Code. * @param talkerCode Talker Code. * @return Talker ID of the talker that would speak the text job. */ virtual TQString talkerCodeToTalkerId(const TQString& talkerCode) = 0; /** * Return a sentence of a job. * @param jobNum Job number of the text job. * If zero, applies to the last job queued by the application, * but if no such job, applies to the current job (if any). * @param seq Sequence number of the sentence. * @return The specified sentence in the specified job. If no such * job or sentence, returns "". */ virtual TQString getTextJobSentence(uint jobNum=0, uint seq=0) = 0; /** * Determine if kttsd is currently speaking any text jobs. * @return True if currently speaking any text jobs. */ virtual bool isSpeakingText() const = 0; /** * Remove a text job from the queue. * @param jobNum Job number of the text job. * If zero, applies to the last job queued by the application, * but if no such job, applies to the current job (if any). * * The job is deleted from the queue and the textRemoved signal is emitted. * * If there is another job in the text queue, and it is marked speakable, * that job begins speaking. */ virtual ASYNC removeText(uint jobNum=0) = 0; /** * Start a text job at the beginning. * @param jobNum Job number of the text job. * If zero, applies to the last job queued by the application, * but if no such job, applies to the current job (if any). * * Rewinds the job to the beginning. * * The job is marked speakable. * If there are other speakable jobs preceeding this one in the queue, * those jobs continue speaking and when finished, this job will begin speaking. * If there are no other speakable jobs preceeding this one, it begins speaking. * * The textStarted signal is emitted when the text job begins speaking. * When all the sentences of the job have been spoken, the job is marked for deletion from * the text queue and the textFinished signal is emitted. */ virtual ASYNC startText(uint jobNum=0) = 0; /** * Stop a text job and rewind to the beginning. * @param jobNum Job number of the text job. * If zero, applies to the last job queued by the application, * but if no such job, applies to the current job (if any). * * The job is marked not speakable and will not be speakable until startText * or resumeText is called. * * If there are speaking jobs preceeding this one in the queue, they continue speaking. * * If the job is currently speaking, the textStopped signal is emitted, * the job stops speaking, and if the next job in the queue is speakable, it * begins speaking. * * Depending upon the speech engine and plugin used, speech may not stop immediately * (it might finish the current sentence). */ virtual ASYNC stopText(uint jobNum=0) = 0; /** * Pause a text job. * @param jobNum Job number of the text job. * If zero, applies to the last job queued by the application, * but if no such job, applies to the current job (if any). * * The job is marked as paused and will not be speakable until resumeText or * startText is called. * * If there are speaking jobs preceeding this one in the queue, they continue speaking. * * If the job is currently speaking, the textPaused signal is emitted and the job * stops speaking. Note that if the next job in the queue is speakable, it does * not start speaking as long as this job is paused. * * Depending upon the speech engine and plugin used, speech may not stop immediately * (it might finish the current sentence). * * @see resumeText */ virtual ASYNC pauseText(uint jobNum=0) = 0; /** * Start or resume a text job where it was paused. * @param jobNum Job number of the text job. * If zero, applies to the last job queued by the application, * but if no such job, applies to the current job (if any). * * The job is marked speakable. * * If the job is currently speaking, or is waiting to be spoken (speakable * state), the resumeText() call is ignored. * * If the job is currently queued, or is finished, it is the same as calling * @see startText . * * If there are speaking jobs preceeding this one in the queue, * those jobs continue speaking and when finished this job will begin * speaking where it left off. * * The textResumed signal is emitted when the job resumes. * * @see pauseText */ virtual ASYNC resumeText(uint jobNum=0) = 0; /** * Get a list of the talkers configured in KTTS. * @return A TQStringList of fully-specified talker codes, one * for each talker user has configured. * * @see talkers */ virtual TQStringList getTalkers() = 0; /** * Change the talker for a text job. * @param jobNum Job number of the text job. * If zero, applies to the last job queued by the application, * but if no such job, applies to the current job (if any). * @param talker New code for the talker to do the speaking. Example "en". * If NULL, defaults to the user's default talker. * If no plugin has been configured for the specified Talker code, * defaults to the closest matching talker. */ virtual ASYNC changeTextTalker(const TQString &talker, uint jobNum=0 ) = 0; /** * Get the user's default talker. * @return A fully-specified talker code. * * @see talkers * @see getTalkers */ virtual TQString userDefaultTalker() = 0; /** * Move a text job down in the queue so that it is spoken later. * @param jobNum Job number of the text job. * If zero, applies to the last job queued by the application, * but if no such job, applies to the current job (if any). * * If the job is currently speaking, it is paused. * If the next job in the queue is speakable, it begins speaking. */ virtual ASYNC moveTextLater(uint jobNum=0) = 0; /** * Jump to the first sentence of a specified part of a text job. * @param partNum Part number of the part to jump to. Parts are numbered starting at 1. * @param jobNum Job number of the text job. * If zero, applies to the last job queued by the application, * but if no such job, applies to the current job (if any). * @return Part number of the part actually jumped to. * * If partNum is greater than the number of parts in the job, jumps to last part. * If partNum is 0, does nothing and returns the current part number. * If no such job, does nothing and returns 0. * Does not affect the current speaking/not-speaking state of the job. */ virtual int jumpToTextPart(int partNum, uint jobNum=0) = 0; /** * Advance or rewind N sentences in a text job. * @param n Number of sentences to advance (positive) or rewind (negative) in the job. * @param jobNum Job number of the text job. * If zero, applies to the last job queued by the application, * but if no such job, applies to the current job (if any). * @return Sequence number of the sentence actually moved to. Sequence numbers * are numbered starting at 1. * * If no such job, does nothing and returns 0. * If n is zero, returns the current sequence number of the job. * Does not affect the current speaking/not-speaking state of the job. */ virtual uint moveRelTextSentence(int n, uint jobNum=0) = 0; /** * Add the clipboard contents to the text queue and begin speaking it. */ virtual ASYNC speakClipboard() = 0; /** * Displays the %KTTS Manager dialog. In this dialog, the user may backup or skip forward in * any text job by sentence or part, rewind jobs, pause or resume jobs, or * delete jobs. */ virtual void showDialog() = 0; /** * Stop the service. */ virtual void kttsdExit() = 0; /** * Re-start %KTTSD. */ virtual void reinit() = 0; /** * Return the KTTSD deamon version number. * @since KDE 3.5 */ virtual TQString version() = 0; //@} k_dcop_signals: void ignoreThis(); /** @name DCOP Signals */ //@{ /** * This signal is emitted when KTTSD starts or restarts after a call to reinit. */ void kttsdStarted(); /** * This signal is emitted just before KTTSD exits. */ void kttsdExiting(); /** * This signal is emitted when the speech engine/plugin encounters a marker in the text. * @param appId DCOP application ID of the application that queued the text. * @param markerName The name of the marker seen. * * @see markers */ void markerSeen(const TQCString& appId, const TQString& markerName); /** * This signal is emitted whenever a sentence begins speaking. * @param appId DCOP application ID of the application that queued the text. * @param jobNum Job number of the text job. * @param seq Sequence number of the text. * * @see getTextCount */ void sentenceStarted(const TQCString& appId, uint jobNum, uint seq); /** * This signal is emitted when a sentence has finished speaking. * @param appId DCOP application ID of the application that queued the text. * @param jobNum Job number of the text job. * @param seq Sequence number of the text. * * @see getTextCount */ void sentenceFinished(const TQCString& appId, uint jobNum, uint seq); /** * This signal is emitted whenever a new text job is added to the queue. * @param appId The DCOP senderId of the application that created the job. * @param jobNum Job number of the text job. */ void textSet(const TQCString& appId, uint jobNum); /** * This signal is emitted whenever a new part is appended to a text job. * @param appId The DCOP senderId of the application that created the job. * @param jobNum Job number of the text job. * @param partNum Part number of the new part. Parts are numbered starting * at 1. */ void textAppended(const TQCString& appId, uint jobNum, int partNum); /** * This signal is emitted whenever speaking of a text job begins. * @param appId The DCOP senderId of the application that created the job. * @param jobNum Job number of the text job. */ void textStarted(const TQCString& appId, uint jobNum); /** * This signal is emitted whenever a text job is finished. The job has * been marked for deletion from the queue and will be deleted when another * job reaches the Finished state. (Only one job in the text queue may be * in state Finished at one time.) If startText or resumeText is * called before the job is deleted, it will remain in the queue for speaking. * @param appId The DCOP senderId of the application that created the job. * @param jobNum Job number of the text job. */ void textFinished(const TQCString& appId, uint jobNum); /** * This signal is emitted whenever a speaking text job stops speaking. * @param appId The DCOP senderId of the application that created the job. * @param jobNum Job number of the text job. * * The signal is only emitted if stopText() is called and the job is currently * speaking. */ void textStopped(const TQCString& appId, uint jobNum); /** * This signal is emitted whenever a speaking text job is paused. * @param appId The DCOP senderId of the application that created the job. * @param jobNum Job number of the text job. */ void textPaused(const TQCString& appId, uint jobNum); /** * This signal is emitted when a text job, that was previously paused, resumes speaking. * @param appId The DCOP senderId of the application that created the job. * @param jobNum Job number of the text job. */ void textResumed(const TQCString& appId, uint jobNum); /** * This signal is emitted whenever a text job is deleted from the queue. * The job is no longer in the queue when this signal is emitted. * @param appId The DCOP senderId of the application that created the job. * @param jobNum Job number of the text job. */ void textRemoved(const TQCString& appId, uint jobNum); //@} }; #endif // _KSPEECH_H_