[Top] [Contents] [Index] [ ? ]

Speech Synthesis Interface Protocol

This manual documents Speech Synthesis Interface Protocol, version 0.2.

Copyright © 2001, 2002, 2003 Brailcom, o.p.s., http://www.brailcom.cz .

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License.”

You can also (at your option) distribute this manual under the GNU General Public License:

Permission is granted to copy, distribute and/or modify this document 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.

A copy of the license is included in the section entitled “GNU General Public License”

Please contact us on http://www.freebsoft.org

Menu


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. Introduction


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Purpose

Speech Synthesis Interface Protocol is a device independent layer for speech synthesis, developed with the goal of making the usage of speech synthesis easier for application programmers. It takes care of most of the output-related tasks necessary to solve in speech enabled applications. What is a very high level GUI library to graphics, Speech Synthesis Interface Protocol is to speech synthesis.

Up to now, the applications that wanted to implement speech output had to handle all the device dependent aspects of communication with different speech synthesizers themselves. Speech Synthesis Interface Protocol (SSIP) aims to provide a totally independent abstract set of commands by which different applications can talk to some central Speech Server installed on the system that than talks to the synthesizers themselves. This way, user applications don’t have to care about the particular synthesizers available on the system and the synthesizers don’t have to care about the installed user applications.

SSIP is not only a device independent language for speech synthesis related requests, but also a mechanism to coordinate the interaction and conflicts between different clients’ needs in a central place in the system. Through the priority system, the central Speech Server that implements SSIP can decide which messages are considered the most important at any particular time and say them, while possibly supressing others.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Protocol Philosophy

Speech Synthesis Interface Protocol defines a reasonable subset of the different capabilities provided by the different synthesizers. It supports some basic events (message, key, character, ...) as well as changing the basic voice parameters (language, voice, rate, pitch, ...) or the more advanced ones (punctuation mode, spelling mode, ...).

None of the commands or parameters of SSIP depends on the characteristics of the particular devices that are being used. For example when the client application wants to change the language for the next message, it only calls the appropriate SSIP command and it leaves the Speech Server to decide which synthesizer to use.

SSIP was designed to allow multiple simultaneous connections to the server. A connection is identified by an identification string provided by the client application and an id number. Each connection with all its parameters is considered a closed space independent of the others, so that different clients can maintain different settings in their connections and then the Speech Server should take care of setting the right parameters on the synthesizer according to the origin of each request. One client can even establish several connections to maintain different contexts.

SSIP also solves the issue when more than one client wants to speak at one time or when more messages come than it’s possible to say. Each message has an assigned priority and according to this priority, when multiple messages come to the server, they are directly said, postponed or suppressed.

It is important to understand the difference between SSIP and higher level protocols like SABLE, VoiceXML or SSML. Speech Synthesis Interface Protocol is not a markup language in which one would write a document. SSIP is rather the underlaying tool that the application would use to let you read and browse the documents encoded in either ordinary formats (like plain text, HTML, PDF) or the voice-enabled formats (SABLE, VoiceXML, SSML). These higher level protocols describe only how the document should be said, while SSIP is the means to actually do it on your system. In this manner, one of the supported formats of the messages you can send through SSIP is SSML.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Higher Level API

SSIP is the basic interface protocol that is being used in the communication of a client with the central Speech Server on a system. However, in many cases it may be more convenient for application programmers not to use SSIP directly (having to care about open socket connections etc.) but rather use an interface wrapper written in the specific programming language they use. There is no obstacle in SSIP for this option, and in fact, this approach is highly encouraged.

This way, application programmers should finally be able to use such simple functions as speech_open(), speech_printf() and speech_set_rate() in their programs.

We believe this can make writing new speech enabled applications a lot easier and allow programmers to make more of them.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2. Basic Terminology


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. General Rules

SSIP communicates with the clients through a defined set of text commands, in the usual manner for common Internet protocols. The characters sent through the Speech Synthesis Interface Protocol are encoded using the UTF-8 encoding.

Each SSIP command, unless specified otherwise, consists of exactly one line. The line is sent in the following format:

 
command arg ...

where command is a case insensitive command name and args are its arguments separated by spaces. The command arguments which come from a defined set of values are case insensitive as well. The number of arguments is dependent on the particular command and there can be commands having no arguments.

All lines of SSIP input and output must be ended with a pair of carriage return and line feed characters, in that order.

When you connect to Speech Server, you should at least set your client name, through the SET SELF CLIENT_NAME command (see section Parameter Setting). This is important to get a proper identification of your client — to allow managing it from the control center application and to identify it in a message history browser. You might want to set other connection parameters as well. Look for more details in Parameter Setting.

An SSIP connection is preferably closed by issuing the QUIT command, see Other Commands.

SSIP is a synchronous protocol — you send commands and only after a complete response from SSIP arrives back are you allowed to send the next command. Usually, the SSIP connection remains open during the whole run of the particular client application. If you close the connection and open it again, you must set all the previously set parameters again, SSIP doesn’t store session parameters between connections.

The protocol allows you to perform commands influencing other currently connected or previously connected clients. This allows you to write a control application managing or browsing all the messages received by the current Speech Server process. The mechanism is completely relaxed, there are no restrictions on managing some aspects of sound output for other users, however, there is a mechanism to prevent one user from seeing history messages of another user.

