CLC-4-TTS: Core Library Components for Text-To-Speech

Table of Contents

1. Introduction
2. Conventions Used In This Documentation
3. List of Functions Provided
4. Usage Instructions
   • CLC_Init
   • CLC_Shutdown
   • CLC_Make_TTS_History_Buffer
   • CLC_Ready
   • CLC_Interrupt
   • CLC_Say
   • CLC_Read
   • CLC_Recently_Read
   • CLC_SAPI5_Direct_Speak
   • CLC_Spell
   • CLC_SAPI5_FixMessage
   • CLC_Shout
   • CLC_ShoutSpell
   • CLC_FREETTS_InsertSpaces
   • CLC_SayWithProperties
   • CLC_ReadWithProperties
   • CLC_ShoutWithProperties
   • CLC_SetLanguage
5. Changes

1. Introduction

This library is a collection of useful functions for creating text-to-speech applications, such as a screen reader, within Mozilla Firefox. Installing the CLC-4-TTS extension will give all other extensions within Firefox the ability to use the JavaScript functions provided in this library. The CLC-4-TTS extension by itself is only a library and does not add any hotkeys or menus to Firefox. All functions and global variables used in this library are preceded with "CLC_" to avoid any potential naming conflicts. Currently, Microsoft SAPI 5, FreeTTS, Orca, and Apple's TTS are available.

To install the FreeTTS engine, you will need to install the Java Runtime Environment and then install the CLC-4-TTS: FreeTTS for Firefox files.

The Java Runtime Environment can be downloaded from Sun Microsystems by following this link.

After you have installed the Java Runtime Environment, please download CLC-4-TTS FreeTTS for Firefox installer by following this link. If your Java Runtime Environment has been properly installed, you should be able to directly run this Java-based installer.

The code for this library is open source and is licensed under the terms of the GNU GPL.

2. Conventions Used In This Documentation

While JavaScript is not typed the way C++ and Java are, I believe it is still helpful to identify the expected type of the inputs and outputs of the various functions. In order to do so, I have adopted the documentation convention of "RETURNTYPE functionname(TYPE_ARG1, TYPE_ARG2, ...)" for all of the functions presented here.

Example:
A function (non_existant_dummy_add_function) that is expected to add two integers passed in as arguments to it (X and Y) and return the result would be presented in the documentation as:
"int non_existant_dummy_add_function(int_x, int_y)"
An example of using such a function in your JavaScript would be:

var myfirstnumber = 1;
var mysecondnumber = 2;
var myanswer = non_existant_dummy_add_function(myfirstnumber, mysecondnumber);
alert(myanswer);

The expected result of the above example would be the number 3 showing up in an alert box.
The following is a list of types that I have used and what they mean:

• Void - Same as C/C++
• Int - Same as C/C++
• Char - Same as C/C++
• Bool - Same as C/C++
• String - Null terminated char array, same as C/C++
• DOM-Obj - A node object in the Mozilla Firefox DOM that can be accessed via JavaScript. Note that this object is a reference to the actual object being displayed in the Firefox browser. Hence, modifications to the values of such objects will be reflected in what is shown in the browser. These objects can be thought of as a C++ class. The easiest way to answer any questions about these objects (such as what its data members are and what class functions are available) is to examine the object using the DOM Inspector that comes with Firefox. Make sure you set the Object view in the DOM Inspector to "JavaScript Object" (the default view is DOM Node).

3. List of Functions Provided

• bool CLC_Init(int_engine)
  Initializes the CLC-4-TTS library using the specified engine. Currently, the only valid choices are "1" which will choose the Microsoft SAPI 5 engine, "2" which will choose the Java FreeTTS engine, and "3" which will choose the Orca engine. This function will return true for success and false for failure.
• 
  
• void CLC_Shutdown()
  Stops the speech engine. Performs a shut down on any speech engines that must be manually shut down.
  
  
• void CLC_Make_TTS_History_Buffer(int_maxsize)
  When the CLC-4-TTS library is initialized, the history buffer size is automatically set to a default of 20 DOM-Obj. If you wish to change this buffersize, call this function to set a new maxsize.
  
  
• bool CLC_Ready()
  Queries the CLC-4-TTS library to see if it is ready to process a speech request. Returns true if it is ready; false if not ready.
  
  
