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
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.
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.
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.
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 Parameter Setting Commands). 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 Commands.
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 (Speech Output Control Commands and Parameter Setting Commands) 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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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:
Completed 100%
message to know the work has completed). Speech
Server waits until there are no more messages of this priority waiting
in queues and if the last of them wasn’t spoken yet, it speaks it with
the priority message
.
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.
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.
This command sets message priority to p. p must be one of
the values important
, text
, message
,
notification
, progress
. See Priority Categories.
Only self
is allowed as the ‘target’ argument.
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:
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 Speech Output Control Commands 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.
SPEAK
SOUND_ICON
CHAR
KEY
SET SELF RATE
SET SELF PITCH
SET SELF VOLUME
SET SELF VOICE
SET SELF LANGUAGE
SET SELF PUNCTUATION
SET SELF CAP_LET_RECOGN
QUIT
BLOCK END
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
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 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-US
(American 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 | most | some | none }
Set punctuation mode to the given value. all
means speak all
punctuation characters, none
means speak no punctuation characters,
some
and most
mean speak only intermediate sets of punctuation
characters defined in the synthesizer’s configuration or symbols files.
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 Information Retrieval Commands).
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 Information Retrieval Commands).
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 Information Retrieval Commands).
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.
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 tabs. 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
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.
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 Speech Output Control Commands. 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
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
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 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 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 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 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 Types of Events.
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. Because of flatpak and other technologies checking the user id isn’t enough. So now, only those messages that come from the same client connection are accessible.
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 Speech Output Control Commands), 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 Parameter Setting Commands).
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 Parameter Setting Commands).
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:
?
, substituting
any single alphanumeric character, and *
, substituting any
number (incl. zero) of alphanumeric characters.
Returned messages are sorted by the following rules:
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.
QUIT
Close the connection.
HELP
Print a short list of all SSIP commands, as a multi-line message.
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:
Informative response — general information about the protocol, help messages.
Operation was completely successful.
Server error, problem on the server side.
Client error, invalid arguments or parameters received.
Client error, invalid command syntax, unparseable input.
Event notifications. See See Events Notifications 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 100
–599
, 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 700
–800
,
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.
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
This appendix defines all the recognized symbolic key names. The names are case sensitive.
space
underscore
double-quote
alt
control
hyper
meta
shift
super
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
There are none currently.
The following voice names are always present in the output of the
LIST VOICES
command (see Information Retrieval Commands):
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 Parameter Setting Commands) must
accept any of them. If the given voice is not available, it is mapped
to another voice by the output module.
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.
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.
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.
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.
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.
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:
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.
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.”
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.
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.
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.
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.
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.
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.
Copyright © 1989, 1991 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.
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 Lesser 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.
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.
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.
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.
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.
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.
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.
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 a brief idea of what it does. Copyright (C) yyyy 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, see <https://www.gnu.org/licenses/>.
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) year 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 Lesser General Public License instead of this License.