Some of the commands (Controlling Speech Output and Parameter Setting) take an argument in the form:

 
        { id | all | self }

where the value can be the id of the connection the command should be performed on (a positive number), the string all to act on all clients of this server or self to act on the connection itself. Unless you are writing a special client for managing Speech Server or unless you have specific needs, you should only use the self value for this argument.

Not all parameter setting commands may receive all kinds of the first parameter defined above, for instance, some of them may receive only self.

SSIP replies have the following format:

 
ccc-line 1
ccc-line 2
...
ccc-line n-1
ddd line n

where n is a positive integer, and ccc and ddd are three-digit long numeric codes identifying the result of the command. The last line determines the overall result of the command. The result code is followed by an English message describing the result of the action in a human readable form.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. SSIP Commands

Commands recognized by SSIP can be divided into several groups: Speech synthesis and sound output commands, speech control commands, parameter setting commands, commands retrieving information about current client and server settings, commands handling the message history, and other commands. Each of these command groups is described in one of the following sections.

In the command descriptions, the command is written together with its arguments. Optional arguments are enclosed by square brackets ([ and ]), alternatives are separated by the vertical rule (|) and are grouped within braces ({ and }) or square brackets for mandatory or optional arguments respectively. Literal argument values are typeset in lowercase letters (they are case insensitive), and variable arguments are typeset like this. Ellipsis denoted by three dots (...) means repetition (zero or more times) of all the arguments within the current brackets.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1 Speech Synthesis and Sound Output

These commands invoke actual output to particular output device. The particular way how the message is handled depends on current speech parameter settings and user configuration.

SPEAK

Start receiving a text message and synthesize it. After sending a reply to the command, Speech Server waits for the text of the message. The text can spread over any number of lines and is finished by an end of line marker followed by the line containing the single character . (dot). Thus the complete character sequence closing the input text is CR LF . CR LF. If any line within the sent text starts with a dot, an extra dot is prepended before it.

During reception of the text message, Speech Server doesn’t send responses for the lines sent. The response line is sent only immediately after the SPEAK command and after receiving the closing dot line.

The content of the message can be either a plain text or a SSML (Speech Synthesis Markup Language) text. See SET SELF SSML_MODE. There is no guarantee that the SSML markup will be respected, so the application shouldn’t rely on them. The external parameters can still be set by the parameter setting commands. SSML is intended only for additional markup inside the message. In SSML mode, each message must begin with <speak> and end with </speak>.

Speech Server can start speech synthesis as soon as a sufficient amount of the text arrives; it generally needn’t (but may) wait until the end of data marker is received.

There is no explicit upper limit on the size of the text, but the server administrator may set one in the configuration or the limit can be enforced by available system resources. If the limit is exceeded, the whole text is accepted, but the excess is ignored and an error response code is returned after processing the final dot line.

The reply takes the form

 
225-msg_id
225 OK MESSAGE QUEUED

where msg_id is a unique id assigned to this message in Speech Server. This is useful for the History Handling commands as well as for Message Events Notification and Index Marking.

The SPEAK command might be used for example in this way:

 
SPEAK
230 OK RECEIVING DATA
hi
.
225-21
225 OK MESSAGE QUEUED
CHAR char

Speak letter char. char can be any character representable by the UTF-8 encoding. The only exception is the character space ( ); that can’t be sent directly. In this case, a string space must be sent instead.

 
CHAR e
CHAR \
CHAR space
CHAR &

This command is intended to be used for speaking single letters, e.g. when reading a character under cursor or when spelling words.

KEY key-name

Speak key identified by key-name. The command is intended to be used for speaking keys pressed by the user.

key-name is a case sensitive symbolic key name. It is composed of a key name, optionally prepended with one or more prefixes, each containing an auxiliary key name and the underscore character.

Key name may contain any character excluding control characters (for example, the characters in the range 0 to 31 in the ASCII table, characters in the range 128 to 159 in the Latin-* tables and other “invisible” characters), spaces, underscores, and double quotes.

The recognized key names are:

Examples of valid key names:

 
a
A
shift_a
shift_A
ú
$
enter
shift_kp-enter
control_alt_delete
control
SOUND_ICON icon-name

Send a sound identified by icon-name to the audio output. icon-name is a symbolic name of the given sound from the standard set listed in Standard Sound Icons, or another name from the particular Speech Server sound icon configuration.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2 Controlling Speech Output

These commands can stop or resume speech or audio output. They all affect only the synthesis process and output to a sound device, they do not affect the message history.

STOP { id | all | self }

Immediately stop outputting the current message (whatever it is — text, letter, key, or sound icon) from the identified client, if any is being output. If the command argument is self, the last message from the current client connection is stopped. If it is all, stop currently output message or messages from all the clients. Otherwise, argument id must be given as a positive integer and the currently processed message from the client connection identified by id is stopped; if there is none such, do nothing.

CANCEL { id | all | self }

This command is the same as STOP, with the exception that it stops as yet unspoken output messages as well. All currently queued messages are stored into the message history without being sent to the audio output device.

PAUSE { id | all | self }

Stop audio output immediately, but do not discard anything. All the currently speaking and currently or later queued messages are postponed and saved for later processing, until a corresponding RESUME command is received.

The meaning of the command arguments is the same as in the STOP command.

RESUME { id | all | self }

Cancel the effect of the previously issued PAUSE command. Note that messages of the priority “progress” and “notification” received during the pause are not output (but they remain stored in the message history).