• void CLC_Interrupt()
  Interrupts whatever is currently being said and makes the speech engine stop speaking.
  
  
• void CLC_Say(string_message, int_pitch)
  Speaks the message at the specified pitch. Valid values for pitch are -2 (very low), -1 (low), 0 (normal), 1 (high), and 2 (very high).
  
  
• void CLC_Read(DOM-Obj_contentobj, string_contentText, int_pitch)
  Functions similarly to the CLC_Say function. Speaks the contentText at the specified pitch. However, unlike the CLC_Say function, the CLC_Read function stores the contentObj in the read history. This allows you to later query the read history buffer for recently read objects. The valid values for pitch are the same as for CLC_Say.
  
  
• DOM-Obj CLC_Recently_Read(int_index)
  Returns the "i"th object that was most recently read using the CLC_Read function where "i" is defined as index+1.
  
  
• void CLC_SAPI5_Direct_Speak(string_sapi5xml, int_speakflags)
  Gives you direct access to the SAPI5 TTS engine. Consult the SAPI 5 SDK help documentation for details about the SAPI 5 XML grammar and what the speakflag enumerations are. If you use this function, be aware that your code will NOT be portable for other speech engines. It is recommended that you stick with the CLC_Say and CLC_Read functions as much as possible since those functions will be supported for use in future speech engines implemented in this library.
  
  
• void CLC_Spell(string_message, int_pitch)
  Spells out the message letter by letter at the specified pitch. Valid values for pitch are -2 (very low), -1 (low), 0 (normal), 1 (high), and 2 (very high).
  
  
• string CLC_SAPI5_FixMessage(string_message)
  Returns a fixed version of the "string_message" that can be spoken correctly by SAPI5. Note: You do NOT need this function unless you are writing functions that directly use SAPI5 (ie, you have chosen to use the CLC_SAPI5_Direct_Speak function). You do NOT need to fix the string inputs for CLC_Say, CLC_Read, and CLC_Spell. As long as SAPI5 has been chosen as the TTS engine, these 3 functions will automatically use CLC_SAPI5_FixMessage to fix any strings passed to them.
  
  
• void CLC_Shout(string_message, int_pitch)
  Shouts (interrupts all other messages) the message at the specified pitch. Valid values for pitch are -2 (very low), -1 (low), 0 (normal), 1 (high), and 2 (very high).
  
  
• void CLC_ShoutSpell(string_message, int_pitch)
  Shout (interrupts all other messages) spells out the message letter by letter at the specified pitch. Valid values for pitch are -2 (very low), -1 (low), 0 (normal), 1 (high), and 2 (very high).
  
  
• void CLC_FREETTS_InsertSpaces(string_message)
  Adds a space after each character of string_message.
  
  

4. Usage Instructions

CLC_Init

bool CLC_Init(int_engine)

Input parameters:

• int_engine - Integer that specifies the speech engine to be used. Currently only SAPI 5 (1), FreeTTS (2), and Orca (3) have been implemented.

• bool - True if initialization was successful; false if failed.

• None.

• To use SAPI 5, initialize the library with:
  CLC_Init(1);
• To use FreeTTS, initialize the library with:
  CLC_Init(2);
• To use Orca, initialize the library with:
  CLC_Init(3);
• If a CLC-4-TTS engine is already active, this function will automatically shut down the active engine first and then initialize the new selected engine.

CLC_Shutdown

void CLC_Shutdown()

Input parameters:

• None

• void - This function has no return value.

• None

• You should use this function when you no longer need the TTS engine. Note that this will only perform a manual shutdown on speech engines that must be manually shutdown; speech engines which are automatically deallocated by Firefox are stopped and ignored.
• This function is "safe" - calling it when there is no active engine will result in a no op.

CLC_Make_TTS_History_Buffer

void CLC_Make_TTS_History_Buffer(int_maxsize)

Input parameters:

• int_maxsize - Integer that specifies the new maximum size of the buffer.

• void - This function has no return value.

• None

• The default buffer size is 20 DOM-Obj. If you do not wish to change this, you do not need to use this function at all. The 20 DOM-Obj buffer is allocated by default when the CLC-4-TTS library is initialized with CLC_Init.
• Every time this function is called, it creates a brand new buffer and the old buffer is deallocated by JavaScript automatically. This means that if you expand the buffer from 20 to 30, the old DOM-Obj references that you had in the buffer will be lost since you are starting over with a new, empty buffer.
• A large buffer introduces additional processing overhead when using the CLC_Read function. You should not use an unnecessarily large buffer.

