com.nuance.nmdp.speechkit
Class SpeechKit

java.lang.Object
  extended by com.nuance.nmdp.speechkit.SpeechKit

public final class SpeechKit
extends java.lang.Object

This is the SpeechKit core class providing setup and utility methods.

Only one SpeechKit object may be in use at a time, and this is enforced via the static initialize(android.content.Context, java.lang.String, java.lang.String, int, byte[])() method. SpeechKit initializes and manages core networking, recognition, and audio system components, and provides methods for creating Recognizer and Vocalizer instances.


Method Summary
 void cancelCurrent()
          If there is an active recognition or vocalization, cancel it.
 void connect()
          Open the connection to the server if it is not already connected.
 Recognizer createRecognizer(java.lang.String type, int detection, java.lang.String language, Recognizer.Listener listener, android.os.Handler callbackHandler)
          Create a single-use Recognizer object.
 Vocalizer createVocalizerWithLanguage(java.lang.String language, Vocalizer.Listener listener, android.os.Handler callbackHandler)
          Create a Vocalizer initialized with a language.
 Vocalizer createVocalizerWithVoice(java.lang.String voice, Vocalizer.Listener listener, android.os.Handler callbackHandler)
          Create a Vocalizer initialized with a voice.
 Prompt defineAudioPrompt(int resourceId)
          Define an audio prompt from a raw audio resource ID.
 java.lang.String getSessionId()
          This method provides the most recent session ID.
static SpeechKit initialize(android.content.Context appContext, java.lang.String id, java.lang.String host, int port, byte[] applicationKey)
          This method configures the SpeechKit subsystems.
 void release()
          Release the resources owned by SpeechKit.
 void setDefaultRecognizerPrompts(Prompt recordingStart, Prompt recordingStop, Prompt result, Prompt error)
          Set the default audio or vibration Prompts for Recognizers to use.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

initialize

public static SpeechKit initialize(android.content.Context appContext,
                                   java.lang.String id,
                                   java.lang.String host,
                                   int port,
                                   byte[] applicationKey)
This method configures the SpeechKit subsystems.

This method starts the necessary underlying components of the SpeechKit framework. Ensure that the applicationKey parameter contains your correct application key. On calling this method, the SpeechKit object that is returned can be used to perform recognitions and vocalizations.

Calling this method does not initiate a connection with the Nuance speech server. The connection will be established automatically upon starting a recognition or vocalization. To establish a connection in advance, see connect()().

If a SpeechKit is already initialized with the given configuration, this method will simply return the existing SpeechKit instance. If the configuration has changed, the old SpeechKit will be released and a new one will be returned.

Parameters:
appContext - The Android application context.
id - Application identification.
host - The Nuance speech server hostname or IP address.
port - The Nuance speech server port.
applicationKey - Your private application key used for server authentication.
Returns:

release

public void release()
Release the resources owned by SpeechKit.

After calling this method, the SpeechKit instance will no longer be usable, and references should be released to allow for garbage collection. Any Recognizer, Vocalizer, or Prompt objects will also be unusable. To use SpeechKit again, simply call initialize(android.content.Context, java.lang.String, java.lang.String, int, byte[])().


connect

public void connect()
Open the connection to the server if it is not already connected.

Call this function to avoid latency later. This will ping the Nuance speech server and leave the connection open so that the next recognition or vocalization will not be delayed by opening the connection.

Calling this function is optional. SpeechKit will automatically connect to the server when necessary.


createRecognizer

public Recognizer createRecognizer(java.lang.String type,
                                   int detection,
                                   java.lang.String language,
                                   Recognizer.Listener listener,
                                   android.os.Handler callbackHandler)
Create a single-use Recognizer object.

By default, the Recognizer will not play any audio or vibration Prompts. If setDefaultRecognizerPrompts(com.nuance.nmdp.speechkit.Prompt, com.nuance.nmdp.speechkit.Prompt, com.nuance.nmdp.speechkit.Prompt, com.nuance.nmdp.speechkit.Prompt)() has been called, the specified prompts will be played at the specified times. To add custom prompts to this particular Recognizer, use Recognizer.setPrompt(int, com.nuance.nmdp.speechkit.Prompt)().

Parameters:
type - The recognition type. This allows the server to better anticipate the type of phrases the user is likely to say as well as selecting an appropriate vocabulary of words that the user might say and therefore has an impact on recognition accuracy. This type should be specified using one of the predefined strings in Recognizer.RecognizerType unless otherwise specified.
detection - The end of speech detection model used to automatically determine that speech has stopped. Choose this value from Recognizer.EndOfSpeechDetection to reflect the amount of allowable silence within an utterance. This detector is a second way that recording may be stopped, in addition to calling stopRecording on this object in response to a user action.
language - This is language spoken by the user and is expressed as an ISO 639 language code, followed by an underscore "_", followed by the ISO 3166-1 country code. For example, an English speaker from the United States would be expressed as "en_US". A complete list of supported language tags can be found at http://dragonmobile.nuancemobiledeveloper.com/faq.php.
listener - The Recognizer.Listener for recognition responses. The listener will receive notifications when recording starts and stops, when a Recognition result is received, and when a SpeechError occurs.
callbackHandler - An optional Handler that all listener methods will be processed on. If this is null, all listener methods will be called from SpeechKit's thread.
Returns:
The Recognizer object corresponding to the recognition request. Call its start() method to begin the recognition. If the SpeechKit object has been released, this will return null.