It is an error to send the RESUME command when the output corresponding to the given argument is not paused by a previous invocation of the PAUSE command. Such an error is signaled by a 4XX return code.

The meaning of the command arguments is the same as in the STOP command.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3 Priority Setting Commands

A speech synthesizer can’t synthesize everything that comes to it, for the simple reason that messages are often coming faster than a synthetic voice can say them. On the screen of a monitor, there is relatively a lot of space compared to one-channel speech synthesis output. For this reason, SSIP implements a system of several priorities targeted at different types of messages.

The idea is that the task of the programmer of a client application is only to assign a meaningful priority to each message and all the synchronization and switching between the messages (that can be coming from different clients) is automatically handled by the Speech Server by applying certain rules based on the priorities.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.1 Priority Categories

Speech Synthesis Interface Protocol provides a system of five priorities. Every message will either contain explicit priority information, or the default value will be used.

Please see also the diagram below.

Priority important

This message will be said immediately as it comes to server. It is never interrupted. When several concurrent messages of this priority are received by server, they are queued and said in the order they came.

When a new message of level important comes while a message of another priority is being spoken, the other message is canceled and the message with priority important is said instead. Other messages of lower priorities are postponed (priority message and text) until there are no messages of priority important waiting, or are canceled (priority notification and progress).

These messages should be as short as possible and should rarely be used, because they block the output of all other messages.

Priority message

This message will be said when there is no message of priority important or message waiting in the queue. If there are, this message is postponed until those messages are spoken. This means that the priority message doesn’t interrupt itself. If there are messages of priority notification, progress or text waiting in the queue or being spoken when a message of priority message comes, they are canceled.

Priority text

This message will be said when there is no message of priority important or message waiting in the queue. If there are, this message is postponed until the previous messages are spoken.

The priority text interrupts itself. This means that if several messages of this priority are received, they are not said in the order they were received, but only the latest of them is said; others are canceled.

If there are messages of priority notification and progress waiting in the queue or being spoken when a message of priority text comes, they are canceled.

Priority notification

This is a low priority message. If there are messages with priorities important, message, text or progress waiting in the queues or being spoken, this notification message is canceled.

This priority interrupts itself, so if more messages with priority notification come at the same time, only the last of them is spoken.

Priority progress

This is a special priority for messages that are coming shortly one after each other and they carry the information about some work in progress (e.g. Completed 45%).

If new messages interrupted each other (see priority Notification), the user might not receive any complete message.

This priority behaves the same as “notification” except for two things:

This way, even if Speech Server is busy speaking messages of other priorities, we are still sure that the important messages at the end of the progress sequences will be said.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.2 Priority Diagram

Speech Synthesis Interface Protocol Priorities
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.3 Priority Setting Commands

When a priority is set for a given connection, all the newly arriving messages will be said with this priority until it is changed for a new value.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.4 Examples of Using Priorities

Example uses for priority important are:

Example uses for priority message are:

Example uses for priority text are:

Example uses for priority notification are:

Example uses for level progress are:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4 Blocks of Messages Commands

Block commands allow the client to concatenate several messages to form one block that behaves as one message in the priority system and history. After opening the block, client can send a specified subset of the commands and the messages introduced by SPEAK will be processed immediately, however there will be no priority interaction before closing the block. The Controlling Speech Output also handle the whole block as one message.

Take for example this message from an email client:

 
> Hi, how are you?
I'm fine. Thank you.

The character ‘>’ clearly marks who said which part. So it’d be nice to say the two lines with different voices, however, it’d be desirable to treat it all as one message with priority TEXT and have it put together in history, because in fact, it logically is one message.

BLOCK BEGIN

Opens a block of messages. There will be no priority interaction between the messages inside the block, the whole block will be treated as one message of the priority that was specified by previous SET command.

It can only be called outside of a block; nesting is not allowed.

BLOCK END

Closes a block of messages, see BLOCK BEGIN.

It can be only called inside a block opened by BLOCK BEGIN; nesting is not allowed.

A more complete example of SSIP communication using BLOCKs.

 
[...]
SET SELF PRIORITY TEXT
202 OK PRIORITY SET

BLOCK BEGIN
260 OK INSIDE BLOCK

SET SELF VOICE MALE1
209 OK VOICE SET

SPEAK
230 OK RECEIVING DATA
The word
225 OK MESSAGE QUEUED