CLC_Ready

bool CLC_Ready()

Input parameters:

• None

• Bool - True if the active TTS engine is ready to speak; false if it is not ready.

• None

• "Readiness" is defined as able to process another request, has completed all pending requests, AND is not currently speaking. A speech engine that is not ready *may* still be able to have a speech request queued and spoken later (as in the case of SAPI 5), but such behavior is NOT a guaranteed property of the CLC_Say and CLC_Read functions and is not necessarily true for other TTS engines.
• The official SAPI 5 documentation (the SAPI 5.1 help file that comes with the SDK) has an inconsitency in it regarding the dwRunningState data member of the SPVOICESTATUS object. In the Enumerations section, for SPRUNSTATE, the documentation enumerates two values: SPRS_DONE and SPRS_IS_SPEAKING. However, in the Structures section, for SPVOICESTATUS, there is the following statement about dwRunningState:

  "Indicates the status of the voice.. That is, whether it is currently speaking, is done with all pending speak requests, or is currently waiting to speak."

  After experimentation, I have determined that the latter is true; that is 0 == waiting, 1 == done, 2 == speaking. Readiness for SAPI 5 is defined as being in the "done" state.

CLC_Interrupt

void CLC_Interrupt()

Input parameters:

• None

• void - This function has no return value.

• None

• This function will make the speech engine stop speaking as quickly as possible. If the speech engine allows for queued speech requests and there are currently requests in the queue, all those requests will be discarded.
• This function only stops the speech engine; it will NOT release the engine. This means that you do not need to intialize the engine again and you may continue to use CLC_Say and CLC_Read functions afterwards.

CLC_Say

void CLC_Say(string_message, int_pitch)

Input parameters:

• string_message - String of text that you wish the speech engine to speak.
• int_pitch - Integer value that indicates the pitch that should be used by the speech engine. Valid values for pitch are -2 (very low), -1 (low), 0 (normal), 1 (high), and 2 (very high).

• void - This function has no return value.

• Invalid pitch - Getting this error means that the pitch value is unacceptable. Check and make sure that int_pitch is an integer value between -2 and 2 (inclusive).

• The 0 pitch value is whatever the middle pitch value is for the selected speech engine and everything else is relative to that. This means that if you set the middle pitch of your speech engine to a higher pitch, all of the pitches will be raised accordingly.
• This function is "polite" - calling it while the speech engine is saying something else will not interrupt what is currently being spoken. If you DO wish to interrupt what is currently being spoken, use CLC_Interrupt before calling CLC_Say.
• For the SAPI 5 engine, calling this while the SAPI 5 engine is busy causes the speech request to go into queue. It will be spoken as soon as all previous queue requests have been completed. However, the speech request going into queue is not a generally guaranteed property of this function and may not be true for other speech engines. If you wish to absolutely guarantee that this request will be spoken, you should use CLC_Ready to ensure that the speech engine is ready. Alternatively, you could call CLC_Interrupt before CLC_Say to force the speech engine to stop speaking and speak the current request immediately.

CLC_Read

void CLC_Read(DOM-Obj_contentobj, string_contentText, int_pitch)

Input parameters:

• DOM-Obj_contentobj - DOM-Obj that is the source for what you wish the speech engine to speak. This DOM-Obj will be put into the read history buffer and can be retrieved later on.
• string_contentText - String of text that you wish the speech engine to speak.
• int_pitch - Integer value that indicates the pitch that should be used by the speech engine. Valid values for pitch are -2 (very low), -1 (low), 0 (normal), 1 (high), and 2 (very high).

• void - This function has no return value.

• Invalid pitch - Getting this error means that the pitch value is unacceptable. Check and make sure that int_pitch is an integer value between -2 and 2 (inclusive).

