1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename ssip.info 4@settitle Speech Synthesis Interface Protocol 5@finalout 6@c @setchapternewpage odd 7@c %**end of header 8 9@syncodeindex pg cp 10@syncodeindex fn cp 11@syncodeindex vr cp 12 13@dircategory Sound 14@dircategory Development 15 16@direntry 17* SSIP: (ssip). Speech Synthesis Interface Protocol. 18@end direntry 19 20@titlepage 21@title Speech Synthesis Interface Protocol 22@author Tom@'a@v{s} Cerha <@email{cerha@@freebsoft.org}> 23@author Hynek Hanke <@email{hanke@@freebsoft.org}> 24@author Milan Zamazal <@email{zamazal@@freebsoft.org}> 25@author @url{http://www.freebsoft.org} 26@page 27@vskip 0pt plus 1filll 28 29This manual documents Speech Synthesis Interface Protocol, version 0.2. 30 31Copyright @copyright{} 2001-2007 Brailcom, o.p.s., http://www.brailcom.cz . 32 33 34@quotation 35Permission is granted to copy, distribute and/or modify this document 36under the terms of the GNU Free Documentation License, Version 1.2 or 37any later version published by the Free Software Foundation; with no 38Invariant Sections, with no Front-Cover Texts and no Back-Cover Texts. 39A copy of the license is included in the section entitled ``GNU Free 40Documentation License.'' 41@end quotation 42 43You can also (at your option) distribute this manual under the GNU 44General Public License: 45 46@quotation 47Permission is granted to copy, distribute and/or modify this document 48under the terms of the GNU General Public License as published by the 49Free Software Foundation; either version 2 of the License, or (at your 50option) any later version. 51 52A copy of the license is included in the section entitled ``GNU 53General Public License'' 54@end quotation 55 56@end titlepage 57 58@ifnottex 59@node Top, Introduction, (dir), (dir) 60 61This manual documents Speech Synthesis Interface Protocol, version 0.2. 62 63Copyright @copyright{} 2001, 2002, 2003 Brailcom, o.p.s., http://www.brailcom.cz . 64 65@quotation 66Permission is granted to copy, distribute and/or modify this document 67under the terms of the GNU Free Documentation License, Version 1.2 or 68any later version published by the Free Software Foundation; with no 69Invariant Sections, with no Front-Cover Texts and no Back-Cover Texts. 70A copy of the license is included in the section entitled ``GNU Free 71Documentation License.'' 72@end quotation 73 74You can also (at your option) distribute this manual under the GNU 75General Public License: 76 77@quotation 78Permission is granted to copy, distribute and/or modify this document 79under the terms of the GNU General Public License as published by the 80Free Software Foundation; either version 2 of the License, or (at your 81option) any later version. 82 83A copy of the license is included in the section entitled ``GNU 84General Public License'' 85@end quotation 86 87Please contact us on @url{http://www.freebsoft.org} 88 89@end ifnottex 90 91@ifhtml 92@heading Menu 93@end ifhtml 94 95@contents 96 97@menu 98* Introduction:: 99* Basic Terminology:: 100* General Rules:: 101* SSIP Commands:: 102* Return Codes:: 103* Appendices:: 104* GNU Free Documentation License:: 105* GNU General Public Licence:: 106@end menu 107 108@node Introduction, Basic Terminology, Top, Top 109@chapter Introduction 110 111@menu 112* Purpose:: 113* Protocol Philosophy:: 114* Higher Level API:: 115@end menu 116 117@node Purpose, Protocol Philosophy, Introduction, Introduction 118@section Purpose 119 120Speech Synthesis Interface Protocol is a device independent layer for 121speech synthesis, developed with the goal of making the usage of 122speech synthesis easier for application programmers. It takes care of 123most of the output-related tasks necessary to solve in speech enabled 124applications. What is a very high level GUI library to graphics, 125Speech Synthesis Interface Protocol is to speech synthesis. 126 127Up to now, the applications that wanted to implement speech output had 128to handle all the device dependent aspects of communication with 129different speech synthesizers themselves. Speech Synthesis Interface 130Protocol (SSIP) aims to provide a totally independent abstract set of 131commands by which different applications can talk to some central 132Speech Server installed on the system that than talks to the 133synthesizers themselves. This way, user applications don't have 134to care about the particular synthesizers available on the system 135and the synthesizers don't have to care about the installed user 136applications. 137 138SSIP is not only a device independent language for speech synthesis 139related requests, but also a mechanism to coordinate the interaction 140and conflicts between different clients' needs in a central place in 141the system. Through the priority system, the central Speech Server 142that implements SSIP can decide which messages are considered the most 143important at any particular time and say them, while possibly 144supressing others. 145 146@node Protocol Philosophy, Higher Level API, Purpose, Introduction 147@section Protocol Philosophy 148 149Speech Synthesis Interface Protocol defines a reasonable subset of the 150different capabilities provided by the different synthesizers. It 151supports some basic events (message, key, character, ...) as well as 152changing the basic voice parameters (language, voice, rate, pitch, 153...) or the more advanced ones (punctuation mode, spelling mode, ...). 154 155None of the commands or parameters of SSIP depends on the characteristics 156of the particular devices that are being used. For example when 157the client application wants to change the language for the next 158message, it only calls the appropriate SSIP command and it leaves the 159Speech Server to decide which synthesizer to use. 160 161SSIP was designed to allow multiple simultaneous connections to 162the server. A connection is identified by an identification string 163provided by the client application and an id number. Each connection 164with all its parameters is considered a closed space independent of 165the others, so that different clients can maintain different settings 166in their connections and then the Speech Server should take care of setting 167the right parameters on the synthesizer according to the origin of each 168request. One client can even establish several connections to maintain 169different contexts. 170 171SSIP also solves the issue when more than one client wants to speak 172at one time or when more messages come than it's possible to say. 173Each message has an assigned priority and according to this priority, 174when multiple messages come to the server, they are directly said, 175postponed or suppressed. 176 177It is important to understand the difference between SSIP and 178higher level protocols like SABLE, VoiceXML or SSML. Speech 179Synthesis Interface Protocol is not a markup language in which one 180would write a document. SSIP is rather the underlaying tool that the 181application would use to let you read and browse the documents encoded 182in either ordinary formats (like plain text, HTML, PDF) or the 183voice-enabled formats (SABLE, VoiceXML, SSML). These higher level 184protocols describe only how the document should be said, while SSIP is 185the means to actually do it on your system. In this manner, one of the 186supported formats of the messages you can send through SSIP is SSML. 187 188@node Higher Level API, , Protocol Philosophy, Introduction 189@section Higher Level API 190 191SSIP is the basic interface protocol that is being used in the 192communication of a client with the central Speech Server on a 193system. However, in many cases it may be more convenient for application 194programmers not to use SSIP directly (having to care about open 195socket connections etc.) but rather use an interface wrapper written 196in the specific programming language they use. There is no obstacle in 197SSIP for this option, and in fact, this approach is highly 198encouraged. 199 200This way, application programmers should finally be able to use such 201simple functions as speech_open(), speech_printf() and 202speech_set_rate() in their programs. 203 204We believe this can make writing new speech enabled applications 205a lot easier and allow programmers to make more of them. 206 207@node Basic Terminology, General Rules, Introduction, Top 208@chapter Basic Terminology 209 210@itemize 211 212@cindex SSIP 213@cindex Speech Synthesis Interface Protocol 214@item @emph{Speech Synthesis Interface Protocol} or @emph{SSIP} is the 215device-independent protocol described in this document through which 216client application can send their requests for speech synthesis to the 217Speech Server. 218 219@cindex Speech Server 220@item @emph{Speech Server} 221is the server application that implements Speech Synthesis Interface 222Protocol, as described in this document, and provides an interface 223for client applications. 224 225@cindex client 226@cindex client application 227@item @emph{Client} or @emph{client application} 228is every application that connects to Speech Server and talks to 229it through the Speech Synthesis Interface Protocol. In other words, 230this is the application that ``wants to speak''. 231 232@cindex message 233@item @emph{Message} 234is a chunk of text that a client sends to Speech Server to request 235saying something or play some sound. 236 237@item @emph{To cancel a message} 238means to stop saying it and/or remove it from the queue of messages 239waiting to be said. However, it is not removed from the history, where 240it was stored after being received by Speech Server. 241 242@end itemize 243 244 245@node General Rules, SSIP Commands, Basic Terminology, Top 246@chapter General Rules 247 248SSIP communicates with the clients through a defined set of text 249commands, in the usual manner for common Internet protocols. The 250characters sent through the Speech Synthesis Interface Protocol are 251encoded using the UTF-8 encoding. 252 253Each SSIP command, unless specified otherwise, consists of exactly one 254line. The line is sent in the following format: 255 256@example 257@var{command} @var{arg} ... 258@end example 259 260where @var{command} is a case insensitive command name and @var{arg}s 261are its arguments separated by spaces. The command arguments which 262come from a defined set of values are case insensitive as well. The 263number of arguments is dependent on the particular command and there 264can be commands having no arguments. 265 266All lines of SSIP input and output must be ended with a pair of 267carriage return and line feed characters, in that order. 268 269When you connect to Speech Server, you should at least set your client 270name, through the @code{SET SELF CLIENT_NAME} command (@pxref{Parameter Setting 271Commands}). This is important to get a proper identification of your client 272--- to allow managing it from the control center application and to identify it 273in a message history browser. You might want to set other connection 274parameters as well. Look for more details in @ref{Parameter Setting Commands}. 275 276An SSIP connection is preferably closed by issuing the @code{QUIT} 277command, see @ref{Other Commands}. 278 279SSIP is a synchronous protocol --- you send commands and only after a 280complete response from SSIP arrives back are you allowed to send the 281next command. Usually, the SSIP connection remains open 282during the whole run of the particular client application. If you 283close the connection and open it again, you must set all the 284previously set parameters again, SSIP doesn't store session 285parameters between connections. 286 287The protocol allows you to perform commands influencing other currently 288connected or previously connected clients. This allows you to write a 289control application managing or browsing all the messages received by 290the current Speech Server process. The mechanism is completely 291relaxed, there are no restrictions on managing some aspects of 292sound output for other users, however, there is a mechanism 293to prevent one user from seeing history messages of another 294user. 295 296Some of the commands (@ref{Speech Output Control Commands} 297and @ref{Parameter Setting Commands}) 298take an argument in the form: 299@example 300 @{ @var{id} | all | self @} 301@end example 302 303where the value can be the @code{id} of the connection the command should 304be performed on (a positive number), the string @code{all} to 305act on all clients of this server or @code{self} to act on the connection 306itself. Unless you are writing a special client for managing 307Speech Server or unless you have specific needs, you 308should only use the @code{self} value for this argument. 309 310Not all parameter setting commands may receive all kinds of the first 311parameter defined above, for instance, some of them may receive only 312@code{self}. 313 314SSIP replies have the following format: 315 316@example 317@var{ccc}-line 1 318@var{ccc}-line 2 319... 320@var{ccc}-line @var{n}-1 321@var{ddd} line @var{n} 322@end example 323 324where @var{n} is a positive integer, and @var{ccc} and @var{ddd} are 325three-digit long numeric codes identifying the result of the command. 326The last line determines the overall result of the command. The result 327code is followed by an English message describing the result of the 328action in a human readable form. 329 330@node SSIP Commands, Return Codes, General Rules, Top 331@chapter SSIP Commands 332 333Commands recognized by SSIP can be divided into several groups: Speech 334synthesis and sound output commands, speech control commands, 335parameter setting commands, commands retrieving information about 336current client and server settings, commands handling the message 337history, and other commands. Each of these command groups is 338described in one of the following sections. 339 340In the command descriptions, the command is written together with its 341arguments. Optional arguments are enclosed by square brackets 342(@code{[} and @code{]}), alternatives are separated by the vertical 343rule (@code{|}) and are grouped within braces (@code{@{} and 344@code{@}}) or square brackets for mandatory or optional arguments 345respectively. Literal argument values are typeset in lowercase letters 346(they are case insensitive), and variable arguments are typeset 347@var{like this}. Ellipsis denoted by three dots (@code{...}) means 348repetition (zero or more times) of all the arguments within the 349current brackets. 350 351@menu 352* Speech Synthesis and Sound Output Commands:: 353* Speech Output Control Commands:: 354* Message Priority Commands:: 355* Blocks of Messages Commands:: 356* Parameter Setting Commands:: 357* Information Retrieval Commands:: 358* Message Events Notification and Index Marking:: 359* History Handling Commands:: 360* Other Commands:: 361@end menu 362 363@node Speech Synthesis and Sound Output Commands, Speech Output Control Commands, SSIP Commands, SSIP Commands 364@section Speech Synthesis and Sound Output 365 366These commands invoke actual output to particular output device. The 367particular way how the message is handled depends on current speech 368parameter settings and user configuration. 369 370@table @code 371@item SPEAK 372@anchor{SPEAK} 373Start receiving a text message and synthesize it. After sending a 374reply to the command, Speech Server waits for the text of the 375message. The text can spread over any number of lines and is 376finished by an end of line marker followed by the line containing the 377single character @code{.} (dot). Thus the complete character sequence 378closing the input text is @code{CR LF . CR LF}. If any line within 379the sent text starts with a dot, an extra dot is prepended before it. 380 381During reception of the text message, Speech Server doesn't send 382responses for the lines sent. The response line is sent only 383immediately after the @code{SPEAK} command and after receiving the 384closing dot line. 385 386The content of the message can be either a plain text or a SSML 387(Speech Synthesis Markup Language) text. See @code{SET SELF 388SSML_MODE}. There is no guarantee that the SSML markup will be 389respected, so the application shouldn't rely on them. The external 390parameters can still be set by the parameter setting commands. SSML is 391intended only for additional markup inside the message. In SSML mode, 392each message must begin with @code{<speak>} and end with 393@code{</speak>}. 394 395Speech Server can start speech synthesis as soon as a sufficient 396amount of the text arrives; it generally needn't (but may) wait until 397the end of data marker is received. 398 399There is no explicit upper limit on the size of the text, but the 400server administrator may set one in the configuration or the limit can 401be enforced by available system resources. If the limit is exceeded, 402the whole text is accepted, but the excess is ignored and an 403error response code is returned after processing the final dot line. 404 405The reply takes the form 406 407@example 408225-msg_id 409225 OK MESSAGE QUEUED 410@end example 411 412where @var{msg_id} is a unique id assigned to this message in Speech 413Server. This is useful for the @ref{History Handling Commands} 414commands as well as for @ref{Message Events Notification and Index Marking}. 415 416The @code{SPEAK} command might be used for example in this way: 417 418@example 419SPEAK 420230 OK RECEIVING DATA 421hi 422. 423225-21 424225 OK MESSAGE QUEUED 425@end example 426 427@item CHAR @var{char} 428Speak letter @var{char}. @var{char} can be any character 429representable by the UTF-8 encoding. The only exception is the 430character space (@code{ }); that can't be sent directly. In this case, 431a string @code{space} must be sent instead. 432 433@example 434CHAR e 435CHAR \ 436CHAR space 437CHAR & 438@end example 439 440This command is intended to be used for speaking single letters, 441e.g. when reading a character under cursor or when spelling words. 442 443@item KEY @var{key-name} 444@anchor{SSIP KEY} 445Speak key identified by @var{key-name}. The command is intended to be 446used for speaking keys pressed by the user. 447 448@var{key-name} is a case sensitive symbolic key name. It is composed 449of a key name, optionally prepended with one or more prefixes, each 450containing an auxiliary key name and the underscore character. 451 452Key name may contain any character excluding control characters (for example, 453the characters in the range 0 to 31 in the ASCII table, characters in the 454range 128 to 159 in the Latin-* tables and other ``invisible'' 455characters), spaces, underscores, and double quotes. 456 457The recognized key names are: 458 459@itemize 460@item 461Any single UTF-8 character, excluding the exceptions defined above. 462 463@item 464Any of the symbolic key names defined in @ref{Key Names}. 465@end itemize 466 467Examples of valid key names: 468 469@example 470a 471A 472shift_a 473shift_A 474@'{u} 475$ 476enter 477shift_kp-enter 478control_alt_delete 479control 480@end example 481 482@item SOUND_ICON @var{icon-name} 483@anchor{SSIP SOUND_ICON} 484Send a sound identified by @var{icon-name} to the audio output. 485@var{icon-name} is a symbolic name of the given sound from the 486standard set listed in @ref{Standard Sound Icons}, or another name 487from the particular Speech Server sound icon configuration. 488@end table 489 490@node Speech Output Control Commands, Message Priority Commands, Speech Synthesis and Sound Output Commands, SSIP Commands 491@section Controlling Speech Output 492 493These commands can stop or resume speech or audio output. They all 494affect only the synthesis process and output to a sound device, they 495do not affect the message history. 496 497@table @code 498@item STOP @{ @var{id} | all | self @} 499Immediately stop outputting the current message (whatever it is --- 500text, letter, key, or sound icon) from the identified client, if any 501is being output. If the command argument is @code{self}, the last message 502from the current client connection is stopped. If it is @code{all}, 503stop currently output message or messages from all the clients. 504Otherwise, argument @var{id} must be given as a positive integer and 505the currently processed message from the client connection identified 506by @var{id} is stopped; if there is none such, do nothing. 507 508@item CANCEL @{ @var{id} | all | self @} 509This command is the same as @code{STOP}, with the exception that it 510stops as yet unspoken output messages as well. All currently queued messages 511are stored into the message history without being sent to the audio 512output device. 513 514@item PAUSE @{ @var{id} | all | self @} 515Stop audio output immediately, but do not discard anything. All the 516currently speaking and currently or later queued messages are postponed 517and saved for later processing, until a corresponding @code{RESUME} 518command is received. 519 520The meaning of the command arguments is the same as in the @code{STOP} 521command. 522 523@item RESUME @{ @var{id} | all | self @} 524Cancel the effect of the previously issued @code{PAUSE} command. 525Note that messages of the priority ``progress'' and ``notification'' received during 526the pause are not output (but they remain stored in the message history). 527 528It is an error to send the @code{RESUME} command when the output 529corresponding to the given argument is not paused by a previous 530invocation of the @code{PAUSE} command. Such an error is signaled by 531a @code{4XX} return code. 532 533The meaning of the command arguments is the same as in the @code{STOP} 534command. 535@end table 536 537@node Message Priority Commands, Blocks of Messages Commands, Speech Output Control Commands, SSIP Commands 538@section Priority Setting Commands 539@cindex priorities 540 541A speech synthesizer can't synthesize everything that comes to it, 542for the simple reason that messages are often coming faster 543than a synthetic voice can say them. On the screen of a 544monitor, there is relatively a lot of space compared to 545one-channel speech synthesis output. For this reason, SSIP 546implements a system of several priorities targeted at different 547types of messages. 548 549The idea is that the task of the programmer of a client application 550is only to assign a meaningful priority to each message and all the 551synchronization and switching between the messages (that can be 552coming from different clients) is automatically handled by the Speech Server 553by applying certain rules based on the priorities. 554 555@menu 556* Priority Categories:: What are the available priorities. 557* Priority Diagram:: Schematic diagram of used priority model. 558* Priority Setting Commands:: 559* Examples of Using Priorities:: A few examples of using the priorities. 560@end menu 561 562@node Priority Categories, Priority Diagram, Message Priority Commands, Message Priority Commands 563@subsection Priority Categories 564 565Speech Synthesis Interface Protocol provides a system of five priorities. Every 566message will either contain explicit priority information, or the 567default value will be used. 568 569Please see also the diagram below. 570 571@heading Priority @code{important} 572@cindex Priority important 573 574This message will be said immediately as it comes to server. 575It is never interrupted. When several concurrent messages of 576this priority are received by server, they are queued and said 577in the order they came. 578 579When a new message of level @code{important} comes while a message of 580another priority is being spoken, the other message is canceled 581and the message with priority @code{important} is said instead. Other messages 582of lower priorities are postponed (priority @code{message} and 583@code{text}) until there are no messages of priority important 584waiting, or are canceled (priority @code{notification} and @code{progress}). 585 586These messages should be as short as possible and should rarely be 587used, because they block the output of all other messages. 588 589@heading Priority @code{message} 590@cindex Priority message 591 592This message will be said when there is no message of priority 593@code{important} or @code{message} waiting in the queue. If there are, 594this message is postponed until those messages are spoken. This 595means that the priority @code{message} doesn't interrupt itself. If 596there are messages of priority @code{notification}, @code{progress} or 597@code{text} waiting in the queue or being spoken when a message of 598priority @code{message} comes, they are canceled. 599 600@heading Priority @code{text} 601@cindex Priority text 602 603This message will be said when there is no message of priority 604@code{important} or @code{message} waiting in the queue. If there are, 605this message is postponed until the previous messages are spoken. 606 607The priority text interrupts itself. This means that if several messages 608of this priority are received, they are not said in the order they 609were received, but only the latest of them is said; others are 610canceled. 611 612If there are messages of priority @code{notification} and 613@code{progress} waiting in the queue or being spoken when a message 614of priority @code{text} comes, they are canceled. 615 616@heading Priority @code{notification} 617 618This is a low priority message. If there are messages with priorities 619@code{important}, @code{message}, @code{text} or @code{progress} 620waiting in the queues or being spoken, this @code{notification} 621message is canceled. 622 623This priority interrupts itself, so if more messages with priority 624@code{notification} come at the same time, only the last of them is 625spoken. 626 627@heading Priority @code{progress} 628 629This is a special priority for messages that are coming 630shortly one after each other and they carry the information 631about some work in progress (e.g.@ @code{Completed 45%}). 632 633If new messages interrupted each other (see priority 634Notification), the user might not receive any complete 635message. 636 637This priority behaves the same as ``notification'' except 638for two things: 639 640@itemize 641@item 642The messages of this priority don't interrupt each other, 643instead, a newly arriving message is canceled if another message is 644being spoken. 645@item 646Speech Server tries to detect the last message of a series of messages 647(for instance, it's important for the user to hear the final 648@code{Completed 100%} message to know the work has completed). Speech 649Server waits until there are no more messages of this priority waiting 650in queues and if the last of them wasn't spoken yet, it speaks it with 651the priority @code{message}. 652@end itemize 653 654This way, even if Speech Server is busy speaking messages of other 655priorities, we are still sure that the important messages at the 656end of the @code{progress} sequences will be said. 657 658@node Priority Diagram, Priority Setting Commands, Priority Categories, Message Priority Commands 659@subsection Priority Diagram 660 661@image{figures/priorities,,,Speech Synthesis Interface Protocol Priorities} 662 663@node Priority Setting Commands, Examples of Using Priorities, Priority Diagram, Message Priority Commands 664@subsection Priority Setting Commands 665 666When a priority is set for a given connection, all the newly arriving 667messages will be said with this priority until it is changed for a new 668value. 669 670@itemize 671 672@item SET self PRIORITY @var{p} 673 674This command sets message priority to @var{p}. @var{p} must be one of 675the values @code{important}, @code{text}, @code{message}, 676@code{notification}, @code{progress}. @xref{Priority Categories}. 677 678Only @code{self} is allowed as the `target' argument. 679 680@end itemize 681 682@node Examples of Using Priorities, , Priority Setting Commands, Message Priority Commands 683@subsection Examples of Using Priorities 684 685Example uses for priority @code{important} are: 686 687@itemize 688@item error messages 689@item very important messages 690@item ... 691@end itemize 692 693Example uses for priority @code{message} are: 694 695@itemize 696@item regular program messages 697@item warnings 698@item ... 699@end itemize 700 701Example uses for priority @code{text} are: 702 703@itemize 704@item text the user is working on 705@item menu items 706@item ... 707@end itemize 708 709Example uses for priority @code{notification} are: 710 711@itemize 712@item less important status information 713@item letters when typing input 714@item run-time help 715@item ... 716@end itemize 717 718Example uses for level @code{progress} are: 719 720@itemize 721@item ``completed 15%'', ``completed 16%'', ``completed 17%'' 722@item ``Loading sounds'', ``Loading graphics'', ``Loading ai'', ... 723@end itemize 724 725 726@node Blocks of Messages Commands, Parameter Setting Commands, Message Priority Commands, SSIP Commands 727@section Blocks of Messages Commands 728 729Block commands allow the client to concatenate several messages to form one 730block that behaves as one message in the priority system and history. After 731opening the block, client can send a specified subset of the commands and 732the messages introduced by @code{SPEAK} will be processed immediately, however 733there will be no priority interaction before closing the block. 734The @ref{Speech Output Control Commands} also handle the whole block as one 735message. 736 737Take for example this message from an email client: 738 739@example 740> Hi, how are you? 741I'm fine. Thank you. 742@end example 743 744The character `>' clearly marks who said which part. So it'd be nice to say 745the two lines with different voices, however, it'd be desirable to treat it all 746as one message with priority TEXT and have it put together in history, 747because in fact, it logically @emph{is} one message. 748 749@table @code 750@item BLOCK BEGIN 751Opens a block of messages. There will be no priority interaction between 752the messages inside the block, the whole block will be treated as one message 753of the priority that was specified by previous @code{SET} command. 754 755It can only be called outside of a block; nesting is not allowed. 756 757@itemize 758The allowed commands inside a block are: 759 @item @code{SPEAK} 760 @item @code{SOUND_ICON} 761 @item @code{CHAR} 762 @item @code{KEY} 763 @item @code{SET SELF RATE} 764 @item @code{SET SELF PITCH} 765 @item @code{SET SELF VOLUME} 766 @item @code{SET SELF VOICE} 767 @item @code{SET SELF LANGUAGE} 768 @item @code{SET SELF PUNCTUATION} 769 @item @code{SET SELF CAP_LET_RECOGN} 770 @item @code{QUIT} 771 @item @code{BLOCK END} 772@end itemize 773 774@item BLOCK END 775Closes a block of messages, see @code{BLOCK BEGIN}. 776 777It can be only called inside a block opened by @code{BLOCK BEGIN}; 778nesting is not allowed. 779@end table 780 781A more complete example of SSIP communication using BLOCKs. 782 783@example 784[...] 785SET SELF PRIORITY TEXT 786202 OK PRIORITY SET 787 788BLOCK BEGIN 789260 OK INSIDE BLOCK 790 791SET SELF VOICE MALE1 792209 OK VOICE SET 793 794SPEAK 795230 OK RECEIVING DATA 796The word 797225 OK MESSAGE QUEUED 798 799SET SELF VOICE MALE2 800209 OK VOICE SET 801SPEAK 802230 OK RECEIVING DATA 803`Free' 804225 OK MESSAGE QUEUED 805 806SET SELF VOICE MALE1 807209 OK VOICE SET 808SPEAK 809230 OK RECEIVING DATA 810in Free Software refers to freedom, not price. 811225 OK MESSAGE QUEUED 812 813BLOCK END 814261 OK OUTSIDE BLOCK 815@end example 816 817@node Parameter Setting Commands, Information Retrieval Commands, Blocks of Messages Commands, SSIP Commands 818@section Parameter Setting 819 820The @code{SET} command sets various control parameters of the 821synthesized speech or server configuration. The parameter is always 822denoted by the second command argument. 823 824All the settings take effect on the connections specified in the first 825argument (@pxref{General Rules}) and until the parameter setting is 826changed by another invocation of the appropriate @code{SET} command or 827until the connection is closed. 828 829The voice property and TTS-processing settings can sometimes be 830without any real effect if the end synthesizer doesn't provide the 831required functionality. This is not considered an error in the 832implementation of SSIP. 833 834@table @code 835@item SET self CLIENT_NAME @var{user}:@var{client}:@var{component} 836Set client's name. Client name consists of the user name, client 837(application) identification, and the identification of the component 838of the client (application). Each of the parts of the client name may 839contain only alphanumeric characters, dashes (@code{-}) and underscores 840(@code{_}). 841 842For example, for a client called @code{lynx} that creates an SSIP 843connection for its command processing, the name could be set in the 844following way: 845 846@example 847SET CLIENT_NAME joe:lynx:cmd_processing 848@end example 849 850The client name is used in the server configuration settings, client 851listings and message history handling. All its three parts can be 852arbitrary, but it's important to define and follow rules for each 853application supporting Speech Synthesis Interface Protocol, so that 854a Speech Server user can configure all the aspects of the speech 855output easily. 856 857Usually, this command should be sent as the very first command when a 858new SSIP connection is established. The command may be 859sent only once within a single connection. Attempts to change the 860client's name once it's already set are answered with an error code. 861 862Only @code{self} is allowed as the `target' argument. 863 864@item SET all DEBUG @{ON|OFF@} 865If set to @code{ON}, Speech Dispatcher will write all its debugging 866information (including output modules) with maximal verbosity into a 867debug directory which is reported by the server to the client in reply 868to this command. When subsequently set to @code{OFF}, Speech 869Dispatcher will stop writing out debugging information into this path 870and close all the appropriate logging files. 871 872The intended use for this functionality is on-line debugging from 873client application. If the user wants to report a problem, the client 874application will ask him/her for a place to generate the logs, to repeat 875the situation that he/she considers to be a bug, and then perhaps it will 876automatically pack the logs and offer to send them to the developers 877of Speech Dispatcher or another appropriate place where the contained 878information can be processed. 879 880Warning: This option results in a lot of data being written into the 881output logs and so should not be left on for an unnecessarily long 882time. 883 884@example 885SET all DEBUG ON 886262-/home/hanke/.cache/speech-dispatcher/log/debug 887262 OK DEBUGGING SET 888@end example 889 890@item SET @{all | self | @var{id} @} OUTPUT_MODULE @var{module} 891Set the output module to @var{module}. This overrides the 892selection based on language. Only values returned by the 893@code{LIST OUTPUT_MODULES} command are permitted. 894@xref{list-output-modules}. 895 896@example 897SET self OUTPUT_MODULE espeak 898216 OK OUTPUT MODULE SET 899@end example 900 901@item GET OUTPUT_MODULE 902Get the output module currently in use. This takes no parameters 903and simply returns the current output module. 904 905@example 906GET OUTPUT_MODULE 907251-espeak 908251 OK GET RETURNED 909@end example 910 911@item SET @{ all | self | @var{id} @} LANGUAGE @var{language-code} 912Set recommended language for this client according to @var{language-code}. 913@var{language-code} is the code of the language according to RFC 1766. 914 915For example, to set the preferred language to Czech, you send the 916following command: 917 918@example 919SET SELF LANGUAGE cs 920@end example 921 922Please note, that switching a language may require switching a voice, 923so this command may actually override a previous call to @code{SET VOICE} or 924@code{SET SYNTHESIS_VOICE}. 925 926The default for the Speech Dispatcher implementation of SSIP 927is determined by the @code{DefaultLanguage} setting in the 928@code{speechd.conf} file. The factory default is @code{en-US} (American English). 929 930@item SET @{self@} SSML_MODE @var{mode} 931Set the mode of the text received in the message body sent by the 932@code{SPEAK} command. This can be either a plain text, if @code{mode} 933is set to @code{off} or a SSML marked text, if @code{mode} is set to @code{on}. 934 935There is no guarantee that the SSML markup will be respected, so 936the application shouldn't rely on them. The external parameters 937can still be set by the parameter setting commands. SSML is intended 938only for additional markup inside the message. In SSML mode, each 939message must begin with @code{<speak>} and end with @code{</speak>}. 940 941For example a simple `hello world' looks like this: 942 943@example 944SET SELF SSML_MODE on 945SPEAK 946<speak> 947Hello world! 948</speak> 949. 950@end example 951 952@item SET @{ all | self | @var{id} @} PUNCTUATION @{ all | most | some | none @} 953Set punctuation mode to the given value. @code{all} means speak all 954punctuation characters, @code{none} means speak no punctuation characters, 955@code{some} and @code{most} mean speak only intermediate sets of punctuation 956characters defined in the synthesizer's configuration or symbols files. 957The default for the Speech Dispatcher implementation of SSIP 958is determined by the @code{DefaultPunctuationMode} setting in the 959@code{speechd.conf} file. The factory default is @code{none}. 960 961@item SET @{ all | self | @var{id} @} SPELLING @{ on | off @} 962Switch spelling on or off. If spelling is set to on, all the 963incoming messages will be said letter-by-letter, instead of 964speaking them as whole words. 965The default for the Speech Dispatcher implementation of SSIP 966is determined by the @code{DefaultSpelling} setting in the 967@code{speechd.conf} file. The factory default is @code{off}. 968 969@item SET @{ all | self | @var{id} @} CAP_LET_RECOGN @{ none | spell | icon @} 970Set capital letters recognition mode. @code{none} switches this 971feature off. @code{spell} causes capital letters to be spelled 972in the speech using the table set as @code{CAP_LET_RECOGN_TABLE}. 973With parameter @code{icon}, each capital letter will be preceeded 974by a sound icon (either sound or textual) specified by the user 975in his configuration. 976The default for the Speech Dispatcher implementation of SSIP 977is determined by the @code{DefaultCapLetRecognition} setting in the 978@code{speechd.conf} file. The factory default is @code{none}. 979 980@item SET @{ all | self | @var{id} @} VOICE_TYPE @var{name} 981Set the voice identified by @var{name}. @var{name} must be one of the voice 982identifiers returned by the command @code{LIST VOICES} (@pxref{Information 983Retrieval Commands}). 984 985There is a standard set of voice identifiers defined in @ref{Standard 986Voices}. 987 988The default for the Speech Dispatcher implementation of SSIP 989is determined by the @code{DefaultVoiceType} setting in the 990@code{speechd.conf} file. The factory default is @code{MALE1}. 991 992@item GET VOICE_TYPE 993Gets the current pre-defined voice. A list of voice identifiers can be 994obtained by the command @code{LIST VOICES} (@pxref{Information 995Retrieval Commands}). 996 997@example 998GET VOICE_TYPE 999251-MALE1 1000251 OK GET RETURNED 1001@end example 1002 1003@item SET @{ all | self | @var{id} @} SYNTHESIS_VOICE @var{name} 1004Set the voice identified by @var{name}. @var{name} is a voice name 1005recognized by the current synthesizer. It must be one of the names 1006returned by the command @code{LIST SYNTHESIS_VOICES} run for the 1007appropriate synthesizer. (@pxref{Information Retrieval Commands}). 1008 1009Please note, that switching to a particular voice may require 1010switching a language, so this command may actually override a previous 1011call to @code{SET LANGUAGE}. 1012 1013@item SET @{ all | self | @var{id} @} RATE @var{n} 1014Set the rate of speech. @var{n} is an integer value within the range 1015from -100 to 100, lower values meaning slower 1016speech and higher values meaning faster speech. 1017The default for the Speech Dispatcher implementation of SSIP 1018is determined by the @code{DefaultRate} setting in the 1019@code{speechd.conf} file. The factory default is 0. 1020 1021@item GET RATE 1022Get the current rate of speech value. 1023 1024@example 1025GET RATE 1026251-10 1027251 OK GET RETURNED 1028@end example 1029 1030@item SET @{ all | self | @var{id} @} PITCH @var{n} 1031Set the pitch of speech. @var{n} is an integer value within the range 1032from -100 to 100, lower values meaning lower 1033pitch and higher values meaning higher pitch. 1034The default for the Speech Dispatcher implementation of SSIP 1035is determined by the @code{DefaultPitch} setting in the 1036@code{speechd.conf} file. The factory default is 0. 1037 1038@item GET PITCH 1039Get the current pitch value. 1040 1041@example 1042GET PITCH 1043251-10 1044251 OK GET RETURNED 1045@end example 1046 1047@item SET @{ all | self | @var{id} @} VOLUME @var{n} 1048Set the volume of speech. @var{n} is an integer value within the range 1049from -100 to 100. lower values meaning lower 1050volume and higher values meaning higher volume. 1051The default for the Speech Dispatcher implementation of SSIP 1052is determined by the @code{DefaultVolume} setting in the 1053@code{speechd.conf} file. The factory default is 100. 1054 1055@item GET VOLUME 1056Get the current volume value. 1057 1058@example 1059GET VOLUME 1060251-100 1061251 OK GET RETURNED 1062@end example 1063 1064@item SET @{ all | self | @var{id} @} PAUSE_CONTEXT @var{n} 1065Set the number of (more or less) sentences that should be repeated 1066after a previously paused text is resumed. If there isn't enough text 1067before the pause spot, the entire message is repeated. @var{n} 1068is a positive integer value specifying the number of sentences to 1069repeat. 1070The default for the Speech Dispatcher implementation of SSIP 1071is determined by the @code{DefaultPauseContext} setting in the 1072@code{speechd.conf} file. The factory default is 0. 1073 1074@item SET @{ all | self | @var{id} @} HISTORY @{ on | off @} 1075Enable (@code{on}) or disable (@code{off}) storing of received 1076messages into history. 1077 1078This command is intended for use by message history browsers and 1079usually should not be used by other kinds of clients. 1080@end table 1081 1082@node Information Retrieval Commands, Message Events Notification and Index Marking, Parameter Setting Commands, SSIP Commands 1083@section Retrieving Information 1084 1085The @code{LIST} command serves for retrieving information that can be 1086presented to the user for selection of the values to the @code{SET} 1087command. The information listed is selected according to the first 1088argument of the @code{LIST} command. 1089 1090@table @code 1091@anchor{list-output-modules} 1092@item LIST OUTPUT_MOUDLES 1093Lists the available output modules putting each module identification 1094name one on a single line. 1095 1096Example: 1097@example 1098LIST OUTPUT_MODULES 1099250-festival 1100250-espeak 1101250 OK MODULE LIST SENT 1102@end example 1103 1104 1105@item LIST VOICES 1106Lists the available symbolic voice names putting each voice name on a single 1107line. These are symbolic names that are mapped to the real voices used in the 1108synthesizer either automatically or via synthesizer or output module 1109configuration. 1110 1111Example: 1112@example 1113LIST VOICES 1114249-MALE1 1115249-MALE2 1116249-MALE3 1117249-FEMALE1 1118249-FEMALE2 1119249-FEMALE3 1120249-CHILD_MALE 1121249-CHILD_FEMALE 1122249 OK VOICE LIST SENT 1123@end example 1124 1125@item LIST SYNTHESIS_VOICES 1126 1127Lists the available voices for the current synthesizer in use. These 1128names differ from those obtained by @code{LIST VOICES} in that they 1129are names of the real voices used inside the synthesizer. 1130 1131This feature should only be used to allow the user to choose the voice. 1132All automatic switching of voices (unless user-configurable) should be 1133done using the symbolic voice names which can be configured in the synthesizer. 1134 1135Each voice name is listed on a separate line together with its language 1136code and dialect identification string separated by tabs. The dialect 1137identification strings do not have well-defined meaning yet. If no dialect 1138is specified by the synthesizer, the value @code{none} is used. 1139 1140Example: 1141@example 1142LIST SYNTHESIS_VOICES 1143249-afrikaans af none 1144249-welsh-test cy none 1145249-german de none 1146249-greek_test el none 1147249-en-rhotic en r 1148249-lancashire en uk-north 1149249 OK VOICE LIST SENT 1150@end example 1151 1152@end table 1153 1154@node Message Events Notification and Index Marking, History Handling Commands, Information Retrieval Commands, SSIP Commands 1155@section Message Events Notification and Index Marking 1156 1157@menu 1158* Why Events Notification:: 1159* Types of Events:: 1160* Events Notifications in SSIP:: 1161* Switching Notifications On and Off:: 1162@end menu 1163 1164@node Why Events Notification, Types of Events, Message Events Notification and Index Marking, Message Events Notification and Index Marking 1165@subsection Why Events Notification 1166 1167Applications can send messages to a Speech Server through the SSIP 1168@code{SPEAK} command. However, this command only puts the received 1169message into a queue in Speech Server and returns immediately. The 1170message then will or will not be said at some particular time 1171according to its priority. Through Message Events Notification, the 1172application is able to discover certain kind of events, including when 1173the message started to be played on the speakers, when it terminated 1174playing, when it was paused and resumed, or when it was 1175interrupted/discarded. It is also possible to get notification when a 1176certain place in the given text was reached while playing the 1177synthesized text on the speakers -- this capability, however, might or 1178might not be supported by the end synthesizer and so client 1179applications should not rely on it. 1180 1181@node Types of Events, Events Notifications in SSIP, Why Events Notification, Message Events Notification and Index Marking 1182@subsection Types of Events 1183 1184SSIP recognizes several types of events. Each event is reported 1185together with the unique identification of the message and client it 1186is associated with. This is an overview of available events. For 1187detailed SSIP syntax, please look below. 1188 1189@table @code 1190@item BEGIN 1191 1192This event means that the synthesizer just started to speak the 1193message and the user is able to hear the speech on his/her speakers. 1194 1195Please note that not every message stored for speaking by the 1196@code{SPEAK} command will issue this event. It can issue the 1197@code{CANCEL} event instead. 1198 1199@item END 1200 1201This event means that the synthesizer just terminated speaking the 1202message (by reaching its end) and the user is no longer able to hear 1203the speech on their speakers. 1204 1205Again, note that not every message that has already reported the 1206@code{BEGIN} event will necessarily get to the @code{END} event. 1207It might instead issue the @code{CANCEL} or @code{PAUSE} events. 1208 1209@item CANCEL 1210 1211The @code{CANCEL} event is reported when the message was canceled 1212(either after @code{BEGIN} during speaking or even before, when waiting 1213in the queues) and will not be spoken anymore. 1214 1215@item PAUSE 1216 1217The event @code{PAUSE} means that the message that was being spoken 1218was paused and no longer produces any sound on the speakers, but 1219was not discarded and the rest of the message might be spoken again after the 1220@code{RESUME} command is sent. @xref{Speech Output Control 1221Commands}. This will be reported by the @code{RESUME} event. 1222 1223@code{PAUSE} is always preceded by the event @code{BEGIN}, and can 1224be followed by either the event @code{RESUME} or @code{CANCEL}. 1225 1226@item RESUME 1227 1228The event @code{RESUME} means that a message that was paused 1229while being spoken, just started to continue and again produces 1230sound in the speakers. 1231 1232@code{RESUME} is always preceeded by the event @code{PAUSE}, and can 1233be followed by either the event @code{END} or @code{CANCEL}. 1234 1235@item INDEX_MARK 1236 1237This event means that some previously specified place in the text 1238(so-called index mark) was reached when speaking the synthesized 1239message in the speakers. It is always accompanied by an additional 1240parameter that indicates which place it is -- the name of the index 1241mark. 1242 1243@end table 1244 1245Example (not in SSIP syntax): 1246 1247This SSML message 1248@example 1249 <speak>Hello, <mark name="mark1"/> how does it work?</speak> 1250@end example 1251would issue the following sequence of events if it is not discarded or paused: 1252 1253@example 1254 BEGIN 1255 INDEX_MARK "mark1" 1256 END 1257@end example 1258 1259 1260or this one if it gets paused after the first index mark and then later resumed. 1261 1262@example 1263 BEGIN 1264 INDEX_MARK "mark1" 1265 PAUSE 1266 RESUME 1267 END 1268@end example 1269 1270@node Events Notifications in SSIP, Switching Notifications On and Off, Types of Events, Message Events Notification and Index Marking 1271@subsection Events Notification in SSIP 1272 1273Event notifications, if requested, are reported asynchronously in 1274SSIP. This means that they are not sent as replies to any particular 1275requests but can arrive anytime. However, notifications can't arrive 1276in the time between when a SSIP command is sent by the client and its 1277reply is sent back by the server. 1278 1279Each notification consists of a multi-line SSIP reply as defined in 1280@ref{General Rules}, and includes at least two parameters: 1281@code{msg_id} and @code{client_id}. @code{msg_id} is the 1282identification number of the message the event is related to, 1283@ref{SPEAK} while @code{client_id} is the identification number of the 1284client who sent the message. Some events may have additional 1285parameters. 1286 1287@table @code 1288@item INDEX_MARK 1289 1290@example 1291700-msg_id 1292700-client_id 1293700-index_mark 1294700 END 1295@end example 1296 1297The event @code{INDEX_MARK} carries a special parameter 1298@code{index_mark} which is a string of characters identifying the 1299index mark, as specified by the client application (e.g. by the 1300SSML tag <mark/>. 1301 1302@item BEGIN 1303 1304@example 1305701-msg_id 1306701-client_id 1307701 BEGIN 1308@end example 1309@item END 1310 1311@example 1312702-msg_id 1313702-client_id 1314702 END 1315@end example 1316 1317@item CANCEL 1318 1319@example 1320703-msg_id 1321703-client_id 1322703 CANCELED 1323@end example 1324 1325@item PAUSE 1326 1327@example 1328704-msg_id 1329704-client_id 1330704 PAUSED 1331@end example 1332 1333@item RESUME 1334 1335@example 1336705-msg_id 1337705-client_id 1338705 RESUMED 1339@end example 1340@end table 1341 1342 1343@node Switching Notifications On and Off, , Events Notifications in SSIP, Message Events Notification and Index Marking 1344@subsection Switching Notifications On and Off 1345 1346The client application might or might not want to receive the 1347notifications about events, or it might want to receive some but not 1348others. SSIP allows clients to specify which notifications are to be 1349used. 1350 1351The following commands for setting notifications on and off affect all 1352the text messages (sent by the @code{SPEAK} SSIP command) based on 1353when the appropriate @code{SPEAK} command was called. So if for 1354example, you set all notifications on, send a message and then set all 1355notifications off, you will receive all the available notifications 1356for that message even though it might start speaking after the 1357notifications are already turned off. 1358 1359@table @code 1360@item SET SELF NOTIFICATION ALL @{ on | off @} 1361 1362Set all available event notifications to either ``on'' or ``off'' for 1363for the messages that follow. @xref{Types of Events}. 1364 1365@item SET SELF NOTIFICATION BEGIN @{ on | off @} 1366@item SET SELF NOTIFICATION END @{ on | off @} 1367 1368Set the event notifications for @code{BEGIN} or @code{END} to either 1369``on'' or ``off'' for the messages that follow. @xref{Types of Events}. 1370 1371@item SET SELF NOTIFICATION CANCEL @{ on | off @} 1372 1373Set the event notifications for @code{CANCEL} to @code{mode} where 1374@code{mode} is either ``on'' or ``off'' for switching the 1375notifications on or off for the messages that follow. @xref{Types of 1376Events}. 1377 1378@item SET SELF NOTIFICATION PAUSE @{ on | off @} 1379@item SET SELF NOTIFICATION RESUME @{ on | off @} 1380 1381Set the event notifications for @code{PAUSE} or @code{RESUME} to 1382@code{mode} where @code{mode} is either ``on'' or ``off'' for 1383switching the notifications on or off for the messages that 1384follow. @xref{Types of Events}. 1385 1386@item SET SELF NOTIFICATION INDEX_MARKS @{ on | off @} 1387 1388Set the event notifications for @code{INDEX_MARK} to either ``on'' or 1389``off'' for switching the notifications on or off for the messages 1390that follow. @xref{Types of Events}. 1391 1392@end table 1393 1394@node History Handling Commands, Other Commands, Message Events Notification and Index Marking, SSIP Commands 1395@section History Handling 1396 1397@menu 1398* Purpose of Message History:: 1399* Message History in SSIP:: 1400@end menu 1401 1402@node Purpose of Message History, Message History in SSIP, History Handling Commands, History Handling Commands 1403@subsection Purpose of Message History 1404 1405It seems a good feature for the blind and visually impaired to 1406provide the possibility to browse, through some simple client, the 1407history of received and previously said messages. 1408 1409Some messages are even received by Speech Server without being said, 1410because there will always be more space for information on the screen 1411than speech output can possibly provide. 1412 1413For this reason, SSIP defines a set of commands that allow client 1414applications to browse through the history of previously received 1415messages saved on the server. The idea is that @emph{each} message 1416received by the server should be accessible through the history and 1417the user can search for it later by time, keywords or using other 1418methods. 1419 1420On the other hand, this may cause security issues as several 1421clients may connect to Speech Server and they might originate 1422from different users. Because of flatpak and other technologies 1423checking the user id isn't enough. So now, only those messages 1424that come from the same client connection are accessible. 1425 1426@node Message History in SSIP, , Purpose of Message History, History Handling Commands 1427@subsection Message History in SSIP 1428 1429History is handled by the @code{HISTORY} command. It can take many 1430forms, described below, that allow browsing, retrieving and repeating 1431stored messages. In each invocation of the @code{HISTORY} command 1432there is no difference between processing spoken or not spoken 1433messages, all the received messages are processed. 1434 1435The implementation of these history commands in the Speech Dispatcher 1436implementation of SSIP is still under 1437way. If you want to use them, please contact us to see the 1438current status. 1439 1440There is a @dfn{history cursor} pointing to some message in the 1441history. You can move it across history messages and retrieve the 1442message the cursor is pointing to, using the @code{HISTORY CURSOR} set 1443of command arguments described below. 1444 1445@table @code 1446@item HISTORY GET CLIENT_LIST 1447List known client names, their identifiers and status. Each connection is 1448listed on a separate line in the following format: 1449 1450@example 1451@var{id} @var{name} @var{status} 1452@end example 1453 1454where @var{id} is a client id that can be used in other history 1455handling requests or in the speech output control commands 1456(@pxref{Speech Output Control Commands}), @var{name} is the client 1457name as set through the @code{SET SELF CLIENT_NAME} command, and 1458@var{status} is @code{1} for connected clients and @code{0} for 1459disconnected clients. @var{id}s are unique within a single run of 1460Speech Server. 1461 1462Sample SSIP reply: 1463 1464@example 1465240-0 joe:speechd_client:main 0 1466240-1 joe:speechd_client:status 0 1467240-2 unknown:unknown:unknown 1 1468240 OK CLIENTS LIST SENT 1469@end example 1470 1471@item HISTORY GET CLIENT_ID 1472Return id of the client itself. 1473 1474The id is listed on a separate line in the following format: 1475 1476@example 1477@var{id} 1478@end example 1479 1480Example: 1481@example 1482200-123 1483200 OK CLIENT ID SENT 1484@end example 1485 1486@item HISTORY GET CLIENT_MESSAGES @{ @var{id} | all | self @} @var{start} @var{number} 1487List identifiers of messages sent by the client identified by 1488@var{id}. If the special identifier @code{all} is used, identifiers 1489of messages sent by all clients are listed; if the special identifier 1490@code{self} is used, identifiers of messages sent by this client are 1491listed. 1492 1493@var{number} of messages is listed, starting from the message numbered 1494@var{start}. Both @var{number} and @var{start} must be positive 1495integers. The first message is numbered 1, the second 2, etc. If the 1496given range exceeds the range of available messages, no error is 1497signaled and the given range is restricted to the available range of 1498messages. 1499 1500Messages are sorted by the criterion used in the last client's 1501invocation of the @code{HISTORY SORT} command. If no @code{HISTORY 1502SET} has been invoked yet, the messages are sorted from the oldest to 1503the newest, according to their time of arrival at Speech Server. 1504 1505Each message id is listed, together with other information, on a 1506separate line, in the following format: 1507 1508@example 1509@var{id} @var{client-id} @var{client-name} "@var{time}" @var{priority} "@var{intro}" 1510@end example 1511 1512@var{client-id} is a numeric identifier of the client which sent the 1513message, @var{client-name} is its name as set by the @code{SET SELF 1514CLIENT_NAME} command (@pxref{Parameter Setting Commands}). 1515@var{time} is the time of arrival of the message, in the fixed length 1516@code{YYYY-MM-DD HH:MM:SS} format. @var{priority} is the priority of 1517the message, one of the values accepted by the @code{SET SELF PRIORITY} 1518command (@pxref{Parameter Setting Commands}). 1519 1520@var{intro} is the introductory part of the message of a certain 1521maximum length, see the @code{HISTORY SET SHORT_MESSAGE_LENGTH} 1522command. @var{intro} does not contain any double quotes nor the line 1523feed character. 1524 1525All the message identifiers in the history, regardless of clients that 1526issued them, are unique within a single run of Speech Server and 1527remain unchanged. 1528 1529@item HISTORY GET LAST 1530List the id of the last message sent by the client. 1531 1532The id is listed on a separate line of the following format: 1533 1534@example 1535@var{id} 1536@end example 1537 1538If the client hasn't sent any message yet, return an error code. 1539 1540@item HISTORY GET MESSAGE @var{id} 1541Return the text of the history message identified by @var{id}. If 1542@var{id} doesn't refer to any message, return an error code instead. 1543The text is sent as a multi-line message, with no escaping or special 1544transformation. 1545 1546An example SSIP response to the command: 1547 1548@example 1549200-Hello, world! 1550200-How are you? 1551200 OK MESSAGE SENT 1552@end example 1553 1554@item HISTORY CURSOR GET 1555Get the id of the message the history cursor is pointing to. 1556 1557The id is listed on a separate line. Sample SSIP reply to 1558this command: 1559 1560@example 1561243-42 1562243 OK CURSOR POSITION RETURNED 1563@end example 1564 1565@item HISTORY CURSOR SET @{ @var{id} | all | self @} @{ first | last | pos @var{n} @} 1566Set the history cursor to the given position. The meaning of the 1567first argument after @code{SET} is the same as in the @code{HISTORY 1568GET CLIENT_MESSAGES} command. The argument @code{first} asks to set 1569the cursor on the first position and the argument @code{last} asks to 1570set the cursor on the last position of the history of the given 1571client. If the argument @code{pos} is used, the position is set to 1572@var{n}, where @var{n} is a positive integer. It is an error if 1573@var{id} doesn't identify any client or if @var{n} doesn't point to 1574any existing position in the history. 1575 1576As for the order and numbering of the messages in the history, the 1577same rules apply as in @code{HISTORY GET CLIENT_MESSAGES}. See above. 1578 1579@item HISTORY CURSOR @{ forward | backward @} 1580Move the cursor one position @code{forward}, resp. @code{backward}, 1581within the messages of the client specified in the last @code{HISTORY 1582CURSOR SET} command. If there is no next, resp. previous, message, 1583don't move the cursor and return an error code. 1584 1585@item HISTORY SAY @var{id} 1586Speak the message from history identified by @var{id}. If @var{id} 1587doesn't refer to any message, return an error code instead. 1588 1589The message is spoken as it would be sent by its originating command 1590(@code{SPEAK} or @code{SOUND_ICON}), but the @emph{current} settings 1591(priority, etc.) apply. 1592 1593@item HISTORY SORT @{ asc | desc @} @{ time | user | client_name | priority | message_type @} 1594Sort the messages in history according to the given criteria. If the 1595second command argument is @code{asc}, sort in ascending order, if 1596it is @code{desc}, sort in descending order. The third command 1597argument specifies the message property to order by: 1598 1599@table @code 1600@item time 1601Time of arrival of the message. 1602 1603@item user 1604User name. 1605 1606@item client_name 1607Client name, excluding user name. 1608 1609@item priority 1610Priority. 1611 1612@item message_type 1613Type of the message (text, sound icon, character, key), in the order 1614specified in the Speech Server configuration or by the @code{HISTORY 1615SET MESSAGE_TYPE_ORDERING} command. 1616@end table 1617 1618The sorting is stable --- order of all the messages that are equal in 1619the given ordering remains the same. 1620 1621The sorting is specific to the given client connection, other 1622connections are unaffected by invocation of this command. 1623 1624@item HISTORY SET SHORT_MESSAGE_LENGTH @var{length} 1625Set the maximum length of short versions of history messages to 1626@var{length} characters. @var{length} must be a non-negative integer. 1627 1628Short (truncated) versions of history messages are used e.g. in the 1629answer to the @code{HISTORY GET CLIENT_MESSAGES} format. 1630 1631@item HISTORY SET MESSAGE_TYPE_ORDERING "@var{ordering}" 1632Set the ordering of the message types, from the minimum to the 1633maximum. @var{ordering} is a sequence of the following symbols, 1634separated by spaces: @code{text}, @code{sound_icon}, @code{char}, 1635@code{key}. The symbols are case insensitive and each of them must be 1636present in @var{ordering} exactly once. 1637 1638The specified ordering can be used by the @code{HISTORY SORT} command. 1639 1640@item HISTORY SEARCH @{ @var{id} | all | self @} "@var{condition}" 1641Return the list of history messages satisfying @var{condition}. The 1642command allows searching messages by given words. The output format 1643is the same as the @code{HISTORY GET CLIENT_MESSAGES} command. 1644 1645The meaning of the first argument after @code{SEARCH} is the same as 1646the @code{HISTORY GET CLIENT_MESSAGES} command. 1647 1648@var{condition} is constructed according to the following grammar 1649rules: 1650 1651@table @code 1652@item @var{condition} :: @var{word} 1653Matches messages containing @var{word}. 1654 1655@item @var{condition} :: ( ! @var{condition} ) 1656Negation of the given condition. 1657 1658@item @var{condition} :: ( @var{condition} [ & @var{condition} ... ] ) 1659Logical AND --- all the conditions must be satisfied. 1660 1661@item @var{condition} :: ( @var{condition} [ | @var{condition} ... ] ) 1662Logical OR --- at least one of the conditions must be satisfied. 1663@end table 1664 1665Spaces within the condition are insignificant and ignored. 1666 1667The following rules apply to @var{word}s: 1668 1669@itemize @minus 1670@item 1671@var{word} is a sequence of adjacent alphanumeric characters. 1672 1673@item 1674If @var{word} contains any upper-case letter, the search for the word 1675is case sensitive, otherwise it's case insensitive. 1676 1677@item 1678@var{word} must match whole word, not only its substring. 1679 1680@item 1681@var{word} can contain the wild card characters @code{?}, substituting 1682any single alphanumeric character, and @code{*}, substituting any 1683number (incl. zero) of alphanumeric characters. 1684@end itemize 1685 1686Returned messages are sorted by the following rules: 1687 1688@enumerate 1689@item 1690The primary sorting is defined by the number of the satisfied 1691subconditions on the top level of the given condition, from the 1692highest (best matching messages first) to the lowest. This takes 1693effect only if the given condition is the OR rule. 1694 1695@item 1696The criterion used in the last client's invocation of the 1697@code{HISTORY SORT} command. If no @code{HISTORY SORT} has been 1698invoked yet, the messages are sorted from the oldest to the newest, 1699according to their time of arrival. 1700@end enumerate 1701@end table 1702 1703@node Other Commands, , History Handling Commands, SSIP Commands 1704@section Other Commands 1705 1706@table @code 1707@item QUIT 1708Close the connection. 1709 1710@item HELP 1711Print a short list of all SSIP commands, as a multi-line message. 1712@end table 1713 1714@node Return Codes, Appendices, SSIP Commands, Top 1715@chapter Return Codes 1716 1717Each line of the SSIP output starts with a three-digit numeric code of 1718the form @var{NXX} where @var{N} determines the result group and 1719@var{xx} denotes the finer classification of the result. 1720 1721SSIP defines the following result groups: 1722 1723@table @var 1724@item 1xx 1725Informative response --- general information about the protocol, help 1726messages. 1727 1728@item 2xx 1729Operation was completely successful. 1730 1731@item 3xx 1732Server error, problem on the server side. 1733 1734@item 4xx 1735Client error, invalid arguments or parameters received. 1736 1737@item 5xx 1738Client error, invalid command syntax, unparseable input. 1739 1740@item 7xx 1741Event notifications. See @xref{Events Notifications in SSIP}. 1742@end table 1743 1744Result groups @var{1xx} and @var{2xx} correspond to successful 1745actions, other groups to unsuccessful actions. Only the groups 1746defined here may be returned in an SSIP connection. 1747 1748Currently, for return codes in the range @code{100}--@code{599}, only the meaning of 1749the first digit of the result code is defined. The last two digits are 1750insignificant and can be of any value. Clients shouldn't rely on the 1751unspecified digits in any way. 1752 1753However, the return codes in the range @code{700}--@code{800}, 1754reserved for events notification, are well defined in the appropriate 1755section of SSIP documentation and client applications can rely on 1756them. 1757 1758In the future, these return codes should be fixed so that clients can 1759rely on them. 1760 1761@menu 1762* Sample SSIP Dialog:: 1763@end menu 1764 1765@node Sample SSIP Dialog, , Return Codes, Return Codes 1766@section Example of an SSIP Dialog 1767 1768The following example illustrates a sample dialog with SSIP. The 1769client connects to a Speech Server, sets all the common parameters, 1770sends two text messages, displays the list of clients, instructs 1771Speech Server to repeat the second message, and closes the connection. 1772Lines starting with a numeric code are response lines of the server, 1773other lines are the lines sent by the client. 1774 1775@example 1776SET SELF CLIENT_NAME joe:vi:default 1777208 OK CLIENT NAME SET 1778SET SELF PRIORITY MESSAGE 1779202 OK PRIORITY SET 1780SPEAK 1781230 OK RECEIVING DATA 1782Hello, I'm am SSIP communication example! 1783How are you? 1784. 1785225 OK MESSAGE QUEUED 1786SPEAK 1787230 OK RECEIVING DATA 1788Still there? 1789. 1790225 OK MESSAGE QUEUED 1791HISTORY GET CLIENT_LIST 1792240-1 jim:Emacs:default 0 1793240-2 jim:Emacs:default 0 1794240-3 unknown:unknown:unknown 0 1795240-4 jim:Emacs:default 1 1796240-5 joe:vi:default 1 1797240 OK CLIENTS LIST SENT 1798HISTORY GET LAST 1799242-39 joe:vi:default 1800242 OK LAST MSG SENT 1801HISTORY SAY 39 1802225 OK MESSAGE QUEUED 1803QUIT 1804231 HAPPY HACKING 1805@end example 1806 1807 1808@node Appendices, GNU Free Documentation License, Return Codes, Top 1809@appendix Appendices 1810 1811@menu 1812* Key Names:: List of the symbolic key names. 1813* Standard Sound Icons:: List of the standard sound icon names. 1814* Standard Voices:: 1815@end menu 1816 1817@node Key Names, Standard Sound Icons, Appendices, Appendices 1818@appendixsec Key Names 1819 1820This appendix defines all the recognized symbolic key names. The 1821names are case sensitive. 1822 1823@subheading Special Key Names 1824 1825@table @code 1826@item space 1827@item underscore 1828@item double-quote 1829@end table 1830 1831@subheading Auxiliary Keys 1832 1833@table @code 1834@item alt 1835@item control 1836@item hyper 1837@item meta 1838@item shift 1839@item super 1840@end table 1841 1842@subheading Control Character Keys 1843 1844@table @code 1845@item backspace 1846@item break 1847@item delete 1848@item down 1849@item end 1850@item enter 1851@item escape 1852@item f1 1853@item f2 1854@item f3 1855@item f4 1856@item f5 1857@item f6 1858@item f7 1859@item f8 1860@item f9 1861@item f10 1862@item f11 1863@item f12 1864@item f13 1865@item f14 1866@item f15 1867@item f16 1868@item f17 1869@item f18 1870@item f19 1871@item f20 1872@item f21 1873@item f22 1874@item f23 1875@item f24 1876@item home 1877@item insert 1878@item kp-* 1879@item kp-+ 1880@item kp-- 1881@item kp-. 1882@item kp-/ 1883@item kp-0 1884@item kp-1 1885@item kp-2 1886@item kp-3 1887@item kp-4 1888@item kp-5 1889@item kp-6 1890@item kp-7 1891@item kp-8 1892@item kp-9 1893@item kp-enter 1894@item left 1895@item menu 1896@item next 1897@item num-lock 1898@item pause 1899@item print 1900@item prior 1901@item return 1902@item right 1903@item scroll-lock 1904@item space 1905@item tab 1906@item up 1907@item window 1908@end table 1909 1910@node Standard Sound Icons, Standard Voices, Key Names, Appendices 1911@appendixsec Standard Sound Icons 1912 1913There are none currently. 1914 1915@node Standard Voices, , Standard Sound Icons, Appendices 1916@appendixsec Standard Voices 1917 1918The following voice names are always present in the output of the 1919@code{LIST VOICES} command (@pxref{Information Retrieval Commands}): 1920 1921@table @code 1922@item MALE1 1923@item MALE2 1924@item MALE3 1925@item FEMALE1 1926@item FEMALE2 1927@item FEMALE3 1928@item CHILD_MALE 1929@item CHILD_FEMALE 1930@end table 1931 1932The actual presence of any of these voices is not guaranteed. But the 1933command @code{SET VOICE} (@pxref{Parameter Setting Commands}) must 1934accept any of them. If the given voice is not available, it is mapped 1935to another voice by the output module. 1936 1937@node GNU Free Documentation License, GNU General Public Licence, Appendices, Top 1938@appendix GNU Free Documentation License 1939@center Version 1.2, November 2002 1940@cindex FDL, GNU Free Documentation License 1941 1942@include fdl.texi 1943 1944@node GNU General Public Licence, , GNU Free Documentation License, Top 1945@appendix GNU General Public License 1946@center Version 2, June 1991 1947@cindex GNU General Public License 1948 1949@include gpl.texi 1950 1951@bye 1952