TTSCP is a client-server connection-oriented, both human- and machine-readable communication protocol, remotely similar to the File Transfer Protocol in spirit. TTSCP is offered as a standard interface for controlling generic speech processing applications, not only Text-To-Speech ones. It is primarily designed to run atop TCP, but any reliable connection-oriented underlying protocol should theoretically work as well.
The server awaits new connections on a single TCP port.
There are two types of connections: control connections
used to issue commands by the client and to return status
information, such as completion messages by the server,
and data connections used to transfer the actual data.
Immediately after the underlying connection is opened,
the server transmits a session header (see below)
and treats the connection as a control connection, until
the data command is issued by the client, causing
it to become a data connection.
Every TTSCP connection (both a control one and a data one) obtains a connection handle from the server inside the session header. This handle is a string of alphanumeric characters which uniquely identifies the connection and which also serves as an access token for it. Other connections can use such a handle to interrupt a control connection's task in progress, to disconnect any connection, to process data received from a data connection etc.
A TTSCP session is a sequence
of commands, their results and referenced data lasting
from setting up the control connection until its disconnection
or the data command.
Any party may quit the session at any time, but must advise
the other one either by the done command (the client)
or by a 600 response code or higher (the server).
If a done command is sent before a preceding command
has completed, the server will proceed with the
preceding commands. If a 600 or higher error code
is received as a response to a command and subsequent commands
have already been sent by the client, they will not be executed.
A data connection may be silently disconnected by the client
at any time. To allow reliable disconnection detection by the
server, every data connection is attached to an already
existing control connection (as specified with the data
command) and it will be automatically disconnected when
the control connection is disconnected. This attachment relation
doesn't prevent other control connections from referencing this
data connection using its handle, it only limits its lifetime.
The session header (as sent before a TTSCP session starts)
is a sequence of lines. The first line
shall exactly match the string TTSCP spoken here; the clients
are strongly encouraged to use this string to identify the protocol.
Each of the following lines contains
a TTSCP header keyword terminated by a colon and a single space
and the value associated with the keyword. The client may choose
not to use these values at all, or to scan only for some header
keywords. The last line in the header shall contain the handle
keyword.
A typical TTSCP session looks like this, with client commands unindented and server responses indented.
TTSCP spoken here
protocol: 0
extensions:
server: Epos
release: 2.4.6
handle: O29-m2UZ
user user@host.domain.net
452 user not found
setl some_option on
200 OK
strm $zC-4EEl0:raw:rules:diphs:synth:/dev/dsp
200 OK
appl 34
112 started
122 total bytes
3622
123 written bytes
3622
200 OK
done
600 goodbye
The "user" and "done" commands may become mandatory, the rest may be freely used between them. For the interaction with a human, the "help" command is available.
It is legal to use "anonymous" instead of the address in the user command: "user anonymous". It is also legal to switch users with additional user commands. This may cause context switches.
It is advised to check the greeting string received to begin in "TTSCP ". If it doesn't, the client or possibly the server may be obsolete or an unrelated protocol may be used at the port.
In this document, a "newline" produced by the server or the client should be
a CR LF character sequence. It is allowed for both parties to
accept a LF character without a preceding CR character as a valid
line separator, but it is never legal to rely on this practice.
The set of session header keywords and their sequence may vary between
TTSCP implementations. Some lower case keywords are defined by this document;
in addition, any implementation may supply its own keywords provided
their first two characters are lower case x and dash, respectively,
or they consist solely of upper case letters. Both standard and
implementation specific keywords are limited to upper and lower case
letters (case sensitive), digits, dashes and underlines;
however, the values associated with some keywords may contain any printable
ISO 8859 characters. There are three mandatory keywords
(protocol, extensions and handle, in order of appearance
in the session header).
The value is a whitespace separated list of semi-standard and non-standard
extensions supported by this TTSCP server. Only extensions defined by
this document or a future version of this document should be advertised;
custom or experimental extensions may be advertised provided their
first two characters are lower case x and dash, respectively.
At present, there are no extensions defined, so the list should be empty,
but this keyword is nevertheless mandatory.
The value is a connection handle for this control connection. The handle stays valid when the connection is turned into a data connection. Only lower and upper case letters, digits, dashes and underlines may occur in the handle. This keyword is mandatory and must appear last in the session header.
The value is a decimal number identifying the major TTSCP protocol version.
The current protocol version number is 0 (previous versions had no
session header). It is likely that protocol versions unknown to the
client will be fundamentally incompatible. It is mandatory to begin the
session header with this keyword. It is recommended to check it on the
client side.
Server release. The formatting and interpretation is implementation dependent.
Server name. Different versions of the same implementation should typically use an identical value for this keyword.
The data is passed between modules in one of the following formats:
This is what the "text" in "text-to-speech" stands for.
Internal text representation, suitable for arbitrary processing, but unsuitable for input or output. Before output, it must be converted to another format first. For a description, see the text structure representation overview.
Conversion to plain text dismisses prosody.
Conversion to plain text dismisses segment layer if any.
This format has been introduced by the MBROLA synthesizer development team. Together with the "sequence of segments" it is one of the two possible input formats to a speech synthesizer in Epos. With the MBROLA synthesizer you have to use SSIF.
SSIF is line oriented, each line corresponding to a single phone; the line contains several whitespace separated components.
The first component is the SAMPA notation of the phone; the second component is its duration in milliseconds.
Subsequent components are prosody points. Each prosody point
is enclosed in parentheses and consists of two or three
integers separated by commas. The first value locates
the prosody point within the phone per cent (e.g. the value
of 99 corresponds to just before the end of the phone);
the second value indicates the desired pitch at that prosody
point (the value of 100 indicates the default pitch);
the third value, which is not currently supported by MBROLA,
and which is optional, indicates the intensity at that point.
It is the responsibility of the synthesizer to do piecewise
linear interpolation between prosody points.
Every segment is a quadruple of segment number, assigned frequency (pitch), intensity (volume) and time factor (speed). The initial segment is dummy (to be skipped); its segment number contains the total number of segments in this sequence. The corresponding prosodic parameters are undefined. They should preferably be zero.
The integer values should be encoded as 32-bit little endian integers.
This format is currently being replaced by SSIF, although it will remain to be supported for some additional period time.
The traditional MS Windows RIFF .wav file header and data.
Two liberties may be taken when waveform data in this format is sent
via a data connection.
First, the total length of the RIFF form field
may contain a negative number. In this case, the length
of the form shall be determined from the data length as indicated
in the corresponding TTSCP control connection. Also, if this
field contains a positive number, which conflicts with the data
length indicated in the corresponding TTSCP control connection,
the recipient may choose any one of them or return a 435 error.
Second, if only fmt and data chunks are present in the
RIFF form being sent, and the length of the data chunk is negative,
the length of the data chunk shall be determined from the
total length of the RIFF form. (Epos never actually takes advantage
of this rule.)
This format allows storing labels (i.e. pointers to specific positions within the waveform); Epos does use this feature if enabled e.g. using the label_phones option to label phone and/or segment boundaries within the waveform.
TTSCP commands are newline-terminated strings. Each of them begins with a command identifier, some of them may continue with optional or mandatory parameters, depending on the particular command. Each command generates one or more "replies", the last reply indicating completion and sometimes also some command-specific information.
appl Apply the current data processing stream (see the strm command to some data. The parameter is a decimal number specifying the number of bytes to be processed.
Before the completion reply, zero or more 122 replies are received
by the client, every one followed by a decimal number on a line
by itself, preceded with a single space. This is the number of
bytes written by the output module per task. Usually, if the appl
command generates a single successful task only, there shall be exactly
one such reply, but if e.g. the
chunk module has split the
input text into more independent parts, multiple outputs and
multiple 122 replies may appear; if e.g. the
join module has
been employed, there may be no 122 reply at all if the text being
processed is considered unterminated.
Such an intermediate reply should be sent as soon as the number
of bytes to be sent is known to the TTSCP server to avoid certain
deadlock scenarios caused by an insufficient buffer capacity between
the server and the client. The number of bytes actually sent may
be even smaller in case of a user break or another unexpected situation;
it shall never be larger and it shall be exactly the number of bytes
sent by the server upon a successful completion reply.
Before the completion reply, one or more 123 replies for every 122 reply are received by the client. Every 123 reply is followed by a decimal number on a line by itself, preceded with a single space. This is the number of bytes actually successfully written by the output module. This intermediate reply should be sent as soon as the data is sent. When the client eventually receives a successful completion reply, the sum of byte counts received with 123 replies shall match the number of bytes sent by the server.
For every 122 reply, there shall be a corresponding sequence of 123 replies
such that no unrelated 122 or 123 replies intervene. The sum of byte counts
received with these 123 replies shall match the byte count received with
the 122 reply. In other words, the replies relating to different subtasks
must preserve the time ordering. If an error condition prematurely terminates
the appl command processing, this behavior is not required for
the last subtask whose processing has begun, independent of whether
its 122 reply has been received by the client.
The relative ordering of 122 and 123 replies for the same subtask is not specified by the TTSCP.
The completion response code is received when all the modules have finished processing and data has been output by the output module. Some of the data may however still be being processed by hardware, e.g. a sound card, or may be delayed by the network.
Using appl before the first strmstatic.
This option must be on to provide any debugging information (except for
daemon activity logging controlled by
the daemon_log option and syslog logging.
The minimum severity level of debugging messages which should be printed.