createVocalizerWithLanguage

public Vocalizer createVocalizerWithLanguage(java.lang.String language,
                                             Vocalizer.Listener listener,
                                             android.os.Handler callbackHandler)
Create a Vocalizer initialized with a language.

The Vocalizer object is used as a text to speech service. A default voice will be chosen by the server based on the language selection. After initializing, the speak methods can be called repeatedly to enqueue sequences of spoken text. Each spoken string will result in one or more listener methods called to inform the receiver of speech progress. At any point speech can be stopped with the cancel method.

Parameters:
language - The language tag in the format of the ISO 639 language code, followed by an underscore "_", followed by the ISO 3166-1 country code. This language should correspond to the language of the text provided to the Vocalizer.speakString(java.lang.String, java.lang.Object)() method. See http://dragonmobile.nuancemobiledeveloper.com/faq.php for a list of supported languages and voices.
listener - The Vocalizer.Listener for vocalization progress. The listener will receive notifications when speech starts and stops, or when a SpeechError occurs.
callbackHandler - An optional Handler that all listener methods will be processed on. If this is null, all listener methods will be called from SpeechKit's thread.
Returns:
The Vocalizer object corresponding to the speech request. If the SpeechKit object has been released, this will return null.

createVocalizerWithVoice

public Vocalizer createVocalizerWithVoice(java.lang.String voice,
                                          Vocalizer.Listener listener,
                                          android.os.Handler callbackHandler)
Create a Vocalizer initialized with a voice.

This initializer provides more fine grained control than the createVocalizerWithLanguage(java.lang.String, com.nuance.nmdp.speechkit.Vocalizer.Listener, android.os.Handler)() method by allowing for the selection of a particular voice. For example, this allows for explicit choice between male and female voices in some languages. The Vocalizer object returned may be used exactly as initialized in the createVocalizerWithLanguage(java.lang.String, com.nuance.nmdp.speechkit.Vocalizer.Listener, android.os.Handler)() case.

Parameters:
voice - The specific voice to use for speech. The list of supported voices sorted by language can be found at http://dragonmobile.nuancemobiledeveloper.com/faq.php.
listener - The Vocalizer.Listener for vocalization progress. The listener will receive notifications when speech starts and stops, or when a SpeechError occurs.
callbackHandler - An optional Handler that all listener methods will be processed on. If this is null, all listener methods will be called from SpeechKit's thread.
Returns:
The Vocalizer object corresponding to the speech request. If the SpeechKit object has been released, this will return null.

getSessionId

public java.lang.String getSessionId()
This method provides the most recent session ID.

If there is an active connection to the server, this method provides the session ID of that connection. If no connection to the server currently exists, this method provides the session ID of the previous connection. If no connection to the server has yet been made, this method returns null.

Returns:
Session ID as a string or null if no connection has been established yet.

defineAudioPrompt

public Prompt defineAudioPrompt(int resourceId)
Define an audio prompt from a raw audio resource ID.

The resource is loaded using a MediaPlayer, so ensure that your audio resource is properly supported by MediaPlayer (i.e., MediaPlayer.create(context, resourceId) returns non-null). Audio prompts may consume significant system resources, so it is recommended to minimize the number of audio prompts. Releasing the prompt will free the resources it consumes, but render the prompt unusable. All unreleased audio prompts will be released when SpeechKit is released.

To obtain a vibration prompt object, see Prompt.vibration(int)().

Parameters:
resourceId - The resource ID (e.g. R.raw.soundfile). Must be a raw uncompressed resource.
Returns:
A Prompt object, which can be used to cause a Recognizer to play audio at certain stages of the recognition. Returns null if the resource can't be opened or if the SpeechKit object has been released.

setDefaultRecognizerPrompts

public void setDefaultRecognizerPrompts(Prompt recordingStart,
                                        Prompt recordingStop,
                                        Prompt result,
                                        Prompt error)
Set the default audio or vibration Prompts for Recognizers to use.

When recognizers are created, they will use these default prompts. To configure specific prompts for specific Recognizers, call Recognizer.setPrompt(int, com.nuance.nmdp.speechkit.Prompt)().

Parameters:
recordingStart - The prompt to play when recording begins. Pass null if no default recording start prompt is desired.
recordingStop - The prompt to play when listening ends. Pass null if no default recording stop prompt is desired.
result - The prompt to play when a result is received. Pass null if no default result prompt is desired.
error - The prompt to play when an error occurs. Pass null if no default error prompt is desired.

cancelCurrent

public void cancelCurrent()
If there is an active recognition or vocalization, cancel it. Does nothing if there is no active recognition or vocalization.

This is equivalent to calling Recognizer.cancel()() or Vocalizer.cancel()().