2.4 Customization

All the customization options described below are accessible in the customization group ‘speechd-el’ and its subgroups.

2.4.1 Selecting Drivers

By default speechd-el speaks to ssip and brltty drivers. You can change the set of active drivers by customizing the following variable:

speechd-out-active-drivers

List of names of active output drivers.

If a driver that does not work is present in the variable (e.g. the list contains the brltty symbol while BRLTTY is not actually running), you receive an error message. To prevent the error message, remove the driver from this variable.

When you want to enable or disable some driver temporarily, you can use the following commands:

M-x speechd-out-enable-driver

Enable the given output driver.

M-x speechd-out-disable-driver

Disable the given output driver.

2.4.2 Speech Dispatcher Host Connection Configuration

Host connection variables allow you connect to Speech Dispatcher or BRLTTY running on a remote host or a non-default port and to specify other TCP connection parameters.

Speech Dispatcher connection options:

speechd-host

Name of the host running Speech Dispatcher to connect to, given as a string. Default is either the contents of the shell variable SPEECHD_HOST variable if set, or "localhost".

speechd-port

Port number to connect to. Default is either the contents of the shell variable SPEECHD_PORT if set, or the default Speech Dispatcher port.

speechd-timeout

Maximum number of seconds to wait for a Speech Dispatcher answer. If it is exceeded, speechd-el closes the connection. Normally, Speech Dispatcher should answer protocol commands immediately, but if you talk to a Speech Dispatcher in a strange way through a lagging network, you may want to increase the limit.

speechd-spdsend

If non-nil, it is a string naming the spdsend binary (normally "spdsend") to use for communication with Speech Dispatcher. If nil or if you use Emacs 22 or higher, spdsend is not used.

Usually you shouldn't care about this variable.

BRLTTY connection options:

brltty-default-host

Name of the host running BRLTTY to connect to, given as a string. Default is "localhost".

brltty-default-port

Port number to connect to. It can be either a single number or a list of numbers; in the latter case the given port numbers are attempted in the order they are given until Emacs connects to something. Default is the list of the standard BrlAPI ports.

brltty-authentication-file

File containing the BrlAPI authentication key. It is important to set the variable properly, otherwise the connection to BRLTTY gets rejected. Default is "/etc/brlapi.key".

brltty-coding

Coding in which texts should be sent to BRLTTY. Default is iso-8859-1; if you use non-Western language, you may need to change it to display its characters correctly on the Braille display.

brltty-tty

Number of the Linux console on which speechd-el runs. If this value is not set correctly, speechd-el may not interact well with other applications communicating with BRLTTY. speechd-el tries to find the correct value itself, if this doesn't work, set this variable properly or set the CONTROLVT environment variable.

brltty-timeout

Maximum number of seconds to wait for a BRLTTY answer. If it is exceeded, speechd-el closes the connection. Normally, BRLTTY should answer protocol commands immediately, but if you talk to BrlAPI in a strange way through a lagging network, you may want to increase the limit.

2.4.3 Default Priorities

If a speechd-el function sends a message to the output device without an explicitly specified priority, the priorities defined by the following variables are used. By changing the values, you can achieve interesting effects. For instance, changing the value of speechd-default-key-priority from notification to message makes all typed characters to be echoed and makes them to interrupt common text reading.

The valid values of all the variables here are: important, message, text, notification, progress. They correspond to Speech Dispatcher priorities, see the Speech Dispatcher manual for more details.

speechd-default-text-priority

Default priority of most text messages.

speechd-default-sound-priority

Default priority of sound icons.

speechd-default-char-priority

Default priority of spelled characters.

speechd-default-key-priority

Default priority of typed keys.

2.4.4 Basic Customization of Speaking

speechd-speak-echo

Symbol determining how to read typed characters. It can have one of the following values:

character

Read characters when they are typed.

word

Read only whole words once they are written.

nil

Don't echo anything on typing.

speechd-speak-deleted-char

Defines which character to speak when deleting a character. If non-nil, speak the deleted character, otherwise speak the adjacent character.

speechd-speak-buffer-name

