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: 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 Session Header Keywords

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 extensions 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 handle 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. protocol The value is a decimal number identifying the major TTSCP protocol version. The current protocol version number is release Server release. The formatting and interpretation is implementation dependent. server Server name. Different versions of the same implementation should typically use an identical value for this keyword. Data Formats

The data is passed between modules in one of the following formats: plain text phonetic structure of the text (TSR) Speech Synthesizer Input Format (SSIF) sequence of segments waveform file Plain Text

This is what the "text" in "text-to-speech" stands for. Text Structure Representation

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 . Conversion to plain text dismisses prosody. Conversion to plain text dismisses segment layer if any. Speech Synthesizer Input Format

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 Sequence of Segments

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. Waveform

The traditional MS Windows RIFF to label phone and/or segment boundaries within the waveform. TTSCP Commands

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 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 module has split the input text into more independent parts, multiple outputs and multiple 122 replies may appear; if e.g. the 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 intr

Interrupt a single data

Turn this control connection into a data connection. The parameter is the handle of an existing control connection to attach this connection to. The sole consequence of this attachment relation is a disconnect of the data connection when the specified control connection is disconnected. (It is therefore common for a client to open two connections, to get their connection handles, to turn one into a data connection and to attach it to the other connection. That way the client obtains a control and a data connection which will gracefully shutdown even after the client abruptly disconnects.) The server sends a completion reply for this command (response code 200 if successful). After the first newline character following the 200 response code is received, no more control information will arrive. Likewise, the client may not send any TTSCP commands after the newline-terminated data command. If the delh

Terminate a specified data connection. The parameter is the data connection handle to be terminated, as returned by a former done

Issued as the last command in a session. The client may exit just after sending this command. The server should reply with error code 600. down

Stop the server. Quit pending sessions. May disappear in the future. help

Request for TTSCP syntax help. The server response is undefined except for the proper error code termination (class 2 or 4). Suggested behavior is to reply with "441 help yourself" or a brief list of commands with explanation. If a parameter is given, the server may supply more specific information, such as verbose description of a single command. The usual completion reply rules apply. Specifically, care must be taken lest the help text contain a line beginning with a digit. pass

Attempts to validate an account, as given by a previous "user" command. If no valid "user" command was ever received, the internal server password may be used. This may enable some internal commands such as "down" or "setg". (Epos stores this internal password in /var/run/epos.pwd while it is listening on the standard TTSCP port.) The password is a string of alphanumeric characters, dashes and underlines, no more than 250 bytes long. setg

Globally set a server configuration parameter. The parameter is a whitespace-separated "option value" pair. The server may ignore this command altogether with an error code 442. The server will reply with an error code 412 if the value assigned is illegal, or with 451 if the server is configured not to allow to change this parameter (may depend on the current authentication status). The settings, if successful, will apply to all future connections. They will typically not affect existing connections, unless specified otherwise. For this reason, this command should be available only to authenticated and trusted users. If the option name is "language", the command will attempt to switch the default language. The same goes for "voice". The standardization status of this command is still unclear. It is definitely reasonable to use compatible option names between server implementations where applicable, but the set of useful configuration parameters seems to be impossible to specify in advance. Any comment on this issue is welcome. setl

