@c $Id$

@cindex @acronym{TTS}
@cindex speech system
@cindex speech settings

This section documents Emacspeak's  various user commands for controlling the
text to speech (@acronym{TTS}) system.

@menu
* Controlling Echo::             Character, Word and Line Echo.
* Speech Output  Control::       Indicating case, capitalization and indentation.
* Miscellaneous:: Miscellaneous @acronym{TTS} Commands.
@end menu

@node  Controlling Echo
@subsection   Character, Word And Line Echo.

@cindex line echo
@cindex character echo
@cindex word echo

By default, Emacspeak speaks characters as they are typed @MDash{}
this is called character echo; Words are spoken as they are completed
@MDash{} this is called word echo.  Emacspeak can also optionally
speak each line as it is typed @MDash{} this is called line echo.

Character, word and line echo can be toggled @MDash{} either in the
current buffer @MDash{} or for all buffers (globally).  To toggle the
specific echo functionality for all buffers, precede the specific
command with @kbd{C-u}.  Note that in the documentation below, this
use of @kbd{C-u} is indicated using the common Emacs terminology of
@emph{prefix arg} or @emph{interactive prefix arg}.

@table @kbd
@findex emacspeak-toggle-character-echo
@kindex C-e d k
@item C-e d k
@code{emacspeak-toggle-character-echo}

Toggle state of Emacspeak character echo.  Interactive PREFIX arg
means toggle the global default value, and then set the current local
value to the result.

@findex emacspeak-toggle-word-echo
@kindex C-e d w
@item C-e d w
@code{emacspeak-toggle-word-echo}

Toggle state of Emacspeak word echo.  Interactive PREFIX arg means
toggle the global default value, and then set the current local value
to the result.


@findex emacspeak-toggle-line-echo
@kindex C-e d l
@item C-e d l
@code{emacspeak-toggle-line-echo}

Toggle state of Emacspeak line echo.  Interactive PREFIX arg means
toggle the global default value, and then set the current local value
to the result.
@end table

@node Speech Output  Control
@subsection Setting  TTS Characteristics.

Emacspeak user commands can set different characteristics of the speech
output such as speech rate and  punctuations mode.

Emacspeak provides a number of settings that affect how  attributes of
the text such as capitalization are conveyed.
These include settings that produce a short tone for each upper case
letter,  as well as a smart mode for speaking mixed case words which is
especially useful when programming.
These settings can be made locally in a given buffer or be applied to
all buffers by preceding these commands with @kbd{C-u}.

@table @kbd

@findex dtk-set-rate
@kindex C-e d r
@item C-e d r
@code{dtk-set-rate}

Set speaking RATE for the @acronym{TTS}.  Interactive PREFIX arg means set the
global default value, and then set the current local value to the
result.

@findex dtk-set-character-scale
@kindex C-e d f
@item C-e d f
@code{dtk-set-character-scale}

Set scale FACTOR for speech rate.  Speech rate is scaled by this
factor when speaking characters.  Interactive PREFIX arg means set the
global default value, and then set the current local value to the
result.

This function is advised.

Before-advice `emacspeak-auto':
Automatically defined advice to speak interactive prompts.

@findex dtk-set-predefined-speech-rate
@kindex C-e d DIGIT
@item C-e d DIGIT
@code{dtk-set-predefined-speech-rate}

Set speech rate to one of nine predefined levels using digit keys
@kbd{0} through @kbd{9}.  Interactive PREFIX arg says to set the rate
globally.

@findex dtk-set-punctuations
@kindex C-e d p
@item C-e d p
@code{dtk-set-punctuations}

Set punctuation mode to MODE.  Possible values are `some', `all', or
`none'.  Interactive PREFIX arg means set the global default value,
and then set the current local value to the result.

@findex dtk-set-pronunciation-mode
@kindex C-e d m
@item C-e d m
@code{dtk-set-pronunciation-mode}

Set pronunciation MODE.  This command is valid only for newer
Dectalks, e.g.  the Dectalk Express.  Possible values are `math, name,
europe, spell', all of which can be turned on or off.  Argument STATE
specifies new state.

@findex dtk-toggle-split-caps
@kindex C-e d s
@item C-e d s
@code{dtk-toggle-split-caps}

Toggle split caps mode.  Split caps mode is useful when reading
Hungarian notation in program source code.  Interactive PREFIX arg
means toggle the global default value, and then set the current local
value to the result.
@code{dtk-toggle-caps}
@item C-e d c
@kindex C-e d c
@findex dtk-toggle-caps