When you switch to another buffer and this variable is non-nil, read the new buffer name. If the variable value is the symbol text, read the text from the cursor position to the end of line in the new buffer as well. If the variable is nil, read the text without speaking the buffer name.

speechd-speak-whole-line

If non-nil, read whole line on movement by default. Otherwise read from the point to the end of line on movement by default.

speechd-speak-on-minibuffer-exit

When this variable is non-nil, speechd-el reads the text around cursor after exiting from minibuffer or its recursive level if there is nothing else to read.

speechd-speak-read-command-keys

This variable defines in which situations command keys should be read when their command is performed. If t, the command keys are always read. If nil, they are never read. If list, it may contain one or more of the following symbols describing the situations in which the keys should be read:

movement

Read the command keys if the cursor has moved, no buffer modification happened.

modification

Buffer was modified, the cursor hasn't moved.

movement-modification

Buffer was modified and the cursor was moved.

If the variable value is t, the command keys are read before the command is performed. Otherwise, their reading is delayed after the command is executed, since the buffer changes and cursor movement must be detected first.

speechd-speak-ignore-command-keys

List of commands that should never echo their command keys.

speechd-speak-read-command-name

If non-nil, read the command name instead of the command keys in the situations defined by the variable speechd-speak-read-command-keys.

speechd-speak-message-time-interval

Minimum time in seconds, after which the same message may be repeated. If the message is the same as the last one, it is not spoken unless the number of seconds defined here has passed from the last spoken message.

2.4.5 Auto-Reading Buffers

It sometimes useful to start reading some buffers without user's explicit request. For instance, if a help command is invoked, the user usually wants to read the help text immediately. The following variables contain lists of names of the buffers that may be read automatically if they get changed by the last command and are visible in some window of the current frame.

speechd-speak-auto-speak-buffers

Content of these buffers is read after the command on the above conditions if nothing else (e.g. text around a new cursor position) is to be read.

speechd-speak-force-auto-speak-buffers

Like speechd-speak-auto-speak-buffers except that the buffer content is read forcibly, even when something else could be read.

The following variables define how to handle texts inserted during performing user commands. Only newly inserted text is read, the options don't affect processing of deleted text. Also, the options don't affect insertions within commands processed in a special way by speechd-el or user definitions, like self-insert-command.

speechd-speak-buffer-insertions

Defines whether insertions in the current buffer should be read automatically. The value may be one of the following symbols:

nil

Don't read the inserted texts.

t

Read all the inserted texts.

one-line

Read only the first lines of inserted texts.

whole-buffer

Read whole buffer if it was modified in any way.

speechd-speak-insertions-in-buffers

List of names of buffers, in which insertions are automatically read, whether the buffer is current or not and regardless the speechd-speak-buffer-insertions variable.

speechd-speak-priority-insertions-in-buffers

List of names of buffers, in which insertions are automatically read immediately as they appear, not only after a command is evaluated as with speechd-speak-insertions-in-buffers. This is typically useful in comint buffers.

speechd-speak-align-buffer-insertions

If non-nil, the insertion text to be read is extended to the beginning of the first word affected by the insertion. This is particularly useful in completion functions.

If the last command modified the current buffer and moved its cursor to a completely different position, the new cursor position is not indicated in the alternative output. You can change it through the following variable:

speechd-speak-movement-on-insertions

If t, read the text around new cursor position even when the current buffer was modified. If read-only, read it only in read-only buffers. If nil, don't read it.

2.4.6 Reading State Changes

speechd-el can read information about current Emacs state, like current buffer name, major and minor modes or other buffer attributes, see See section Informatory Commands. Changes in the Emacs state information can be reported automatically, according to the user configuration:

speechd-speak-state-changes

List of identifiers of the Emacs state changes to be automatically reported. The following symbols are recognized as state change identifiers:

buffer-name

buffer-identification

(only in Emacs 22 or higher)

buffer-modified

buffer-read-only

frame-name

frame-identification

(only in Emacs 22 or higher)

header-line

(only in Emacs 22 or higher)

major-mode

minor-modes

