summaryrefslogtreecommitdiffstats
path: root/interfaces/kspeech
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commitce4a32fe52ef09d8f5ff1dd22c001110902b60a2 (patch)
tree5ac38a06f3dde268dc7927dc155896926aaf7012 /interfaces/kspeech
downloadtdelibs-ce4a32fe52ef09d8f5ff1dd22c001110902b60a2.tar.gz
tdelibs-ce4a32fe52ef09d8f5ff1dd22c001110902b60a2.zip
Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'interfaces/kspeech')
-rw-r--r--interfaces/kspeech/Makefile.am10
-rw-r--r--interfaces/kspeech/dcoptexttospeech.desktop70
-rw-r--r--interfaces/kspeech/kspeech.h1286
-rw-r--r--interfaces/kspeech/kspeechsink.h164
4 files changed, 1530 insertions, 0 deletions
diff --git a/interfaces/kspeech/Makefile.am b/interfaces/kspeech/Makefile.am
new file mode 100644
index 000000000..a1ecda67f
--- /dev/null
+++ b/interfaces/kspeech/Makefile.am
@@ -0,0 +1,10 @@
+INCLUDES=-I$(top_srcdir)/dcop $(all_includes)
+
+# Header files to be installed.
+include_HEADERS = kspeech.h kspeechsink.h
+
+# Define DCOP/Text-to-Speech Service Type.
+kde_servicetypes_DATA = dcoptexttospeech.desktop
+
+DOXYGEN_REFERENCES = kdecore dcop kio kdeui kparts
+include ../../admin/Doxyfile.am
diff --git a/interfaces/kspeech/dcoptexttospeech.desktop b/interfaces/kspeech/dcoptexttospeech.desktop
new file mode 100644
index 000000000..272752137
--- /dev/null
+++ b/interfaces/kspeech/dcoptexttospeech.desktop
@@ -0,0 +1,70 @@
+[Desktop Entry]
+Type=ServiceType
+X-KDE-ServiceType=DCOP/Text-to-Speech
+Comment=Text-to-Speech Service with a DCOP interface
+Comment[af]=Tekste-tot-spraak diens met DCOP intervlak
+Comment[be]=Сервіс агалошвання тэксту з інтэрфэйсам DCOP
+Comment[bg]=Синтез на глас с интерфейс DCOP
+Comment[bn]=ডিকপ (DCOP) ইন্টারফেস সহ টেক্সট-টু-স্পীচ সার্ভিস
+Comment[bs]=Servis za izgovaranje teksta sa DCOP interfejsom
+Comment[ca]=Servei de síntesi de veu amb una interfície DCOP
+Comment[cs]=Služba text-na-řeč s DCOP rozhraním
+Comment[csb]=Ùsłëżnota czëtaniô tekstu z interfejsã DCOP
+Comment[cy]=Gwasanaeth Testun-i-Lafar efo rhyngwyneb DCOP
+Comment[da]=Tekst-til-tale tjeneste med DCOP-grænseflade
+Comment[de]=Sprachausgabe mit DCOP-Schnittstelle
+Comment[el]=Υπηρεσία κειμένου-σε-ομιλία με διασύνδεση DCOP
+Comment[eo]=LegitaTeksto (TTS) kun DCOP-interfaco
+Comment[es]=Texto a servicio de voz con un interfaz DCOP
+Comment[et]=Teksti kõneks muutmise teenus DCOP-liidesega
+Comment[eu]='Testua-ahoskatzea' zerbitzua DCOP interfazearekin
+Comment[fa]=خدمت متن به سخن با یک واسط DCOP
+Comment[fi]=Teksti-Puheeksi palvelu DCOP-rajapinnalla
+Comment[fr]=Service de synthèse vocale munie d'une interface DCOP
+Comment[fy]=tekst-ta-prate mei in DCOP-ynterface
+Comment[ga]=Seirbhís Téacs-go-Caint le comhéadan DCOP
+Comment[gl]= Servizo de Texto a Fala con interface DCOP
+Comment[he]=שירות טקסט לדיבור עם ממשק DCOP
+Comment[hr]=Usluga tekst-u-govor s DCOP sučeljem.
+Comment[hsb]=konwertowanje teksta na rěč z DCOP-interfejsom
+Comment[hu]=Szövegfelolvasó szolgáltatás DCOP-felülettel
+Comment[id]=Layanan Text-to-Speech Service dengan antarmuka DCOP
+Comment[is]=Texti-í-tal þjónusta með DCOP viðmóti
+Comment[it]=Servizio di pronuncia con un'interfaccia DCOP
+Comment[ja]=DCOP インターフェースで動作するテキスト読み上げサービス
+Comment[ka]=ტექსტის სინთეზის ძრავი DCOP ინტერფეისით
+Comment[kk]=DCOP интерфейсті мәтіннен дыбыстап оқу қызметі
+Comment[km]=សេវា អត្ថបទ-ទៅ-សំដី ដែល​មានចំណុចប្រទាក់ DCOP
+Comment[lb]=Sproochausgab-Service mat engem DCOP-Interface
+Comment[lt]=Teksto vertimo kalba tarnyba su DCOP sąsaja
+Comment[mk]=Сервис за текст-во-говор со DCOP-интерфејс
+Comment[ms]=Servis Teks-ke-Tutur dengan antara muka DCOP
+Comment[nb]=Tekst til tale-program med DCOP-grensesnitt
+Comment[nds]=Vörleesdeenst mit DCOP-Koppelsteed
+Comment[ne]=DCOP इन्टरफेससँग पाठ-बाट-बोली सेवा
+Comment[nl]=Tekst-tot-spraak-dienst met een DCOP interface
+Comment[nn]=Tekst-til-tale-teneste med DCOP-grensesnitt
+Comment[pa]=ਇੱਕ DCOP ਇੰਟਰਫੇਸ ਨਾਲ ਪਾਠ-ਤੋਂ-ਬੋਲੀ ਸੇਵਾ
+Comment[pl]=Usługa czytania tekstu z interfejsem DCOP
+Comment[pt]=Servidor Texto-para-Voz com interface DCOP
+Comment[pt_BR]=Serviço de conversão de texto para fala com uma interface DCOP
+Comment[ro]=Serviciu text-vorbire cu interfaţă DCOP
+Comment[ru]=Сервис синтеза речи с интерфейсом DCOP
+Comment[rw]=Serivise Umwandiko-ku-Kuvuga ifite imigaragarire DCOP
+Comment[se]=Hupmejuvvon teaksta bálválus mas lea DCOP-lákta
+Comment[sk]=Služba prevodu textu na reč s rozhraním DCOP
+Comment[sl]=Servis, ki spremeni besedilo v govor, z vmesnikom DCOP
+Comment[sr]=Текст—у—говор сервис са DCOP интерфејсом
+Comment[sr@Latn]=Tekst—u—govor servis sa DCOP interfejsom
+Comment[sv]=Text till tal-tjänst med ett DCOP-gränssnitt
+Comment[ta]= DCOP இடைமுகத்துடன் உரையில் இருந்து பேச்சு சேவை
+Comment[te]=డికాప్ ఇంటర్ఫేస్ కల్గిన వాచకం నుంచి మాటలకు మార్చు సేవ
+Comment[tg]=Хидмати матни овоздор бо интерфейси DCOP
+Comment[th]=บริการเปลี่ยนข้อความเป็นเสียงพูด พร้อมด้วยส่วนติดต่อกับ DCOP
+Comment[tr]=DCOP arayüzü ile Metinden Ses Servisi
+Comment[tt]=DCOP protokolı aşa eşläwçe Mäten-Uquçı Xezmät
+Comment[uk]=Служба синтезу мовлення з інтерфейсом DCOP
+Comment[vi]=Dịch vụ Văn bản sang Tiếng nói có giao diện DCOP
+Comment[zh_CN]=带 DCOP 接口的文本到语音服务
+Comment[zh_HK]=附有 DCOP 介面的文字朗讀工具
+Comment[zh_TW]=DCOP 介面的文字轉語音服務
diff --git a/interfaces/kspeech/kspeech.h b/interfaces/kspeech/kspeech.h
new file mode 100644
index 000000000..b97314760
--- /dev/null
+++ b/interfaces/kspeech/kspeech.h
@@ -0,0 +1,1286 @@
+/***************************************************** vim:set ts=4 sw=4 sts=4:
+ kspeech.h
+ KTTSD DCOP Interface
+ --------------------
+ Copyright:
+ (C) 2002-2003 by José Pablo Ezequiel "Pupeno" Fernández <pupeno@kde.org>
+ (C) 2003-2004 by Olaf Schmidt <ojschmidt@kde.org>
+ (C) 2004-2005 by Gary Cramblitt <garycramblitt@comcast.net>
+ -------------------
+ 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 <dcopobject.h>
+#include <qstringlist.h>
+
+/**
+ * @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 <text> <talker>
+ @endverbatim
+ *
+ * where \<text\> is the text to be spoken, and \<talker\> 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 <text> <talker>
+ @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 <kspeech_stub.h>
+ 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(QWidget *parent, const char *name) :
+ KParts::ReadOnlyPart(parent, 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")) {
+ QString error;
+ if (KApplication::startServiceByDesktopName("kttsd", QStringList(), &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 <kspeechsink.h>
+ class MyPart:
+ public KParts::ReadOnlyPart,
+ virtual public KSpeechSink
+ {
+ protected:
+ ASYNC sentenceStarted(const QCString& appId, const uint jobNum, const uint seq);
+ @endverbatim
+ *
+ * You can combine sending and receiving in one object.
+ *
+ @verbatim
+ #include <kspeechsink.h>
+ class MyPart:
+ public KParts::ReadOnlyPart,
+ public KSpeech_stub,
+ virtual public KSpeechSink
+ {
+ protected:
+ ASYNC sentenceStarted(const QCString& 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(QWidget *parent, const char *name) :
+ KParts::ReadOnlyPart(parent, 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(QCString,uint,uint)",
+ "sentenceStarted(QCString,uint,uint)",
+ false);
+ @endverbatim
+ *
+ * Notice that the argument signatures differ slightly from the actual declarations. For
+ * example
+ *
+ @verbatim
+ ASYNC sentenceStarted(const QCString& appId, const uint jobNum, const uint seq);
+ @endverbatim
+ *
+ * becomes
+ *
+ @verbatim
+ "sentenceStarted(QCString,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 QCString& 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
+ * \code
+ * <voice lang="en" name="kal" gender="male"/>
+ * <prosody volume="soft" rate="fast"/>
+ * <kttsd synthesizer="Festival" />
+ * \endcode
+ *
+ * (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 <pupeno@kde.org>
+ * @author Gary Cramblitt <garycramblitt@comcast.net>
+ * @author Olaf Schmidt <ojschmidt@kde.org>
+ * @author Gunnar Schmi Dt <gunnar@schmi-dt.de>
+ */
+
+// 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 QString &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 QString &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 QString &msg, const QString &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 QString &warning, const QString &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 QString &message, const QString &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
+ QString::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 QString &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 QString &text, const QString &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 QString &text, const QString &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 QString &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 QString &filename, const QString &talker,
+ const QString& 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 QString 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 QDataStream containing information about the job.
+ * Blank if no such job.
+ *
+ * The stream contains the following elements:
+ * - int state - Job state.
+ * - QCString appId - DCOP senderId of the application that requested the speech job.
+ * - QString 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
+ QByteArray jobInfo = getTextJobInfo(jobNum);
+ QDataStream stream(jobInfo, IO_ReadOnly);
+ int state;
+ QCString appId;
+ QString 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 QByteArray 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 QString talkerCodeToTalkerId(const QString& 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 QString 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 QStringList of fully-specified talker codes, one
+ * for each talker user has configured.
+ *
+ * @see talkers
+ */
+ virtual QStringList 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 QString &talker, uint jobNum=0 ) = 0;
+
+ /**
+ * Get the user's default talker.
+ * @return A fully-specified talker code.
+ *
+ * @see talkers
+ * @see getTalkers
+ */
+ virtual QString 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 QString 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 QCString& appId, const QString& 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 QCString& 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 QCString& 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 QCString& 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 QCString& 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 QCString& 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 QCString& 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 QCString& 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 QCString& 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 QCString& 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 QCString& appId, uint jobNum);
+ //@}
+};
+
+#endif // _KSPEECH_H_
diff --git a/interfaces/kspeech/kspeechsink.h b/interfaces/kspeech/kspeechsink.h
new file mode 100644
index 000000000..e90a005f1
--- /dev/null
+++ b/interfaces/kspeech/kspeechsink.h
@@ -0,0 +1,164 @@
+/***************************************************** vim:set ts=4 sw=4 sts=4:
+ kspeechsink.h
+ KTTSD DCOP Signal Sink Interface
+ --------------------------------
+ Copyright:
+ (C) 2004 by Gary Cramblitt <garycramblitt@comcast.net>
+ -------------------
+ Original author: 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. *
+ * *
+ ***************************************************************************/
+
+/**
+ * @interface KSpeechSink
+ *
+ * KTTSD DCOP Signal Sink
+ *
+ * @since KDE 3.4
+ *
+ * This defines the interface to sink signals emitted by KTTSD, the KDE Text-to-speech Deamon.
+ * The DCOP IDL Compiler generates a skeleton file from this interface definition that will
+ * marshal the arguments for you.
+ *
+ * @section Usage
+ *
+ * See the Signals section of kspeech.h for instructions.
+ *
+ * @warning The KSpeechSink interface is still being developed and is likely to change in the future.
+*/
+
+#ifndef _KSPEECHSINK_H_
+#define _KSPEECHSINK_H_
+
+#include <dcopobject.h>
+
+class KSpeechSink : 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 */
+ mtSmml = 2, /**< %Speech Markup Meta-language */
+ mtSable = 3 /**< Sable 2.0 */
+ };
+
+ k_dcop:
+ /**
+ * This signal is emitted when KTTSD starts or restarts after a call to reinit.
+ */
+ virtual ASYNC kttsdStarted() { };
+ /**
+ * This signal is emitted just before KTTSD exits.
+ */
+ virtual ASYNC 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
+ */
+ virtual ASYNC markerSeen(const QCString& appId, const QString& markerName) { Q_UNUSED(appId); Q_UNUSED(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
+ */
+ virtual ASYNC sentenceStarted(const QCString& appId, uint jobNum, uint seq) { Q_UNUSED(appId); Q_UNUSED(jobNum); Q_UNUSED(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
+ */
+ virtual ASYNC sentenceFinished(const QCString& appId, uint jobNum, uint seq) { Q_UNUSED(appId); Q_UNUSED(jobNum); Q_UNUSED(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. NULL if kttsd.
+ * @param jobNum Job number of the text job.
+ */
+ virtual ASYNC textSet(const QCString& appId, uint jobNum) { Q_UNUSED(appId); Q_UNUSED(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.
+ */
+ virtual ASYNC textAppended(const QCString& appId, uint jobNum, int partNum) { Q_UNUSED(appId); Q_UNUSED(jobNum); Q_UNUSED(partNum); };
+
+ /**
+ * This signal is emitted whenever speaking of a text job begins.
+ * @param appId The DCOP senderId of the application that created the job. NULL if kttsd.
+ * @param jobNum Job number of the text job.
+ */
+ virtual ASYNC textStarted(const QCString& appId, uint jobNum) { Q_UNUSED(appId); Q_UNUSED(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. NULL if kttsd.
+ * @param jobNum Job number of the text job.
+ */
+ virtual ASYNC textFinished(const QCString& appId, uint jobNum) { Q_UNUSED(appId); Q_UNUSED(jobNum); };
+ /**
+ * This signal is emitted whenever a speaking text job stops speaking.
+ * @param appId The DCOP senderId of the application that created the job. NULL if kttsd.
+ * @param jobNum Job number of the text job.
+ */
+ virtual ASYNC textStopped(const QCString& appId, uint jobNum) { Q_UNUSED(appId); Q_UNUSED(jobNum); };
+ /**
+ * This signal is emitted whenever a speaking text job is paused.
+ * @param appId The DCOP senderId of the application that created the job. NULL if kttsd.
+ * @param jobNum Job number of the text job.
+ */
+ virtual ASYNC textPaused(const QCString& appId, uint jobNum) { Q_UNUSED(appId); Q_UNUSED(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. NULL if kttsd.
+ * @param jobNum Job number of the text job.
+ */
+ virtual ASYNC textResumed(const QCString& appId, uint jobNum) { Q_UNUSED(appId); Q_UNUSED(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. NULL if kttsd.
+ * @param jobNum Job number of the text job.
+ */
+ virtual ASYNC textRemoved(const QCString& appId, uint jobNum) { Q_UNUSED(appId); Q_UNUSED(jobNum); };
+};
+
+#endif // _KSPEECHSINK_H_