Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

speech-dispatcher-client

Outdated egg!
speech-dispatcher-client
1. Description
2. Author
3. Repository
4. Requirements
5. API
6. License
7. Version history
  1. Version 0.0.1

Description

Implementation of Speech Dispatcher's SSIP protocol (version 0.2).

Author

O.S. Systems, maintained by Mario Domenech Goulart

Repository

https://github.com/OSSystems/chicken-speech-dispatcher-client

API

Parameters

[parameter] (enable-debug? [default=#f])
[parameter] (debug-to [default=(current-error-port)])

Records

`connection`

The connection record represents the connection to the Speech Dispatcher server. It is returned by the connect procedure.

[procedure] (connection? OBJ)

Return #t if the given OBJ is a connection record.

[procedure] (connection-path CONNECTION)

Return the connection path. It the connection is via Unix sockets, return the path to the socket file. If the connection is via TCP, the connection path is #f.

[procedure] (connection-type CONNECTION)

Return the connection type: unix if Unix socket; tcp if TCP.

[procedure] (connection-host CONNECTION)

Return the connection host (for TCP connections). The connection is Unix socket, return #f.

[procedure] (connection-port CONNECTION)

Return the connection network port (for TCP connections). The connection is Unix socket, return #f.

[procedure] (connection-inport CONNECTION)

Return the Scheme input port for the connection.

[procedure] (connection-outport CONNECTION)

Return the Scheme output port for the connection.

`response`

Protocol procedures return response records.

[procedure] (response? OBJ)

Return #t if the given OBJ is a response record.

[procedure] (response-code RESPONSE)

Return the response code of the given response record.

[procedure] (response-data RESPONSE)

Return the response data of the given response record.

[procedure] (response-status RESPONSE)

Return the response status text of the given response record.

Procedures

[procedure] (connect #!key path host port)

Connect to the Speech Dispatcher server. If path is provided, connects to the server using Unix sockets. If host and port are provided, connect to the server via TCP.

Returns a connection record.

Protocol procedures

The procedures in this section correspond to the Speech Synthesis Interface Protocol commands.

All of them return a response object.

Whenever you see thing in the procedures parameter list, you can use all, self or a positive integer as arguments.

[procedure] (speak conn text)

Speak the given text.

[procedure] (list-voices conn)

List the voices available on the server.

[procedure] (list-output-modules conn)

Lists the available output modules on the server.

[procedure] (list-synthesis-voices conn)

Lists the available voices for the current synthesizer in use on the server.

[procedure] (key conn key-name)

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

[procedure] (stop conn thing)

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

[procedure] (cancel conn thing)

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.

[procedure] (pause conn thing)

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.

[procedure] (resume conn thing)

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.

[procedure] (set-client-name conn client-name)

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 conn "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 connection 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.

[procedure] (set-output-module conn thing 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.

[procedure] (set-language conn thing language)

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-language conn 'self '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 server's speechd.conf file. The factory default is en (English).

[procedure] (set-ssml-mode conn 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>.

[procedure] (set-punctuation conn thing mode)

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

[procedure] (set-spelling conn thing status)

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 server's speechd.conf file. The factory default is off.

[procedure] (set-capital-letters-recognition conn thing mode)

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 server's speechd.conf file. The factory default is none.

[procedure] (set-voice conn thing name)

Set the voice identified by name. name must be one of the voice identifiers returned by the command list-voices.

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

[procedure] (set-synthesis-voice conn thing 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-voice run for the appropriate synthesizer.

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.

[procedure] (set-rate conn thing 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 server's speechd.conf file. The factory default is 0.

[procedure] (set-pitch conn thing 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 server's speechd.conf file. The factory default is 0.

[procedure] (set-volume conn thing 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 server's speechd.conf file. The factory default is 100.

[procedure] (set-pause-context conn thing 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 server's speechd.conf file. The factory default is 0.

[procedure] (set-history conn thing status)

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.

[procedure] (set-self-notification-all conn status)

Set all available event notifications to either on or off for the messages that follow.

[procedure] (set-self-notification-begin conn status)
[procedure] (set-self-notification-end conn status)

Set the event notifications for BEGIN or END to either on or off for the messages that follow

[procedure] (set-self-notification-cancel conn status)

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.

[procedure] (set-self-notification-pause conn status)
[procedure] (set-self-notification-resume conn status)

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.

[procedure] (set-self-notification-index-marks conn status)

Set the event notifications for INDEX_MARK to either on or off for switching the notifications on or off for the messages that follow.

[procedure] (set-debug conn status)

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 for a place to generate the logs, to repeat the situation that he 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.

[procedure] (set-priority conn priority)

This command sets message priority to priority. priority must be one of the values important, text, message, notification, progress.

[procedure] (block-begin conn)

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.

The allowed commands inside a block are:

SPEAK
SOUND_ICON
CHAR
KEY
SET SELF RATE
SET SELF PITCH
SET SELF VOLUME
SET SELF VOICE
SET SELF LANGUAGE
QUIT
BLOCK END

[procedure] (block-end conn)

Closes a block of messages, see block-begin.

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

[procedure] (history-get-client-list conn)

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

 id name status

where id is a client id that can be used in other history handling requests or in the speech output control commands (see section Controlling Speech Output), name is the client name as set through the set-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.

[procedure] (history-get-client-id conn)

Return id of the client itself.

[procedure] (history-get-client-messages conn thing 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-client-name command (see section Parameter Setting). time is the time of arrival of the message, in the fixed length YYYY-MM-DD HH:MM:SS format. priority is the priority of the message, one of the values accepted by the set-priority command.

intro is the introductory part of the message of a certain maximum length, see the history-set-shor-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.

[procedure] (history-get-last conn)

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

[procedure] (history-get-message conn 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.

[procedure] (history-get-cursor conn)

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

[procedure] (history-set-cursor conn thing pos #!optional 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.

[procedure] (history-cursor conn direction)

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.

[procedure] (history-say conn 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.

[procedure] (history-sort conn order criteria)

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.

[procedure] (history-set-short-message-length conn 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.

[procedure] (history-set-message-type-ordering conn ordering)

Set the ordering of the message types, from the minimum to the maximum. ordering is a list of the following symbols: 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.

[procedure] (history-search conn thing 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 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:

word is a sequence of adjacent alphanumeric characters.
If word contains any upper-case letter, the search for the word is case sensitive, otherwise it's case insensitive.
word must match whole word, not only its substring.
word can contain the wild card characters ?, substituting any single alphanumeric character, and *, substituting any number (incl. zero) of alphanumeric characters.

Returned messages are sorted by the following rules:

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

[procedure] (quit conn)

Close the connection.

[procedure] (help conn)

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

License

Copyright (c) 2014, O.S. Systems Software LTDA
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. The name of the authors may not be used to endorse or promote products
   derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Version history

Version 0.0.1

Initial release.