• The 0 pitch value is whatever the middle pitch value is for the selected speech engine and everything else is relative to that. This means that if you set the middle pitch of your speech engine to a higher pitch, all of the pitches will be raised accordingly.
• This function is "polite" - calling it while the speech engine is saying something else will not interrupt what is currently being spoken. If you DO wish to interrupt what is currently being spoken, use CLC_Interrupt before calling CLC_Read.
• For the SAPI 5 engine, calling this while the SAPI 5 engine is busy causes the speech request to go into queue. It will be spoken as soon as all previous queue requests have been completed. However, the speech request going into queue is not a generally guaranteed property of this function and may not be true for other speech engines. If you wish to absolutely guarantee that this request will be spoken, you should use CLC_Ready to ensure that the speech engine is ready. Alternatively, you could call CLC_Interrupt before CLC_Read to force the speech engine to stop speaking and speak the current request immediately.
• The benefit of using a CLC_Read rather than a CLC_Say is that the CLC_Read function will keep track of the most recently read objects. This can allow you to do things such as repeating what was recently read, retrieving additional information about what was recently read (ie, if the last item was a link), etc. However, if you do not plan on using the read history buffer at all, you can go ahead and just use the CLC_Say function.
• This function will NOT error check for you. If you accidentally pass in a DOM-Obj that is unrelated to what you are reading, this function will accept that. When you later try to retrieve the recently read object, it will be exactly what you passed in (that is, it will be the same wrong object). Moral of the story: Be sure you pass in the correct object.

CLC_Recently_Read

DOM-Obj CLC_Recently_Read(int_index)

Input parameters:

• int_index - Integer value that is used as the index of the history buffer. The history buffer is organized such that the most recently read item is at the smallest index position. In other words, use 0 to retrieve the last item that was read.

• DOM-Obj - The DOM-Obj stored in the history buffer at the index position specified. If there is no DOM-Obj at the index positon, a null value will be returned.

• Out of bounds of the Read History Buffer - This means that the int_index argument is not acceptable. Check and make sure that the int_index parameter is an integer between 0 and maxbuffersize-1 (inclusive). The default buffersize is 20, so if you did not use CLC_Make_TTS_History_Buffer, your int_index value must be between 0 and 19 (inclusive).

• There is no error checking involved as far as what the recently read object actually is. So if you passed in the wrong DOM-Obj when you used CLC_Read, you will get the same wrong object back when you use CLC_Recently_Read.

CLC_SAPI5_Direct_Speak

void CLC_SAPI5_Direct_Speak(string_sapi5xml, int_speakflags)

Input parameters:

• string_sapi5xml - String of XML text that is formatted in SAPI 5 grammar. Refer to the Microsoft SAPI SDK documentation to learn about SAPI 5 XML grammar.
• int_speakflags - Integer value that will set various speech properties. As quoted from the Microsoft SAPI SDK documentation, the enumeration is

  typedef enum SPEAKFLAGS
  {
  //--- SpVoice flags
  SPF_DEFAULT,
  SPF_ASYNC,
  SPF_PURGEBEFORESPEAK,
  SPF_IS_FILENAME,
  SPF_IS_XML,
  SPF_IS_NOT_XML,
  SPF_PERSIST_XML,
  
  //--- Normalizer flags
  SPF_NLP_SPEAK_PUNC,
  
  //--- Masks
  SPF_NLP_MASK,
  SPF_VOICE_MASK,
  SPF_UNUSED_FLAGS
  } SPEAKFLAGS;

  Refer to the Microsoft SAPI SDK documentation for more information.

• void - This function has no return value.

• Must use the SAPI 5 TTS engine to use the CLC_SAPI5_Direct_Speak function - This error means that the active speech engine is NOT SAPI 5. Check and make sure that you have called CLC_Init(1) before using this function and that CLC_Init(something_other_than_1) and CLC_Shutdown have not been accidentally invoked.

• This function requires SAPI 5 as the underlying speech engine. Thus, anything that you code which uses this function will not work if you try to switch over to any of the future engines that get added to this library. It is recommended that you use CLC_Say and CLC_Read as much as possible since those functions are generic and will work for future engines that get added. Only use the CLC_SAPI5_Direct_Speak function if you do not have any other reasonable way and are not concerned about portability issues to other speech engines.
• Based on my experimentation, these flags are actually a bit enum.
  This means that it is not 0,1,2,3,4,5,... but rather 0,1,2,4,8,16,...
  
  So the first one SPF_DEFAULT has a value of 0,
  the second one SPF_ASYNC has a value of 1,
  the next one SPF_PURGEBEFORESPEAK has a value of 2,
  the next one SPF_IS_FILENAME has a value of 4,
  the next one SPF_IS_XML has a value of 8,
  the next one SPF_IS_NOT_XML has a value of 16, etc etc etc.
  
  To set multiple flags, add them together.
  (If you wanted async and to treat it as not XML, you would set it to 17.)
  
  

