You can edit this page using wiki syntax for markup.

Article contents:== Outdated egg! This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for [[/eggref/5/speech-dispatcher-client|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 [[https://wiki.call-cc.org/chicken-projects/egg-index-5.html|egg index]]. Otherwise, please consider porting this egg to the current version of CHICKEN. [[tags: egg speech-dispatcher-client]] == speech-dispatcher-client [[toc:]] === Description Implementation of Speech Dispatcher's [[http://cvs.freebsoft.org/doc/speechd/ssip.html|SSIP protocol]] (version 0.2). === Author [[http://www.ossystems.com.br|O.S. Systems]], maintained by [[/users/mario-domenech-goulart|Mario Domenech Goulart]] === Repository [[https://github.com/OSSystems/chicken-speech-dispatcher-client|https://github.com/OSSystems/chicken-speech-dispatcher-client]] === Requirements * [[http://wiki.call-cc.org/egg/unix-sockets|unix-sockets]] === API ==== Parameters <parameter>(enable-debug? [default=#f])</parameter> <parameter>(debug-to [default=(current-error-port)])</parameter> ==== Records ===== {{connection}} The connection record represents the connection to the Speech Dispatcher server. It is returned by the {{connect}} procedure. <procedure>(connection? OBJ)</procedure> Return {{#t}} if the given {{OBJ}} is a {{connection}} record. <procedure>(connection-path CONNECTION)</procedure> 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)</procedure> Return the connection type: {{unix}} if Unix socket; {{tcp}} if TCP. <procedure>(connection-host CONNECTION)</procedure> Return the connection host (for TCP connections). The connection is Unix socket, return {{#f}}. <procedure>(connection-port CONNECTION)</procedure> Return the connection network port (for TCP connections). The connection is Unix socket, return {{#f}}. <procedure>(connection-inport CONNECTION)</procedure> Return the Scheme input port for the connection. <procedure>(connection-outport CONNECTION)</procedure> Return the Scheme output port for the connection. ===== {{response}} Protocol procedures return {{response}} records. <procedure>(response? OBJ)</procedure> Return {{#t}} if the given {{OBJ}} is a response record. <procedure>(response-code RESPONSE)</procedure> Return the response code of the given response record. <procedure>(response-data RESPONSE)</procedure> Return the response data of the given response record. <procedure>(response-status RESPONSE)</procedure> Return the response status text of the given response record. ==== Procedures <procedure>(connect #!key path host port)</procedure> 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 [[http://cvs.freebsoft.org/doc/speechd/ssip.html|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)</procedure> Speak the given {{text}}. <procedure>(list-voices conn)</procedure> List the voices available on the server. <procedure>(list-output-modules conn)</procedure> Lists the available output modules on the server. <procedure>(list-synthesis-voices conn)</procedure> Lists the available voices for the current synthesizer in use on the server. <procedure>(key conn key-name)</procedure> Speak key identified by {{key-name}}. The command is intended to be used for speaking keys pressed by the user. <procedure>(stop conn thing)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> Set all available event notifications to either {{on}} or {{off}} for the messages that follow. <procedure>(set-self-notification-begin conn status)</procedure> <procedure>(set-self-notification-end conn status)</procedure> 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)</procedure> 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> <procedure>(set-self-notification-resume conn status)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> This command sets message priority to {{priority}}. {{priority}} must be one of the values {{important}}, {{text}}, {{message}}, {{notification}}, {{progress}}. <procedure>(block-begin conn)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> Return id of the client itself. <procedure>(history-get-client-messages conn thing start number)</procedure> 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)</procedure> List the id of the last message sent by the client. <procedure>(history-get-message conn id)</procedure> 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)</procedure> Get the id of the message the history cursor is pointing to. <procedure>(history-set-cursor conn thing pos #!optional n)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> 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)</procedure> Close the connection. <procedure>(help conn)</procedure> 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. Description of your changes:

I would like to authenticate

Spam control

What do you get when you multiply 5 by 1?