buffer-file-coding

terminal-coding

input-method

process

speechd-speak-display-modes

List of minor modes to be read by their display string rather than name. To use the display form of a mode identification may be useful in cases when the display form is more concise than the mode name or when the display form changes without actual change of the mode.

2.4.7 Signalling

Certain situations may be signalled by icons. Icon is typically a short sound or a special indication on a Braille display(1) signalling some event (such as displaying a message, entering prompt, or reaching an empty line). The following variable enables or disables the predefined indications. To learn how to define your own indications, See section Defining Your Own Command Feedbacks.

speechd-speak-signal-events

List of symbols, containing names of events to signal with an icon. The following event names are supported:

start

Start or restart of speechd-el.

empty

Empty text in various situations.

beginning-of-line

Reaching beginning of line after the forward-char and backward-char commands.

end-of-line

Reaching end of line after the forward-char and backward-char commands.

minibuffer

Entering minibuffer.

message

Messages in echo area follow.

2.4.8 Text Properties

By default, after a movement command speechd-el reads the current line. But if the cursor position is surrounded by a text having text properties (typically faces, but any text properties count), speechd-el may read just the piece of the text around the cursor having uniform properties.

Also, if font lock mode is enabled, faces may be mapped to different voices.

speechd-speak-by-properties-on-movement

Method of selection of the piece of text to be read on movement. The variable may take one of the following values.

nil

Text properties are not considered at all.

t

All text properties are considered.

list of faces

Only the named faces are considered.

speechd-speak-by-properties-always

List of commands that always consider text properties, even when the speechd-speak-by-properties-on-movement variable is nil.

speechd-speak-by-properties-never

List of commands that never consider text properties, even when the speechd-speak-by-properties-on-movement variable is non-nil.

speechd-speak-faces

This variable allows you to invoke actions when the cursor ends up on a certain face after a user command is performed. The variable value is an alist with elements of the form (face . action).

If a movement command leaves the cursor on a face and there is no explicit reading bound to the command, action is invoked. If action is a string, that string is read. If action is a function, it is invoked, with no arguments.

speechd-face-voices

Mapping of faces to voices. The variable value is an alist with elements of the form (face . voice) where face is a face and voice is a voice identifier defined in speechd-voices, see Defining voices. Each face is spoken in the corresponding voice. If there's no item for a given face in this variable, the face is spoken in the current voice.

Note that the mapping takes the effect only if font lock mode is enabled.

2.4.9 Using multiple languages

You can use speechd-el with multiple languages. However, the process can't be easily automated, since ordinary text does not contain any information about its language. So if you want to use speechd-el with the output being spoken in multiple languages, you must provide speechd-el some hints.

The language settings described below currently apply only to the spoken output, to select the proper voice. They don't affect the Braille output; but you may want to set language coding for Braille, See section Speech Dispatcher Host Connection Configuration.

The basic means for providing language information to speechd-el is the variable speechd-language. Each time speechd-el is about to speak a piece of text, it checks the variable for the language code and if it is non-nil, it speaks the text in the corresponding language. The non-nil value must be a string of the RFC 1766 language code (e.g. en, cs, etc.).

Most often you will probably want to set the variable in a particular file, see (emacs)File Variables section `File Variables' in GNU Emacs Manual, or as a buffer local variable, see (emacs)Locals section `Locals' in GNU Emacs Manual, in mode hooks, see (emacs)Hooks section `Hooks' in GNU Emacs Manual.

If a piece of the text has the language property containing the RFC 1766 language code, it is spoken in the corresponding language, regardless of other settings. You can use the speechd-language function to put the property on a string in your Elisp programs.

Another good way of using multiple languages is to use multiple connections for separating language dependent buffers or modes, see Multiple Connections, and to set the language parameter for each such a connection, see Connection Voices.

If nothing helps better, you can select languages according to the current input method:

speechd-speak-input-method-languages

Alist mapping input methods to languages. Each of the alist elements is of the form (input-method-name . language), where input-method-name is a string naming the input method and language is an RFC 1766 language code accepted by SSIP (e.g. en, cs, etc.). If the current input method is present in the alist, the corresponding language is selected unless overridden by another setting.