CLC_Spell

void CLC_Spell(string_message, int_pitch)

Input parameters:

• string_message - String of text that you wish the speech engine to spell out.
• int_pitch - Integer value that indicates the pitch that should be used by the speech engine. Valid values for pitch are -2 (very low), -1 (low), 0 (normal), 1 (high), and 2 (very high).

• void - This function has no return value.

• Invalid pitch - Getting this error means that the pitch value is unacceptable. Check and make sure that int_pitch is an integer value between -2 and 2 (inclusive).

• The 0 pitch value is whatever the middle pitch value is for the selected speech engine and everything else is relative to that. This means that if you set the middle pitch of your speech engine to a higher pitch, all of the pitches will be raised accordingly.
• This function is "polite" - calling it while the speech engine is saying something else will not interrupt what is currently being spoken. If you DO wish to interrupt what is currently being spoken, use CLC_Interrupt before calling CLC_Spell.
• For the SAPI 5 engine, calling this while the SAPI 5 engine is busy causes the speech request to go into queue. It will be spoken as soon as all previous queue requests have been completed. However, the speech request going into queue is not a generally guaranteed property of this function and may not be true for other speech engines. If you wish to absolutely guarantee that this request will be spoken, you should use CLC_Ready to ensure that the speech engine is ready. Alternatively, you could call CLC_Interrupt before CLC_Spell to force the speech engine to stop speaking and speak the current request immediately.

CLC_SAPI5_FixMessage

string CLC_SAPI5_FixMessage(string_message)

Input parameters:

• string_message - String of text that you wish to fix for to ensure correct processing when used with SAPI5 directly.

• string - The fixed string that will work correctly for SAPI5.

• None

• You do not need to use this function unless you are working with SAPI5 directly (ie, you are using CLC_SAPI5_Direct_Speak).
• CLC_Say, CLC_Read, and CLC_Spell all automatically use this function if the active TTS engine is SAPI5, so you do not need to use it on any strings passed in to these functions.
• Currently, the only known problem that SAPI5 has is with strings which contain a < symbol. This becomes interpreted as the start of a new XML command and causes the rest of the string after it to become silenced. Disabling XML parsing is not a good idea since XML is what enables the other speech properties such as pitch control and spelling mode. Therefore, this problem is solved by replacing all < symbols that occur in the string with the XML escape character representation for it, which is &lt.

CLC_Shout

void CLC_Shout(string_message, int_pitch)

Input parameters:

• string_message - String of text that you wish the speech engine to speak.
• int_pitch - Integer value that indicates the pitch that should be used by the speech engine. Valid values for pitch are -2 (very low), -1 (low), 0 (normal), 1 (high), and 2 (very high).

• void - This function has no return value.

• Invalid pitch - Getting this error means that the pitch value is unacceptable. Check and make sure that int_pitch is an integer value between -2 and 2 (inclusive).

• The 0 pitch value is whatever the middle pitch value is for the selected speech engine and everything else is relative to that. This means that if you set the middle pitch of your speech engine to a higher pitch, all of the pitches will be raised accordingly.
• This function is NOT "polite" - calling it while the speech engine is saying something else will interrupt what is currently being spoken. CLC_Shout messages have TOP priority, with the highest priority given to the last issued CLC_Shout function call. Any messages interrupted by CLC_Shout are purged from the system and LOST. This has the same effect of doing a CLC_Interrupt followed immediately by a CLC_Say except it is usually more efficient since whenever possible (ie, if the underlying speech engine has a purge_before_speak option), it only makes one call to the underlying speech engine instead of two.
• For the SAPI 5 engine, this is only one call to SAPI and not two, since SAPI can purge all messages before speaking.

CLC_ShoutSpell

void CLC_ShoutSpell(string_message, int_pitch)

Input parameters:

• string_message - String of text that you wish the speech engine to spell out.
• int_pitch - Integer value that indicates the pitch that should be used by the speech engine. Valid values for pitch are -2 (very low), -1 (low), 0 (normal), 1 (high), and 2 (very high).

• void - This function has no return value.

• Invalid pitch - Getting this error means that the pitch value is unacceptable. Check and make sure that int_pitch is an integer value between -2 and 2 (inclusive).