SET SELF VOICE MALE2
209 OK VOICE SET
SPEAK
230 OK RECEIVING DATA
`Free'
225 OK MESSAGE QUEUED

SET SELF VOICE MALE1
209 OK VOICE SET
SPEAK
230 OK RECEIVING DATA
in Free Software refers to freedom, not price.
225 OK MESSAGE QUEUED

BLOCK END
261 OK OUTSIDE BLOCK

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.5 Parameter Setting

The SET command sets various control parameters of the synthesized speech or server configuration. The parameter is always denoted by the second command argument.

All the settings take effect on the connections specified in the first argument (see section General Rules) and until the parameter setting is changed by another invocation of the appropriate SET command or until the connection is closed.

The voice property and TTS-processing settings can sometimes be without any real effect if the end synthesizer doesn’t provide the required functionality. This is not considered an error in the implementation of SSIP.

SET self CLIENT_NAME user:client:component

Set client’s name. Client name consists of the user name, client (application) identification, and the identification of the component of the client (application). Each of the parts of the client name may contain only alphanumeric characters, dashes (-) and underscores (_).

For example, for a client called lynx that creates an SSIP connection for its command processing, the name could be set in the following way:

 
SET CLIENT_NAME joe:lynx:cmd_processing

The client name is used in the server configuration settings, client listings and message history handling. All its three parts can be arbitrary, but it’s important to define and follow rules for each application supporting Speech Synthesis Interface Protocol, so that a Speech Server user can configure all the aspects of the speech output easily.

Usually, this command should be sent as the very first command when a new SSIP connection is established. The command may be sent only once within a single connection. Attempts to change the client’s name once it’s already set are answered with an error code.

Only self is allowed as the ‘target’ argument.

SET all DEBUG {ON|OFF}

If set to ON, Speech Dispatcher will write all its debugging information (including output modules) with maximal verbosity into a debug directory which is reported by the server to the client in reply to this command. When subsequently set to OFF, Speech Dispatcher will stop writing out debugging information into this path and close all the appropriate logging files.

The intended use for this functionality is on-line debugging from client application. If the user wants to report a problem, the client application will ask him/her for a place to generate the logs, to repeat the situation that he/she considers to be a bug, and then perhaps it will automatically pack the logs and offer to send them to the developers of Speech Dispatcher or another appropriate place where the contained information can be processed.

Warning: This option results in a lot of data being written into the output logs and so should not be left on for an unnecessarily long time.

 
SET all DEBUG ON
262-/home/hanke/.cache/speech-dispatcher/log/debug
262 OK DEBUGGING SET
SET {all | self | id } OUTPUT_MODULE module

Set the output module to module. This overrides the selection based on language. Only values returned by the LIST OUTPUT_MODULES command are permitted. See list-output-modules.

 
SET self OUTPUT_MODULE espeak
216 OK OUTPUT MODULE SET
GET OUTPUT_MODULE

Get the output module currently in use. This takes no parameters and simply returns the current output module.

 
GET OUTPUT_MODULE
251-espeak
251 OK GET RETURNED
SET { all | self | id } LANGUAGE language-code

Set recommended language for this client according to language-code. language-code is the code of the language according to RFC 1766.

For example, to set the preferred language to Czech, you send the following command:

 
SET SELF LANGUAGE cs

Please note, that switching a language may require switching a voice, so this command may actually override a previous call to SET VOICE or SET SYNTHESIS_VOICE.

The default for the Speech Dispatcher implementation of SSIP is determined by the DefaultLanguage setting in the speechd.conf file. The factory default is en (English).

SET {self} SSML_MODE mode

Set the mode of the text received in the message body sent by the SPEAK command. This can be either a plain text, if mode is set to off or a SSML marked text, if mode is set to on.

There is no guarantee that the SSML markup will be respected, so the application shouldn’t rely on them. The external parameters can still be set by the parameter setting commands. SSML is intended only for additional markup inside the message. In SSML mode, each message must begin with <speak> and end with </speak>.

For example a simple ‘hello world’ looks like this:

 
SET SELF SSML_MODE on
SPEAK
<speak>
Hello world!
</speak>
.
SET { all | self | id } PUNCTUATION { all | some | none }

Set punctuation mode to the given value. all means speak all punctuation characters, none means speak no punctuation characters, some means speak only punctuation characters set in the synthesizer’s configuration. The default for the Speech Dispatcher implementation of SSIP is determined by the DefaultPunctuationMode setting in the speechd.conf file. The factory default is none.

SET { all | self | id } SPELLING { on | off }

Switch spelling on or off. If spelling is set to on, all the incoming messages will be said letter-by-letter, instead of speaking them as whole words. The default for the Speech Dispatcher implementation of SSIP is determined by the DefaultSpelling setting in the speechd.conf file. The factory default is off.

SET { all | self | id } CAP_LET_RECOGN { none | spell | icon }

Set capital letters recognition mode. none switches this feature off. spell causes capital letters to be spelled in the speech using the table set as CAP_LET_RECOGN_TABLE. With parameter icon, each capital letter will be preceeded by a sound icon (either sound or textual) specified by the user in his configuration. The default for the Speech Dispatcher implementation of SSIP is determined by the DefaultCapLetRecognition setting in the speechd.conf file. The factory default is none.

SET { all | self | id } VOICE_TYPE name

Set the voice identified by name. name must be one of the voice identifiers returned by the command LIST VOICES (see section Retrieving Information).

There is a standard set of voice identifiers defined in Standard Voices.

The default for the Speech Dispatcher implementation of SSIP is determined by the DefaultVoiceType setting in the speechd.conf file. The factory default is MALE1.

GET VOICE_TYPE

Gets the current pre-defined voice. A list of voice identifiers can be obtained by the command LIST VOICES (see section Retrieving Information).

 
GET VOICE_TYPE
251-MALE1
251 OK GET RETURNED
SET { all | self | id } SYNTHESIS_VOICE name

Set the voice identified by name. name is a voice name recognized by the current synthesizer. It must be one of the names returned by the command LIST SYNTHESIS_VOICES run for the appropriate synthesizer. (see section Retrieving Information).

Please note, that switching to a particular voice may require switching a language, so this command may actually override a previous call to SET LANGUAGE.

SET { all | self | id } RATE n

Set the rate of speech. n is an integer value within the range from -100 to 100, lower values meaning slower speech and higher values meaning faster speech. The default for the Speech Dispatcher implementation of SSIP is determined by the DefaultRate setting in the speechd.conf file. The factory default is 0.

GET RATE

Get the current rate of speech value.

 
GET RATE
251-10
251 OK GET RETURNED
SET { all | self | id } PITCH n

Set the pitch of speech. n is an integer value within the range from -100 to 100, lower values meaning lower pitch and higher values meaning higher pitch. The default for the Speech Dispatcher implementation of SSIP is determined by the DefaultPitch setting in the speechd.conf file. The factory default is 0.

GET PITCH

Get the current pitch value.

 
GET PITCH
251-10
251 OK GET RETURNED
SET { all | self | id } VOLUME n

Set the volume of speech. n is an integer value within the range from -100 to 100. lower values meaning lower volume and higher values meaning higher volume. The default for the Speech Dispatcher implementation of SSIP is determined by the DefaultVolume setting in the speechd.conf file. The factory default is 100.

GET VOLUME

Get the current volume value.

 
GET VOLUME
251-100
251 OK GET RETURNED
SET { all | self | id } PAUSE_CONTEXT n

Set the number of (more or less) sentences that should be repeated after a previously paused text is resumed. If there isn’t enough text before the pause spot, the entire message is repeated. n is a positive integer value specifying the number of sentences to repeat. The default for the Speech Dispatcher implementation of SSIP is determined by the DefaultPauseContext setting in the speechd.conf file. The factory default is 0.

SET { all | self | id } HISTORY { on | off }

Enable (on) or disable (off) storing of received messages into history.

This command is intended for use by message history browsers and usually should not be used by other kinds of clients.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.6 Retrieving Information

The LIST command serves for retrieving information that can be presented to the user for selection of the values to the SET command. The information listed is selected according to the first argument of the LIST command.

LIST OUTPUT_MOUDLES

Lists the available output modules putting each module identification name one on a single line.

Example:

 
LIST OUTPUT_MODULES
250-festival
250-espeak
250 OK MODULE LIST SENT
LIST VOICES

Lists the available symbolic voice names putting each voice name on a single line. These are symbolic names that are mapped to the real voices used in the synthesizer either automatically or via synthesizer or output module configuration.

Example:

 
LIST VOICES
249-MALE1
249-MALE2
249-MALE3
249-FEMALE1
249-FEMALE2
249-FEMALE3
249-CHILD_MALE
249-CHILD_FEMALE
249 OK VOICE LIST SENT
LIST SYNTHESIS_VOICES

Lists the available voices for the current synthesizer in use. These names differ from those obtained by LIST VOICES in that they are names of the real voices used inside the synthesizer.

This feature should only be used to allow the user to choose the voice. All automatic switching of voices (unless user-configurable) should be done using the symbolic voice names which can be configured in the synthesizer.

Each voice name is listed on a separate line together with its language code and dialect identification string separated by spaces. The dialect identification strings do not have well-defined meaning yet. If no dialect is specified by the synthesizer, the value none is used.

Example:

 
LIST SYNTHESIS_VOICES
249-afrikaans af none
249-welsh-test cy none
249-german de none
249-greek_test el none
249-en-rhotic en r
249-lancashire en uk-north
249 OK VOICE LIST SENT

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.7 Message Events Notification and Index Marking


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.7.1 Why Events Notification

Applications can send messages to a Speech Server through the SSIP SPEAK command. However, this command only puts the received message into a queue in Speech Server and returns immediately. The message then will or will not be said at some particular time according to its priority. Through Message Events Notification, the application is able to discover certain kind of events, including when the message started to be played on the speakers, when it terminated playing, when it was paused and resumed, or when it was interrupted/discarded. It is also possible to get notification when a certain place in the given text was reached while playing the synthesized text on the speakers – this capability, however, might or might not be supported by the end synthesizer and so client applications should not rely on it.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.7.2 Types of Events

SSIP recognizes several types of events. Each event is reported together with the unique identification of the message and client it is associated with. This is an overview of available events. For detailed SSIP syntax, please look below.

BEGIN

This event means that the synthesizer just started to speak the message and the user is able to hear the speech on his/her speakers.

Please note that not every message stored for speaking by the SPEAK command will issue this event. It can issue the CANCEL event instead.

END

This event means that the synthesizer just terminated speaking the message (by reaching its end) and the user is no longer able to hear the speech on their speakers.

Again, note that not every message that has already reported the BEGIN event will necessarily get to the END event. It might instead issue the CANCEL or PAUSE events.

CANCEL

The CANCEL event is reported when the message was canceled (either after BEGIN during speaking or even before, when waiting in the queues) and will not be spoken anymore.

PAUSE

The event PAUSE means that the message that was being spoken was paused and no longer produces any sound on the speakers, but was not discarded and the rest of the message might be spoken again after the RESUME command is sent. See section Controlling Speech Output. This will be reported by the RESUME event.

PAUSE is always preceded by the event BEGIN, and can be followed by either the event RESUME or CANCEL.

RESUME

The event RESUME means that a message that was paused while being spoken, just started to continue and again produces sound in the speakers.

RESUME is always preceeded by the event PAUSE, and can be followed by either the event END or CANCEL.

INDEX_MARK

This event means that some previously specified place in the text (so-called index mark) was reached when speaking the synthesized message in the speakers. It is always accompanied by an additional parameter that indicates which place it is – the name of the index mark.

Example (not in SSIP syntax):

This SSML message

 
        <speak>Hello, <mark name="mark1"/> how does it work?</speak>

would issue the following sequence of events if it is not discarded or paused:

 
        BEGIN
        INDEX_MARK "mark1"
        END

or this one if it gets paused after the first index mark and then later resumed.

 
        BEGIN
        INDEX_MARK "mark1"
        PAUSE
        RESUME
        END

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.7.3 Events Notification in SSIP

Event notifications, if requested, are reported asynchronously in SSIP. This means that they are not sent as replies to any particular requests but can arrive anytime. However, notifications can’t arrive in the time between when a SSIP command is sent by the client and its reply is sent back by the server.

Each notification consists of a multi-line SSIP reply as defined in General Rules, and includes at least two parameters: msg_id and client_id. msg_id is the identification number of the message the event is related to, SPEAK while client_id is the identification number of the client who sent the message. Some events may have additional parameters.

INDEX_MARK
 
700-msg_id
700-client_id
700-index_mark
700 END

The event INDEX_MARK carries a special parameter index_mark which is a string of characters identifying the index mark, as specified by the client application (e.g. by the SSML tag <mark/>.

BEGIN
 
701-msg_id
701-client_id
701 BEGIN
END
 
702-msg_id
702-client_id
702 END
CANCEL
 
703-msg_id
703-client_id
703 CANCELED
PAUSE
 
704-msg_id
704-client_id
704 PAUSED
RESUME
 
705-msg_id
705-client_id
705 RESUMED

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.7.4 Switching Notifications On and Off

The client application might or might not want to receive the notifications about events, or it might want to receive some but not others. SSIP allows clients to specify which notifications are to be used.

The following commands for setting notifications on and off affect all the text messages (sent by the SPEAK SSIP command) based on when the appropriate SPEAK command was called. So if for example, you set all notifications on, send a message and then set all notifications off, you will receive all the available notifications for that message even though it might start speaking after the notifications are already turned off.

SET SELF NOTIFICATION ALL { on | off }

Set all available event notifications to either “on” or “off” for for the messages that follow. See section Types of Events.

SET SELF NOTIFICATION BEGIN { on | off }
SET SELF NOTIFICATION END { on | off }

Set the event notifications for BEGIN or END to either “on” or “off” for the messages that follow. See section Types of Events.

SET SELF NOTIFICATION CANCEL { on | off }

Set the event notifications for CANCEL to mode where mode is either “on” or “off” for switching the notifications on or off for the messages that follow. See section Types of Events.

SET SELF NOTIFICATION PAUSE { on | off }
SET SELF NOTIFICATION RESUME { on | off }

Set the event notifications for PAUSE or RESUME to mode where mode is either “on” or “off” for switching the notifications on or off for the messages that follow. See section Types of Events.

SET SELF NOTIFICATION INDEX_MARKS { on | off }

Set the event notifications for INDEX_MARK to either “on” or “off” for switching the notifications on or off for the messages that follow. See section Types of Events.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.8 History Handling


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.8.1 Purpose of Message History

It seems a good feature for the blind and visually impaired to provide the possibility to browse, through some simple client, the history of received and previously said messages.

Some messages are even received by Speech Server without being said, because there will always be more space for information on the screen than speech output can possibly provide.

For this reason, SSIP defines a set of commands that allow client applications to browse through the history of previously received messages saved on the server. The idea is that each message received by the server should be accessible through the history and the user can search for it later by time, keywords or using other methods.

On the other hand, this may cause security issues as several clients may connect to Speech Server and they might originate from different users. For this reason, only those messages that come from the same user should be accessible by default (if not overridden in server configuration).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.8.2 Message History in SSIP

History is handled by the HISTORY command. It can take many forms, described below, that allow browsing, retrieving and repeating stored messages. In each invocation of the HISTORY command there is no difference between processing spoken or not spoken messages, all the received messages are processed.

The implementation of these history commands in the Speech Dispatcher implementation of SSIP is still under way. If you want to use them, please contact us to see the current status.

There is a history cursor pointing to some message in the history. You can move it across history messages and retrieve the message the cursor is pointing to, using the HISTORY CURSOR set of command arguments described below.

HISTORY GET CLIENT_LIST

List known client names, their identifiers and status. Each connection is listed on a separate line in the following format:

 
id name status

where id is a client id that can be used in other history handling requests or in the speech output control commands (see section Controlling Speech Output), name is the client name as set through the SET SELF CLIENT_NAME command, and status is 1 for connected clients and 0 for disconnected clients. ids are unique within a single run of Speech Server.

Sample SSIP reply:

 
240-0 joe:speechd_client:main 0
240-1 joe:speechd_client:status 0
240-2 unknown:unknown:unknown 1
240 OK CLIENTS LIST SENT
HISTORY GET CLIENT_ID

Return id of the client itself.

The id is listed on a separate line in the following format:

 
id

Example:

 
200-123
200 OK CLIENT ID SENT
HISTORY GET CLIENT_MESSAGES { id | all | self } start number

List identifiers of messages sent by the client identified by id. If the special identifier all is used, identifiers of messages sent by all clients are listed; if the special identifier self is used, identifiers of messages sent by this client are listed.

number of messages is listed, starting from the message numbered start. Both number and start must be positive integers. The first message is numbered 1, the second 2, etc. If the given range exceeds the range of available messages, no error is signaled and the given range is restricted to the available range of messages.

Messages are sorted by the criterion used in the last client’s invocation of the HISTORY SORT command. If no HISTORY SET has been invoked yet, the messages are sorted from the oldest to the newest, according to their time of arrival at Speech Server.

Each message id is listed, together with other information, on a separate line, in the following format:

 
id client-id client-name "time" priority "intro"

client-id is a numeric identifier of the client which sent the message, client-name is its name as set by the SET SELF CLIENT_NAME command (see section Parameter Setting). time is the time of arrival of the message, in the fixed length YYYY-MM-DD HH:MM:SS format. priority is the priority of the message, one of the values accepted by the SET SELF PRIORITY command (see section Parameter Setting).

intro is the introductory part of the message of a certain maximum length, see the HISTORY SET SHORT_MESSAGE_LENGTH command. intro does not contain any double quotes nor the line feed character.

All the message identifiers in the history, regardless of clients that issued them, are unique within a single run of Speech Server and remain unchanged.

HISTORY GET LAST

List the id of the last message sent by the client.

The id is listed on a separate line of the following format:

 
id

If the client hasn’t sent any message yet, return an error code.

HISTORY GET MESSAGE id

Return the text of the history message identified by id. If id doesn’t refer to any message, return an error code instead. The text is sent as a multi-line message, with no escaping or special transformation.

An example SSIP response to the command:

 
200-Hello, world!
200-How are you?
200 OK MESSAGE SENT
HISTORY CURSOR GET

Get the id of the message the history cursor is pointing to.

The id is listed on a separate line. Sample SSIP reply to this command:

 
243-42
243 OK CURSOR POSITION RETURNED
HISTORY CURSOR SET { id | all | self } { first | last | pos n }

Set the history cursor to the given position. The meaning of the first argument after SET is the same as in the HISTORY GET CLIENT_MESSAGES command. The argument first asks to set the cursor on the first position and the argument last asks to set the cursor on the last position of the history of the given client. If the argument pos is used, the position is set to n, where n is a positive integer. It is an error if id doesn’t identify any client or if n doesn’t point to any existing position in the history.

As for the order and numbering of the messages in the history, the same rules apply as in HISTORY GET CLIENT_MESSAGES. See above.

HISTORY CURSOR { forward | backward }

Move the cursor one position forward, resp. backward, within the messages of the client specified in the last HISTORY CURSOR SET command. If there is no next, resp. previous, message, don’t move the cursor and return an error code.

HISTORY SAY id

Speak the message from history identified by id. If id doesn’t refer to any message, return an error code instead.

The message is spoken as it would be sent by its originating command (SPEAK or SOUND_ICON), but the current settings (priority, etc.) apply.

HISTORY SORT { asc | desc } { time | user | client_name | priority | message_type }

Sort the messages in history according to the given criteria. If the second command argument is asc, sort in ascending order, if it is desc, sort in descending order. The third command argument specifies the message property to order by:

time

Time of arrival of the message.

user

User name.

client_name

Client name, excluding user name.

priority

Priority.

message_type

Type of the message (text, sound icon, character, key), in the order specified in the Speech Server configuration or by the HISTORY SET MESSAGE_TYPE_ORDERING command.

The sorting is stable — order of all the messages that are equal in the given ordering remains the same.

The sorting is specific to the given client connection, other connections are unaffected by invocation of this command.

HISTORY SET SHORT_MESSAGE_LENGTH length

Set the maximum length of short versions of history messages to length characters. length must be a non-negative integer.

Short (truncated) versions of history messages are used e.g. in the answer to the HISTORY GET CLIENT_MESSAGES format.

HISTORY SET MESSAGE_TYPE_ORDERING "ordering"

Set the ordering of the message types, from the minimum to the maximum. ordering is a sequence of the following symbols, separated by spaces: text, sound_icon, char, key. The symbols are case insensitive and each of them must be present in ordering exactly once.

The specified ordering can be used by the HISTORY SORT command.

HISTORY SEARCH { id | all | self } "condition"

Return the list of history messages satisfying condition. The command allows searching messages by given words. The output format is the same as the HISTORY GET CLIENT_MESSAGES command.

The meaning of the first argument after SEARCH is the same as the HISTORY GET CLIENT_MESSAGES command.

condition is constructed according to the following grammar rules:

condition :: word

Matches messages containing word.

condition :: ( ! condition )

Negation of the given condition.

condition :: ( condition [ & condition ... ] )

Logical AND — all the conditions must be satisfied.

condition :: ( condition [ | condition ... ] )

Logical OR — at least one of the conditions must be satisfied.

Spaces within the condition are insignificant and ignored.

The following rules apply to words:

Returned messages are sorted by the following rules:

  1. The primary sorting is defined by the number of the satisfied subconditions on the top level of the given condition, from the highest (best matching messages first) to the lowest. This takes effect only if the given condition is the OR rule.
  2. The criterion used in the last client’s invocation of the HISTORY SORT command. If no HISTORY SORT has been invoked yet, the messages are sorted from the oldest to the newest, according to their time of arrival.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.9 Other Commands

QUIT

Close the connection.

HELP

Print a short list of all SSIP commands, as a multi-line message.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Return Codes

Each line of the SSIP output starts with a three-digit numeric code of the form NXX where N determines the result group and xx denotes the finer classification of the result.

SSIP defines the following result groups:

1xx

Informative response — general information about the protocol, help messages.

2xx

Operation was completely successful.

3xx

Server error, problem on the server side.

4xx

Client error, invalid arguments or parameters received.

5xx

Client error, invalid command syntax, unparseable input.

7xx

Event notifications. See See section Events Notification in SSIP.

Result groups 1xx and 2xx correspond to successful actions, other groups to unsuccessful actions. Only the groups defined here may be returned in an SSIP connection.

Currently, for return codes in the range 100599, only the meaning of the first digit of the result code is defined. The last two digits are insignificant and can be of any value. Clients shouldn’t rely on the unspecified digits in any way.

However, the return codes in the range 700800, reserved for events notification, are well defined in the appropriate section of SSIP documentation and client applications can rely on them.

In the future, these return codes should be fixed so that clients can rely on them.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.1 Example of an SSIP Dialog

The following example illustrates a sample dialog with SSIP. The client connects to a Speech Server, sets all the common parameters, sends two text messages, displays the list of clients, instructs Speech Server to repeat the second message, and closes the connection. Lines starting with a numeric code are response lines of the server, other lines are the lines sent by the client.

 
SET SELF CLIENT_NAME joe:vi:default
208 OK CLIENT NAME SET
SET SELF PRIORITY MESSAGE
202 OK PRIORITY SET
SPEAK
230 OK RECEIVING DATA
Hello, I'm am SSIP communication example!
How are you?
.
225 OK MESSAGE QUEUED
SPEAK
230 OK RECEIVING DATA
Still there?
.
225 OK MESSAGE QUEUED
HISTORY GET CLIENT_LIST
240-1 jim:Emacs:default 0
240-2 jim:Emacs:default 0
240-3 unknown:unknown:unknown 0
240-4 jim:Emacs:default 1
240-5 joe:vi:default 1
240 OK CLIENTS LIST SENT
HISTORY GET LAST
242-39 joe:vi:default
242 OK LAST MSG SENT
HISTORY SAY 39
225 OK MESSAGE QUEUED
QUIT
231 HAPPY HACKING

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

A. Appendices


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

A.1 Key Names

This appendix defines all the recognized symbolic key names. The names are case sensitive.

Special Key Names

space
underscore
double-quote

Auxiliary Keys

alt
control
hyper
meta
shift
super

Control Character Keys

backspace
break
delete
down
end
enter
escape
f1
f2
f3
f4
f5
f6
f7
f8
f9
f10
f11
f12
f13
f14
f15
f16
f17
f18
f19
f20
f21
f22
f23
f24
home
insert
kp-*
kp-+
kp--
kp-.
kp-/
kp-0
kp-1
kp-2
kp-3
kp-4
kp-5
kp-6
kp-7
kp-8
kp-9
kp-enter
left
menu
next
num-lock
pause
print
prior
return
right
scroll-lock
space
tab
up
window

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

A.2 Standard Sound Icons

There are none currently.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

A.3 Standard Voices

The following voice names are always present in the output of the LIST VOICES command (see section Retrieving Information):

MALE1
MALE2
MALE3
FEMALE1
FEMALE2
FEMALE3
CHILD_MALE
CHILD_FEMALE

The actual presence of any of these voices is not guaranteed. But the command SET VOICE (see section Parameter Setting) must accept any of them. If the given voice is not available, it is mapped to another voice by the output module.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

B. GNU Free Documentation License

Version 1.2, November 2002

 
Copyright © 2000,2001,2002 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

    A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

    The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

    A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

    The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

    A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.

    The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
    15. Preserve any Warranty Disclaimers.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

    You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

    If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

B.1 ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

 
  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.2
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:

 
    with the Invariant Sections being list their titles, with
    the Front-Cover Texts being list, and with the Back-Cover Texts
    being list.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

C. GNU General Public License

Version 2, June 1991

 
Copyright © 1989, 1991 Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software—to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation’s software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author’s protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors’ reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone’s free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

  1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The “Program,” below, refers to any such program or work, and a “work based on the Program” means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term “modification.”) Each licensee is addressed as “you.”

    Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

  2. You may copy and distribute verbatim copies of the Program’s source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

    You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

  3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
    1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
    2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
    3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

    Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

    In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

  4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
    1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

    The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

    If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

  5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
  6. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
  7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients’ exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
  8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

    If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

    It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

    This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

  9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
  10. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and “any later version,” you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

  11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
  1. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  2. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.

 
one line to give the program's name and an idea of what it does.
Copyright (C) 19yy  name of author

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.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

 
Gnomovision version 69, Copyright (C) 20yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c' 
for details.

The hypothetical commands ‘show w’ and ‘show c’ should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than ‘show w’ and ‘show c’; they could even be mouse-clicks or menu items—whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a “copyright disclaimer” for the program, if necessary. Here is a sample; alter the names:

 
Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written 
by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.


[Top] [Contents] [Index] [ ? ]

Table of Contents


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated by Milan Zamazal on September 4, 2015 using texi2html 1.82.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ < ] Back Previous section in reading order 1.2.2
[ > ] Forward Next section in reading order 1.2.4
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ Up ] Up Up section 1.2
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated by Milan Zamazal on September 4, 2015 using texi2html 1.82.