2.4.10 Defining voices

You can define special voices in speechd-el that can be used in different situations, e.g. to speak different faces in different voices (see section Text Properties) or to set different punctuation modes for different kinds of buffers (see section Multiple Connections). speechd-el voices define not only basic voice characteristics, but also speech characteristics like pitch or rate and special properties like punctuation reading or capital character signalization.

Voice definition is contained in the following variable:

speechd-voices

Alist of voice identifiers and their parameters.

Each element of the list is of the form (voice-id . parameters), where voice-id is a symbol under which the voice will be accessed and parameters is an alist of parameter identifiers and parameter values. Valid parameter names are the following symbols: language, gender, age, style, name, rate, pitch, volume, punctuation-mode, capital-character-mode, message-priority, output-module. Please note that any parameter entry present will change the corresponding parameter, even if the parameter value is nil or empty; if you don't want to change the parameter in any way by the voice, don't put it to the list (and don't enable its entry in customize).

name value is a string identifying Speech Dispatcher voice name. If it is not given, the parameters gender, age, and style are considered to select a Speech Dispatcher voice. gender value can be one of the symbols male, female, neutral. age can be one of the symbols middle-adult, child. neutral. style can be one of the numbers 1, 2, 3 (style values are likely to be changed in future).

The message-priority parameter sets priority of any message of the voice. Its value is any of the message priority symbols.

See the corresponding speechd-set-* functions for valid values of other parameters.

The voice named nil is special, it defines a default voice. Explicit definition of its parameters is optional.

2.4.11 Connection Voices

With the help of the following variable you can let set various connection parameters, like speech rate, language, etc., automatically. speechd-el can open multiple connections according to various criteria (see section Multiple Connections), you can set different parameters to different connections, based on their names.

speechd-connection-voices

Alist of connection names and corresponding voices. Each list element is of the form (connection-name . voice), where connection-name is a connection name given as a string and voice is a voice identifier defined in the variable speechd-voices.

The default voice (named nil) is used for connections that are not present in this variable.

So that changing the value of the variable could take the full effect, the open connections must be reopened. Unless you use the customization interface, you must invoke the C-u M-x speechd-speak command to ensure this.

There is a command to help you with setting connection voice and its parameters:

C-e C-a

Store the current connection parameters to a specified voice in the speechd-voices variable and set that voice for the current connection in the speechd-connection-voices variable.

Please note you are still responsible to save the variables if you want to use them in future sessions.

2.4.12 Multiple Connections

You can arrange speechd-el to use separate connections to Speech Dispatcher for certain buffers or major modes. This is basically useful to allow independent parameter setting for those buffers and major modes, both by hand and through the configuration (see section Connection Voices).

Each Speech Dispatcher connection has its unique name. By default, speechd-el uses a connection named "default". All you need to create a separate connection is to let speechd-el choose a different connection name in certain situations. The process of connection name selection is driven by the speechd-speak-connections variable.

speechd-speak-connections

Alist mapping major modes and buffers to Speech Dispatcher connections. Each element of the alist is of the form (mode-or-buffer . connection-name).

When speechd-el wants to send a message, it tests the current environment against the mode-or-buffer entries. mode-or-buffer may be one of the following objects, in the order of priority from the highest to the lowest:

• a list, representing a function call that should return a non-nil value if and only if the element should be applied
• regular expression matching desired buffer names
• the symbol :minibuffer, representing minibuffers
• major mode symbol
• nil, representing non-buffer areas, e.g. echo area
• t, representing the default value if nothing else matches

If more entries match in some situation, the entry with the highest priority is used.

connection-name is an arbitrary non-empty string naming the corresponding connection. If no connection with such a name is open in the running speechd-el, it is automatically created when there's something to send to it.

speechd-cancelable-connections

List of names of connections that are cancelled by default when a cancel function is called.

2.4.13 Keys

The command keys of speechd-el are defined by the speechd-speak-prefix variable and the speechd-speak-mode-map key map.

speechd-speak-prefix

This variable defines the prefix key of the speechd-el commands, which is C-e by default. If you change the variable value after speaking has already been started through the speechd-speak command and you do not set it through the customization interface, you must rerun the speechd-speak so that the change took any effect.

speechd-speak-mode-map

This key map holds the mapping of the keys following the prefix key. You can set keys here in the usual way, e.g.

(define-key speechd-speak-mode-map "t" 'speechd-say-text)

to get the speechd-say-text command bound to the C-e t key (assuming C-e is the prefix key).

2.4.14 Braille Display Keys

When using Braille display output, speechd-el can bind actions to the Braille display keys. The Braille key bindings are defined in the following variables:

speechd-braille-key-functions

Alist of Braille display key codes and corresponding Emacs functions. If the given key is pressed, the corresponding function is called with a speechd-brltty-driver instance as its single argument (read the source code for information about speechd-el output drivers).

The key codes are either integers (for BRLTTY 3.7 and older) or lists containing three integers (for BRLTTY 3.8 and newer). See the default variable value for examples of possible key codes.

The assigned functions needn't be interactive. Actually as the functions may be invoked by asynchronous events any time at any place, they shouldn't modify current environment in any inappropriate way. For this reason it is recommended not to assign user commands to the keys here.

‘speechd-brltty.el’ contains some predefined functions that can be assigned to the Braille display keys here:

speechd-brltty-scroll-left

Scroll towards the beginning of the currently displayed message.

speechd-brltty-scroll-right

Scroll towards the end of the currently displayed message.

speechd-brltty-scroll-to-bol

Scroll to the beginning of the currently displayed message.

speechd-brltty-scroll-to-eol

Scroll to the end of the currently displayed message.

speechd-brltty-scroll-to-cursor

Scroll to the cursor position (if any) in the displayed message.

speechd-brltty-finish-message

Stop displaying the current message and display the next one.

speechd-brltty-cancel

Stop displaying the current message and discard all messages waiting in the queue.

speechd-brltty-previous-message

Display the previous message from the history.

speechd-brltty-next-message

Display the next message from the history.

speechd-brltty-first-message

Display the first message in the history.

speechd-brltty-last-message

Display the last message in the history.

Additionally, the following macro is provided:

speechd-brltty-command-key-function key

Insert function for handling key as a general input key. This is useful for handling Braille keys acting as general character input keys.

The speechd-braille-key-functions variable contains some default bindings initially, but as the keys and their codes differ a lot for various Braille displays, you probably need to adjust it for your particular device. You can figure out the display key codes by setting the speechd-braille-show-unknown-keys variable to t and pressing the display keys.

speechd-braille-show-unknown-keys

If non-nil, show codes of the pressed Braille keys that have no function assigned in speechd-braille-key-functions. This is useful to figure out the Braille key codes.

With BrlTTY 3.8 and higher BrlTTY can handle many braille keys itself in X environment. So speechd-el doesn't try to handle most keys itself by default. Instead it handles only keys assigned in speechd-braille-key-functions. If this is a problem, typically when looking for braille key codes, the following command can be useful:

C-e C-b k

Toggle handling braille keys by speechd-el. If BrlTTY handles the keys (this is the default behavior), speechd-el receives only keys which are assigned to commands in speechd-braille-key-functions. If speechd-el handles the keys, then BrlTTY sends all the pressed keys to speechd-el without processing them itself.

2.4.15 Minor mode hooks

speechd-el provides a minor mode that enables and disables the reading, See section Starting Speech and Braille Output. You can let perform custom actions on entering it through the following hook.

speechd-speak-mode-hook

Hook run when speechd-speak minor mode is enabled.

2.4.16 Debugging speechd-el

When you try to debug speechd-speak functions, you can experience the problem of recursive reading in the Elisp debugger. To avoid it, you can instruct speechd-el to be quiet in Elisp debuggers:

speechd-speak-in-debugger

If nil, speechd-speak functions won't be reading in Elisp debuggers.

This document was generated by Hynek Hanke on March, 26 2009 using texi2html 1.78.