• The 0 pitch value is whatever the middle pitch value is for the selected speech engine and everything else is relative to that. This means that if you set the middle pitch of your speech engine to a higher pitch, all of the pitches will be raised accordingly.
• This function is NOT "polite" - calling it while the speech engine is saying something else will interrupt what is currently being spoken. CLC_ShoutSpell messages have TOP priority, with the highest priority given to the last issued CLC_ShoutSpell function call. Any messages interrupted by CLC_ShoutSpell are purged from the system and LOST. This has the same effect of doing a CLC_Interrupt followed immediately by a CLC_Spell except it is usually more efficient since whenever possible (ie, if the underlying speech engine has a purge_before_speak option), it only makes one call to the underlying speech engine instead of two.
• For the SAPI 5 engine, this is only one call to SAPI and not two, since SAPI can purge all messages before speaking.

CLC_FREETTS_InsertSpaces

string CLC_FREETTS_InsertSpaces(string_message)

Input parameters:

• string_message - String of text that you wish to have spaces inserted into

• string - This function returns a string that contains the same content as string_message except all the original characters in the string are now followed by a space.

• None

• Example: Using "hello" as input will result in an output of "h e l l o ".
• This function is a workaround for the FreeTTS engine to make it spell out a string.

CLC_SayWithProperties

void CLC_SayWithProperties(string_message, array_speechProperties, array_additionalProperties)

Input parameters:

• string_message - String of text that you wish the speech engine to speak.
• array_speechProperties - Array of arrays of two integers, the first integer being the value and the second integer being the mode. The standard modes are:
  • 0 = absolute
  • 1 = percentage (assumes % sign: 50% is integer 50, etc.)
  • 2 = enumeration (0 is the medium level, negative numbers for lower, positive numbers for higher - total number of levels are same as defined in CSS)
  Since this is a work in progress, to avoid forcing people who use this function to modify their programs any time a new speech property is added, the properties will be processed in the following defined order:
  • 0 = pitch; standard modes
  • 1 = pitch range; standard modes
  • 2 = speaking rate; standard modes
  • 3 = volume; standard modes
• array_additionalProperties - Dummy placeholder array. This parameter is not currently used, but it may be used in the future for dealing with properties which are more qualitative than quantitative. (Such as using a string to specify a voice by name.)

• void - This function has no return value.

• None

• This function behaves the same as CLC_Say except it allows developers to specify speech properties

CLC_ReadWithProperties

void CLC_ReadWithProperties(DOM-Obj_contentobj, contentText, array_speechProperties, array_additionalProperties)

Input parameters:

• DOM-Obj_contentobj - DOM-Obj that is the source for what you wish the speech engine to speak. This DOM-Obj will be put into the read history buffer and can be retrieved later on.
• string_contentText - String of text that you wish the speech engine to speak.
• array_speechProperties - Array of arrays of two integers, the first integer being the value and the second integer being the mode. The standard modes are:
  • 0 = absolute
  • 1 = percentage (assumes % sign: 50% is integer 50, etc.)
  • 2 = enumeration (0 is the medium level, negative numbers for lower, positive numbers for higher - total number of levels are same as defined in CSS)
  Since this is a work in progress, to avoid forcing people who use this function to modify their programs any time a new speech property is added, the properties will be processed in the following defined order:
  • 0 = pitch; standard modes
  • 1 = pitch range; standard modes
  • 2 = speaking rate; standard modes
  • 3 = volume; standard modes
• array_additionalProperties - Dummy placeholder array. This parameter is not currently used, but it may be used in the future for dealing with properties which are more qualitative than quantitative. (Such as using a string to specify a voice by name.)

• void - This function has no return value.

• None

• This function behaves the same as CLC_Read except it allows developers to specify speech properties

CLC_ShoutWithProperties

void CLC_ShoutWithProperties(string_message, array_speechProperties, array_additionalProperties)

Input parameters:

• string_message - String of text that you wish the speech engine to speak.
• array_speechProperties - Array of arrays of two integers, the first integer being the value and the second integer being the mode. The standard modes are:
  • 0 = absolute
  • 1 = percentage (assumes % sign: 50% is integer 50, etc.)
  • 2 = enumeration (0 is the medium level, negative numbers for lower, positive numbers for higher - total number of levels are same as defined in CSS)
  Since this is a work in progress, to avoid forcing people who use this function to modify their programs any time a new speech property is added, the properties will be processed in the following defined order:
  • 0 = pitch; standard modes
  • 1 = pitch range; standard modes
  • 2 = speaking rate; standard modes
  • 3 = volume; standard modes