Set a server configuration parameter. The parameter is a whitespace-separated "option value" pair. The server may ignore this command altogether with an error code 442. In any case, this setting should never alter the execution environment of existing and/or future sessions. (In Epos, setting a static option using show

Show a configuration parameter value. The parameter is an option name. The server may reply with the value of the option requested, preceded by a single space character, or it may ignore this command with error code 442. strm

Prepare a data flow stream. The parameter is a colon-separated sequence of data processing modules; commands such as . The stream is not automatically active. It processes data only when requested by the command. The stream lasts until the next strm command or termination of the TTSCP connection, then it is deleted. user

The TTSCP Modules Input and Output Modules

The input and output modules follow the same syntax conventions. If the module name begins with a option. It must be impossible to escape from such name space by inserting parent directory references in a file name or otherwise. A TTSCP implementation can decide to reject some or all file input and output modules with a 454 reply. If the module name begins with a Processing Modules

At the moment there are only few modules implemented that do a real processing. All of them have fixed names and types. name | input format | output format | notes@ chunk | plain text | plain text | splits text @ join | plain text | plain text | joins texts @ raw | plain text | TSR | parses text @ stml | STML text | TSR | parses STML @ rules | TSR | TSR | apply rules @ print | TSR | plain text | @ dump | TSR | SSIF | extract SSIF @ diphs | TSR | segments | extract segments @ syn | SSIF | waveform | speech synthesis @ synth | segments | waveform | speech synthesis @

Available processing modules

chunk

The text is split into parts convenient for latter processing. These parts usually correspond at least to whole utterances; it is correct not to split the text at all, but care must be taken not to cause a split which significantly alters the final rendering of the text. join

It is customary to use the raw

The input text is converted in a language dependent way to the TSR, assuming it is a plain text without any specific TTS escape sequences or other special formatting conventions. Except for tokenization and whitespace reduction the conversion should not try to process the text, especially not in a language dependent way; this goal doesn't seem to be always feasible. rules

The voice dependent TTS or other rules are applied to a TSR. print

The TSR is converted to a plain text representation, suitable as a user-readable output. The conversion should be as straightforward as possible and should not emit any special formatting character sequences. Ideally, the successive application of the dump

... diphs

This module extracts the segment layer from the input TSR into the linear segment stream format; the rest of TSR is discarded. There may be an implementation-dependent limit on the size of the segment stream produced. If more segments should be produced, the module may emit more subtasks; see the command for discussion concerning subtask reporting. t synth

The input segment stream is synthesized in a voice dependent way. Explicit Data Type Specifiers

Sometimes an ambiguity concerning the type of data passed at a certain point within the stream may occur. This is currently the case with streams consisting of input and output modules only (such as a stream to play out an audio icon from a waveform file to a sound card device); in the future, ambiguously typed versatile processing modules may be introduced, too. Sometimes the data type is semantically irrelevant (for example, a socket-to-socket forwarding stream), sometimes the default data type, that is, a plain text, is a reasonable choice. There are however instances where the type matters, like copying a waveform file to a sound card device: the waveform header must be stripped off and the appropriate . name | data format @ t | plain text @ s | STML text @ i | the server-internal text structure representation @ p | SSIF @ d | segments @ w | waveform @

Explicit data type specifiers

The data formats are described in . Response Codes

Any server Response Classes

Within TTSCP, nine response classes have been defined. Out of these, one is used for in-progress communication, four indicate the results of commands, and the remaining four are reserved for future extensions. code | error type | suggested action @ 0xx | reserved | (server queries client?) @ 1xx | still OK | informative only @ 2xx | OK, command completed | transmit another command @ 3xx | reserved | notify user / ignore @ 4xx | command failed | transmit another command @ 5xx | reserved | notify user @ 6xx | connection terminated | notify user if unexpected @ 7xx | reserved | notify user @ 8xx | server crash or shutdown | notify user @

TTSCP response classes

The client is expected to send another command whenever it receives a 2xx or a 4xx response, not to send otherwise. The client should treat the connection as terminated, whenever it receives any response with code 5xx or higher. It may also quit at any time just after sending a "done" command to the server; the server will however confirm that command with a reply of 600 before disconnecting. Replies of 8xx except 80x are reserved for cases of severe server misconfiguration, or detected programming bugs. Their meanings are very implementation dependent (implementations are encouraged not to issue them except in emergency). If such a reply is ever received, the server has abnormally terminated. The messages accompanying 3xx and higher response codes are likely to be interesting to the user if there is one. Any message without an error code is a data flow primarily meant for the user if any; a sequence of these may occur only after some 1xx response, except for debugging messages if on. At the moment, some error codes contain letters. Later, all of them will consist of digits only and will be space-terminated. Response Subclasses

The subclass depends on the response class. The most interesting classes are 3xx and 4xx, i.e. errors, where the subclass indicates both the nature of the problem, and the suggested way of dealing with it (especially in the case of 4xx responses). The same meaning is attached to these subclasses also in case of 6xx and 8xx responses. The middle digit of 1xx and 2xx responses has still no meaning attached (there are only a few such responses). code | error type | suggested action@ 0 | none | relax; assume user-initiated interruption@ 1 | syntax | notify user@ 2 | busy or timing | wait and retry@ 3 | bad data | notify user@ 4 | not found | notify user@ 5 | access denied | notify user@ 6 | server error | have user notify server author@ 7 | network error | wait and retry@

TTSCP error subclasses

Currently Defined Messages

111 | daemon talks@ 112 | apply task started@ 122 | apply task total bytes count follows@ 123 | apply task chunk bytes count follows@ 141 | option value follows@ 142 | data connection handle follows@ 200 | daemon is happy and ready@ 211 | access granted@ 212 | anonymous access granted@

TTSCP success codes as issued by Epos

401 | intr command received@ 411 | command not recognized@ 412 | option passed illegal value@ 413 | command too long, ignored@ 414 | parameter should be a positive integer@ 415 | no or bad stream@ 416 | no parameter allowed@ 417 | parameter missing@ 418 | bad format or encoding@ 421 | output voice busy@ 422 | out of memory@ 423 | nothing to interrupt@ 431 | unknown character in text@ 432 | received bad segments@ 435 | received bad waveform (unused)@ 436 | data connection disconnected@ 437 | permanent read error@ 438 | end of file@ 439 | hw cannot handle this waveform@ 441 | help not available@ 442 | no such option@ 443 | no such language or voice@ 444 | invalid connection handle@ 445 | could not open file@ 446 | out of range (never issued)@ 447 | invalid option value@ 448 | cannot send woven pointery@ 451 | not authorized to do this@ 452 | no such user or bad password@ 453 | not allowed to use localsound@ 454 | not allowed to use filesystem input/output modules@ 456 | input too long@ 461 | input triggered server bug@ 462 | unimplemented feature@ 463 | input triggered configuration bug@ 464 | input triggered OS incompatibility@ 465 | i/o problem : error on close()@ 466 | command stuck@ 467 | fatal signal@ 471 | tcpsyn received invalid waveform@ 472 | unresolved remote tcpsyn server@ 473 | unreachable remote tcpsyn server@ 474 | remote tcpsyn server uses an unknown protocol@ 475 | remote tcpsyn server returned error@ 476 | remote tcpsyn server timed out@

TTSCP error codes as issued by Epos

The 8xx class of responses (fatal errors) is still very unsettled and many of the codes listed there will later be removed or merged together. Applications should not try to decode them except possibly for the middle digit. The same goes for all x6x subclasses of errors (internal errors). 600 | session ended normally@ 601 | server reinitializing as requested@ 800 | server shutting down as requested by client@ 801 | error explicitly reported in config files@ 811 | rules or dictionary file syntax@ 812 | generic configuration file syntax@ 813 | impossibilia referenced in config files@ 814 | bad command line@ 841 | cannot open necessary configuration file@ 842 | no voices configured@ 843 | up-to-date configuration files not found@ 844 | no unicode or SAMPA maps found@ 861 | internal error: impossible branch of execution@ 862 | internal error: invariance violation@ 863 | internal error: buffer overflow@ 864 | insufficient capacity@ 865 | server crashed, reason unspecified@ 869 | double fault@ 871 | network unreachable@ 872 | server already running@ 881 | too many syntax errors in rule files@ 882 | infinite include cycle@

TTSCP session termination codes as issued by Epos