@c $Id$
@node TTS Servers
@chapter TTS Servers

Emacspeak produces spoken output by communicating with one of many
speech servers.  This section documents the communication protocol
between the client application i.e. Emacspeak, and the @acronym{TTS,
Text to Speech} server. This section is primarily intended for
developers wishing to:

@itemize @bullet
@item
Create new speech servers that comply with this communication protocol

@item
Developers of other client applications who wish to use the various
Emacspeak speech servers.
@end itemize

For additional notes on how to log and view @acronym{TTS} server commands when
developing a speech server, see
@url{http://emacspeak.blogspot.com/2015/04/howto-log-speech-server-output-to-aid.html}.

@section High-level Overview

The @acronym{TTS} server reads commands from standard input, and script
@emph{speech-server} can be used to cause a @acronym{TTS} server to communicate
via a @acronym{TCP} socket. Speech server commands are used by the client
application to make specific requests of the server; the server
listens for these requests in a non-blocking read loop and executes
requests as they become available. Requests can be classified as
follows:

@itemize @bullet
@item
Commands that send text to be spoken.

@item
Commands that set @emph{state} of the @acronym{TTS} server.
@end itemize

All commands are of the form

@example
commandWord @{arguments@}
@end example

The braces are optional if the command argument contains no white
space.  The speech server maintains a @emph{current state} that
determines various characteristics of spoken output such as speech
rate, punctuations mode etc. (see set of commands that manipulate
speech state for complete list).  The client application @emph{queues}
The text and non-speech audio output to be produced before asking the
server to @emph{dispatch} the set of queued requests, i.e. start
producing output.

Once the server has been asked to produce output, it removes items
from the front of the queue, sends the requisite commands to the
underlying @acronym{TTS} engine, and waits for the engine to acknowledge that
the request has been completely processed. This is a non-blocking
operation, i.e., if the client application generates additional
requests, these are processed @emph{immediately}.

The above design allows the Emacspeak @acronym{TTS} server to be @emph{highly}
responsive; Client applications can queue large amounts of text
(typically queued a clause at a time to achieve the best prosody), ask
the @acronym{TTS} server to start speaking, and interrupt the spoken output at
any time.

@subsection Commands That Queue Output.

This section documents commands that either produce spoken output, or
queue output to be produced on demand.  Commands that place the
request on the queue are clearly marked.

@example
version
@end example

Speaks the @emph{version} of the @acronym{TTS} engine. Produces output
immediately.

@example
tts_say text
@end example

Speaks the specified @emph{text} immediately. The text is not
pre-processed in any way, contrast this with the primary way of
speaking text which is to queue text before asking the server to
process the queue.

Note that this command needs to handle the special syntax for morpheme
boundaries @samp{[*]}.  The @samp{[*]} syntax is specific to the
Dectalk family of synthesizers; servers for other @acronym{TTS} engines need to
map this pattern to the engine-specific code for each engine. As an
example, see @file{servers/outloud} A morpheme boundary results in
synthesizing compound words such as @emph{left bracket} with the right
intonation; using a space would result in that phrase being
synthesized as two separate words.

@example
l c
@end example

Speak @emph{c} a single character, as a letter.  The character is
spoken immediately. This command uses the @acronym{TTS} engine's capability to
speak a single character with the ability to flush speech
@emph{immediately}.  Client applications wishing to produce
character-at-a-time output, e.g., when providing character echo during
keyboard input should use this command.

@example
d
@end example

This command is used to @emph{dispatch} all queued requests.  It was
renamed to a single character command (like many of the commonly used
@acronym{TTS} server commands) to work more effectively over slow (9600) dialup
lines.  The effect of calling this command is for the @acronym{TTS} server to
start processing items that have been queued via earlier requests.

@example
tts_pause
@end example

This pauses speech @emph{immediately}.  It does not affect queued
requests; when command @emph{tts_resume} is called, the output resumes
at the point where it was paused. Not all @acronym{TTS} engines provide this
capability.

@example
tts_resume
@end example

Resume spoken output if it has been paused earlier.

@example
s
@end example

Stop speech @emph{immediately}.  Spoken output is interrupted, and all
pending requests are flushed from the queue.

@example
q text
@end example

Queues text to be spoken. No spoken output is produced until a
@emph{dispatch} request is received via execution of command @emph{d}.


@example
c codes
@end example

Queues synthesis codes to be sent to the @acronym{TTS} engine.  Codes are sent
to the engine with no further transformation or processing.  The codes
are inserted into the output queue and will be dispatched to the @acronym{TTS}
engine at the appropriate point in the output stream.

@example
a filename
@end example

Cues the audio file identified by filename for playing.

@example
t freq length
@end example

Queues a tone to be played at the specified frequency and having the
specified length.  Frequency is specified in hertz and length is
specified in milliseconds.

@example
sh duration
@end example

Queues the specified duration of silence. Silence is specified in
milliseconds.

@subsection Commands That Set State

@example
tts_reset
@end example

Reset @acronym{TTS} engine to default settings.

@example
tts_set_punctuations mode
@end example

Sets @acronym{TTS} engine to the specified punctuation
mode. Typically, @acronym{TTS} servers provide at least three modes:

@itemize @bullet
@item
None: Do not speak punctuation characters.

@item
Some: Speak some punctuation characters. Used for English prose.

@item
All: Speak out @emph{all} punctuation characters; useful in
programming modes.
@end itemize

@example
tts_set_speech_rate rate
@end example

Sets speech rate. The interpretation of this value is typically
engine specific.

@example
tts_set_character_scale factor
@end example

Scale factor applied to speech rate when speaking individual
characters.Thus, setting speech rate to 500 and character scale to 1.2
will cause command @emph{l} to use a speech rate of
@emph{500 * 1.2 = 600}.

@example
tts_split_caps flag
@end example

Set state of @emph{split caps} processing. Turn this on to speak
mixed-case (@acronym{AKA} Camel Case) identifiers.

@example
tts_capitalize flag
@end example

Indicate capitalization via a beep tone or voice pitch.

@example
tts_allcaps_beep flag
@end example

Setting this flag produces a high-pitched beep when speaking words
that are in all-caps, e.g. abbreviations.