• array_additionalProperties - Dummy placeholder array. This parameter is not currently used, but it may be used in the future for dealing with properties which are more qualitative than quantitative. (Such as using a string to specify a voice by name.)

• void - This function has no return value.

• None

• This function behaves the same as CLC_Shout except it allows developers to specify speech properties

CLC_SetLanguage

void CLC_SetLanguage(string_theLanguage)

Input parameters:

• string_theLanguage - String of text that is the language that the synthesizer should use.

• void - This function has no return value.

• None

• The input string_theLanguage should be the standard language name abbreviations used in the HTML lang attribute.
• This will only try to use the language, but it does NOT guarantee that the language will be used. In particular, this will fail if you do not have a synthesizer for the language installed or if the sythesizer is not using the expected language id tag.

5. Changes

• 1.0 - Initial release
• 1.1 - Bugfix release: Corrects a serious problem with the uninstallation process and offers better stability for the CLC_Say and CLC_Read functions
• 1.2 - Enhancements: Added CLC_Spell. Fixed the problem of strings with the < symbol being silenced after the < symbol
• 1.3 - Bugfix release: Corrected a JavaScript type bug by forcing conversion. JavaScript automatically assumed an incorrect type when presented with a number that should be treated as a string, not int. Forced conversion to string by padding with the space character at the end.
• 1.4 - Bugfix release: Space padding method was not good since having a null string before it introduced two quotes which added to the two quotes around the space padding resulted in a sequence of four quotes in a row. This sequence becomes misinterpreted by JavaScript as a string with contents which are two consecutive quotes. Changed CLC_SAPI5_FixMessage so that if the replace function does not exist (which is the case if the input is treated as a number), the output of the function will simply be the input as is. This eliminates the need to force a string conversion since passing a number to the SAPI dll automatically converts that number to a string.
• 1.5 - Enhancements: Added CLC_Shout to allow interrupting and speaking to happen in as few XPCOM calls as possible.
• 1.6 - Enhancements: Added CLC_ShoutSpell to allow interrupting and speaking to happen in as few XPCOM calls as possible - needed to have punctuation announced.
• 1.7 - Bug fix for Asian languages: Thanks to Kenji Inoue, a bug in the DLL that kept CLC-4-TTS from functioning correctly with Asian voices has now finally been corrected.
• 1.8 - Minor change to the overlay file to cause this library to be loaded for the commonDialog.xul (needed in order to make these functions available for things like JavaScript alerts).
• 1.9 - Support for FreeTTS added! Commented out error messages as those can cause infinite loops.
• 2.0 - Version bump for compatibility with Firefox 1.5.
• 2.1 - Linux compatibility upgrade for CLC-4-TTS; now it should work with all flavors of Linux. Added basic necessities for implementing speech properties.
• 2.2 - Stability enhancement for Java FreeTTS initialization routine.
• 2.3 - Optimization for Java FreeTTS initialization routine and bug fixes for speech properties. Some speech properties still do not work in FreeTTS - that is a known issue resulting from a lack of JSML support in Java FreeTTS; I am looking into possible workarounds.
• 2.4 - Speech properties work much better in FreeTTS.
• 2.5 - Changed behavior of CLC_Shutdown so that it only shuts down engines that have to be manually shutdown. Since both SAPI 5 and FreeTTS are automatically shutdown when Firefox is closed, this function just stops the engines without a shutdown. Prevents other extensions using this library from accidentally killing the TTS used by Fire Vox.
• 2.6 - Support for Orca added.
• 2.7 - Support for setting the synthesizer language added.
• 2.8 - Version bump for compatibility with Firefox 2.0.
• 2.9 - Change to how readiness is checked when Orca is the selected speech engine; the new method is far more efficient and leads to a significant increases in performance and stability.
• 3.0 - More stability enhancements for Orca.
• 3.1 - Added support for Emacspeak Speech Server.
• 3.2 - Port for Emacspeak Speech Server is now 2222.
• 3.3 - Added support for Mac TTS. Improved behavior of readiness checking for Orca - should be much stabler and faster now.