Toggle capitalization.  when set, capitalization is indicated by a
@emph{cap} before the word, and upper-case words are indicated with a
@emph{acc} before the word.  Interactive PREFIX arg means toggle the global default
value, and then set the current local value to the result.
@end table

In addition, Emacspeak can convey the indentation of lines as they are
spoken @MDash{} This is relevant when programming and is the default
when working with program source.

@table @kbd
@findex emacspeak-toggle-audio-indentation
@kindex C-e d i
@item C-e d i
@code{emacspeak-toggle-audio-indentation}

Toggle state of Emacspeak audio indentation.  Interactive PREFIX arg
means toggle the global default value, and then set the current local
value to the result.  

@end table
@node Miscellaneous
@subsection Miscellaneous Speech Commands

Speech can be stopped using command @code{dtk-stop} @MDash{} though in
normal use, the action of moving the cursor will stop ongoing speech.
The speech server can be stopped and restarted for cases where the
user wants to switch to a different server @MDash{} or in the rare
case to nuke a runaway speech server.

@table @kbd

@findex dtk-stop
@kindex C-e s
@item C-e s
dtk-stop

Stop speech now.

@findex dtk-toggle-quiet
@kindex C-e d q
@item C-e d q
@code{dtk-toggle-quiet}

Toggle state of the speech device between being quiet and talkative.
Useful if you want to continue using an Emacs session that has
emacspeak loaded but wish to make the speech shut up.  Optional
argument PREFIX specifies whether speech is turned off in the current
buffer or in all buffers.

@findex dtk-emergency-restart
@kindex C-e C-s
@item C-e C-s
@code{dtk-emergency-restart}

Use this to nuke the currently running dtk server and restart it.
Useful if you want to switch to another synthesizer while emacspeak is
running.  Also useful for emergency stopping of speech.
@end table

Finally, here are the remaining commands available via the
@acronym{TTS} related keymap @kbd{C-e d}.

@table @kbd

@findex dtk-add-cleanup-pattern
@kindex C-e d a
@item C-e d a
@code{dtk-add-cleanup-pattern}

Add this pattern to the list of repeating patterns that are cleaned
up.  Optional interactive prefix arg deletes this pattern if
previously added.  Cleaning up repeated patterns results in emacspeak
speaking the pattern followed by a repeat count instead of speaking
all the characters making up the pattern.  Thus, by adding the
repeating pattern `.' (this is already added by default) emacspeak
will say ``aw fifteen dot'' when speaking the string
``...............'' instead of ``period period period period''.

@findex dtk-select-server
@kindex C-e d d
@item C-e d d
@code{dtk-select-server}

Select a speech server interactively.  This will be the server that is
used when you next call either M-x dtk-initialize or C-e C-s.
Argument PROGRAM specifies the speech server program.

@findex dtk-toggle-splitting-on-white-space
@kindex C-e d @key{SPACE}
@item C-e d @key{SPACE}
@code{dtk-toggle-splitting-on-white-space}

Toggle splitting of speech on white space.  This affects the internal
state of emacspeak that decides if we split text purely by clause
boundaries, or also include whitespace.  By default, emacspeak sends a
clause at a time to the speech device.  This produces fluent speech
for normal use.  However in modes such as `shell-mode' and some
programming language modes, clause markers appear infrequently, and
this can result in large amounts of text being sent to the speech
device at once, making the system unresponsive when asked to stop
talking.  Splitting on white space makes emacspeak's stop command
responsive.  However, when splitting on white space, the speech sounds
choppy since the synthesizer is getting a word at a time.

@findex dtk-set-chunk-separator-syntax
@kindex C-e d @key{RETURN}
@item C-e d @key{RETURN}
@code{dtk-set-chunk-separator-syntax}

Interactively set how text is split in chunks.  See the Emacs
documentation on syntax tables for details on how characters are
classified into various syntactic classes.  Argument S specifies the
syntax class.

@findex emacspeak-dial-dtk
@kindex C-e d t
@item C-e d t
@code{emacspeak-dial-dtk}

Prompt for and dial a phone NUMBER with the Dectalk.

@findex tts-speak-version
@kindex C-e d  cap V
@item C-e d  cap V
@code{tts-speak-version}

Use this to find out which version of the @acronym{TTS} firmware you
are running.

@findex emacspeak-zap-dtk
@kindex C-e d z
@item C-e d z
@code{emacspeak-zap-dtk}

Send this command to the @acronym{TTS} engine directly.

@end table
