Remove this line
[kdeaccessibility.git] / doc / kttsd / index.docbook
blobc9bd457ac6d94ba3a5aeef49ed787d70e3b94d8d
1 <?xml version="1.0" ?>
2 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
3 <!ENTITY ktts "<application>KTTS</application>">
4 <!ENTITY kappname "&ktts;">
5 <!ENTITY package "kdeaccessibility">
6 <!ENTITY mbrola "<application>MBROLA</application>">
7 <!ENTITY % imageobjectco.module "INCLUDE">
8 <!ENTITY % addindex "IGNORE">
9 <!ENTITY % English "INCLUDE">
11 <!-- Note to translators: KTTSD is meant to be built under KDE
12 versions 3.2 and later. Please avoid entities that won't
13 be defined under those KDE versions. Thanks.
14 -->
16 <!-- kdoctemplate v0.9 January 10 2003
17 Changes to comments to clarify entity usage January 10 2003
18 Minor update to "Credits and Licenses" section on August 24, 2000
19 Removed "Revision history" section on 22 January 2001
20 Changed to Installation/Help menu entities 18 October 2001
21 Other minor cleanup and changes 18 October 2001
22 FPI change and minor changes November 2002 -->
24 <!--
25 This template was designed by: David Rugge davidrugge@mindspring.com
26 with lots of help from: Eric Bischoff ebisch@cybercable.tm.fr
27 and Frederik Fouvry fouvry@sfs.nphil.uni-tuebingen.de
28 of the KDE DocBook team.
30 You may freely use this template for writing any sort of KDE documentation.
31 If you have any changes or improvements, please let us know.
33 Remember:
34 - in XML, the case of the <tags> and attributes is relevant ;
35 - also, quote all attributes.
37 Please don't forget to remove all these comments in your final documentation,
38 thanks ;-).
39 -->
41 <!-- ................................................................ -->
43 <!-- The language must NOT be changed here. -->
44 <!-- If you are writing original documentation in a language other -->
45 <!-- than English, change the language above ONLY, not here -->
46 <book lang="&language;">
48 <!-- This header contains all of the meta-information for the document such
49 as Authors, publish date, the abstract, and Keywords -->
51 <bookinfo>
52 <title>The &ktts; Handbook</title>
54 <authorgroup>
55 <author>
56 <!-- This is just put in as an example. For real documentation, please
57 define a general entity in entities/contributor.entities, e.g.
58 <!ENTITY George.N.Ugnacious "<personname><firstname>George</firstname><othername>N.</othername><surname>Ugnacious</surname></personname>">
59 <!ENTITY George.N.Ugnacious.mail "<email>gnu@kde.org</email>">
60 and use `&George.N.Ugnacious; &George.N.Ugnacious.mail;' in the author element.
61 -->
62 <personname>
63 <firstname>Gary</firstname>
64 <othername>R.</othername>
65 <surname>Cramblitt</surname>
66 </personname>
67 <email>garycramblitt@comcast.net</email>
68 </author>
70 <!-- TRANS:ROLES_OF_TRANSLATORS -->
72 </authorgroup>
74 <copyright>
75 <year>2004-2005</year>
76 <holder>Gary R. Cramblitt</holder>
77 </copyright>
78 <!-- Translators: put here the copyright notice of the translation -->
79 <!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook
80 and in the FDL itself on how to use it. -->
81 <legalnotice>&FDLNotice;</legalnotice>
83 <!-- Date and version information of the documentation
84 Don't forget to include this last date and this last revision number, we
85 need them for translation coordination !
86 Please respect the format of the date (YYYY-MM-DD) and of the version
87 (V.MM.LL), it could be used by automation scripts.
88 Do NOT change these in the translation. -->
90 <date>2005-07-31</date>
91 <releaseinfo>1.05.00</releaseinfo>
93 <!-- Abstract about this handbook -->
95 <abstract>
96 <para>
97 &ktts; - the &kde; Text-to-Speech system - is
98 a plugin based service that
99 allows any &kde; (or non-&kde;) application to speak using the &DCOP; interface.
100 </para>
102 <para>&ktts; intends to be the implementation for the &kde; Text-to-Speech API.</para>
104 </abstract>
106 <!-- This is a set of Keywords for indexing by search engines.
107 Please at least include KDE, the KDE package it is in, the name
108 of your application, and a few relevant keywords. -->
110 <keywordset>
111 <keyword>KDE</keyword>
112 <keyword>accessibility</keyword>
113 <keyword>kdeaccessibility</keyword>
114 <keyword>TTS</keyword>
115 <keyword>Text-to-Speech</keyword>
116 <keyword>KTTSD</keyword>
117 <keyword>kttsmgr</keyword>
118 <keyword>festival</keyword>
119 <keyword>flite</keyword>
120 <keyword>hadifix</keyword>
121 <keyword>MBROLA</keyword>
122 <keyword>freetts</keyword>
123 <keyword>epos</keyword>
124 <keyword>SSML</keyword>
125 </keywordset>
127 </bookinfo>
129 <!-- The contents of the documentation begin here. Label
130 each chapter so with the id attribute. This is necessary for two reasons: it
131 allows you to easily reference the chapter from other chapters of your
132 document, and if there is no ID, the name of the generated HTML files will vary
133 from time to time making it hard to manage for maintainers and for the CVS
134 system. Any chapter labelled (OPTIONAL) may be left out at the author's
135 discretion. Other chapters should not be left out in order to maintain a
136 consistent documentation style across all KDE apps. -->
138 <!-- ====================================================================== -->
140 <chapter id="introduction">
141 <title>Introduction</title>
143 <!-- The introduction chapter contains a brief introduction for the
144 application that explains what it does and where to report
145 problems. Basically a long version of the abstract. Don't include a
146 revision history. (see installation appendix comment) -->
148 <para>&ktts; is a subsysem within &kde; for producing
149 Text-to-Speech (TTS). It provides a common API for &kde; programmers to give
150 TTS capabilities to their applications. It provides some
151 nice capabilities for end users as well.</para>
153 <para>User features:</para>
155 <itemizedlist>
156 <listitem><para>Speak contents of a text file.</para></listitem>
157 <listitem><para>Speak &kde; notification events (KNotify).</para></listitem>
158 <listitem><para>Speak all or part of the text of a web page in &konqueror;.</para></listitem>
159 <listitem><para>Speak all or part of the text in &kate; text editor,
160 including instances where &kate; is embedded in another &kde; application.</para></listitem>
161 <listitem><para>Long text is parsed into sentences. User may backup by sentence
162 or paragraph, replay, pause, and stop playing.</para></listitem>
163 <listitem><para>Audio output via &arts;, ALSA, GStreamer (version 0.8.7 or later), or aKode.</para></listitem>
164 <listitem><para>User-configurable filters for substituting misspoken words, choosing
165 speech synthesizers, and transforming XHMTL/&XML; documents.</para></listitem>
166 </itemizedlist>
168 <para>Programmer features:</para>
170 <itemizedlist>
171 <listitem><para>Priority system for screen reader outputs, warnings and messages, while still playing regular texts.</para></listitem>
172 <listitem><para>Plugin-based architecture for support of a wide variety of speech synthesis engines and drivers.</para></listitem>
173 <listitem><para>Permit generation of speech from the command line (or via shell scripts) using the &kde; &DCOP; utilities.</para></listitem>
174 <listitem><para>Provide a lightweight and easily usable interface for applications to generate speech output.</para></listitem>
175 <listitem><para>Applications need not be concerned about contention over the speech device.</para></listitem>
176 <listitem><para>FUTURE: Provide support for speech markup languages, such as VoiceXML, Sable, &Java; Speech Markup Language (JSML), and Speech Markup Meta-language (SMML).</para></listitem>
177 <listitem><para>FUTURE: Provide limited support for embedded speech markers.</para></listitem>
178 <listitem><para>Asynchronous to prevent system blocking.</para></listitem>
179 </itemizedlist>
181 <para>&ktts; actually consists of several programs:
182 <variablelist>
184 <varlistentry>
185 <term><command>kttsd</command></term>
186 <listitem><para>the &kde; Text-to-Speech Daemon, which is a non-&GUI;
187 application that provides TTS services to applications via &DCOP;.
188 </para></listitem></varlistentry>
190 <varlistentry>
191 <term><command>kttsmgr</command></term>
192 <listitem><para>a &GUI; application for configuring and controlling
193 kttsd. kttsmgr sits in the system tray.
194 </para></listitem></varlistentry>
196 <varlistentry>
197 <term><command>libkhtmlkttsdplugin</command></term>
198 <listitem><para>A plugin for the &konqueror; web browser that permits you
199 to speak all or a portion of the text on a web page.
200 </para></listitem></varlistentry>
202 <varlistentry>
203 <term><command>ktexteditor_kttsd</command></term>
204 <listitem><para>A plugin for the &kate; text editor that permits you to speak
205 all or a portion of a text file.
206 </para></listitem></varlistentry>
208 </variablelist>
209 </para>
211 <!-- ...................................................................... -->
213 <sect1 id="support">
214 <title>Support</title>
215 <para>
216 In addition to the &kde; Bugzilla database (
217 <ulink url="http://bugs.kde.org/">http://bugs.kde.org/</ulink>
218 ), discussions for &ktts;
219 currently take place in the kde-accessibility mailing list. Subscribe at
220 <ulink url="https://mail.kde.org/mailman/listinfo/kde-accessibility">
221 https://mail.kde.org/mailman/listinfo/kde-accessibility</ulink>. Developers
222 also hang out in IRC (irc.kde.org, channel #kde-accessibility).
223 </para>
224 </sect1>
226 </chapter>
228 <!-- ====================================================================== -->
230 <chapter id="using-kapp">
231 <title>Using &ktts;</title>
233 <para>
234 <warning><para>Before you can use &ktts;, you must install at least one speech
235 synthesis engine and make sure it is working. See <xref linkend="installation" />.
236 </para></warning></para>
238 <!-- ...................................................................... -->
241 <sect1 id="starting-kttsmgr">
242 <title>Starting <command>kttsmgr</command></title>
244 <para>
245 To start the &ktts; system, type the following command in a &konsole;
246 </para>
248 <para><userinput>kttsmgr</userinput></para>
250 <para>or click on kttsmgr in the &kde; Menu.</para>
252 <para>If this is the first time running <command>kttsmgr</command>, or
253 if you have not yet configured any talkers, the <guilabel>Talkers</guilabel>
254 screen appears. See <xref linkend="configure-plugin" />.
255 If you have already configured at least one talker, the <guilabel>General</guilabel>
256 screen appears. See <xref linkend="general" />.</para>
258 </sect1>
260 <!-- ...................................................................... -->
263 <sect1 id="configure-plugin">
264 <title>Configuring Synthesis Plugins (Talkers)</title>
266 <para>Most text-to-speech (TTS) synthesizers offer multiple languages and voices
267 and may offer multiple speaking genders, volumes, and rates. You may configure more than
268 one instance of a synthesizer. Each combination of language, synthesizer, voice,
269 gender, volume, and rate is called a talker. You must configure at least one talker
270 before you can start &ktts; and begin speaking text.</para>
272 <note><para>Multiple talkers for the same synthesizer is similar to multiple print
273 queues for a single physical printer.</para></note>
275 <para>When applications send text to &ktts;, they may specify the
276 attributes of the preferred talker to do the synthesis. For example,
277 an application may request an English language female talker. If you have
278 configured a talker with both the English language and female gender, that
279 talker will be used, otherwise the closest matching talker will be automatically
280 picked. To learn more about how &ktts; picks talkers, see
281 <xref linkend="filters" />.</para>
283 <para>When you click the <guilabel>Talkers</guilabel> tab in <command>kttsmgr</command>,
284 the <guilabel>Talkers</guilabel> screen appears. This screen also automatically
285 appears if you start <command>kttsmgr</command> and you have not yet configured
286 any talkers.</para>
288 <para>
289 <screenshot>
290 <screeninfo>The &kde; Text-to-Speech Manager (Talkers tab).</screeninfo>
291 <mediaobjectco>
292 <imageobjectco>
293 <areaspec units="calspair">
294 <area id="pt-talker-1" coords="1 1"/>
295 <area id="pt-talker-2" coords="1 1"/>
296 <area id="pt-talker-3" coords="1 1"/>
297 <area id="pt-talker-4" coords="1 1"/>
298 <area id="pt-talker-5" coords="1 1"/>
299 <area id="pt-talker-6" coords="1 1"/>
300 </areaspec>
301 <imageobject>
302 <imagedata fileref="talkers.png" format="PNG"/>
303 </imageobject>
304 </imageobjectco>
305 <textobject>
306 <phrase>The &kde; Text-to-Speech Manager (Talkers tab)</phrase>
307 </textobject>
308 </mediaobjectco>
309 </screenshot>
310 </para>
312 <para>
313 <calloutlist>
314 <callout arearefs="pt-talker-1"><para>Click to add a new talker.</para></callout>
315 <callout arearefs="pt-talker-2"><para>All the configured <guilabel>Talkers</guilabel> are listed here. Highest priority <guilabel>Talkers</guilabel> are listed at the top. The top-most talker will be used to do the speaking when an application does not specify a talker.</para></callout>
316 <callout arearefs="pt-talker-3"><para>Click on a talker in the list to highlight it and click this button to remove it.</para></callout>
317 <callout arearefs="pt-talker-4"><para>Click on a talker in the list to highlight it and click this button to display the synthesis plugin's configuration dialog. See below.</para></callout>
318 <callout arearefs="pt-talker-5"><para>Click on a talker in the list to highlight it and click this button to move it down one row in the list. The lower a talker appears in the list, the lower its priority.</para></callout>
319 <callout arearefs="pt-talker-6"><para>Click one of these buttons to apply the changes you have made to the running &ktts; system.</para></callout>
320 </calloutlist>
321 </para>
323 <para>When you click the <guibutton>Add</guibutton> button, the <guilabel>Add Talker</guilabel> screen appears.</para>
325 <para>
326 <screenshot>
327 <screeninfo>Add Talker screen.</screeninfo>
328 <mediaobjectco>
329 <imageobjectco>
330 <areaspec units="calspair">
331 <area id="pt-addtalker-1" coords="1 1"/>
332 <area id="pt-addtalker-2" coords="1 1"/>
333 <area id="pt-addtalker-3" coords="1 1"/>
334 </areaspec>
335 <imageobject>
336 <imagedata fileref="addtalker.png" format="PNG"/>
337 </imageobject>
338 </imageobjectco>
339 <textobject>
340 <phrase>Add Talker screen</phrase>
341 </textobject>
342 </mediaobjectco>
343 </screenshot>
344 </para>
346 <para>
347 <calloutlist>
348 <callout arearefs="pt-addtalker-1"><para>You can select a speech synthesis
349 plugin by either <guilabel>Synthesizer</guilabel> name, or by the <guilabel>Language</guilabel> the synthesizer can speak.
350 Check the radio button next to the corresponding box. When the
351 <guilabel>Language</guilabel> radio button is checked, the
352 <guilabel>Language</guilabel> box displays all the languages supported by
353 all available synthesizers, and the <guilabel>Synthesizer</guilabel> box
354 displays only those synthesizers that support the chosen language.
355 When the <guilabel>Synthesizer</guilabel> radio button is checked,
356 the <guilabel>Synthesizer</guilabel> box displays all available
357 synthesizers, and the <guilabel>Language</guilabel> box displays
358 only the languages supported by the chosen synthesizer.</para></callout>
359 <callout arearefs="pt-addtalker-2"><para>Choose the language and
360 synthesizer plugin here.</para></callout>
361 <callout arearefs="pt-addtalker-3"><para>When you click here,
362 most synthesizer plugins will automatically configure themselves,
363 choosing a default setup. A new talker
364 will appear in the list in the <guilabel>Talkers</guilabel> screen.
365 Click the <guibutton>Edit</guibutton> button to display or edit the talker's
366 configuration.</para></callout>
367 </calloutlist>
368 </para>
370 <para>When you click the <guibutton>Add</guibutton> button on the
371 <guilabel>Talkers</guilabel> tab and add a talker that cannot
372 automatically configure itself, or click the
373 <guibutton>Edit</guibutton> button,
374 the <guilabel>Talker Configuration</guilabel> screen appears.
375 Each speech synthesis plugin has a different
376 <guilabel>Talker Configuration</guilabel> screen. The following is an example for
377 configuring the Festival Interactive plugin. For specifics for each
378 kind of plugin, see <xref linkend="configuration" />.</para>
380 <para>
381 <screenshot>
382 <screeninfo>Talker Configuration</screeninfo>
383 <mediaobjectco>
384 <imageobjectco>
385 <areaspec units="calspair">
386 <area id="pt-prop-1" coords="1 1"/>
387 <area id="pt-prop-2" coords="1 1"/>
388 <area id="pt-prop-3" coords="1 1"/>
389 <area id="pt-prop-4" coords="1 1"/>
390 <area id="pt-prop-5" coords="1 1"/>
391 <area id="pt-prop-6" coords="1 1"/>
392 <area id="pt-prop-7" coords="1 1"/>
393 </areaspec>
394 <imageobject>
395 <imagedata fileref="festivalintconf.png" format="PNG"/>
396 </imageobject>
397 </imageobjectco>
398 <textobject>
399 <phrase>Talker Configuration</phrase>
400 </textobject>
401 </mediaobjectco>
402 </screenshot>
403 </para>
405 <para>
406 <calloutlist>
407 <callout arearefs="pt-prop-1"><para>Specify the path to the Festival executable program.
408 If Festival is in your PATH environment variable, just enter
409 <userinput><replaceable>festival</replaceable></userinput>.</para></callout>
410 <callout arearefs="pt-prop-2"><para>Click to scan for available voices.</para></callout>
411 <callout arearefs="pt-prop-3"><para>Select a voice.</para></callout>
412 <callout arearefs="pt-prop-4"><para>Select a character encoding for text sent to Festival.
413 For voices that are known to &ktts;, this setting will be picked for you automatically. In general, western languages use ISO 8859-1. Eastern European languages such
414 as Czech or Slovak use ISO 8859-2.</para></callout>
415 <callout arearefs="pt-prop-5"><para>Click to test. You should hear a test sentence spoken.</para></callout>
416 <callout arearefs="pt-prop-6"><para>Use these controls to set the volume, talking speed, and
417 pitch (tone) of the synthesized speech. If any of these are disabled (grayed), the chosen
418 voice does not support changing them.</para></callout>
419 <callout arearefs="pt-prop-7"><para>Some voices, such as the MultiSyn voices, are so large
420 that they require several seconds to load. Checking this box will cause them to be loaded
421 when KTTSD is started, thereby saving time (at the expense of using more memory)
422 before the first sentence is synthesized.</para></callout>
423 </calloutlist>
424 </para>
426 <para>Click the <guibutton>OK</guibutton> button to save the talker configuration settings.</para>
428 <warning><para>
429 Be sure to click the <guibutton>Apply</guibutton> button, otherwise your
430 changes will not take effect in the running &ktts; system.
431 </para></warning>
433 <para>Assuming the test worked, you are almost ready to begin using &ktts;.
434 Now go back to the <guilabel>General</guilabel> tab and check the
435 <guilabel>Enable Text-to-Speech System (KTTSD)</guilabel> box. This
436 will start the &kde; TTS Daemon. See <xref linkend="general" />.
437 You may now begin using &ktts; to
438 speak text. Click the <guilabel>Jobs</guilabel> tab to create and manage text jobs.
439 See <xref linkend="jobmgr" />.
440 </para>
442 </sect1>
444 <!-- ...................................................................... -->
447 <sect1 id="general">
448 <title>Starting KTTSD and Setting General Options</title>
450 <para>Once you have configured at least one talker,
451 you can start the &kde; Text-to-Speech System. Click on the
452 <guilabel>General</guilabel> tab. The <guilabel>General</guilabel>
453 screen appears. You can also set some general options on this screen.
454 </para>
456 <para>
457 <screenshot>
458 <screeninfo>The &kde; Text-to-Speech Manager (General tab).</screeninfo>
459 <mediaobjectco>
460 <imageobjectco>
461 <areaspec units="calspair">
462 <area id="pt-gen-1" coords="1 1"/>
463 <area id="pt-gen-2" coords="1 1"/>
464 <area id="pt-gen-3" coords="1 1"/>
465 <area id="pt-gen-4" coords="1 1"/>
466 <area id="pt-gen-5" coords="1 1"/>
467 <area id="pt-gen-6" coords="1 1"/>
468 </areaspec>
469 <imageobject>
470 <imagedata fileref="general.png" format="PNG"/>
471 </imageobject>
472 </imageobjectco>
473 <textobject>
474 <phrase>The &kde; Text-to-Speech Manager (General tab)</phrase>
475 </textobject>
476 </mediaobjectco>
477 </screenshot>
478 </para>
480 <para>
481 <calloutlist>
482 <callout arearefs="pt-gen-1"><para>Check this box to activate the &ktts; system.
483 This starts the &kde; TTS Daemon (KTTSD). If KTTSD starts successfully,
484 the <guilabel>Jobs</guilabel> tab will appear.
485 Once KTTSD has been started, you can begin creating and speaking text jobs.
486 See <xref linkend="jobmgr" />. Unchecking will stop KTTSD and deactivate the &kde; TTS system.
487 <note><para>If this box is disabled, you have not yet configured any talkers
488 (or you forgot to click the <guibutton>Apply</guibutton> button).
489 See <xref linkend="configure-plugin"/>.</para></note>
490 </para></callout>
491 <callout arearefs="pt-gen-2"><para>When this box is checked, an icon appears
492 in the system tray whenever <command>kttsmgr</command> is running. In this
493 mode, clicking <guibutton>OK</guibutton> or <guibutton>Cancel</guibutton> does
494 not cause <command>kttsmgr</command> to exit. Instead, the screen
495 disappears but <command>kttsmgr</command> continues running in the system
496 tray. Click the icon to restore the screen. To quit <command>kttsmgr</command>,
497 right-click on the icon in the system tray and choose <guilabel>Quit</guilabel>.
498 When unchecked, an icon does not appear in the system tray. Clicking <guibutton>OK</guibutton>
499 or <guibutton>Cancel</guibutton> quits <command>kttsmgr</command>.
500 <note><para>When <command>kttsmgr</command> exits,
501 &ktts; keeps running if the <guilabel>Enable Text-to-Speech System (KTTSD)</guilabel> box is checked.</para></note>
502 <note><para>This option does not take effect until the next time
503 <command>kttsmgr</command> is started.</para></note>
504 <note><para>This option has no effect when <command>kttsmgr</command> is
505 running in the &kcontrol;.</para></note>
506 </para></callout>
507 <callout arearefs="pt-gen-3"><para>When this box is checked, the <command>kttsmgr</command> screen appears when you start <command>kttsmgr</command>. If unchecked, the
508 <command>kttsmgr</command> icon appears in the system tray when
509 <command>kttsmgr</command> is started, but the screen does not appear.
510 Click the icon in the system tray to make the screen appear.</para></callout>
511 <callout arearefs="pt-gen-4"><para>When this box is checked, and <command>kttsmgr</command> is
512 not already running, it will appear in the system tray whenever KTTSD is speaking.
513 This gives you an opportunity to stop or otherwise manage the speaking.</para></callout>
514 <callout arearefs="pt-gen-5"><para>When this box is checked, and <command>kttsmgr</command>
515 automatically appears in the system tray whenever speaking, it will also disappear
516 automatically when speaking has finished.</para></callout>
517 <callout arearefs="pt-gen-6"><para>Be sure to click here to save your settings.</para></callout>
518 </calloutlist>
519 </para>
521 </sect1>
523 <!-- ...................................................................... -->
526 <sect1 id="jobmgr">
527 <title>Managing Text Jobs</title>
529 <para>When you click the <guilabel>Jobs</guilabel> tab in <command>kttsmgr</command>,
530 the <guilabel>Jobs</guilabel> screen appears.</para>
532 <para>
533 <screenshot>
534 <screeninfo>The &kde; Text-to-Speech Manager (Jobs tab).</screeninfo>
535 <mediaobjectco>
536 <imageobjectco>
537 <areaspec units="calspair">
538 <area id="pt-jobmgr-1" coords="1 1"/>
539 <area id="pt-jobmgr-2" coords="1 1"/>
540 <area id="pt-jobmgr-3" coords="1 1"/>
541 <area id="pt-jobmgr-4" coords="1 1"/>
542 <area id="pt-jobmgr-5" coords="1 1"/>
543 <area id="pt-jobmgr-6" coords="1 1"/>
544 <area id="pt-jobmgr-7" coords="1 1"/>
545 </areaspec>
546 <imageobject>
547 <imagedata fileref="jobs.png" format="PNG"/>
548 </imageobject>
549 </imageobjectco>
550 <textobject>
551 <phrase>The &kde; Text-to-Speech Manager (Jobs tab)</phrase>
552 </textobject>
553 </mediaobjectco>
554 </screenshot>
555 </para>
557 <para>
558 <calloutlist>
559 <callout arearefs="pt-jobmgr-1"><para>All of the text jobs currently in the queue
560 are listed here, together with the application that queued the job,
561 the current job state, number of sentences in the job,
562 and current sentence number. The <guilabel>Talker ID</guilabel> corresponds to the
563 <guilabel>ID</guilabel> column on the <guilabel>Talkers</guilabel> screen.
564 </para></callout>
565 <callout arearefs="pt-jobmgr-2"><para>The buttons in this row permit you to start,
566 delete, and pause text jobs. Select a job in the list above, then click
567 one of these buttons.</para></callout>
568 <callout arearefs="pt-jobmgr-3"><para>The buttons in this row permit
569 you to advance or rewind by sentence within the job selected in the list
570 above. (Not all jobs have multiple parts.)</para></callout>
571 <callout arearefs="pt-jobmgr-4"><para>The buttons in this row permit
572 you to speak the text currently in the &kde; clipboard, or open a text file
573 for speaking. You can also refresh the list of text jobs or
574 change the talker for a job. See <xref linkend="selecttalker" />.</para></callout>
575 <callout arearefs="pt-jobmgr-5"><para>The currently-speaking sentence
576 appears here.</para></callout>
577 <callout arearefs="pt-jobmgr-6"><para>When you click <guibutton>OK</guibutton>,
578 all changes to settings on other screens are applied (if any) and
579 <command>kttsmgr</command> minimizes to the system tray. Click on the icon
580 in the system tray to restore the screen.</para></callout>
581 <callout arearefs="pt-jobmgr-7"><para>Drag this divider to resize
582 the jobs listing and <guilabel>Current sentence</guilabel> panels.</para></callout>
583 </calloutlist>
584 </para>
586 <note><para>The <guilabel>Jobs</guilabel> tab only appears when KTTSD is running. If you do not see the <guilabel>Jobs</guilabel> tab, click on the
587 <guilabel>General</guilabel> tab and check the
588 <guilabel>Enable Text-to-Speech (KTTSD)</guilabel> box.</para>
589 </note>
591 <note><para>If you do not have the &arts; audio subsystem installed, but you
592 do have ALSA, GStreamer, or aKode installed, click the <guilabel>Audio</guilabel> tab.
593 See <xref linkend="audio" />.</para></note>
595 <note><para>Only Text jobs are listed and controlled on this screen.
596 Screen Reader Output, Warnings, and Messages are not displayed. For more information
597 about &ktts; message types, see <xref linkend="filters" />.</para></note>
599 </sect1>
601 <!-- ...................................................................... -->
603 <sect1 id="audio">
604 <title>Audio Settings</title>
606 <para>When you click the <guilabel>Audio</guilabel> tab in <command>kttsmgr</command>,
607 the <guilabel>Audio</guilabel> screen appears.</para>
609 <para>
610 <screenshot>
611 <screeninfo>The &kde; Text-to-Speech Manager (Audio tab).</screeninfo>
612 <mediaobjectco>
613 <imageobjectco>
614 <areaspec units="calspair">
615 <area id="pt-audio-1" coords="1 1"/>
616 <area id="pt-audio-2" coords="1 1"/>
617 <area id="pt-audio-3" coords="1 1"/>
618 <area id="pt-audio-4" coords="1 1"/>
619 <area id="pt-audio-5" coords="1 1"/>
620 </areaspec>
621 <imageobject>
622 <imagedata fileref="audio.png" format="PNG"/>
623 </imageobject>
624 </imageobjectco>
625 <textobject>
626 <phrase>The &kde; Text-to-Speech Manager (Audio tab)</phrase>
627 </textobject>
628 </mediaobjectco>
629 </screenshot>
630 </para>
632 <para>
633 <calloutlist>
634 <callout arearefs="pt-audio-1"><para>Select the method of audio output here.
635 If a component is is grayed, either &ktts; was compiled
636 without that support for that audio plugin, or &ktts; was unable to load the
637 necessary libraries.
638 </para></callout>
639 <callout arearefs="pt-audio-2"><para>If GStreamer or aKode is selected for audio output,
640 choose the audio sink method here. If no sinks are listed, you need
641 to install at least one. If ALSA is selected, choose the PCM device here. See <xref linkend="requirements" />.
642 </para></callout>
643 <callout arearefs="pt-audio-3"><para>Adjust the speed of talking here.
644 50% is approximately twice as slow as normal while 200% is approximately
645 twice as fast. You must have the <command>sox</command> utility installed for this setting
646 to work.
647 </para></callout>
648 <callout arearefs="pt-audio-4"><para>When this box is checked, &ktts; will
649 copy temporary audio files (.wav files) into the indicated folder. Choose
650 any folder on your hard drive you like, but you must have write access to it.
651 This can be useful for creating audio files of speech for other purposes.
652 The files will have names of the form <filename>kttsd-J-SS</filename> where
653 <filename>J</filename> is the job number and <filename>SS</filename> is the sentence number.
654 Existing files with the same name will be deleted.
655 <emphasis>Do not forget to uncheck this box, otherwise your hard drive will fill up!</emphasis>
656 </para></callout>
657 <callout arearefs="pt-audio-5"><para>Be sure to click <guibutton>Apply</guibutton>
658 to apply the new settings to the running &ktts; system.
659 </para></callout>
660 </calloutlist>
661 </para>
663 <note><para>There are two ways to adjust the speed of speech in &ktts;.
664 Many of the <guilabel>Talkers</guilabel> have a <guilabel>Speed</guilabel>
665 setting in their configuration dialogs, which you can display by clicking
666 <guibutton>Edit</guibutton> on the <guilabel>Talkers</guilabel> screen. This
667 <guilabel>Speed</guilabel> setting on the <guilabel>Audio</guilabel> screen
668 is in addition to the talker speed setting and generally can be used
669 even if the talker does not support a speed setting. For this speed setting
670 to work, you must have the <command>sox</command>
671 utility installed on your system (Debian users:
672 <command>apt-get install sox</command>). Also, this speed setting is ignored
673 when speaking text containing SSML. (See <xref linkend="ssml" />)</para></note>
675 <note><para>The list of ALSA devices includes all the ALSA PCM devices and
676 plugins configured in your system. Many of the choices will not work.
677 You must experiment to find a device that works for you. If in doubt,
678 choose <guilabel>default</guilabel>.</para></note>
680 </sect1>
682 <!-- ...................................................................... -->
684 <sect1 id="interruption">
685 <title>Text Interruption Settings</title>
687 <para>When you click the <guilabel>Interruption</guilabel> tab in <command>kttsmgr</command>,
688 the <guilabel>Interruption</guilabel> screen appears.</para>
690 <para>
691 <screenshot>
692 <screeninfo>The &kde; Text-to-Speech Manager (Interruption tab).</screeninfo>
693 <mediaobjectco>
694 <imageobjectco>
695 <areaspec units="calspair">
696 <area id="pt-interruption-1" coords="1 1"/>
697 <area id="pt-interruption-2" coords="1 1"/>
698 <area id="pt-interruption-3" coords="1 1"/>
699 <area id="pt-interruption-4" coords="1 1"/>
700 </areaspec>
701 <imageobject>
702 <imagedata fileref="interruption.png" format="PNG"/>
703 </imageobject>
704 </imageobjectco>
705 <textobject>
706 <phrase>The &kde; Text-to-Speech Manager (Interruption tab)</phrase>
707 </textobject>
708 </mediaobjectco>
709 </screenshot>
710 </para>
712 <para>This screen permits you to specify special actions to be taken whenever
713 a text job is interrupted by another, higher priority, message. There are
714 four kinds of speech jobs that &ktts; handles:
715 <itemizedlist>
716 <listitem><para>Regular text.</para></listitem>
717 <listitem><para>Messages.</para></listitem>
718 <listitem><para>Warnings.</para></listitem>
719 <listitem><para>Screen Reader Output.</para></listitem>
720 </itemizedlist>
721 </para>
723 <para>Screen Reader Output has the highest priority. It is reserved for use
724 by Screen Reader applications. Screen Reader Output preempts all other
725 messages, causing those jobs to pause. Once the Screen Reader Output has
726 been spoken, the preempted jobs will automatically resume.
727 </para>
729 <para>Warnings are the next highest priority. It is reserved for high-priority
730 messages, such as "CPU is over-heating." A Warning will preempt Messages
731 and regular text, causing those jobs to pause. Once the Warning has been
732 spoken, the preempted jobs will automatically resume.</para>
734 <para>Messages are the next highest priority. A Message will preempt regular
735 text jobs. &kmouth; is an example of an application that uses Messages.
736 For example, while reading out long text from a web page,
737 &kmouth; can be used to greet someone who walks into the room.</para>
739 <para>All four kinds of jobs are queues, except for Screen Reader Output.
740 If a Screen Reader Output is sent from an application while
741 &ktts; is speaking another Screen Reader Output, the speaking message
742 is stopped and discarded.</para>
744 <para>When a text job is interrupted by a Message, Warning, or Screen Reader Output,
745 &ktts; will add the audio outputs on this screen to the stream.</para>
747 <para>
748 <calloutlist>
749 <callout arearefs="pt-interruption-1"><para>This message is spoken whenever a regular text job is interrupted.</para></callout>
750 <callout arearefs="pt-interruption-2"><para>This audio file is sounded whenever a regular text job is interrupted. If both a <guilabel>Pre-sound</guilabel>
751 and a <guilabel>Pre-message</guilabel> are specified, the
752 <guilabel>Pre-sound</guilabel> is sounded before the <guilabel>Pre-message</guilabel>.</para></callout>
753 <callout arearefs="pt-interruption-3"><para>This message is spoken whenever an
754 interrupted text job resumes.</para></callout>
755 <callout arearefs="pt-interruption-4"><para>This audio file is sounded whenever an
756 interrupted text job resumes. It is sounded last.</para></callout>
757 </calloutlist>
758 </para>
760 <note><para>The settings on this screen apply only to regular text jobs.
761 Messages, Warnings, and Screen Reader Outputs have no special actions when
762 they are preempted by a higher-priority message.</para></note>
764 </sect1>
766 <!-- ...................................................................... -->
769 <sect1 id="web">
770 <title>Speaking Text from Web Pages</title>
772 <para>While running the &kde; &konqueror; web browser, you can speak the text
773 of the web page displayed. First ensure that &ktts; is running.
774 Highlight the text you want spoken and choose
775 <menuchoice>
776 <guisubmenu>Tools</guisubmenu>
777 <guisubmenu>Speak Text</guisubmenu>
778 </menuchoice> on the main menu.
779 <action>After a moment, the highlighted text should begin speaking.</action>
780 </para>
782 <tip><para>It is almost always a good idea to highlight the text on the
783 web page you want spoken. You can skip this step, but you will
784 hear a lot of &HTML; headers and other invisible tags spoken.</para></tip>
786 </sect1>
788 <!-- ...................................................................... -->
791 <sect1 id="kate">
792 <title>Speaking Text from &kate; Text Editor</title>
794 <para>While running the &kde; Advanced Text Editor (&kate;), you can speak the text
795 displayed. First ensure that &ktts; is running.
796 Highlight the text you want spoken and choose
797 <menuchoice>
798 <guisubmenu>Tools</guisubmenu>
799 <guisubmenu>Speak Text</guisubmenu>
800 </menuchoice> on the main menu.
801 <action>After a moment, the highlighted text should begin speaking.</action>
802 </para>
804 <tip><para>You do not have to first highlight text. In this case, the entire
805 file will be spoken.</para></tip>
807 <tip><para>This also works when &kate; is running embedded in another application,
808 such as &konqueror; or &quanta;.</para></tip>
810 </sect1>
812 <!-- ...................................................................... -->
814 <sect1 id="knotify">
815 <title>Speaking Notifications (KNotify)</title>
817 <para>KNotify is the notification subsystem within &kde;, which alerts you
818 to events you configure within the &kde; system. You can configure
819 &ktts; to speak text notifications.</para>
821 <para>For example, &konversation;, a &kde; IRC application, permits you
822 to configure a wide variety of notifications. For instance, you can tell
823 &konversation; to notify you whenever a message appears in an IRC channel
824 with your nickname in it. Together with &ktts; you can
825 have &kde; speak the text of the IRC message to you.</para>
827 <para>In general, if a &kde; application supports KNotify, a
828 <guilabel>Notifications</guilabel> menu item will appear under the
829 application's <guilabel>Settings</guilabel> menu. The specifics for configuring
830 each application with KNotify vary from application to application.</para>
832 <para>To enable &ktts; to speak KNotify text notifications,
833 start <command>kttsmgr</command> and click the <guilabel>Notifications</guilabel> tab.
834 The <guilabel>Notifications</guilabel> screen appears.</para>
836 <para>
837 <screenshot>
838 <screeninfo>The &kde; Text-to-Speech Manager (Notifications tab).</screeninfo>
839 <mediaobjectco>
840 <imageobjectco>
841 <areaspec units="calspair">
842 <area id="pt-notify-1" coords="1 1"/>
843 <area id="pt-notify-2" coords="1 1"/>
844 <area id="pt-notify-3" coords="1 1"/>
845 <area id="pt-notify-4" coords="1 1"/>
846 <area id="pt-notify-5" coords="1 1"/>
847 <area id="pt-notify-6" coords="1 1"/>
848 <area id="pt-notify-7" coords="1 1"/>
849 <area id="pt-notify-8" coords="1 1"/>
850 <area id="pt-notify-9" coords="1 1"/>
851 <area id="pt-notify-10" coords="1 1"/>
852 </areaspec>
853 <imageobject>
854 <imagedata fileref="notifications.png" format="PNG"/>
855 </imageobject>
856 </imageobjectco>
857 <textobject>
858 <phrase>The &kde; Text-to-Speech Manager (Notification tab)</phrase>
859 </textobject>
860 </mediaobjectco>
861 </screenshot>
862 </para>
864 <para>
865 <calloutlist>
866 <callout arearefs="pt-notify-1"><para>Check this box to enable speaking of
867 &kde; notifications. If unchecked, everything else on this screen is disabled
868 and &ktts; does not speak any notifications.</para></callout>
869 <callout arearefs="pt-notify-2"><para>When checked, any application
870 that sends an event with a sound will not be spoken by &ktts;.</para></callout>
871 <callout arearefs="pt-notify-3"><para>Use these buttons to add or delete
872 application events from the list below. When you click
873 the <guibutton>Add</guibutton> button, a screen appears in which
874 you select the application and event you want to add to the list.
875 </para></callout>
876 <callout arearefs="pt-notify-4"><para>This event will speak the message
877 &konversation; sends when someone mentions your nickname in an Internet Relay Chat message.
878 </para></callout>
879 <callout arearefs="pt-notify-5"><para>For all other events coming from
880 &konversation;, no action will be taken in &ktts;.</para></callout>
881 <callout arearefs="pt-notify-6"><para>For all events not otherwise
882 specified in the list, no action will be taken in &ktts;.</para></callout>
883 <callout arearefs="pt-notify-7"><para>Use this box to specify what
884 &ktts; should do when it receives an event. Your choices are:</para>
885 <para>
886 <variablelist>
887 <varlistentry>
888 <term>Speak event name</term>
889 <listitem><para>Speaks the name of the event; what you see listed in the
890 event list on this screen.</para></listitem>
891 </varlistentry>
892 <varlistentry>
893 <term>Speak the notification message</term>
894 <listitem><para>Speaks the message as it is sent from the application.</para></listitem>
895 </varlistentry>
896 <varlistentry>
897 <term>Do not speak the notification</term>
898 <listitem><para>Does not speak this event at all.</para></listitem>
899 </varlistentry>
900 <varlistentry>
901 <term>Speak custom text</term>
902 <listitem><para>Speaks the text you enter in the box to the right.</para></listitem>
903 </varlistentry>
904 </variablelist>
905 </para>
906 </callout>
907 <callout arearefs="pt-notify-8"><para>If the action is
908 <guilabel>Speak custom text</guilabel>, enter the text of the message
909 you would like spoken here. Within the message, you may use the following
910 substitution strings:</para>
911 <para>
912 <variablelist>
913 <varlistentry>
914 <term>%e</term>
915 <listitem><para>The name of the event</para></listitem>
916 </varlistentry>
917 <varlistentry>
918 <term>%a</term>
919 <listitem><para>The name of the application that sent the event</para></listitem>
920 </varlistentry>
921 <varlistentry>
922 <term>%m</term>
923 <listitem><para>The message the application sent</para></listitem>
924 </varlistentry>
925 </variablelist>
926 </para>
927 </callout>
928 <callout arearefs="pt-notify-9"><para>Test the message by clicking here.</para></callout>
929 <callout arearefs="pt-notify-10"><para>You may specify the attributes of the
930 desired talker to speak the notification message here.
931 <command><userinput>default</userinput></command>
932 will use the topmost talker listed in the <guilabel>Talkers</guilabel>
933 screen. See <xref linkend="selecttalker" />.
934 </para></callout>
935 </calloutlist>
936 </para>
938 <para>Notice there are three levels of events. If an action for a specific event
939 of a specific application is specified, that action is taken. Otherwise, if
940 an action for all other events of a specific application is specified, that
941 action is taken. Otherwise, the action specified for all other events
942 under <guilabel>Default (all other events)</guilabel> is taken.</para>
944 <para>The event <guilabel>all notifications</guilabel>
945 for application <guilabel>Default (all other events)</guilabel>
946 may not be deleted from the list. For the default all other events,
947 you may specify the kind of notifications that are spoken, as follows:</para>
949 <variablelist>
950 <varlistentry>
951 <term>none</term>
952 <listitem><para>None will be spoken.</para></listitem>
953 </varlistentry>
954 <varlistentry>
955 <term>notification dialogs</term>
956 <listitem><para>Notifications that display a dialog on your screen, that you must then
957 dismiss, will be spoken.</para></listitem>
958 </varlistentry>
959 <varlistentry>
960 <term>passive popups</term>
961 <listitem><para>Notifications that display a passive dialog on your screen,
962 that automatically disappear after a moment, will be spoken.</para></listitem>
963 </varlistentry>
964 <varlistentry>
965 <term>notification dialogs and passive popups</term>
966 <listitem><para>Notifications that display on screen, passively or not,
967 will be spoken.</para></listitem>
968 </varlistentry>
969 <varlistentry>
970 <term>all notifications</term>
971 <listitem><para>All notifications, regardless of whether they produce
972 a display on screen, will be spoken.</para></listitem>
973 </varlistentry>
974 </variablelist>
976 <tip><para>String Replacer filters are a good way to clean up messages
977 sent from applications if they are mispronounced or misspoken in
978 &ktts;. The <filename>kmail.xml</filename> file, which
979 comes with &ktts;, is a good example. It removes <command>br</command>,
980 and <command>b</command> tags from the &kmail; notification messages and also removes the
981 phrase <command>/local/inbox/</command>, since this
982 may be safely assumed in most cases. See <xref linkend="stringreplacer" />.
983 </para></tip>
985 <para>Use the <guibutton>Save</guibutton> button to save your
986 notification settings to a file. Use the <guibutton>Load</guibutton>
987 button to load saved settings from a file. The loaded events are merged
988 with existing events in the list. If you want to start with
989 an empty event list, click the <guibutton>Clear</guibutton>
990 button first. All events except for <guilabel>all notifications</guilabel>
991 will be erased.</para>
993 <note><para>Be sure to click <guibutton>Apply</guibutton>
994 or <guibutton>OK</guibutton> to save your settings.</para></note>
996 </sect1>
998 <!-- ...................................................................... -->
1000 <sect1 id="ssml">
1001 <title>SSML</title>
1003 <para>The Speech Synthesis Markup Language (SSML) is a W3C standard
1004 for marking up text for speech output. It provides tags for controlling
1005 voices, rate of speech, volume, gender, and pitch (tone). It also
1006 provides tags for controlling how words are spoken, for instance
1007 spelling out abbreviations. SSML is part of the VoiceXML specification,
1008 which is also a W3C standard.</para>
1010 <para>At this time, &ktts; provides limited and very basic support for
1011 SSML. It currently has the following restrictions.</para>
1013 <itemizedlist>
1014 <listitem><para>Works only with the Festival Interactive and Hadifix Talkers.</para></listitem>
1015 <listitem><para>You must install the <command>rab_diphone</command>
1016 (British male) voice, as this is the default voice Festival uses when speaking
1017 SSML.</para></listitem>
1018 <listitem><para>The <guilabel>Speed</guilabel> setting on the <guilabel>Audio</guilabel>
1019 screen is ignored when speaking text containing SSML.</para></listitem>
1020 <listitem><para>If the <guilabel>Speed</guilabel> or <guilabel>Pitch</guilabel>
1021 settings in the Festival configuration dialog are not set to 100%, it
1022 will usually cause the SSML text to be spoken in a monotone.</para></listitem>
1023 </itemizedlist>
1025 <para>The following sample text can be used to experiment with SSML.</para>
1027 <programlisting><![CDATA[
1028 <?xml version="1.0" encoding="UTF-8"?>
1029 <!DOCTYPE speak PUBLIC "-//W3C//DTD SYNTHESIS 1.0//EN"
1030 "http://www.w3.org/TR/speech-synthesis/synthesis.dtd">
1032 <speak version="1.0" xml:lang="en-US">
1033 <prosody pitch="low">
1034 Who's been sleeping in my bed?
1035 </prosody>
1036 said papa bear.
1037 <prosody pitch="medium">
1038 Who's been sleeping in my bed?
1039 </prosody>
1040 said momma bear.
1041 <prosody pitch="high">
1042 Who's been sleeping in my bed?
1043 </prosody>
1044 said baby bear.
1045 </speak>
1046 ]]></programlisting>
1048 <para>More robust support for SSML is planned for the next version of
1049 &ktts;.
1050 </para>
1052 </sect1>
1054 <!-- ...................................................................... -->
1056 <sect1 id="filters">
1057 <title>Filters (Advanced)</title>
1059 <para>Filters are an advanced feature of &ktts;. For the
1060 basic operation of &ktts;, they are not needed.</para>
1062 <para>Filters are used to pre-process text before it is sent to the
1063 speech synthesis engine. They are useful for enhancing speech,
1064 substituting for misspoken words or abbreviations, choosing the
1065 appropriate language and talker to do the speaking, or working around
1066 certain limitations of speech synthesizers and their voices.</para>
1068 <!-- ...................................................................... -->
1070 <sect2 id="msg-types">
1071 <title>Types of &ktts; Messages</title>
1073 <para>To understand how to use filters, it is
1074 helpful to first understand how text is processed by &ktts;.
1075 Text spoken by &ktts; is of four possible types.</para>
1077 <para>
1078 <itemizedlist>
1079 <listitem><para>Screen Reader Output.</para></listitem>
1080 <listitem><para>Warnings.</para></listitem>
1081 <listitem><para>Messages</para></listitem>
1082 <listitem><para>Text Jobs</para></listitem>
1083 </itemizedlist>
1084 </para>
1086 <para>The type is determined by the application that sends the text
1087 to &ktts;.</para>
1089 <para>Screen Reader Output has the highest priority. It is reserved for use
1090 by Screen Reader applications. Screen Reader Output preempts all other
1091 messages, causing those jobs to pause. Once the Screen Reader Output has
1092 been spoken, the preempted messages will automatically resume.
1093 </para>
1095 <para>Warnings are the next highest priority. It is reserved for high-priority
1096 messages, such as "CPU is over-heating." A Warning will preempt Messages
1097 and regular text, causing those jobs to pause. Once the Warning has been
1098 spoken, the preempted messages will automatically resume.</para>
1100 <para>Messages are the next highest priority. A Message will preempt regular
1101 text jobs. &kmouth; is an example of an application that uses Messages.
1102 For example, while reading out long text from a web page,
1103 &kmouth; can be used to greet someone who walks into the room.
1104 &kde; Notifications are also Messages (see <xref linkend="knotify" />).</para>
1106 <para>The rest are ordinary Text Jobs. Any job you initiate from the
1107 <guilabel>Jobs</guilabel> tab is a Text Job. KSayit is an example
1108 of an application that uses Text Jobs. Text Jobs are intended for
1109 longer speech output that is not urgent.</para>
1111 <para>All four kinds of jobs are queues, except for Screen Reader Output.
1112 If a Screen Reader Output is sent from an application while
1113 &ktts; is speaking another Screen Reader Output, the speaking message
1114 is stopped and discarded.</para>
1116 </sect2>
1118 <!-- ...................................................................... -->
1120 <sect2 id="filter-types">
1121 <title>Types of Filters</title>
1123 <para>The first thing you must know about filters is that they are
1124 never applied to Screen Reader Output. They are applied to
1125 Warnings, Messages, and Text jobs, and also &kde; notifications (KNotify).</para>
1127 <para>There are two kinds of filters --
1128 ordinary filters and Sentence Boundary Detector (SBD) filters.
1129 SBDs break text up into individual sentences. This allows
1130 &ktts; to begin speaking faster because it need only
1131 synthesize the first sentence; not the entire Text Job.
1132 It also permits you to advance or rewind by sentence in the
1133 <guilabel>Jobs</guilabel> tab, or to stop or pause Text Jobs when
1134 the speech synthesizer does not directly support stopping of speech.
1135 </para>
1137 <para>Ordinary filters process the text and pass it on to the
1138 next filter. There are currently three kinds of ordinary filters.
1139 </para>
1141 <para>
1142 <itemizedlist>
1143 <listitem><para>String Replacers.</para></listitem>
1144 <listitem><para>&XML; Transformers</para></listitem>
1145 <listitem><para>Talker Choosers.</para></listitem>
1146 </itemizedlist>
1147 </para>
1149 <note><para>Filters are implemented using a plugin architecture.
1150 In the future, there may be additional kinds of filters.</para></note>
1152 <para>String Replacer filters substitute pieces of text with
1153 other text. The replaced pieces are matched either as words or
1154 as regular expressions. &ktts; comes with pre-defined
1155 String Replacer filters for speaking abbreviations, speaking
1156 chat emoticons, such as ":-)", or reformatting notification
1157 messages from &konversation; or &kmail; into a more understandable
1158 form.
1159 </para>
1161 <para>&XML; Transformers use an &XML; Style Language - Transforms (XSLT)
1162 file to convert &XML; of one format to another format.
1163 &ktts; comes with a couple of XSLT files for converting
1164 &XHTML; into SSML.
1165 </para>
1167 <para>Talker Choosers permit you redirect jobs to a talker
1168 based on the contents of the text, or upon the application that sent it
1169 to &ktts;. For example, if you have configured a female talker
1170 in the <guilabel>Talkers</guilabel> tab, you can direct text coming from
1171 KSayIt to that talker. See <xref linkend="configure-plugin" />.
1172 </para>
1174 <para>Each of these kinds of filters has configurable rules for when
1175 the filter should apply itself to the text to be spoken. If the
1176 filter determines that it should not apply itself, the text
1177 is passed on to the next filter unaltered.</para>
1179 <para>When a Text Job, Message, Warning, or &kde; Notification message is sent to &ktts;,
1180 it passes through each of the enabled filters you have configured in the
1181 screen below. The order is from top to bottom. After passing through
1182 each of the ordinary filters listed in the top portion of the screen, Text Jobs
1183 are passed to the <guilabel>Sentence Boundary Detector</guilabel> (SBD) filters.
1184 (&kde; Notifications, Warnings, and Messages never pass through SBD filters.)
1185 Unlike ordinary filters, the first SBD filter that makes changes to the text
1186 stops any further filtering.
1187 </para>
1189 </sect2>
1191 <!-- ...................................................................... -->
1193 <sect2 id="configure-filters">
1194 <title>Configuring Filters</title>
1196 <para>To use filters, click the <guilabel>Filters</guilabel> tab in <command>kttsmgr</command>.</para>
1198 <para>
1199 <screenshot>
1200 <screeninfo>The &kde; Text-to-Speech Manager (Filters tab).</screeninfo>
1201 <mediaobjectco>
1202 <imageobjectco>
1203 <areaspec units="calspair">
1204 <area id="pt-filters-1" coords="1 1"/>
1205 <area id="pt-filters-2" coords="1 1"/>
1206 <area id="pt-filters-3" coords="1 1"/>
1207 <area id="pt-filters-4" coords="1 1"/>
1208 <area id="pt-filters-5" coords="1 1"/>
1209 <area id="pt-filters-6" coords="1 1"/>
1210 <area id="pt-filters-7" coords="1 1"/>
1211 <area id="pt-filters-8" coords="1 1"/>
1212 </areaspec>
1213 <imageobject>
1214 <imagedata fileref="filters.png" format="PNG"/>
1215 </imageobject>
1216 </imageobjectco>
1217 <textobject>
1218 <phrase>The &kde; Text-to-Speech Manager (Filters tab)</phrase>
1219 </textobject>
1220 </mediaobjectco>
1221 </screenshot>
1222 </para>
1224 <para>
1225 <calloutlist>
1226 <callout arearefs="pt-filters-1"><para>This is the list of configured ordinary filters.
1227 If unchecked, the filter is inactive and will be bypassed.
1228 Filters are applied in the order specified here, top to bottom.</para></callout>
1229 <callout arearefs="pt-filters-2"><para>Click here to add a new filter. You will
1230 be prompted for the kind of filter to add. After choosing the kind,
1231 see the configuration dialogs below.</para></callout>
1232 <callout arearefs="pt-filters-3"><para>Click here to remove a filter.</para></callout>
1233 <callout arearefs="pt-filters-4"><para>Click here to change the configuration
1234 of a filter. See the configuration dialogs below.</para></callout>
1235 <callout arearefs="pt-filters-5"><para>Click these buttons to move a filter
1236 up or down in the list.</para></callout>
1237 <callout arearefs="pt-filters-6"><para>These are the Sentence Boundary Detector
1238 filters. When you first start &ktts;, the Standard Sentence Boundary Detector
1239 is automatically configured for you. You can change this filter's configuration,
1240 or add additional Sentence Boundary Detectors, but we advise beginners not
1241 to change them.</para></callout>
1242 <callout arearefs="pt-filters-7"><para>This drop-down button permits you
1243 to add, remove, edit, or change the order of Sentence Boundary Detector filters.</para></callout>
1244 <callout arearefs="pt-filters-8"><para>Be sure to click here, otherwise your
1245 settings will not take effect.</para></callout>
1246 </calloutlist>
1247 </para>
1249 </sect2>
1251 <!-- ...................................................................... -->
1253 <sect2 id="stringreplacer">
1254 <title>Configuring String Replacer Filters</title>
1256 <para>You configure String Replacer filters by supplying
1257 a list of words or regular expressions to be matched.
1258 When the matched words or regular expressions are found in the
1259 text, each is replaced by a substitute string you supply.
1260 Matching is case insensitive.</para>
1262 <para>
1263 <screenshot>
1264 <screeninfo>String Replacer</screeninfo>
1265 <mediaobjectco>
1266 <imageobjectco>
1267 <areaspec units="calspair">
1268 <area id="pt-stringreplacer-1" coords="1 1"/>
1269 <area id="pt-stringreplacer-2" coords="1 1"/>
1270 <area id="pt-stringreplacer-3" coords="1 1"/>
1271 <area id="pt-stringreplacer-4" coords="1 1"/>
1272 <area id="pt-stringreplacer-5" coords="1 1"/>
1273 <area id="pt-stringreplacer-6" coords="1 1"/>
1274 <area id="pt-stringreplacer-7" coords="1 1"/>
1275 <area id="pt-stringreplacer-8" coords="1 1"/>
1276 <area id="pt-stringreplacer-9" coords="1 1"/>
1277 </areaspec>
1278 <imageobject>
1279 <imagedata fileref="stringreplacer.png" format="PNG"/>
1280 </imageobject>
1281 </imageobjectco>
1282 <textobject>
1283 <phrase>String Replacer</phrase>
1284 </textobject>
1285 </mediaobjectco>
1286 </screenshot>
1287 </para>
1289 <para>
1290 <calloutlist>
1291 <callout arearefs="pt-stringreplacer-1"><para>Enter a name for your filter. Use any
1292 name you like that distinquishes it from all other filters.</para></callout>
1293 <callout arearefs="pt-stringreplacer-2"><para>This is the list of words
1294 and regular expressions. The filter searches for matches on each string in
1295 the <guilabel>Match</guilabel> column, replacing the matched string
1296 with the string in the <guilabel>Replace With</guilabel> column. The list
1297 is processed in the order displayed, top to bottom.</para></callout>
1298 <callout arearefs="pt-stringreplacer-3"><para>Click here to add another word or
1299 regular expression to the list.</para></callout>
1300 <callout arearefs="pt-stringreplacer-4"><para>Click here to move the currently
1301 highlighted word or regular expression up or down in the list.</para></callout>
1302 <callout arearefs="pt-stringreplacer-5"><para>Click to change an existing word
1303 or regular expression in the list.</para></callout>
1304 <callout arearefs="pt-stringreplacer-6"><para>Click to remove the currently
1305 highlighted word or regular expression from the list.</para></callout>
1306 <callout arearefs="pt-stringreplacer-7"><para>Use these buttons to load
1307 a list of words or regular expression from a file, save the current list to
1308 a file, or clear the entire list. When loading from a file, the items in the
1309 file are appended to the existing list.</para></callout>
1310 <callout arearefs="pt-stringreplacer-8"><para>If not blank, the filter will
1311 apply itself only if the job's talker language matches
1312 the language you enter here. Click the button to display a list of languages.
1313 You may select more than one language by pressing
1314 <keycap>&Ctrl;</keycap> while clicking.</para></callout>
1315 <callout arearefs="pt-stringreplacer-9"><para>If not blank, the filter will
1316 apply itself only if the text came from one of the applications listed.
1317 You may enter more than one application separated by commas.
1318 Example: <command><userinput>konversation,kmail</userinput></command></para>
1319 <tip><para>You can discover the <guilabel>Application ID</guilabel>
1320 of running programs using the <command>&kdcop;</command> program.
1321 You should leave the &DCOP; numbers out. For example, if &kdcop; shows
1322 an Application ID of <command>kopete-3432</command>, you would just
1323 enter <command><userinput>kopete</userinput></command>.</para></tip></callout>
1324 </calloutlist>
1325 </para>
1327 <para>The String Replacer filter will only apply itself to the text
1328 if all non-blank conditions are met in the
1329 <guilabel>Apply This Filter When</guilabel> box.
1330 If all the boxes are blank, the filter will apply to all text.</para>
1332 <para>All matching is case insensitive.</para>
1334 <para>When matching words, the String Replacer filter internally uses a
1335 regular expression of the form <command>\s<userinput>word</userinput>\s</command>.
1336 In other words, the word must have word boundaries (spaces) on either side of it.</para>
1338 <para>A discussion on how to write regular expressions is outside the scope
1339 of this handbook. If you have the &kde; Regular Expression editor installed,
1340 there is a button available on the <guilabel>Add</guilabel> or
1341 <guilabel>Edit</guilabel> screens that will assist you at
1342 constructing regular expressions. The &kde; Regular Expression Editor is part
1343 of the <command>kdeutils</command> package.</para>
1345 <para>&ktts; comes with a few word list files, including a list
1346 of emoticons, such as ":-)", some abbreviations typically used in IRC or
1347 instant messaging applications, and a list of other abbreviations.
1348 There is also a list of special characters which the current version
1349 of the Polish Festival voice cannot handle.
1350 If you develop useful word lists of your own, use the <guibutton>Save</guibutton>
1351 button to save them to a file and send them to the
1352 &ktts; team for inclusion in the next version.</para>
1354 </sect2>
1356 <!-- ...................................................................... -->
1358 <sect2 id="xmltransformer">
1359 <title>Configuring &XML; Transformer Filters</title>
1361 <para>The &XML; Transformer filter uses XSLT files to transform &XML; from
1362 one format to another. XSLT, the &XML; Style Language - Transforms, is a W3C
1363 standard language for performing such transformations.
1364 It can only be used on well-formed &XML;. You must have the
1365 <command>xsltproc</command> utility installed.</para>
1367 <para>
1368 <screenshot>
1369 <screeninfo>&XML; Transformer</screeninfo>
1370 <mediaobjectco>
1371 <imageobjectco>
1372 <areaspec units="calspair">
1373 <area id="pt-xmltransformer-1" coords="1 1"/>
1374 <area id="pt-xmltransformer-2" coords="1 1"/>
1375 <area id="pt-xmltransformer-3" coords="1 1"/>
1376 <area id="pt-xmltransformer-4" coords="1 1"/>
1377 <area id="pt-xmltransformer-5" coords="1 1"/>
1378 </areaspec>
1379 <imageobject>
1380 <imagedata fileref="xmltransformer.png" format="PNG"/>
1381 </imageobject>
1382 </imageobjectco>
1383 <textobject>
1384 <phrase>&XML; Transformer</phrase>
1385 </textobject>
1386 </mediaobjectco>
1387 </screenshot>
1388 </para>
1390 <para>
1391 <calloutlist>
1392 <callout arearefs="pt-xmltransformer-1"><para>Enter a name for your filter. Use any
1393 name you like that distinquishes it from all other filters.</para></callout>
1394 <callout arearefs="pt-xmltransformer-2"><para>Enter the full path
1395 to an existing XSLT file, which will perform the transformation.</para></callout>
1396 <callout arearefs="pt-xmltransformer-3"><para>Specify the path to the
1397 <command>xsltproc</command> utility. If xsltproc is in your environment
1398 PATH, simply enter <command><userinput>xsltproc</userinput></command>.</para></callout>
1399 <callout arearefs="pt-xmltransformer-4"><para>If not blank, the filter
1400 will apply itself only if the &XML; has the specified root element
1401 or a <command><![CDATA[<!DOCTYPE]]></command> specification
1402 beginning with the entered string. This distinquishes one
1403 form of &XML; from another. For example,
1404 <command><userinput>html</userinput></command> in the
1405 <guilabel>DOCTYPE</guilabel> box will match
1406 <command><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">]]></command>.
1407 </para></callout>
1408 <callout arearefs="pt-xmltransformer-5"><para>If not blank, the filter will
1409 apply itself only if the text came from one of the applications listed.
1410 You may enter more than one application separated by commas.
1411 Example: <command><userinput>konversation,kmail</userinput></command></para>
1412 <tip><para>You can discover the <guilabel>Application ID</guilabel>
1413 of running programs using the <command>&kdcop;</command> program.
1414 You should leave the &DCOP; numbers out. For example, if &kdcop; shows
1415 an Application ID of <command>kopete-3432</command>, you would just
1416 enter <command><userinput>kopete</userinput></command>.</para></tip></callout>
1417 </calloutlist>
1418 </para>
1420 <para>The &XML; Transformer filter will only apply itself to the text
1421 if the specified root element or DOCTYPE are met and if the
1422 application ID is met in the
1423 <guilabel>Apply This Filter When</guilabel> box. If an item in this
1424 box is blank, the test is not performed, so if all the
1425 boxes are blank, the filter will apply itself to all text. However,
1426 you should fill in at least one box, since many text jobs will not be in
1427 &XML; format.</para>
1429 </sect2>
1431 <!-- ...................................................................... -->
1433 <sect2 id="talkerchooser">
1434 <title>Configuring Talker Chooser Filters</title>
1436 <para>Talker Chooser filters are used to direct the text to a desired
1437 talker configured in the <guilabel>Talker</guilabel> tab, or to any
1438 talker having specified attributes. For example,
1439 you can specify that text coming from <command>kmail</command>
1440 should be spoken using a talker configured with a female voice.
1441 See <xref linkend="configure-plugin" />.</para>
1443 <para>Just before &ktts; begins sending text to each of the
1444 filters, it picks a talker to speak the text. The talker chosen is
1445 based on the talker attributes specified by the application that sent
1446 the text to &ktts; and the attributes of the talkers that
1447 you have configured on the <guilabel>Talkers</guilabel> tab.
1448 The Talker Chooser filter permits you to override the
1449 chosen talker.
1450 </para>
1452 <para>
1453 <screenshot>
1454 <screeninfo>Talker Chooser</screeninfo>
1455 <mediaobjectco>
1456 <imageobjectco>
1457 <areaspec units="calspair">
1458 <area id="pt-talkerchooser-1" coords="1 1"/>
1459 <area id="pt-talkerchooser-2" coords="1 1"/>
1460 <area id="pt-talkerchooser-3" coords="1 1"/>
1461 <area id="pt-talkerchooser-4" coords="1 1"/>
1462 <area id="pt-talkerchooser-5" coords="1 1"/>
1463 </areaspec>
1464 <imageobject>
1465 <imagedata fileref="talkerchooser.png" format="PNG"/>
1466 </imageobject>
1467 </imageobjectco>
1468 <textobject>
1469 <phrase>Talker Chooser</phrase>
1470 </textobject>
1471 </mediaobjectco>
1472 </screenshot>
1473 </para>
1475 <para>
1476 <calloutlist>
1477 <callout arearefs="pt-talkerchooser-1"><para>Enter a name for your filter. Use any
1478 name you like that distinquishes it from all other filters.</para></callout>
1479 <callout arearefs="pt-talkerchooser-2"><para>If not blank, the filter will apply
1480 itself only if the text contains the entered regular expression. If it is installed,
1481 click the browse button to launch the &kde; Regular Expression Editor to assist you at entering
1482 the regular expression.</para>
1483 <tip><para>For better performance, try to "anchor" the regular expression to the
1484 start of the string. In other words, start your regular expression with
1485 <command><userinput><![CDATA[^]]></userinput></command>.</para></tip></callout>
1486 <callout arearefs="pt-talkerchooser-3"><para>If not blank, the filter will
1487 apply itself only if the text came from one of the applications listed.
1488 You may enter more than one application separated by commas.
1489 Example: <command><userinput>konversation,kmail</userinput></command></para>
1490 <tip><para>You can discover the <guilabel>Application ID</guilabel>
1491 of running programs using the <command>&kdcop;</command> program.
1492 You should leave the &DCOP; numbers out. For example, if &kdcop; shows
1493 an Application ID of <command>kopete-3432</command>, you would just
1494 enter <command><userinput>kopete</userinput></command>.</para></tip></callout>
1495 <callout arearefs="pt-talkerchooser-4"><para>Specify the attributes of the
1496 talker you prefer to speak the text here. If the text meets the filter
1497 conditions above, a talker will be chosen that most closely matches
1498 the attributes you specify here. Click the button at the right to
1499 display the <guilabel>Select Talker</guilabel> screen.
1500 See <xref linkend="selecttalker" />.</para></callout>
1501 <callout arearefs="pt-talkerchooser-5"><para>Use these buttons
1502 to save your Talker Chooser settings, load settings from a saved file,
1503 or clear all the settings.</para></callout>
1504 </calloutlist>
1505 </para>
1507 <para>The Talker Chooser filter will only apply itself to the text
1508 if all non-blank conditions are met in the
1509 <guilabel>Apply This Filter When</guilabel> box. You must fill in
1510 at least one of the boxes.</para>
1512 <para>The easiest way to learn how to configure Talker Choosers is
1513 to experiment. Disable the Talker Chooser and submit some text.
1514 In the <guilabel>Jobs</guilabel> tab, note the talker that
1515 &ktts; chooses. Click the <guibutton>Change Talker</guibutton>
1516 button, enter some attributes, and try again to see how the choice is affected.
1517 Of course, you must have more than one talker configured for
1518 the Talker Chooser to do anything.</para>
1520 </sect2>
1522 <!-- ...................................................................... -->
1524 <sect2 id="sbd">
1525 <title>Configuring Sentence Boundary Detector Filters</title>
1527 <para>Sentence Boundary Detector (SBD) filters break text up into individual sentences.
1528 This is important because it</para>
1530 <itemizedlist>
1531 <listitem><para>allows &ktts; to begin speaking faster
1532 because it need only synthesize the first sentence, rather than the entire
1533 block of text, which might be very long, and</para></listitem>
1534 <listitem><para>allows you to rewind and advance by sentences in the
1535 <guilabel>Jobs</guilabel> tab, and</para></listitem>
1536 <listitem><para>allows you to pause or stop Text Jobs in the
1537 <guilabel>Jobs</guilabel> tab even if the speech synthesizer is not
1538 capable of being stopped.</para></listitem>
1539 </itemizedlist>
1541 <para>For these reasons, the Standard Sentence Boundary Detector filter
1542 is automatically configured the first time you run <command>kttsmgr</command>
1543 and cannot be disabled (although you can remove it). We advise you
1544 not to modify this filter unless you know what you are doing.</para>
1546 <para>You can, however, add additional SBD filters to solve certain
1547 problems. For example, as of February 2005, the Polish Festival voice
1548 has the annoying attribute of speaking sentence punctuation. It will
1549 speak the periods at the end of each sentence, for instance. You cannot solve this problem
1550 by creating a String Replacer filter to remove the sentence punctuation,
1551 because doing so will prevent the Standard SBD from recognizing any
1552 sentences. Instead, you can create a modified version of the
1553 Standard SBD that recognizes sentences while simultaneously removing
1554 the sentence punctuation. To do this, add an SBD filter and use the
1555 <guibutton>Load</guibutton> button to load the <filename>polish_festival_sbdrc</filename>
1556 file that comes with &ktts;.</para>
1558 <para>SBD filters work by matching an end-of-sentence regular expression
1559 and inserting Tab (decimal 8) characters at the sentence boundaries.
1560 (All Tab characters are automatically stripped from text before filtering begins.)
1561 Note that the Standard SBD preserves the sentence punctuation.
1562 </para>
1564 <para>SBD filters are never applied to &kde; Notification messages (knotify),
1565 Warnings, Messages, or Screen Reader Outputs.</para>
1567 <para>If you accidentally remove the Standard Sentence Boundary Detectory filter,
1568 you can get it back by loading the <filename>standard_sbdrc</filename> file,
1569 which comes with &ktts;.</para>
1571 </sect2>
1573 </sect1>
1575 <!-- ...................................................................... -->
1577 <sect1 id="selecttalker">
1578 <title>Selecting Talkers (Advanced)</title>
1580 <para>You can configure
1581 any number of talkers in the <guilabel>Talkers</guilabel> tab.
1582 See <xref linkend="configure-plugin" />. When applications send text
1583 to &ktts;, they may specify the attributes of a desired
1584 talker to speak the text. &ktts; will pick the closest
1585 matching talker from among the talkers you have configured to satisfy
1586 the application's request. For example, an application might request
1587 the text be spoken by an English female voice. If you have configured
1588 a talker with English language and female gender, that talker will be used.
1589 If you have configured all English male talkers, one of those talkers
1590 will be used. If an application specifies no attributes,
1591 the default (topmost) talker listed in the <guilabel>Talkers</guilabel>
1592 tab is used.</para>
1594 <para>When applications specify the attributes of the desired talker,
1595 they may indicate that certain attributes are "preferred" over other
1596 attributes. For example, an application may specify that it wishes
1597 that a female loud voice speak the text, and that the loud attribute is
1598 "preferred" over the female attribute. If you had a female soft talker
1599 and a male loud talker configured, &ktts; will choose the male
1600 loud talker to do the speaking. Since language is a critical parameter
1601 in making speech understandable, it is always a "preferred" attribute.</para>
1603 <para>Using the <guilabel>Select Talker</guilabel> screen, you may
1604 override application talker settings. The screen is displayed</para>
1606 <itemizedlist>
1607 <listitem><para>when you click the <guibutton>Change Talker</guibutton>
1608 button on the <guilabel>Jobs</guilabel> tab, or</para></listitem>
1609 <listitem><para>when you click the <guilabel>Talker</guilabel> button
1610 on the <guilabel>Filter Configuration</guilabel> dialog for
1611 a Talker Chooser filter, or</para></listitem>
1612 <listitem><para>when you click the <guilabel>Talker</guilabel> button
1613 on the <guilabel>Notifications</guilabel> tab.</para></listitem>
1614 </itemizedlist>
1616 <para>
1617 <screenshot>
1618 <screeninfo>Select Talker</screeninfo>
1619 <mediaobjectco>
1620 <imageobjectco>
1621 <areaspec units="calspair">
1622 <area id="pt-selecttalker-1" coords="1 1"/>
1623 <area id="pt-selecttalker-2" coords="1 1"/>
1624 <area id="pt-selecttalker-3" coords="1 1"/>
1625 <area id="pt-selecttalker-4" coords="1 1"/>
1626 <area id="pt-selecttalker-5" coords="1 1"/>
1627 </areaspec>
1628 <imageobject>
1629 <imagedata fileref="selecttalker.png" format="PNG"/>
1630 </imageobject>
1631 </imageobjectco>
1632 <textobject>
1633 <phrase>Select Talker</phrase>
1634 </textobject>
1635 </mediaobjectco>
1636 </screenshot>
1637 </para>
1639 <para>The screen offers three methods to specify desired talker
1640 attributes:</para>
1642 <itemizedlist>
1643 <listitem><para>Use the default talker (topmost in the
1644 <guilabel>Talkers</guilabel> tab). In other words, no talker attributes
1645 are specified.</para></listitem>
1646 <listitem><para>Use the closest matching talker having one or more specified attributes.</para></listitem>
1647 <listitem><para>Use the closest matching talker having all the attributes
1648 of a configured talker. If you don't delete or modify the talker's settings,
1649 &ktts; will pick that specific talker. If you delete or modify the
1650 talker's settings, then &ktts; will pick the closest matching talker
1651 having the talker's original attributes.</para></listitem>
1652 </itemizedlist>
1654 <para>
1655 <calloutlist>
1656 <callout arearefs="pt-selecttalker-1"><para>Choose the method for entering
1657 the desired talker attributes by clicking one of these radio buttons.</para></callout>
1658 <callout arearefs="pt-selecttalker-2"><para>Choose the attributes of the desired
1659 talker here. Leave an attribute blank if you do not care about that attribute.</para></callout>
1660 <callout arearefs="pt-selecttalker-3"><para>Check this box if you wish the
1661 attribute to be "preferred" over other attributes. You may check more than one
1662 box.</para></callout>
1663 <callout arearefs="pt-selecttalker-4"><para>Since language is a critical factor
1664 in making speech understandable, it is always a preferred attribute. It is rare
1665 that you will use this attribute. The only time you might specify the language
1666 attribute is when you know a specific application sends text in a language
1667 different from your desktop.</para></callout>
1668 <callout arearefs="pt-selecttalker-5"><para>This is a list of the talkers
1669 you currently have configured in &ktts;. By choosing one of these,
1670 in effect, you are specifying all the attributes of that talker. If that
1671 talker is still configured when text is sent, you'll get an exact match and that
1672 talker will be chosen. However, if you later delete the talker, or modify
1673 its settings, it might not be the chosen talker anymore. The talker
1674 most closely matching the original attributes will be chosen.</para></callout>
1675 </calloutlist>
1676 </para>
1678 <para>The <guilabel>Language</guilabel> attribute is special because
1679 text will probably be unintelligible if spoken by a talker that
1680 speaks a language different from the text. Therefore, language
1681 is automatically a "preferred" attribute. If you specify a language,
1682 it will override the chosen language, but if you leave it blank,
1683 the existing language setting will be used. If the application that sent the
1684 text to &ktts; did not specify a language, &ktts; assigns
1685 the language of the topmost talker you have configured in the
1686 <guilabel>Talkers</guilabel> tab. In other words, the topmost
1687 talker is assumed to speak the language of your desktop.</para>
1689 <tip><para>To clear all the attributes in the
1690 <guilabel>Use closest matching Talker having</guilabel> section,
1691 first click the <guilabel>Use default Talker</guilabel> radio button,
1692 then click the <guilabel>Use closest matching Talker having</guilabel>
1693 radio button.</para></tip>
1695 </sect1>
1697 </chapter>
1699 <!-- ====================================================================== -->
1701 <chapter id="commands">
1702 <title>Command Reference</title>
1704 <!-- (OPTIONAL, BUT RECOMMENDED) This chapter should list all of the
1705 application windows and their menubar and toolbar commands for easy reference.
1706 Also include any keys that have a special function but have no equivalent in the
1707 menus or toolbars. This may not be necessary for small apps or apps with no tool
1708 or menu bars. -->
1710 <para>TODO</para>
1712 </chapter>
1714 <!--
1716 <sect1 id="kapp-mainwindow">
1717 <title>The main &ktts; window</title>
1719 <sect2>
1720 <title>The File Menu</title>
1721 <para>
1722 <variablelist>
1723 <varlistentry>
1724 <term><menuchoice>
1725 <shortcut>
1726 <keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
1727 </shortcut>
1728 <guimenu>File</guimenu>
1729 <guimenuitem>New</guimenuitem>
1730 </menuchoice></term>
1731 <listitem><para><action>Creates a new document</action></para></listitem>
1732 </varlistentry>
1733 <varlistentry>
1734 <term><menuchoice>
1735 <shortcut>
1736 <keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
1737 </shortcut>
1738 <guimenu>File</guimenu>
1739 <guimenuitem>Save</guimenuitem>
1740 </menuchoice></term>
1741 <listitem><para><action>Saves the document</action></para></listitem>
1742 </varlistentry>
1743 <varlistentry>
1744 <term><menuchoice>
1745 <shortcut>
1746 <keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
1747 </shortcut>
1748 <guimenu>File</guimenu>
1749 <guimenuitem>Quit</guimenuitem>
1750 </menuchoice></term>
1751 <listitem><para><action>Quits</action> &ktts;</para></listitem>
1752 </varlistentry>
1753 </variablelist>
1754 </para>
1756 </sect2>
1760 <!-- ====================================================================== -->
1762 <chapter id="developers">
1763 <title>Developer's Guide to &ktts;</title>
1765 <para>&ktts; has two Application Programmer Interfaces (APIs):
1766 </para>
1768 <itemizedlist>
1769 <listitem><para>The &kde; Text-to-Speech API, which is used by application
1770 programmers to give their applications TTS capabilities. Applications
1771 communicate with KTTSD via &DCOP;.</para></listitem>
1772 <listitem><para>The KTTSD Plugin API, which is used to add speech
1773 synthesis plugins to KTTSD so that &ktts; will work with
1774 a new speech synthesis engine.</para></listitem>
1775 </itemizedlist>
1777 <para>The following section gives a short description of the &kde; Text-to-Speech API
1778 &DCOP; Interface.
1779 Full documentation for both APIs is available online at the
1780 <ulink url="http://accessibility.kde.org/developer/kttsd/">
1781 &kde; Accessibility</ulink> web site (http://accessibility.kde.org).
1782 </para>
1785 <!-- ...................................................................... -->
1788 <sect1 id="dcop-interface">
1789 <title>The &ktts; &DCOP; Interface</title>
1791 <para>Applications communicate requests for Text-to-Speech services via the
1792 &kde; &DCOP; interface to program <command>kttsd</command> object <command>KSpeech</command>.
1793 </para>
1795 <para>Enter the following commands in a &konsole;.</para>
1797 <para>If KTTSD is not already running</para>
1799 <para><userinput>kttsd</userinput></para>
1801 <para>To queue a text job to be spoken</para>
1803 <para><userinput>dcop kttsd KSpeech setText "<replaceable>text</replaceable>" "<replaceable>talker</replaceable>"</userinput></para>
1805 <para>where <userinput><replaceable>text</replaceable></userinput> is the text to be spoken, and <userinput><replaceable>talker</replaceable></userinput> is a language code
1806 such as <userinput><replaceable>en</replaceable></userinput>, <userinput><replaceable>cy</replaceable></userinput>, &etc; This command does
1807 not speak the text; instead it queues a text job for speaking.</para>
1809 <para>Example.</para>
1811 <para><userinput>dcop kttsd KSpeech setText "This is a test." "en"</userinput></para>
1813 <para>To speak the last queued text job</para>
1815 <para><userinput>dcop kttsd KSpeech startText <replaceable>0</replaceable></userinput></para>
1817 <para>In this case, <userinput>0</userinput> refers to the last text job queued.
1818 You may also specify a specific job number. (If no job number is given, a <userinput>0</userinput> is required.)</para>
1820 <para>To stop the currently speaking text job</para>
1822 <para><userinput>dcop kttsd KSpeech stopText 0</userinput></para>
1824 <para>Depending upon the speech plugin used, speaking may not immediately stop.</para>
1826 <para>There are many more commands that can be sent. To see a list of possible
1827 commands,</para>
1829 <para><userinput>dcop kttsd KSpeech</userinput></para>
1831 <para>or read the
1832 <ulink url="http://accessibility.kde.org/developer/kttsd/">
1833 &kde; Text-to-Speech API</ulink> online.</para>
1835 </sect1>
1837 </chapter>
1839 <!-- ====================================================================== -->
1841 <chapter id="faq">
1842 <title>Questions and Answers</title>
1844 <!-- (OPTIONAL but recommended) This chapter should include all of the silly
1845 (and not-so-silly) newbie questions that fill up your mailbox. This chapter
1846 should be reserved for BRIEF questions and answers! If one question uses more
1847 than a page or so then it should probably be part of the
1848 "Using this Application" chapter instead. You should use links to
1849 cross-reference questions to the parts of your documentation that answer them.
1850 This is also a great place to provide pointers to other FAQ's if your users
1851 must do some complicated configuration on other programs in order for your
1852 application work. -->
1854 &reporting.bugs;
1855 &updating.documentation;
1857 <qandaset id="faqlist">
1858 <qandaentry>
1859 <question>
1860 <para><command>kttsmgr</command> immediately crashes when I start it. I
1861 compiled with debug support and I don't even get a backtrace.</para>
1862 </question>
1863 <answer>
1864 <para>GStreamer has crashed taking &ktts; down with it. You most
1865 likely need to "register" GStreamer. For GStreamer 0.8x, the command is
1866 <command>gst-register-0.8</command>. If this doesn't solve the problem,
1867 you may have an incompatible version of GStreamer installed. You could
1868 try upgrading or uninstalling GStreamer.</para>
1869 </answer>
1870 </qandaentry>
1871 <qandaentry>
1872 <question>
1873 <para>ALSA audio output is not working if I am playing music in another
1874 application at the same time. When I pause a text job, &ktts;
1875 freezes. I notice "unable to open PCM" in the &konsole; output.</para>
1876 </question>
1877 <answer>
1878 <para>You have the ALSA device contention problem, which prevents opening
1879 more than one PCM device at one time. See the ALSA website (dmix) for
1880 possible solutions. <ulink url="www.alsa-project.org">www.alsa-project.org</ulink>
1881 </para>
1882 </answer>
1883 </qandaentry>
1884 <qandaentry>
1885 <question>
1886 <para>I need to start over. How do I get &ktts; completely terminated?</para>
1887 </question>
1888 <answer>
1889 <para>Enter the following commands in a &konsole;:
1890 <programlisting>
1891 killall kttsd
1892 killall kttsmgr
1893 </programlisting>
1894 </para>
1895 </answer>
1896 </qandaentry>
1897 <qandaentry>
1898 <question>
1899 <para>How can I see debugging output from <command>kttsd</command>?</para>
1900 </question>
1901 <answer>
1902 <para>Open two &konsole; windows. First start <command>kttsd</command> in one
1903 window, then start <command>kttsmgr</command> in the second.</para>
1904 </answer>
1905 </qandaentry>
1906 <qandaentry>
1907 <question>
1908 <para>I have an additional Festival voice I downloaded from the Internet.
1909 I installed it, and I can use it in Festival, but it does not show up in <command>kttsmgr</command>.</para>
1910 </question>
1911 <answer>
1912 <para>Edit file <command>$KDEHOME/share/apps/kttsd/festivalint/voices</command> to
1913 add the new voice. The other entries can be used as a guide. If you
1914 successfully add a voice, please send a patch to the developers along
1915 with the &URL; from which you obtained the voice file.</para>
1916 </answer>
1917 </qandaentry>
1918 <qandaentry>
1919 <question>
1920 <para>None of the supported speech synthesizers support the language I need.
1921 Where can I get a synth for my language?</para>
1922 </question>
1923 <answer>
1924 <para>Google(tm) is your friend. This
1925 <ulink url="http://tcts.fpms.ac.be/synthesis/mbrola/mbrtts.html">link</ulink>
1926 might also help. If you find a free synthesis engine that supports your
1927 desired language, and want to add support for it to &ktts;, please
1928 contact the development team. Open source engines are especially welcome.
1929 If you know of a commercial synth, perhaps you can persuade the vendor
1930 to donate a free copy to the &ktts; development team.
1931 In the meantime, you may be able to get
1932 the synth working using the <guilabel>Command</guilabel> plugin.
1933 See <xref linkend="using-with-command" />.</para>
1934 </answer>
1935 </qandaentry>
1936 <qandaentry>
1937 <question>
1938 <para>&ktts; is speaking too slow. How can I speed it up?</para>
1939 </question>
1940 <answer>
1941 <para>There is a <guilabel>Speed</guilabel> setting on the <guilabel>Audio</guilabel>
1942 tab. For this to work, you must have the <command>sox</command> utility
1943 installed and available in the PATH. Some synthesis plugins, such as
1944 Festival Interactive also provide a <guilabel>Speed</guilabel>
1945 setting in the talker configuration dialog. Depending upon the
1946 voice used, it may or may not be enabled.</para>
1947 </answer>
1948 </qandaentry>
1949 <qandaentry>
1950 <question>
1951 <para>OK, that works for some things, but web pages are still spoken too slow.</para>
1952 </question>
1953 <answer>
1954 <para>The speed settings are ignored when &ktts; is speaking
1955 &HTML;. (This is because the &HTML; is converted into SSML, which has its own
1956 "rate" tags.) Either disable the &HTML; &XML; Transformer filter
1957 (see <xref linkend="filters"/>), or if you are brave, edit the .xsl file
1958 in the &HTML; to SSML Transformer filter and increase the default talking rate.</para>
1959 </answer>
1960 </qandaentry>
1961 <qandaentry>
1962 <question>
1963 <para>I cannot get web pages to speak in a female voice. I have female Festival talker
1964 configured, but &ktts; always speaks web pages in a male voice.</para>
1965 </question>
1966 <answer>
1967 <para>As of Festival 1.95 beta, the SABLE GENDER tag doesn't seem to be working.
1968 To keep Festival from producing errors, the SSML to SABLE .xsl file strips the
1969 gender tags out. The same applies to voice tags as well.</para>
1970 </answer>
1971 </qandaentry>
1972 <qandaentry>
1973 <question>
1974 <para>I have the &HTML; &XML; Transformer filter configured, but web pages are not spoken at
1975 all using the Festival plugin.</para>
1976 </question>
1977 <answer>
1978 <para>Due to a bug in Festival 1.95 beta, you must install the
1979 <command>rab_diphone</command> (British male) voice for SABLE to work at all, even
1980 if you are not using that voice to speak the web pages. Also,
1981 make sure the <command>xsltproc</command> utility is installed and in the PATH.</para>
1982 </answer>
1983 </qandaentry>
1984 <qandaentry>
1985 <question>
1986 <para>Certain characters or punctuation seem to be producing errors in the synthesizer,
1987 making it skip entire sentences, or pronounce gibberish. What can I do?</para>
1988 </question>
1989 <answer>
1990 <para>First, make sure the <guilabel>Character encoding</guilabel> option in the
1991 talker's configuration dialog is properly set for the language. If certain words
1992 or characters are causing problems, a String Replacer filter might help.
1993 If certain sentence punctuation characters are confusing the synth, you'll need to
1994 configure a Sentence Boundary Detector filter. See <xref linkend="filters" />.</para>
1995 </answer>
1996 </qandaentry>
1997 <qandaentry>
1998 <question>
1999 <para>I added a String Replacer filter of my own and now &ktts;
2000 will not allow me to rewind or advance by sentence. On the <guilabel>Jobs</guilabel>
2001 tab, it claims each job has only one sentence. What did I do wrong?</para>
2002 </question>
2003 <answer>
2004 <para>You must not filter out sentence punctuation characters (period, question mark,
2005 exclamation mark, colon, and semicolon).
2006 For these characters, use a Sentence Boundary Detector filter instead.</para>
2007 </answer>
2008 </qandaentry>
2009 </qandaset>
2010 </chapter>
2012 <!-- ====================================================================== -->
2014 <chapter id="credits">
2016 <!-- Include credits for the programmers, documentation writers, and
2017 contributors here. The license for your software should then be included below
2018 the credits with a reference to the appropriate license file included in the KDE
2019 distribution. -->
2021 <title>Credits and License</title>
2023 <para>
2024 &ktts;
2025 </para>
2026 <para>
2027 Program Copyright &copy; 2002 Jos&#233; Pablo Ezequiel "Pupeno" Fern&#225;ndez <email>pupeno@kde.org</email>
2028 </para>
2029 <para>
2030 Current Maintainer: Gary Cramblitt <email>garycramblitt@comcast.net</email>
2031 </para>
2032 <para>
2033 Contributors:
2034 <itemizedlist>
2035 <listitem><para>Olaf Schmidt <email>ojschmidt@kde.org</email></para>
2036 </listitem>
2037 <listitem><para>Gunnar Schmi Dt <email>gunnar@schmi-dt.de</email></para>
2038 </listitem>
2039 <listitem><para>Paul Giannaros <email>ceruleanblaze@gmail.com</email></para>
2040 </listitem>
2041 </itemizedlist>
2042 </para>
2044 <para>
2045 Documentation Copyright &copy; 2004 Gary R. Cramblitt <email>garycramblitt@comcast.net</email>
2046 </para>
2048 <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
2050 &underFDL; <!-- FDL: do not remove -->
2052 <!-- Determine which license your application is licensed under,
2053 and delete all the remaining licenses below:
2055 (NOTE: All documentation are licensed under the FDL,
2056 regardless of what license the application uses) -->
2058 &underGPL; <!-- GPL License -->
2060 <note><para>Speech synthesis engines used by &ktts; have their own
2061 licenses. See each engine's documentation or website for details.
2062 Some voices also have their own licensing.</para></note>
2064 </chapter>
2066 <!-- ====================================================================== -->
2068 <appendix id="installation">
2069 <title>Installation</title>
2071 <!-- ...................................................................... -->
2074 <sect1 id="getting-kapp">
2075 <title>How to obtain &ktts;</title>
2077 <!-- This first entity contains boiler plate for applications that are
2078 part of KDE CVS. You should remove it if you are releasing your
2079 application -->
2081 <para>
2082 &install.intro.documentation;
2083 </para>
2085 <para>(FUTURE) Debian Install Command: <command>apt-get install kdeaccessibility</command></para>
2087 <note>
2088 <para>You will find links to source and binary packages
2089 on the <ulink url="http://accessibility.kde.org/developer/kttsd/">
2090 &kde; Accessibility</ulink> web site (http://accessibility.kde.org).</para>
2092 <para>If you have access to the &kde; code repository, you can download &ktts;
2093 by checking out the <command>kdeaccessibility</command> module. &ktts;
2094 will be found in the <command>kttsd</command> folder. You can also
2095 download tarballs of the kdeaccessibility source code from
2096 <ulink url="ftp://ftp.kde.org/pub/kde/">
2097 ftp://ftp.kde.org/pub/kde/</ulink></para>
2098 </note>
2100 </sect1>
2102 <!-- ...................................................................... -->
2105 <sect1 id="requirements">
2106 <title>Requirements</title>
2108 <para>Mandatory requirements:</para>
2110 <para>
2111 <itemizedlist>
2112 <listitem><para>&kde; version 3.2 or later.</para></listitem>
2113 <listitem><para>A speech synthesis engine. The following engines
2114 and spoken languages are currently supported.</para>
2116 <para>
2117 <informaltable id="synth-engines">
2118 <tgroup cols="2">
2119 <tbody>
2121 <row>
2122 <entry>Festival</entry>
2123 <entry>American English, British, Spanish, German, Finnish, Czech, Polish, Russian,
2124 Italian, French Canadian, Kiswahili, Zulu, and Ibibio</entry>
2125 </row>
2127 <row>
2128 <entry>Festival Lite (flite)</entry>
2129 <entry>English</entry>
2130 </row>
2132 <row>
2133 <entry>Hadifix (&mbrola; and txt2pho)</entry>
2134 <entry>German, Hungarian</entry>
2135 </row>
2137 <row>
2138 <entry>Epos</entry>
2139 <entry>Czech, Slovak</entry>
2140 </row>
2142 <row>
2143 <entry>FreeTTS</entry>
2144 <entry>English</entry>
2145 </row>
2147 </tbody>
2148 </tgroup>
2149 </informaltable>
2150 </para>
2152 <para>It also works with any synthesis engine that can be run from a command in
2153 a &konsole;.</para>
2155 <note><para>
2156 The languages listed above may not be comprehensive or up-to-date.
2157 Check the specifications for each engine for a complete list of supported
2158 languages. Also check the
2159 <ulink url="http://accessibility.kde.org/developer/kttsd/index.php">
2160 &ktts;</ulink> website for additional
2161 information that might not have made it into this handbook.
2162 </para></note>
2164 <note>
2165 <para>&ktts; uses a flexible plugin architecture for
2166 speech synthesis engines. If you
2167 want to enhance &ktts; to support another engine, contact the
2168 development team.
2169 </para>
2170 </note>
2172 <para>
2173 See <xref linkend="configuration" /> for specific instructions for each
2174 of these engines.
2175 </para>
2177 </listitem>
2179 <listitem>
2180 <para>At least one of the following audio subsystems:
2182 <itemizedlist>
2183 <listitem><para>&kde; &arts; Soundsystem. &arts; is usually installed with &kde;.</para></listitem>
2184 <listitem><para>ALSA (Advanced &Linux; Sound Architecture). ALSA is installed with
2185 most &Linux; systems. (<ulink url="www.alsa-project.org">www.alsa-project.org</ulink>)</para></listitem>
2186 <listitem><para>GStreamer version 0.8.7 or greater. <emphasis>Note</emphasis>:
2187 Be sure to register your GStreamer plugins by running the <command>gst-register</command>
2188 command prior to using GStreamer in &ktts;.
2189 (<ulink url="http://gstreamer.freedesktop.org">
2190 http://gstreamer.freedesktop.org</ulink>)</para></listitem>
2191 <listitem><para>aKode library. aKode is a decoder library that is part of &kde;.
2192 </para></listitem>
2193 </itemizedlist>
2195 <note><para>The &kde; project plans to drop &arts; starting in version 4.</para></note>
2197 <note><para>Some users experience device contention with ALSA. If your system
2198 has this problem, you will not be able to simultaneously play music while speaking.
2199 &ktts; will also freeze if you pause a text job and then
2200 start another. See the ALSA website (dmix) for possible solutions.</para></note>
2202 <note><para>As of July 2005, aKode does not support a true pause capability.
2203 When you pause a text job in &ktts; it will finish speaking the
2204 current sentence.</para></note>
2206 </para>
2207 </listitem>
2209 </itemizedlist>
2210 </para>
2212 <para>Optional components:</para>
2214 <para>
2215 <itemizedlist>
2217 <listitem>
2218 <para>The <command>sox</command> audio utility is needed for
2219 adjusting overall speech speed, but not required. Debian users can install
2220 sox with the command <command>apt-get install sox</command>.
2221 Sox is included on most &Linux; distribution CDs.</para>
2222 </listitem>
2224 <listitem>
2225 <para>The <command>xsltproc</command> utility is needed for
2226 SSML support and for the &XML; Transformer filter, but not required. Debian users can install
2227 xsltproc with the command <command>apt-get install xsltproc</command>.</para>
2228 </listitem>
2230 </itemizedlist>
2231 </para>
2233 </sect1>
2235 <!-- ...................................................................... -->
2238 <sect1 id="compilation">
2239 <title>Compilation and Installation</title>
2241 <!-- This entity contains the boilerplate text for standard -->
2242 <!-- compilation instructions. If your application requires any -->
2243 <!-- special handling, remove it, and replace with your own text. -->
2245 <!-- &install.compile.documentation; -->
2247 <para>In order to compile &ktts;, you must have a
2248 recent (&kde; 3.4 or greater) copy of the &kde; development files,
2249 including kdelibs and arts.</para>
2251 <para>If you downloaded &ktts; as a tarball, log in
2252 as a normal user and untar the tarball to a suitable folder,
2253 change to that folder, and enter the following commands.</para>
2255 <programlisting>
2256 ./configure
2257 make
2258 </programlisting>
2260 <para>The following <command>configure</command> options are available:</para>
2262 <para>
2263 <informaltable id="configure-audio-options">
2264 <tgroup cols="3">
2265 <tbody>
2267 <row>
2268 <entry><emphasis>Default Option</emphasis></entry>
2269 <entry><emphasis>Description</emphasis></entry>
2270 <entry><emphasis>Alternate</emphasis></entry>
2271 </row>
2272 <row>
2273 <entry>--with-arts</entry>
2274 <entry>Builds the arts audio plugin.</entry>
2275 <entry>--without-arts</entry>
2276 </row>
2277 <row>
2278 <entry>--with-alsa=check</entry>
2279 <entry>Builds the ALSA audio plugin.</entry>
2280 <entry>--with-alsa=no</entry>
2281 </row>
2282 <row>
2283 <entry>--with-gstreamer=no</entry>
2284 <entry>Does not build the GStreamer audio plugin.</entry>
2285 <entry>--with-gstreamer=check</entry>
2286 </row>
2287 <row>
2288 <entry>--with-akode=no</entry>
2289 <entry>Does not build the aKode audio plugin.</entry>
2290 <entry>--with-akode=check</entry>
2291 </row>
2292 </tbody>
2293 </tgroup>
2294 </informaltable>
2295 </para>
2297 <note><para>
2298 In &kde; 4, the &arts; plugin will likely be removed or at least not built by default.
2299 </para></note>
2301 <para>The following speech synthesizer plugins are all built by default.
2302 Some of them are runtime only dependent upon non-free software.
2303 (Non-free according to Debian Policy). The "Configure Option to
2304 not build" column shows the configure command to not build the plugin:</para>
2306 <para>
2307 <informaltable id="configure-synth-options">
2308 <tgroup cols="3">
2309 <tbody>
2311 <row>
2312 <entry><emphasis>Synth</emphasis></entry>
2313 <entry><emphasis>License</emphasis></entry>
2314 <entry><emphasis>Configure Option to not build</emphasis></entry>
2315 </row>
2316 <row><entry>Festival</entry><entry>free</entry><entry>--disable-kttsd-festivalint</entry></row>
2317 <row><entry>Festival Lite</entry><entry>free</entry><entry>--disable-kttsd-flite</entry></row>
2318 <row><entry>Epos</entry><entry>free</entry><entry>--disable-kttsd-epos</entry></row>
2319 <row><entry>Command</entry><entry>free</entry><entry>--disable-kttsd-command</entry></row>
2320 <row><entry>Hadifix</entry><entry>non-free</entry><entry>--disable-kttsd-hadifix</entry></row>
2321 <row><entry>FreeTTS</entry><entry>non-free</entry><entry>--disable-kttsd-freetts</entry></row>
2322 </tbody></tgroup></informaltable></para>
2324 <para>By default, the commands above will install &ktts; to
2325 <filename>/opt/kde3</filename>. If this folder is not in your
2326 $<envar>KDEDIRS</envar> path, you may need to add a
2327 <userinput>--prefix=<replaceable>target</replaceable></userinput> option.
2328 For example,</para>
2330 <programlisting>
2331 ./configure --prefix=/usr/local
2332 make
2333 </programlisting>
2335 <note><para>On Debian systems, <filename><replaceable>/usr/local</replaceable></filename>
2336 is the usual place to install applications compiled from source code.
2337 </para></note>
2339 <para>Login as root and install the compiled &ktts;
2340 using the following commands.</para>
2342 <programlisting>
2344 make install
2345 </programlisting>
2347 <para>If you downloaded the &ktts; source from the
2348 <filename>kdeaccessibility</filename> code repository module, or downloaded the nightly
2349 tarball, use the following commands to compile and install.
2350 </para>
2352 <programlisting>
2353 cd kdeaccessibility
2354 echo kttsd>inst-apps
2355 make -f Makefile.cvs
2356 ./configure
2357 cd kttsd
2358 make
2360 make install
2361 </programlisting>
2363 </sect1>
2365 <!-- ...................................................................... -->
2368 <sect1 id="configuration">
2369 <title>Configuration</title>
2371 <para>Make sure your speech synthesis engine is working before using
2372 &ktts;. Follow the instructions that came with the engine.</para>
2374 <tip>
2375 <para>In some cases, you may need to grant write access to the audio device.</para>
2376 <para><userinput>chmod a+rw <replaceable>/dev/dsp*</replaceable></userinput></para>
2377 </tip>
2379 <!-- ...................................................................... -->
2382 <sect2 id="using-with-festival">
2383 <title>Using with Festival (Interactive)</title>
2385 <para>Festival is one of the best free and open source TTS
2386 engines available. Voice quality is generally good and there are quite
2387 a few languages and voices supported.
2388 For many voices, you can control the volume,
2389 speed of the generated speech, and pitch (tone) from &ktts;.</para>
2391 <para>Synthesizer Name: <guilabel>Festival Interactive</guilabel></para>
2393 <para>&URL;: <ulink url="http://www.cstr.ed.ac.uk/projects/festival/">
2394 http://www.cstr.ed.ac.uk/projects/festival/</ulink>
2395 </para>
2397 <para>Debian Install Command: <userinput>apt-get install festival</userinput></para>
2399 <para>
2400 You will need to install at least one language. Follow the instructions
2401 that come with Festival. If you will be speaking web pages,
2402 you must install the <command>rab_diphone</command> (British Male)
2403 voice.
2404 </para>
2406 <para>Additional English festival voices are available from</para>
2408 <para><ulink url="http://hts.ics.nitech.ac.jp/">http://hts.ics.nitech.ac.jp/</ulink>.
2409 </para>
2411 <para>Additional Spanish, English, and German voices are available from</para>
2413 <para><ulink url="http://cslu.cse.ogi.edu/tts/download/">
2414 http://cslu.cse.ogi.edu/tts/download/</ulink></para>
2416 <para>You must compile an additional module
2417 for these voices, therefore, you must have the Festival source code.
2418 The German voices have limited distribution.
2419 </para>
2421 <para>A Finnish male voice is available from </para>
2423 <para><ulink url="http://www.ling.helsinki.fi/suopuhe/download/">
2424 http://www.ling.helsinki.fi/suopuhe/download/</ulink>.
2425 </para>
2427 <para>A Polish male voice is available from </para>
2429 <para><ulink url="http://www.artegence.com/download/voicexml/speech/festival_polish_voice.tgz">
2430 http://www.artegence.com/download/voicexml/speech/festival_polish_voice.tgz</ulink>.
2431 </para>
2433 <para>A Russian male voice is available from </para>
2435 <para><ulink url="http://nshmyrev.narod.ru/festival/festival.html">
2436 http://nshmyrev.narod.ru/festival/festival.html
2437 </ulink></para>
2439 <para>You must have Festival 1.95 beta or later to use this voice. The voice
2440 is still in early development. Untar to
2441 <filename>festival/lib/voices/russian/</filename>. When you configure the Russian
2442 talker, the voice code is <userinput>msu_ru_nsh_diphone</userinput>. Be sure to
2443 select an 8-bit cryllic encoding, such as <userinput>KOI8-R</userinput>.</para>
2445 <para>Italian voices for Festival 1.95 beta are available at</para>
2447 <para><ulink url="http://www.csrf.pd.cnr.it/TTS/It-FESTIVAL-download.htm">
2448 http://www.csrf.pd.cnr.it/TTS/It-FESTIVAL-download.htm</ulink>.</para>
2450 <para>If you get CRC errors when you unzip, try downloading again.</para>
2452 <para>Kiswahili, Zulu, and Ibibio voices for Festival 1.95 beta are available at</para>
2454 <para><ulink url="http://www.llsti.org/">http://www.llsti.org/</ulink>.</para>
2456 <para>Unfortunately, the Hindi voice also available there will not work with
2457 &ktts;.</para>
2459 <para>Commercial voices, including a French Canadian voice,
2460 can be purchased from Cepstral, LLC at</para>
2462 <para><ulink url="http://www.cepstral.com/">http://www.cepstral.com/</ulink></para>
2464 <para>The FAQ on their Support page has information about using their voices
2465 in Festival.</para>
2467 <para>Festival is typically included with &Linux; distributions. Check your
2468 distro CDs to see if it is included.</para>
2470 <note>
2471 <para>When using the Polish, Hungarian, or Czech languages, be sure the <guilabel>Encoding</guilabel>
2472 option is set to <userinput>ISO 8859-2</userinput>.
2473 </para>
2474 <para>When using the Russian voice, be sure the <guilabel>Encoding</guilabel>
2475 option is set to an 8-bit cryllic encoding, such as <userinput>KOI8-R</userinput>.
2476 </para>
2477 </note>
2479 <!-- ...................................................................... -->
2482 <sect3 id="festival-with-mbrola">
2483 <title>Using Festival with &mbrola;</title>
2485 <para>Festival can be used in combination with the &mbrola; synthesizer.
2486 In this mode, Festival does the lexical analysis and &mbrola; produces the
2487 audio. The &mbrola; binary and &mbrola; voice files can be downloaded from</para>
2489 <para><ulink url="http://festvox.org/mbrola/">http://festvox.org/mbrola/</ulink>.</para>
2491 <para>Follow the instructions in the <filename>readme.txt</filename> that comes with
2492 the download.</para>
2494 <para>Note that &mbrola; is not a complete Text-to-Speech system. &mbrola; synthesizes
2495 speech from diphone files. You must have additional software that can produce
2496 the diphones. When combined with Festival, Festival produces the diphones needed
2497 by &mbrola;. <command>txt2pho</command> can also be used to produce diphones
2498 from German text. See <xref linkend="using-with-hadifix"/> for more information.</para>
2500 <para>There are three methods of combining Festival with &mbrola;.</para>
2502 <para>
2503 <itemizedlist>
2504 <listitem><para><link linkend="mbrola-wrappers">&mbrola; Wrappers</link>.
2505 At the time of writing this Handbook,
2506 this method is limited to English voices.</para></listitem>
2507 <listitem><para><link linkend="ims-german-festival">IMS German Festival</link>.</para></listitem>
2508 <listitem><para><link linkend="festival-czech">Festival-Czech</link>.</para></listitem>
2509 </itemizedlist>
2510 </para>
2512 <!-- ...................................................................... -->
2514 <sect4 id="mbrola-wrappers">
2515 <title>Using Festival with &mbrola; Wrappers</title>
2517 <para>In this method, additional
2518 wrapper code is added to Festival to enable speech synthesis using
2519 &mbrola; voice files. Note that the &mbrola; voice files are <emphasis>not</emphasis>
2520 installed in the &mbrola; folder tree. Instead, they are installed
2521 in the <filename>festival/lib/</filename> folder tree. For instructions, see</para>
2523 <para><ulink url="http://www.cstr.ed.ac.uk/projects/festival/mbrola.html">
2524 http://www.cstr.ed.ac.uk/projects/festival/mbrola.html</ulink></para>
2526 </sect4>
2528 <!-- ...................................................................... -->
2530 <sect4 id="ims-german-festival">
2531 <title>Using IMS German Festival</title>
2533 <para>IMS German Festival is a modified version of Festival that uses German &mbrola;
2534 voices. It works with either Festival version 1.4.1 or Festival 2.0 (1.95beta).
2535 First install Festival and &mbrola;, if you have not already done so.
2536 Next, download IMS German Festival, from</para>
2538 <para>
2539 <ulink url="http://www.ims.uni-stuttgart.de/phonetik/synthesis/festival_opensource.html">
2540 http://www.ims.uni-stuttgart.de/phonetik/synthesis/festival_opensource.html</ulink>.</para>
2542 <para>Follow the instructions in the <filename>README</filename> that comes with the
2543 download. (Note, if using in combination with Festival 2.0, it is <emphasis>not</emphasis>
2544 necessary to apply the <filename>fixes</filename> tarball, but you must still
2545 rebuild festival.) Finally, add the following
2546 lines to the <filename>festival/lib/siteinit.scm</filename> file.</para>
2548 <para>
2549 <programlisting>
2550 (voice-location "german_de1_os" "/usr/local/mbrola/de1"
2551 "German Female, IMS Festival de1")
2552 (voice-location "german_de2_os" "/usr/local/mbrola/de2"
2553 "German Male, IMS Festival de2")
2554 (voice-location "german_de3_os" "/usr/local/mbrola/de3"
2555 "German Female, IMS Festival de3")
2556 </programlisting>
2557 </para>
2559 <para>just above the line that reads</para>
2561 <para>
2562 <programlisting>
2563 (provide 'siteinit)
2564 </programlisting>
2565 </para>
2567 <para>On some systems, the file you edit is <filename>/etc/festival.scm</filename>.
2568 Only add the lines that correspond to the German voices you have installed.
2569 Substitute the correct path for
2570 <userinput><replaceable>/usr/local/mbrola/</replaceable></userinput>.
2571 Also note that (at the time of this writing)
2572 IMS German Festival does not work with the de4, de5, or de6 German voices.</para>
2574 </sect4>
2576 <!-- ...................................................................... -->
2578 <sect4 id="festival-czech">
2579 <title>Using Festival-Czech</title>
2581 <para>This method uses some special code to enable speech synthesis
2582 using Festival with an &mbrola; Czech voice. To install, first download and
2583 install Festival and &mbrola;, and make sure both are working. Next, download
2584 Festival-Czech from</para>
2586 <para><ulink url="http://www.freebsoft.org/festival-czech">
2587 http://www.freebsoft.org/festival-czech</ulink></para>
2589 <note><para>In the following procedures substitute the correct folder
2590 paths as needed.</para></note>
2592 <para>Untar the download to a suitable folder and make
2593 the lexicon. The Festival executable must be in your <envar>PATH</envar>.
2594 </para>
2596 <para>
2597 <programlisting>
2598 cd /usr/local
2599 tar xvfz festival-czech.tar.gz
2600 cd festival-czech
2601 make
2602 </programlisting>
2603 </para>
2605 <para>Download the <filename>cz2</filename> voice file from the &mbrola;
2606 website, and unzip it in the &mbrola; folder.</para>
2608 <para>
2609 <programlisting>
2610 cd /usr/local/mbrola
2611 mkdir cz2
2612 cd cz2
2613 unzip cz2-001009.zip
2614 </programlisting>
2615 </para>
2617 <para>Add the following lines to the <filename>festival/lib/siteinit.scm</filename> file.</para>
2619 <para>
2620 <programlisting>
2621 (set! czech-lexicon-file "/usr/local/festival-czech/czech-lexicon.out")
2622 (set! load-path (cons "/usr/local/festival-czech" load-path))
2623 (require 'czech)
2624 (set! czech-mbrola_database "/usr/local/mbrola/cz2/cz2")
2625 (set! mbrola_progname "/usr/local/mbrola/mbrola")
2626 (voice-location "czech_mbrola_cz2" "/usr/local/mbrola/cz2"
2627 "Czech Male, MBROLA")
2628 (require 'czech-mbrola)
2629 </programlisting>
2630 </para>
2632 <para>just above the line that reads</para>
2634 <para>
2635 <programlisting>
2636 (provide 'siteinit)
2637 </programlisting>
2638 </para>
2640 <para>On some systems, the file you edit is <filename>/etc/festival.scm</filename>.</para>
2642 </sect4>
2644 </sect3>
2646 </sect2>
2648 <!-- ...................................................................... -->
2650 <sect2 id="using-with-flite">
2651 <title>Using with Festival Lite (flite)</title>
2653 <para>Festival Lite is a free open source engine that currently supports
2654 a limited number of voices and languages. It is light weight, but
2655 sacrifices voice quality somewhat.
2656 You cannot control the pitch, volume, or speed of this engine
2657 from &ktts;.</para>
2659 <para>Synthesizer Name: <guilabel>Festival Lite (flite)</guilabel></para>
2661 <para>&URL;: <ulink url="http://www.speech.cs.cmu.edu/flite/index.html">
2662 http://www.speech.cs.cmu.edu/flite/index.html</ulink>
2663 </para>
2665 <para>Debian Install Command: <userinput>apt-get install flite</userinput></para>
2667 <para>flite is typically included with &Linux; distributions. Check your
2668 distro CDs to see if it is included.</para>
2670 <para>Build and install flite following the instructions in the
2671 <filename>README</filename> that comes with it.</para>
2673 </sect2>
2675 <!-- ...................................................................... -->
2678 <sect2 id="using-with-hadifix">
2679 <title>Using with Hadifix (&mbrola; and txt2pho)</title>
2681 <para>Hadifix is a two-stage synthesis engine based on diphones.
2682 The <command>txt2pho</command> utility converts text into diphones
2683 and the &mbrola; engine synthesizes the diphones to sound.
2684 Voice quality is good, but language support is currently somewhat limited.
2685 You can control the voice, pitch, speed, and volume from <application>kttsmgr</application>.
2686 </para>
2688 <para>Synthesizer Name: <guilabel>Hadifix</guilabel></para>
2690 <para>&URL;: see below</para>
2692 <para>Debian Install Command: none</para>
2694 <para>If you do not already have Hadifix installed, do this:</para>
2696 <procedure>
2697 <step><para>Download &mbrola; binary from
2698 <ulink url="http://festvox.org/mbrola/">http://festvox.org/mbrola/</ulink>.</para></step>
2699 <step><para>Install &mbrola; to <filename>/usr/local/mbrola</filename> folder.</para></step>
2700 <step><para>Download at least one german language file from the &mbrola; site.
2701 Unzip to the <filename>/usr/local/mbrola</filename> folder.</para></step>
2702 <step><para>Download txt2pho from</para>
2703 <para>
2704 <ulink url="http://www.ikp.uni-bonn.de/dt/forsch/phonetik/hadifix/HADIFIXforMBROLA.html">
2705 http://www.ikp.uni-bonn.de/dt/forsch/phonetik/hadifix/HADIFIXforMBROLA.html</ulink>.</para>
2706 </step>
2707 <step><para>Unzip txt2pho to <filename>/usr/local/txt2pho</filename>.</para></step>
2708 <step><para>Edit <command>txt2phorc</command> file, putting correct data paths in.</para></step>
2709 <step><para>Either copy <command>txt2phorc</command> to <filename>~/.txt2phorc</filename> or to <filename>/etc/txt2pho</filename>.
2710 Note that you drop the "rc" in file name.</para></step>
2711 <step><para>In <application>kttsmgr</application>, choose the German language
2712 (<guilabel>de</guilabel>), and add <guilabel>Hadifix</guilabel>.</para></step>
2713 <step><para>On the <guilabel>Configure Talker</guilabel> screen,
2714 configure a voice and the paths to &mbrola; and txt2pho.</para></step>
2715 <step><para>Click the <guibutton>Test</guibutton> button to test.</para></step>
2716 </procedure>
2718 <para>A Hungarian implementation for &mbrola; and txt2pho is available at</para>
2720 <para>
2721 <ulink url="http://tkltrans.sourceforge.net/">http://tkltrans.sourceforge.net/</ulink>.
2722 </para>
2724 </sect2>
2726 <!-- ...................................................................... -->
2729 <sect2 id="using-with-epos">
2730 <title>Using with Epos</title>
2732 <para>Epos is a free Czeck and Slovak open source engine.
2733 It is light weight, but sacrifices voice quality somewhat.
2734 You cannot control the volume of this engine
2735 from &ktts;.</para>
2737 <para>Synthesizer Name: <guilabel>Epos TTS Synthesis System</guilabel></para>
2739 <para>&URL;: <ulink url="http://epos.ure.cas.cz/">
2740 http://epos.ure.cas.cz/</ulink>
2741 </para>
2743 <para>Debian Install Command: <userinput>apt-get install epos</userinput></para>
2745 <para>Start <application>kttsmgr</application>. On the <guilabel>Talkers</guilabel> tab,
2746 click the <guibutton>Add</guibutton> button. Choose Czeck or Slovak
2747 language and <guilabel>Epos TTS Synthesis System</guilabel>.
2748 If the epos server executable and client are not
2749 in your <envar>PATH</envar>, specify the paths to these executables
2750 in the <guilabel>Configure Talker</guilabel> screen. The options boxes
2751 permit you to pass additional options to the server and client. In a
2752 &konsole;, type <userinput>epos -h</userinput>
2753 or <userinput>say -h</userinput> for information.</para>
2755 </sect2>
2757 <!-- ...................................................................... -->
2760 <sect2 id="using-with-freetts">
2761 <title>Using with FreeTTS</title>
2763 <para>FreeTTS is a free open source speech engine written in &Java;, which means
2764 that you must have the &Java; Virtual Machine software installed on your
2765 system to use it. It currently has limited voice and language support.
2766 You cannot control the pitch, volume, or speed of this engine
2767 from &ktts;.</para>
2769 <para>Synthesizer Name: <guilabel>FreeTTS</guilabel></para>
2771 <para>&URL;: <ulink url="http://sourceforge.net/projects/freetts/">
2772 http://sourceforge.net/projects/freetts/</ulink>
2773 </para>
2775 <para>Debian Install Command: none</para>
2777 </sect2>
2779 <!-- ...................................................................... -->
2782 <sect2 id="using-with-command">
2783 <title>Using the Command Plugin</title>
2785 <para>The command plugin permits you to use &ktts; with any
2786 speech synthesis engine that can be run as a command in a
2787 &konsole;.</para>
2789 <para>Synthesizer Name: <guilabel>Command</guilabel></para>
2791 <para>&URL;: none</para>
2793 <para>Debian Install Command: none</para>
2795 <para>Ideally, you should use a command that synthesizes to a temporary audio
2796 (wav) file, rather than send the speech directly to the audio device.</para>
2798 <para>If the speech synthesis engine requires text to be encoded
2799 differently from your desktop encoding setting, you must use the
2800 <command>%f</command> parameter to pass the text to the engine.
2801 &ktts; will encode the text in the setting you specify when
2802 it writes the text to the temporary file. If you attempt to pass text
2803 on the command line using the <command>%t</command> parameter,
2804 it will be encoded using your desktop locale setting.
2805 You can also use the <guilabel>Send the data as standard input</guilabel>
2806 option to solve this problem, if the engine accepts input from StdIn.
2807 For example, here is a sample command to send polish text to Festival using
2808 ISO 8859-2 encoding and removing unspeakable punctuation characters.</para>
2810 <para><command>cat %f | tr '(){}[]"' ' ' | festival --tts --language polish</command>
2811 </para>
2813 </sect2>
2815 <!-- ====================================================================== -->
2817 </sect1>
2819 </appendix>
2821 &documentation.index;
2822 </book>
2824 <!--
2825 Local Variables:
2826 mode: xml
2827 sgml-minimize-attributes:nil
2828 sgml-general-insert-case:lower
2829 sgml-indent-step:0
2830 sgml-indent-data:nil
2831 End:
2833 vim:tabstop=2:shiftwidth=2:expandtab