speech-dispatcher
=================

*Common interface to speech synthesis*

Introduction
------------

This is the Speech Dispatcher project (speech-dispatcher). It is a part of the
[Free(b)soft project](https://devel.freebsoft.org/), which is intended to allow
blind and visually impaired people to work with computer and Internet based on
free software.

Speech Dispatcher project provides a high-level *device independent* layer
for access to speech synthesis through a simple, stable and well documented
interface.

Documentation
-------------

Complete documentation may be found in doc directory:
the speech dispatcher documentation: doc/speech-dispatcher.html,
the spd-say documentation: doc/spd-say.html,
and the SSIP protocol documentation: doc/ssip.html.

Read [doc/README](doc/README) for more information.

This documentation is also available online:
the [speech dispatcher documentation](http://htmlpreview.github.com/?https://github.com/brailcom/speechd/blob/master/doc/speech-dispatcher.html),
the [spd-say documentation](http://htmlpreview.github.com/?https://github.com/brailcom/speechd/blob/master/doc/spd-say.html),
and the [SSIP protocol documentation](http://htmlpreview.github.com/?https://github.com/brailcom/speechd/blob/master/doc/ssip.html).

The key features and the supported TTS engines, output subsystems, client
interfaces and client applications known to work with Speech Dispatcher are
listed in [overview of speech-dispatcher](README.overview.md) as well as voices
settings and where to look at in case of a sound or speech issue.

Mailing-lists
-------------

There is a public mailing-list
[speechd-discuss](https://lists.nongnu.org/mailman/listinfo/speechd-discuss)
for this project.

This list is for Speech Dispatcher developers, as well as for users. If you
want to contribute the development, propose a new feature, get help or just be
informed about the latest news, don't hesitate to subscribe. The communication
on this list is held in English.

Development
-----------

Various versions of speech-dispatcher can be downloaded from the [project
archive](https://github.com/brailcom/speechd/releases).

Bug reports, issues, and patches can be submitted to [the github
tracker](https://github.com/brailcom/speechd/issues).

The source code is freely available. It is managed using Git. You can use
the [GitHub web interface](https://github.com/brailcom/speechd) or clone the
repository from:

    https://github.com/brailcom/speechd.git

A Java library is currently developed separately. You can use the [GitHub web
interface](https://github.com/brailcom/speechd-java) or clone the repository
from:

    https://github.com/brailcom/speechd-java.git

To build and install speech-dispatcher and all of it's components, read the
file [INSTALL](INSTALL).


People
------

Speech Dispatcher is being developed in closed cooperation between the Brailcom
company and external developers, both are equally important parts of the
development team. The development team also accepts and processes contributions
from other developers, for which we are always very thankful! See more details
about our development model in Cooperation. Bellow find a list of current inner
development team members and people who have contributed to Speech Dispatcher in
the past:

Development team:

  * Samuel Thibault
  * Jan Buchal
  * Tomas Cerha
  * Hynek Hanke
  * Milan Zamazal
  * Luke Yelavich
  * C.M. Brannon
  * William Hubbs
  * Andrei Kholodnyi

Contributors: Trevor Saunders, Lukas Loehrer,Gary Cramblitt, Olivier Bert, Jacob
Schmude, Steve Holmes, Gilles Casse, Rui Batista, Marco Skambraks ...and many
others.

License
-------

Copyright (C) 2001-2009 Brailcom, o.p.s
Copyright (C) 2018-2020 Samuel Thibault <samuel.thibault@ens-lyon.org>
Copyright (C) 2018 Didier Spaier <didier@slint.fr>

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details (file
COPYING in the root directory).

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.


Note:

- The speech-dispatcher server (src/server/ + src/common/) contains
GPLv2-or-later and LGPLv2.1-or-later source code, but is linked against
libdotconf, which is LGPLv2.1-only at the time of writing.

- The speech-dispatcher modules (src/modules/ + src/common/ + src/audio/)
contain GPLv2-or-later, LGPLv2.1-or-later, and LGPLv2-or-later source code,
but are also linked against libdotconf, which is LGPLv2.1-only at the time of
writing.

- The spd-conf tool (src/api/python/speechd_config/), spd-say tool
(src/clients/say), and spdsend tool (src/clients/spdsend/) are GPLv2-or-later.

- The C API library (src/api/c/) is LGPLv2.1-or-later

- The Common Lisp API library (src/api/cl/) is LGPLv2.1-or-later.

- The Guile API library (src/api/guile/) contains GPLv2-or-later and
LGPLv2.1-or-later source code.

- The Python API library (src/api/python/speechd/) is LGPLv2.1-or-later.

- All tests in src/tests/ are GPLv2-or-later.

Overview of Speech Dispatcher
=============================

Key features:
-------------

  * Common interface to different Text To Speech (TTS) engines
  * Handling concurrent synthesis requests — requests may come asynchronously
  from multiple sources within an application and/or from different applications
  * Subsequent serialization, resolution of conflicts and priorities of incoming
  requests
  * Context switching — state is maintained for each client connection
  independently, event for connections from within one application
  * High-level client interfaces for popular programming languages
  * Common sound output handling — audio playback is handled by Speech
  Dispatcher rather than the TTS engine, since most engines have limited sound
  output capabilities

What is a very high level GUI library to graphics, Speech Dispatcher is to
speech synthesis. The application neither needs to talk to the devices directly
nor to handle concurrent access, sound output and other tricky aspects of the
speech subsystem.

Supported TTS engines:
----------------------

  * Festival
  * Flite
  * Espeak
  * Cicero
  * IBM TTS
  * Espeak+MBROLA (through a generic driver)
  * Epos (through a generic driver)
  * DecTalk software (through a generic driver)
  * Cepstral Swift (through a generic driver)
  * Ivona
  * Pico (possibly through a generic driver)
  * Espeak NG
  * Kali TTS
  * Baratinoo (Voxygen)
  * Mary-TTS

Supported sound output subsystems:
----------------------------------

  * OSS
  * ALSA
  * PulseAudio
  * NAS
  * Libao

The architecture is based on a client/server model. The clients are all the
applications in the system that want to produce speech (typically assisting
technologies). The basic means of client communication with Speech Dispatcher
is through a Unix socket or Inet TCP connection using the Speech Synthesis
Interface Protocol (See the SSIP documentation for more information). High-level
client libraries for many popular programming languages implement this protocol
to make its usage as simple as possible.

Supported client interfaces:
----------------------------

  * C/C++ API
  * Python 3 API
  * Java API
  * Emacs Lisp API
  * Common Lisp API
  * Guile API
  * Simple command line client

A golang API is also available on https://github.com/ilyapashuk/go-speechd

Existing assistive technologies known to work with Speech Dispatcher:

  * speechd-el (see https://devel.freebsoft.org/speechd-el)
  * Orca (see http://live.gnome.org/Orca/SpeechDispatcher)
  * Yasr (see http://yasr.sourceforge.net/)
  * BrlTTY (see http://brltty.com)
  * Chromevox (extension of the Chrome and Chromium browsers)

Voices settings
---------------
The available voices depend on the TTS engines and voices installed.

The voice to use can be set in speech-dispatcher itself, at the system and user
level, and from the client application, like Orca, speechd-el or Chromevox.
The settings in each application and in speech dispatcher are independent of
each others.

The settings in speech-dispatcher at the user level override those
made at the system level.


In speech-dispatcher, the system settings are recorded in the file
/etc/speech-dispatcher/speechd.conf among which a default synthesizer, a voice
type or symbolic name (e.g. MALE1) and a default language.

In turn, each installed voice is associated to a voice type and a language, thus
with this default setting a voice available with these characteristics (voice
type, language, synthesizer) will be chosen if available.


The default values of theses voices parameters can also be set at the system
level customized at the user level: rate, pitch, pitch range and volume.

It is also possible to make the synthesizer depend on the language used.


The user settings are written in the file ~/.config/speech-dispatcher/spd.conf
using the application spd-conf, which also allows to modify the system settings.

spd-conf allows to set the synthesizer, the language and other voice parameters
but not select directly a specific voice.


Instead a specific voice can be chosen from the client application, selecting it
by name in a proposed list that depends on the synthesizer chosen.

The voice name can be a first name like 'bob' or 'viginie", a locale code in the
form language_COUNTRY or a language code followed by a number, for instance.

The language code associated to each name is listed alongside it between
parenthesis, like (fr-FR) for French from France.

Where to look at in case of a sound or speech issue
---------------------------------------------------

Speech dispatcher links together all the components that contribute to speak a
text, so if you don't get speech at all or something is not spoken, or not the
way you expect, this can come from speech dispatcher itself or from any of those
components (or lack of) and their settings:
- the audio subsystem in use, e.g. alsa or pulseaudio,
- the synthesizer in use, e.g espeak-ng or pico,
- the client application, like Orca or speechd-el or an underlying software like
  at-spi,
- the application that provides the text to be spoken, like Firefox.

How to investigate a specific issue goes far beyond this document, but bear in
mind that all listed components can be involved, as the audio equipment in use
and the way it is linked to the computer.


Copyright (C) 2001-2009 Brailcom, o.p.s
Copyright (C) 2018-2020 Samuel Thibault <samuel.thibault@ens-lyon.org>
Copyright (C) 2018 Didier Spaier <didier@slint.fr>
Copyright (C) 2018 Alex ARNAUD <alexarnaud@hypra.fr>

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details (file
COPYING in the root directory).

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

Notes for packagers of Speech Dispatcher.

The python bindings distributed in this release in directory
src/api/python/speechd/ have been ported to Python 3 and are backward
incompatible with Python 2. For applications relying on the Python
bindings, such as the Orca screen reader, to be compatible with this
release, a version must be used which runs on Python 3.

Please make sure to setup the package dependencies correctly
to avoid possible problems.


Copyright (C) 2006 Gary Cramblitt <garycramblitt@comcast.net>
Copyright (C) 2006-2012 Brailcom, o.p.s

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details (file
COPYING in the root directory).

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

Speech Dispatcher Coding Guidelines
===================================

This document describes the coding style used in this repository. All
patches or changes must follow this style. If you have any questions,
please contact the speech dispatcher mailing list.

Coding Style Guidelines for C Code
----------------------------------

The indenting style we use is the same as the linux kernel, with the following exceptions and extensions:

  * Goto statements should not be used unless in very special cases.

  * Function names should be
    * lowercase words separated by underscores.
    * functions which are only implementation details of the given source file
  should be declared as static

  * Variable names
    * global variables should follow the same conventions as functions (e.g.
    `output_modules`)
    * the verbosity of the name of local variables should be appropriate to its
    scope

  * Macro names
    * Macro names should be in uppercase, words separated by underscores
    (e.g. `SPEECHD_OPTION_CB_STR`)

  * Type names
    * New types are defined in mixed uppercase (e.g. MessageType)

If you use
GNU indent 2.2.10 or later, you should run it as follows:

    indent -npro -kr -i8 -ts8 -sob -l80 -ss -ncs -cp1 -il0

For versions of indent earlier than 2.2.10, drop the -il0 from the parameters.

In emacs environment the following can be used (untested):

    (defun speechd-c-mode ()
      "C mode with adjusted defaults for use with Speech Dispatcher."
      (interactive)
      (c-mode)
      (c-set-style "K&R"))

Coding Style Guideline for other code
-------------------------------------

Please respect the coding style of the given component.


Copyright (C) 2001-2018 Brailcom, o.p.s
Copyright (C) 2011 William Hubbs <w.d.hubbs@gmail.com>

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details (file
COPYING in the root directory).

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

This file contains instructions for translators to translate Speech
Dispatcher interface to their languages.  Speech Dispatcher uses
gettext[1] for its internationalization support.

If you're not familiar with gettext po files we recommend that you
read the Gettext manual[2] before continuing.

== Requirements ==

To translate Speech Dispatcher you need a git clone of speech
dispatcher.  If you are not reading this file from a git checkout
please check the `INSTALL` file for detailed instructions.  You will
also need gettext package installed, as recommended on
the `INSTALL` file.

== Adding a new Language ==

If your locale is not already supported by Speech Dispatcher you must
create a new <locale>.po file and translate all contained
messages. The following steps explain the process.

1. ON your Speech Dispatcher source directory change to the po directory.

2. Create a pot template for Speech Dispatcher running:

$ make -C po speech-dispatcher.pot-update

This will create a file called Speech Dispatcher.pot with all
translatable Speech Dispatcher messages.

3. Create the po template for the current system locale from Speech
Dispatcher.pot running

$ msginit

And follow the prompts.  If you want to create a translation for a
different locale please run

$ msginit -l <locale>

where <locale> is the locale's name.  This will create a <locale>.po
file.  msginit will fill in the po template header for you from your
environment but we recommend to double-check that information.

You may also copy the Speech Dispatcher.pot file to <locale>.po and
fill in the header information yourself.

At this stage you can remove the Speech-Dispatcher.pot file since it
is not needed anymore.

4. Open the file `LINGUAS` and add your locale name there.  Please put
one locale on each line and keep the file alphabetically sorted.

5. Translate all messages in <locale>.po and run make.  If you found
errors reported by msgfmt about your <locale>.po file please correct
them before continuing.

6. When you're done see the section about testing below.

== Updating an existing Translation ==

When there are new Speech Dispatcher messages for translation or some
messages are changed, you need to update your <locale.>.po file.

To update an existing po file with new messages please run

$ make -C po <locale>.po-update

Where <locale> is the locale po file to update.

Then you can translate new messages and, if needed, update the ones
gettext guessed wrong when updating the po file.

== Testing your Translation ==

To confirm that your translation works, please install Speech
Dispatcher with your translation included and test it with your system
configured for your locale.

We recommend you test with spd-say and spd-conf, since those are the
tools with more translatable content.

== Sending your Translation to Speech Dispatcher ==

When you think your translation is ready to be included in Speech
Dispatcher send the po file to our development mailling-list at
speechd-discuss@nongnu.org

== References ==

[1] Gettext: https://www.gnu.org/software/gettext/
[2] Gettext Manual: https://www.gnu.org/software/gettext/manual/gettext.html


Copyright (C) 2010 Rui Batista <ruiandrebatista@gmail.com>
Copyright (C) 2012 Brailcom, o.p.s
Copyright (C) 2017 Jan Tojnar <jtojnar@gmail.com>

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details (file
COPYING in the root directory).

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.