Coding Tips

• Check the forums on the CloudGarden website for the latest information.
• Before using a Synthesizer or Recognizer, allocate() it, then wait for it to be allocated using the waitEngineState(Engine.ALLOCATED) method.
• After calling Recognizer commitChanges, wait for the changes to be committed by a call to the Recognizer's waitEngineState(Recognizer.LISTENING) method.
• Before calling getWords, call the setVoice method since several different TTS engines may all be grouped under a single SynthesizerModeDesc (which groups engines by Locale) but when you select the Voice then you are specifying a specific TTS engine.
• Before calling listSpeakers, getProperties, etc, allocate the Recognizer and wait till it is allocated.
• Use as few Synthesizers and Recognizers as possible, and allocate and deallocate them as few times as possible - ideally, allocate on initialization and deallocate on exit.
• Using event-handling Threads: When calling methods on a Recognizer from a method of a ResultListener or EngineListener attached to that Recognizer, put all the calls in a Runnable class and run it from a new Thread - eg, if a "resultAccepted" method wants to call the getSpeakerProfile method of a Recognizer's SpeakerManager then it should spawn a new Thread and do it from there - see the examples.recognition.TestResultListener class for a concrete example. The reason for this is that the "resultAccepted" method is synchronized with the AWTEventQueue and so halts the SAPI4 recognizer's message-handling loop - which means it is unable to respond to requests such as getting/setting speakers.
• For responsive Swing interaction: When using SpeechEvents to interact with Swing components, it is often best to use the SwingUtilities.invokeLater method to perform the work, for example:

ResultAdapter resAd = new ResultAdapter() {
   public void resultUpdated(final ResultEvent e) {
      Runnable r = new Runnable() {
         public void run() {
            resultJTextPane.setText(e.getSource().toString());
         }
      };
      SwingUtilities.invokeLater(r);
      //(new Thread(r)).start(); //...or use this method if the above is unsatisfactory
   }
};

What to try if it doesn't work

• SAPI5 Grammars with lots of rules. If a SAPI5 grammar has too many rules (more than about 500) then the grammar may just fail to work. The solution is to limit the number of rules per grammar and split the rules between several grammars.
• Deadlock: Freezing of a GUI application can often occur when AWT synchronization is active. If this occurs, the simplest fix is just to turn AWT synchronization off with a call (in the initialization part of your application) to

CGEngineCentral.setAWTSynchronization(false).

• Non-responsive Swing interaction: When using SpeechEvents to interact with Swing components, it is often best to use the SwingUtilities.invokeLater method to perform the work - see the "For responsive Swing interaction" note under "Coding Tips" above.
• Strange things can happen if you have another JSAPI implementation (eg IBM's JavaSpeech) on your system. (This should not be a problem with version 1.2.1 since the implementation is in files named cgjaspi.jar and cgjsapi.dll). Check that any other implementations of the JSAPI are removed from your JDK or JRE's classpath. If you have this implementation set up correctly the words "Initializing Cloudgarden's JSAPI 1.0 evaluation (or commercial) version 1.3.2" should appear on a console window when you load CloudGarden's JSAPI library.
• Console error messages such as "ERROR postAndWait failed for msg=1503" - see the "Using event-handling Threads" part of the "Coding Tips" section above.
• "Class not found" or "library not found" errors. One of the most common problem seems to be caused by java not being able to find either cgjsapi.jar, or cgjsapi.dll, or both.You can make sure java can find these files by executing one of the demo batch files (eg TestSynthesizer.bat) from the directory you did the initial jar-file expansion in. If this works, and you start java by using the command "java" - i.e. without any path specified - then you'll need to install the jsapi files in your JRE directory, which is usually at "C:\Program Files\JavaSoft\JRE\1.x\". Put the cgjsapi.jar file in the lib\ext subdirectory and the cgjsapi.dll in the bin subdirectory. If you have multiple JRE installations and don't know which one is the default, install the jsapi files in them all! Alternatively, just make sure cgjsapi.jar is in your classpath, and that cgjsapi132.dll is in a directory included in the PATH environment variable, or is in the directory from which you execute your java classes. See " Installation " for more details.
• Check that the JavaSound package is installed in the JRE running your code if you are using the com.cloudgarden.audio package.
• Check that the JMF 2.1.1 is installed properly if you are using the getDataSink or getDataSource methods of CGAudioManager.
• java.security  Exceptions - read the "Note on Security Permissions " section above. This might happen when running JSAPI under some web servers (such as JWS) and also with the Java plugin or appletviewer.
• If problems occur when using RMI, try using the classic JVM instead of the HotSpot JVM.
• Trouble using speech engines for different languages? - see the examples.ListEnginesTest code.
• Problems with the <SAYAS> tag or VocabManager.addWord method? - see this section .
• Recognition examples crashing with a native-code exception - this problem should have gone away with Version 1.1.1, but if it persists, try this. These examples sometimes crash when only the default profile exists. Adding a new profile (you can create/destroy profiles using the speech control panel, accessible through the Windows Control Panel) stops the crashes - the new profile may subsequently be removed and the crashes should not re-occur.
• Stalling and other strange stuff.  As of version 1.2.1, the values of fields such as Engine.ALLOCATED etc. have been changed to be identical to those used in IBM's jsapi implimentation. This will allow code compiled using IBM's jsapi to run without recompilation using CloudGarden's jsapi. However, if code compiled using versions of CloudGarden's jsapi prior to 1.2.1 are run without re-compilation under version 1.2.1, many weird results, such as stalling during a waitEngineState call, will be obtained. The solution is simply to recompile the code using version 1.2.1 or better.

Known Issues

• Import of individual rules does not always work. The workaround is just to import the whole grammar instead of a single rule.
• For SAPI5 engines, and some SAPI4 engines, the RecognizerProperties methods setSensitivity, setSpeedVsAccuracy etc do not necessarily work - the speech control panel should be used to set these values at present.