Overview | Package | Class | Tree | Index | Help | |||
PREV CLASS | NEXT CLASS | FRAMES | NO FRAMES | ||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Recognizer
provides access to speech recognition
capabilities. The Recognizer
interface extends the
javax.speech.Engine
interface and so inherits the basic engine capabilities and
provides additional specialized capabilities.
The primary capabilities provided by a recognizer are grammar management and
result handling. An application is responsible for providing a recognizer
with grammars. A Grammar
defines a set
of words (technically known as tokens) and defines patterns in which the tokens may
be spoken. When a grammar is active the recognizer listens for speech
in the incoming audio which matches the grammar. When speech is detected
the recognizer produces a Result
. The result object
is passed to the application and contains information on which words were heard.
The types of grammars, mechanisms for creating, modifying and managing grammars, types of results, result handling and other recognizer functions are described in more detail below.
Creating a Recognizer
A Recognizer
is created by a call to
createRecognizer
method of the Central
class.
Detailed descriptions of the procedures for locating, selecting, creating and
initializing a Recognizer are provided in the documentation for
Central
.
Inherited and Extended Engine Capabilities
The Recognizer
interface and the other classes and
interfaces of the javax.speech.recognition
package
extend and modify the basic engine capabilities in the following ways.
Central.availableRecognizers
method and EngineModeDesc
.
EngineModeDesc
as
RecognizerModeDesc
.
allocate
and
deallocate
methods from
Engine
.
pause
and
resume
methods from
Engine
.
getEngineState
,
waitEngineState
and
testEngineState
methods from the
Engine
interface for handling
engine state.
DEALLOCATED
,
ALLOCATED
,
ALLOCATING_RESOURCES
and
DEALLOCATING_RESOURCES
states from the
Engine
interface.
PAUSED
and
RESUMED
sub-states
of the ALLOCATED
state.
PROCESSING
,
LISTENING
and
SUSPENDED
sub-states
of the ALLOCATED
state.
FOCUS_ON
and
FOCUS_OFF
sub-states
of the ALLOCATED
state.
requestFocus
and
releaseFocus
methods for managing an application's speech focus.
suspend
,
commitChanges
.
Engine.getAudioManager
and AudioManager
.
Engine.getEngineProperties
method adds the getRecognizerProperties
so that a cast is not required.
RecognizerAudioListener
and RecognizerAudioEvent
.
Engine.getVocabManager
and VocabManager
.
addEngineListener
and
removeEngineListener
methods from the
Engine
interface.
EngineListener
interface
as RecognizerListener
.
Grammar
,
RuleGrammar
,
DictationGrammar
GrammarEvent
,
and
GrammarListener
,
Result
,
FinalResult
,
FinalRuleResult
,
FinalDictationResult
,
ResultListener
and
ResultEvent
.
Grammars
The creation, modification, enabling, activation and other management of grammars is a core function provided by any recognizer. A recognizer must be provided with one or more grammars that indicate what words and word sequences it should listen for. The basic process for dealing with a grammar are:
Grammar
or obtain a reference
to an existing grammar.
ResultListener
to either the
Recognizer
or Grammar
to get
Result
events.
Grammar
for recognition as required.
Each grammar must be identified by a unique grammar name
which is defined when the Grammar
is created.
The following methods deal with grammar names:
Grammar.getName
returns the name of a Grammar
object.
getRuleGrammar
returns a reference to a Grammar given the grammar's names.
A Recognizer
provides several methods for the creation and loading of
RuleGrammars
:
newRuleGrammar
:
create a RuleGrammar
from scratch
loadJSGF
: create a
RuleGrammar
(s)
from Java Speech Grammar Format text obtained from either a
Reader
or a
URL
.
The advanced
loadJSGF
method provides additional load controls.
readVendorGrammar
:
read a grammar stored in a vendor-specific (non-portable) format.
Other important rule grammar functions are:
deleteRuleGrammar
deletes a loaded grammar.
listRuleGrammars
returns an array
of references to all grammars loaded into a Recognizer
.
RuleGrammar.toString
produces a string representing a RuleGrammar
in Java Speech Grammar Format.
writeVendorGrammar
: write a grammar
in a vendor-specific (non-portable) format.
In addition to RuleGrammars
that an application creates, some recognizers
have "built-in" grammars. A built-in grammar is automatically loaded into
the recognizer when the recognizer is created and are accessible
through the listRuleGrammars
method. Different recognizers
will have different built-in grammars so applications should not rely
upon built-in grammars if they need to be portable.
A DictationGrammar
is the most important kind of built-in
grammar. A dictation grammar supports relatively free-form input of
text. If a recognizer supports dictation, then the
getDictationGrammar
method returns non-null and the
isDictationGrammarSupported
method of the
RecognizerModeDesc
returns true.
Grammar Scope
Each Recognizer
object has a separate name-space. Applications should
be aware that changes to a Grammar
object affect any part of the
application that uses that Grammar
. However, if two separate applications
create a Recognizer
and use a Grammar
with the same name, they
are effectively independent - changes by on app do not affect the
operation of the other app.
Efficiency
The processing of grammars (particularly large grammars) can be
computationally expensive. Loading a new grammar
can take seconds or sometimes minutes. Updates to a
Grammar
may also be slow. Therefore, applications should take
precautions to build grammars in advance and to modify them only
when necessary. Furthermore, an application should
minimize the number of grammars active at any point in time.
Recognizer States
A Recognizer
inherits the PAUSED
and
RESUMED
sub-states of the ALLOCATED
from the Engine
interface. The Recognizer
interface adds two more independent sub-states systems to
the ALLOCATED
state:
LISTENING
, PROCESSING
, SUSPENDED
FOCUS_ON
, FOCUS_OFF
A Recognizer
adds the two state sub-state-system for
FOCUS_ON
and FOCUS_OFF
to indicate
whether this instance of the Recognizer
currently
has the speech focus. Focus is important in a multi-application
environment because more than one application can connect to
an underlying speech recognition engine, but the user gives
speech focus to only one application at a time. Since it is
normal for an application to use only one Recognizer
,
Recognizer
focus and application focus normally
mean the same thing. (Multi-recognizer apps cannot make this
assumption.)
Focus is not usually relevant in telephony applications in which there is a single input audio stream to a single application.
The focus status is a key factor in determining the activation of
grammars and therefore in determining when results will and will
not be generated. The activation conditions for grammars and the
role of focus are described in the documentation for the
Grammar
interface.
When recognizer focus is received a FOCUS_GAINED
event
is issued to RecognizerListeners
. When recognizer
focus is released or otherwise lost, a FOCUS_LOST
event is issued to RecognizerListeners
.
Applications can request speech focus for the Recognizer
by calling the requestFocus
mechanism. This
asynchronous method may return before focus in received.
To determine when focus is on, check for FOCUS_GAINED
events or test the FOCUS_ON
bit of engine state.
Applications can release speech focus from the Recognizer
by calling the releaseFocus
mechanism. This
asynchronous method may return before focus in lost.
To determine whether focus is off, check for FOCUS_LOST
events or test the FOCUS_OFF
bit of engine state.
In desktop environments, it is normal (but not a requirement) for
speech focus to follow window focus. Therefore, it is common
for the requestFocus
method to be called on
AWT events or Swing events such as FocusEvent
and
WindowEvent
.
A well-behaved application only requests focus when it knows that it has the speech focus of the user (the user is talking to it and not to other applications). A well-behaved application will also release focus as soon as it finishes with it.
Recognizer States: Result Recognition
A Recognizer
adds the three state sub-state-system for
LISTENING
, PROCESSING
and
SUSPENDED
to indicate the status of the
recognition of incoming speech. These three states are loosely
coupled with the PAUSED
and RESUMED
states
but only to the extent that turning on and off audio input will
affect the recognition process. An ALLOCATED
recognizer
is always in one of these three states:
LISTENING
state: the Recognizer
is listening to incoming audio for speech that may match an
active grammar but has not detected speech yet.
PROCESSING
state: the Recognizer
is processing incoming speech that may match an active
grammar to produce a result.
SUSPENDED
state: the Recognizer
is temporarily suspended while grammars are updated.
While suspended, audio input is buffered for processing
once the recognizer returns to the LISTENING
and PROCESSING
states.
Recognizer States: Result Recognition: Typical Event Cycle
The typical state cycle is as follows.
Recognizer
starts in the LISTENING
state with a certain set of grammars enabled. When incoming
audio is detected that may match an active grammar, the
Recognizer
transitions to the PROCESSING
state with a RECOGNIZER_PROCESSING
RecognizerEvent
.
The Recognizer
then creates a new Result
and issues a RESULT_CREATED
event to provide
it to the application.
Recognizer
remains in the PROCESSING
state until it completes recognition of the result.
RECOGNIZER_SUSPENDED
RecognizerEvent
to transition from the
PROCESSING
state to the SUSPENDED
state. Once in that state, it issues a result finalization
event to ResultListeners
(RESULT_ACCEPTED
or RESULT_REJECTED
event).
Recognizer
remains in the SUSPENDED
state until processing of the result finalization event
is completed. Applications will usually make any necessary
grammar changes while the recognizer is SUSPENDED
.
In this state the Recognizer
buffers incoming audio.
This buffering allows a user to continue speaking without speech
data being lost. Once the Recognizer
returns to the LISTENING
state the buffered audio
is processed to give the user the perception of real-time
processing.
Recognizer
commits all grammar changes, issues a CHANGES_COMMITTED
event to RecognizerListeners
to return to the
LISTENING
state. It also issues GRAMMAR_CHANGES_COMMITTED
events to GrammarListeners
of changed grammars.
The commit applies all grammar changes made at any point up to
the end of result finalization, typically including changes made in
the result finalization events.
Recognizer
is back in the LISTENING
state listening for speech that matches the new grammars.
RECOGNIZER_PROCESSING
and
RECOGNIZER_SUSPENDED
events are triggered by user
actions: starting and stopping speaking. The third state
transition -- CHANGES_COMMITTED
-- is triggered
programmatically some time after the RECOGNIZER_SUSPENDED
event.
Recognizer States: Result Recognition: Non-Speech Events
For applications that deal only with spoken input the state
cycle above handles most normal speech interactions. For
applications that handle other asynchronous input, additional state
transitions are possible. Other types of asynchronous input
include graphical user interface events (e.g., AWTEvents
),
timer events, multi-threading events, socket events and much more.
When a non-speech event occurs which changes the application state or applicatin data it is often necessary to update the recognizer's grammars. Furthermore, it is typically necessary to do this as if the change occurred in real time - at exactly the point in time at which the event occurred.
The suspend
and commitChanges
methods of a Recognizer
are used to handle
non-speech asynchronous events. The typical cycle for
updating grammars is as follows:
Recognizer
is in the
LISTENING
state (the user is not currently
speaking). As soon as the event is received, the
application calls suspend
to
indicate that it is about to change grammars.
RECOGNIZER_SUSPENDED
event and transitions from the LISTENING
state to the SUSPENDED
state.
commitChanges
method. The recognizer
applies the new grammars, issues a CHANGES_COMMITTED
event to transition from the SUSPENDED
state back to the LISTENING
, and issues
GRAMMAR_CHANGES_COMMITTED
events to all
changed grammars.
Recognizer
resumes recognition of the
buffered audio and then live audio with the new grammars.
Because audio is buffered from the time of the asynchronous
event to the time at which the CHANGES_COMMITTED
occurs, the audio is processed as if the new grammars
were applied exactly at the time of the asynchronous event.
The user has the perception of real-time processing.
Although audio is buffered in the SUSPENDED
state, applications should makes changes and commitChanges
as quickly as possible. This minimizes the possibility of
a buffer overrun. It also reduces delays in recognizing
speech and responding to the user.
Note: an application is not technically required to
call suspend
prior to calling commitChanges
.
If the suspend
call is ommitted the
Recognizer
behaves as if suspend
had been called immediately prior to calling commitChanges
.
An application that does not call suspend
risks
a commit occurring unexpectedly and leaving grammars in
an inconsistent state.
Recognizer States: Result Recognition: Mixing Speech and Non-Speech Events
There is no guarantee that a speech and non-speech events will not be mixed. If a speech event occurs in the absence of non-speech events, the normal event cycle takes place. If a non-speech event occurs in the absence of any speech events, the non-speech event cycle takes place.
We need to consider two cases in which speech and non-speech events interact: (1) when a non-speech event occurs during the processing of a speech event, and (2) when a speech event occurs during the processing of a non-speech event.
Recognizer
is in either the
PROCESSING
state or the SUSPENDED
state. In both cases the event processing for the non-speech
is no different than normal. The non-speech event handler
calls suspend
to indicate it is about
to change grammars, makes the grammar changes, and then
calls commitChanges
to apply the changes.
CHANGES_COMMITTED
event that would normally occur in the normal event cycle
may be delayed until the commitChanges
method
is explicitly called and that the commit applies changes
made in response to both the speech and non-speech events.
If the commitChanges
call for the non-speech
event is made before the end of the result finalization event,
there is no delay of the CHANGES_COMMITTED
event.
Recognizer
is in the SUSPENDED
state, that speech
is buffered, and the speech event is actually delayed until
the Recognizer
returns to the LISTENING
state. Once the Recognizer
returns to the
LISTENING
state, the incoming speech is
processed with the normal event cycle.
Field Summary | |
static long | FOCUS_OFF
FOCUS_OFF is the bit of state that is set when
an ALLOCATED Recognizer does not
have the speech focus of the underlying speech recognition engine.
|
static long | FOCUS_ON
FOCUS_ON is the bit of state that is set when
an ALLOCATED Recognizer has the
speech focus of the underlying speech recognition engine.
|
static long | LISTENING
LISTENING is the bit of state that is set when
an ALLOCATED Recognizer is listening
to incoming audio for speech that may match an active grammar
but has not yet detected speech.
|
static long | PROCESSING
PROCESSING is the bit of state that is set when
an ALLOCATED Recognizer is producing
a Result for incoming speech that may match an
active grammar.
|
static long | SUSPENDED
SUSPENDED is the bit of state that is set
when an ALLOCATED Recognizer is
temporarily suspended while grammar definition and grammar
enabled settings are updated.
|
Method Summary | |
void | addResultListener(ResultListener listener)
Request notifications of all events for all Result
produced by this Recognizer . |
void | commitChanges()
Commit changes to all loaded grammars and all changes of grammar enabling since the last commitChanges .
|
void | deleteRuleGrammar(RuleGrammar grammar)
Delete a RuleGrammar from the Recognizer .
|
void | forceFinalize(boolean flush)
If the Recognizer is in the PROCESSING state
(producing a Result ), force the Recognizer
to immediately complete processing of that result by finalizing it.
|
DictationGrammar | getDictationGrammar(String name)
Return the DictationGrammar for a Recognizer .
|
RecognizerProperties | getRecognizerProperties()
Return the RecognizerProperties object (a JavaBean).
|
RuleGrammar | getRuleGrammar(String name)
Get the RuleGrammar with the specified name.
|
SpeakerManager | getSpeakerManager()
Return an object which provides management of the speakers of a Recognizer . |
RuleGrammar[] | listRuleGrammars()
List the RuleGrammars known to the Recognizer .
|
RuleGrammar | loadJSGF(Reader JSGF)
Create a RuleGrammar from Java Speech Grammar Format text
provided by the Reader . |
RuleGrammar | loadJSGF(URL context,
String grammarName)
Load a RuleGrammar and its imported grammars
from Java Speech Grammar Format text from URLs or from system
resources. |
RuleGrammar | loadJSGF(URL context,
String grammarName,
boolean loadImports,
boolean reloadGrammars,
Vector loadedGrammars)
Load a RuleGrammar in Java Speech Grammar Format text
from a URL or from system resources and optionally load its imports.
|
RuleGrammar | newRuleGrammar(String name)
Create a new RuleGrammar for this recognizer with
a specified grammar name. |
Grammar | readVendorGrammar(InputStream input)
Create a new grammar by reading in a grammar stored in a vendor-specific format. |
Result | readVendorResult(InputStream output)
Read a Result object from a stream in a vendor-specific format.
|
void | releaseFocus()
Release the speech focus from this Recognizer .
|
void | removeResultListener(ResultListener listener)
Remove a ResultListener from this Recognizer .
|
void | requestFocus()
Request the speech focus for this Recognizer from
the underlying speech recognition engine. |
void | suspend()
Temporarily suspend recognition while the application updates grammars prior to a commitChanges call. |
void | writeVendorGrammar(OutputStream output,
Grammar grammar)
Store a grammar in a vendor-specific format. |
void | writeVendorResult(OutputStream output,
Result result)
Store a finalized Result object in a vendor-specific format so
that it can be re-loaded in a future session. |
Field Detail |
public static final long LISTENING
LISTENING
is the bit of state that is set when
an ALLOCATED
Recognizer
is listening
to incoming audio for speech that may match an active grammar
but has not yet detected speech.
A
RECOGNIZER_PROCESSING
event is issued to
indicate a transition out of the LISTENING
state and into the PROCESSING
state.
A
RECOGNIZER_SUSPENDED
event is issued to
indicate a transition out of the LISTENING
state and into the SUSPENDED
state.
A
CHANGES_COMMITTED
event is issued to
indicate a transition into the LISTENING
state from the SUSPENDED
state.
public static final long PROCESSING
PROCESSING
is the bit of state that is set when
an ALLOCATED
Recognizer
is producing
a Result
for incoming speech that may match an
active grammar.
A
RECOGNIZER_SUSPENDED
event is issued to
indicate a transition out of the PROCESSING
state and into the SUSPENDED
state
when recgonition of a Result
is completed.
A
RECOGNIZER_PROCESSING
event is issued to
indicate a transition into the PROCESSING
state from the LISTENING
state when
the start of a new result is detected.
public static final long SUSPENDED
SUSPENDED
is the bit of state that is set
when an ALLOCATED
Recognizer
is
temporarily suspended while grammar definition and grammar
enabled settings are updated.
The Recognizer
enters this state whenever
recognition of a Result
is finalized, and
in response to a call to suspend
.
The primary difference between the SUSPENDED
and PAUSED
states of a Recognizer
is
that audio input is buffered in the SUSPENDED
state. By contrast, the PAUSED
state indicates
that audio input to the Recognizer
is being ignored.
In addition, the SUSPENDED
state is
a temporary state, whereas a Recognizer
can stay in the PAUSED
state indefinately.
A
CHANGES_COMMITTED
event is issued to
indicate a transition out of the SUSPENDED
state and into the LISTENING
state when
all changes to grammars are committed to the recognition process.
A
RECOGNIZER_SUSPENDED
event is issued to
indicate a transition into the SUSPENDED
state from either the LISTENING
state or
PROCESSING
state.
public static final long FOCUS_ON
FOCUS_ON
is the bit of state that is set when
an ALLOCATED
Recognizer
has the
speech focus of the underlying speech recognition engine.
As recognizer focus is gained and lost, a
FOCUS_GAINED
or FOCUS_LOST
event is issued to indicate the state change. The
requestFocus
and releaseFocus
methods allow management of speech focus.
public static final long FOCUS_OFF
FOCUS_OFF
is the bit of state that is set when
an ALLOCATED
Recognizer
does not
have the speech focus of the underlying speech recognition engine.
As recognizer focus is gained and lost, a
FOCUS_GAINED
or FOCUS_LOST
event is issued to indicate the state change. The
requestFocus
and releaseFocus
methods allow management of speech focus.
Method Detail |
public RuleGrammar newRuleGrammar(String name) throws IllegalArgumentException, EngineStateError
RuleGrammar
for this recognizer with
a specified grammar name. The new grammar is used for
recognition only after
changes are committed.
The newRuleGrammar
method operates as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
name
- name of the grammar to be createdRecognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic RuleGrammar loadJSGF(Reader JSGF) throws GrammarException, IOException, EngineStateError
RuleGrammar
from Java Speech Grammar Format text
provided by the Reader
. If the grammar contained
in the Reader
already exists, it is over-written.
The new grammar is used for recognition only after
changes are committed.
It is often useful to load JSGF from a String
by creating a StringReader
object with that string.
The caller is responsible for determining the character encoding of the JSGF document. The character encoding information contained in the JSGF header is ignored.
The loadJSGF
methods operate as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
JSGF
- the Reader from which the grammar text is loadedRecognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic RuleGrammar loadJSGF(URL context, String grammarName) throws GrammarException, MalformedURLException, IOException, EngineStateError
RuleGrammar
and its imported grammars
from Java Speech Grammar Format text from URLs or from system
resources. The loaded grammars are used for recognition only after
changes are committed.
The method returns a reference to the named RuleGrammar
.
The method never returns null
since an exception is
thrown if grammarName
cannot be loaded successfully.
The method attempts to load all imports of grammarName
,
all imports of the imported grammars, and so on. This recursive
load stops when grammars are reached that have already been
loaded or when no more imports are found. The intent is to
ensure that every grammar needed to use the named grammar is loaded.
For example, if we load grammar X, which imports grammar Y, which imports grammars A and B, then all four grammars are loaded. If any of the grammars are already loaded, then it and its imports are not reloaded.
JSGF allows fully-qualified rulename references without a corresponding import statement. This method also attempts to load all grammars referenced by a fully-qualified rulename not already referenced and loaded by a corresponding import statement.
The advanced loadJSGF method provides more control of the loading process. This method is equivalent to:
loadJSGF(url, name, true, false, null);(load imports, don't reload existing grammars, don't provide a list of loaded grammars.)
Locating Grammars
The context
URL parameter is used as the first
parameter of the URL(URL, String)
constructor in
the java.net
package.
The grammarName
is converted to a grammar filename.
The conversion changes each each period character ('.') to a
file separator ('/'). The ".gram" suffix is appended to identify
the grammar file. The grammarName
"com.sun.numbers"
becomes the filename "com/sun/numbers.gram". This filename is
used as the spec
parameter in the URL constructor.
For example,
loadJSGF(new URL("http://www.sun.com/"), "com.sun.numbers")will look for the grammar in the URL "http://www.sun.com/com/sun/numbers.gram" and for its imports in a similar location.
If the derived URL does not exist, loadJSGF
checks
for a system resource with the grammar file using the
ClassLoader.getSystemResource
method. This allows
grammars to be included in the CLASSPATH
.
If the context
is null
, the grammars are
searched for only as a system resource.
Reading Grammars
For each grammar it loads, the recognizer determines the file's character encoding by reading the JSGF header.
An exception is thrown if (1) any JSGF syntax problems are found, (2) if a grammar found in a URL does not match the expected name, or (3) if a grammar cannot be located as either a URL or system resource.
If an exception is thrown part way through loading a set of grammars the list of loaded grammars not explicitly available. The recognizer does not attempt to remove any partially loaded grammars.
The loadJSGF
methods operate as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
base
- the URL context from which grammar locations are derived or
null to load exclusively from system resources
grammarName
- the name of the grammar to be loadedgrammarName
Recognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic RuleGrammar loadJSGF(URL context, String grammarName, boolean loadImports, boolean reloadGrammars, Vector loadedGrammars) throws GrammarException, MalformedURLException, IOException, EngineStateError
RuleGrammar
in Java Speech Grammar Format text
from a URL or from system resources and optionally load its imports.
This method provide an additional control over whether grammars
are reloaded even if they have already been loaded, and allows
caller to receive a list of all grammars loaded by the Recognizer
.
The loaded grammars are used for recognition only after
changes are committed.
The three additional parameters of this method provide the following extensions over the loadJSGF(URL, String) method:
loadImports
: if false
, the method
only loads the RuleGrammar
specified by the
name
parameter.
true
, the method behaves like the
loadJSGF(URL, String)
method and recursively loads imported grammars.
reloadGrammars
: if true
, the method
always loads a RuleGrammar
, even if it is
already loaded into the Recognizer
. The previous
version of the grammar is overwritten.
false
, the method behaves like the
loadJSGF(URL, String)
method and does not load grammars that are already loaded, or
their imports.
loadedGrammars
: if non-null, then as the
Recognizer
loads any grammar it appends a
reference to that RuleGrammar
to the Vector
.
base
- the URL context from which grammar locations are derived or
null to load exclusively from system resources
grammarName
- the name of the grammar to be loaded
loadImports
- if true
, grammars imported by grammarName
are loaded plus their imports
reloadGrammars
- if true
reload all grammars and imports, if false
do not load grammars already loaded into the Recognizer
loadedGrammars
- if non-null a reference to each loaded RuleGrammar
is appended as it is loadedgrammarName
Recognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic RuleGrammar getRuleGrammar(String name) throws EngineStateError
RuleGrammar
with the specified name.
Returns null
if the
grammar is not known to the Recognizer.
The getRuleGrammar
method operates as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
name
- the name of the grammar to be returnedRuleGrammar
reference or null
Recognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic RuleGrammar[] listRuleGrammars() throws EngineStateError
RuleGrammars
known to the Recognizer
.
Returns null
if there are no grammars.
The listRuleGrammars
method operates as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
Recognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic void deleteRuleGrammar(RuleGrammar grammar) throws IllegalArgumentException, EngineStateError
RuleGrammar
from the Recognizer
.
The grammar deletion only takes effect when all
grammar changes are committed.
Recognizers may chose to ignore the deletion of built-in grammars.
The deleteRuleGrammar
method operates as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
Recognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic DictationGrammar getDictationGrammar(String name) throws EngineStateError
DictationGrammar
for a Recognizer
.
Typically, the name
parameter is null
to
get access to the default DictationGrammar
for the
Recognizer
.
If the Recognizer
does not support dictation, or
if it does have a DictationGrammar
with the specified
name, then the method returns null
.
An application can determine whether the Recognizer
supports dictation by calling the isDictationGrammarSupported
method of the RecognizerModeDesc
.
Note: the name
parameter is provided for future extenion
of the API to allow more than one DictationGrammar
to
be defined.
The getDictationGrammar
method operates as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
Recognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic void commitChanges() throws GrammarException, EngineStateError
commitChanges
.
Because all changes are applied atomically (all at once)
the application does not need to be concerned with intermediate
states as it changes grammar definitions and enabling.
The commitChanges
call first checks that all the loaded
grammars are legal. If there are any problems with the
current definition of any RuleGrammar
an
exception is thrown. Problems might include undefined
rule name, illegal recursion and so on (see the
Java Speech Grammar Format Specification and the
GrammarSyntaxDetail
class documentation for details).
The commitChanges
call is asynchronous (the changes
have not necessarily been committed when the call returns).
When the changes have been committed, a CHANGES_COMMITTED
event is issued to all RecognizerListeners
and to the
GrammarListeners
of all changed Grammars
.
Immediately following the CHANGES_COMMITTED
event,
a GRAMMAR_CHANGES_COMMITTED
GrammarEvent
is issued to the GrammarListeners
of all changed grammars.
The roll of commitChanges
in
applying grammar changes in described in the documentation for the
Grammar
interface.
The effect of the commitChanges
method upon
Recognizer
states is
described above. The use of suspend
with commitChanges
and their use for processing
asynchronous non-speech events
are also described above.
It is not an error to commitChanges
when no
grammars have been changed. However, the Recognizer
performs state transitions in the same way as when grammars
are changed.
The commitChanges
method operates as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
Recognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic void suspend() throws EngineStateError
commitChanges
call. The
suspend
call places the Recognizer
in the SUSPENDED
state. While in that state
the incoming audio is buffered. The buffered audio is processed
after the recognizer has committed grammar changes and returned to
the LISTENING
state.
The primary difference between the suspend
and
pause
methods is that audio is buffered while
a Recognizer
is suspended whereas incoming audio is ignored
while in the PAUSED
state. Also, the SUSPENDED
state should only be visited temporarily, whereas a
Recognizer
can be PAUSED
indefinately.
The suspend
method is asynchronous. When
the call returns, the recognizer is not necessarily suspended.
The getEngineState
method, or the
RECOGNIZER_SUSPENDED
events can be used to determine
when the recognizer is actually suspended.
The use of suspend
with commitChanges
for handling atomic grammar changes and for handling
asynchronous events are described above.
Calls to suspend
and commitChanges
do not nest. A single call to commitChanges
can release the Recognizer
after multiple
calls to suspend
.
The suspend
method operates as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
Recognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic void forceFinalize(boolean flush) throws EngineStateError
Recognizer
is in the PROCESSING
state
(producing a Result
), force the Recognizer
to immediately complete processing of that result by finalizing it.
It is acceptable behavior for a Recognizer
to
automatically reject the current result.
The flush
flag indicates whether the recognizer's
internally buffered audio should be processed before forcing the
finalize. Applications needing immediate cessation of recognition
should request a flush. If the force finalize is a response to
a user event (e.g. keyboard or mouse press) then the buffer is
typically not flushed because incoming speech from a user could be lost.
The state behavior of the Recognizer
is the
same as if the Result
had been finalized because
of end-of-utterance. The Recognizer
will transition
to the SUSPENDED
state.
The forceFinalize
method operates as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
Recognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic void requestFocus() throws EngineStateError
Recognizer
from
the underlying speech recognition engine. When the focus
is received, a FOCUS_GAINED
event is issued
to RecognizerListeners
and the Recognizer
changes state from FOCUS_ON
to FOCUS_OFF
.
Since one one application may have recognition focus at any time, applications should only request focus when confident that the user is speaking to that application. Speech focus and other focus issues are discussed above in more detail.
It is not an error for an application to request focus
for a Recognizer
that already has speech focus.
The requestFocus
method operates as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
Recognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic void releaseFocus() throws EngineStateError
Recognizer
.
A FOCUS_LOST
event is issued to
RecognizerListeners
once the focus
is released and the Recognizer
state changes
from FOCUS_OFF
to FOCUS_ON
.
Since one one application may have recognition focus at any time, applications should release focus whenever it is not required. Speech focus and other focus issues are discussed above in more detail.
It is not an error for an application to release focus
for a Recognizer
that does not have speech focus.
Focus is implicitly released when a Recognizer
is deallocated.
The releaseFocus
method operates as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
Recognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic void addResultListener(ResultListener listener)
Result
produced by this Recognizer
. An application
can attach multiple ResultListeners
to a
Recognizer
.
A listener is removed with the removeResultListener
method.
ResultListeners
attached to a Recognizer
are the only ResultListeners
to receive the
RESULT_CREATED
event and all subsequent events.
ResultListener
objects can also be attached to
any Grammar
or to any Result
.
A listener attached to the Grammar
receives
all events that match that Grammar
following a
GRAMMAR_FINALIZED
event.
A listener attached to a Result
receives
all events for that result from the time at which the listener
is attached.
A ResultListener
can be attached or removed in any
Engine
state.
public void removeResultListener(ResultListener listener)
ResultListener
from this Recognizer
.
A ResultListener
can be attached or removed in any
Engine
state.
public RecognizerProperties getRecognizerProperties()
RecognizerProperties
object (a JavaBean).
The method returns exactly the same object as the
getEngineProperties
method in the Engine
interface. However, with the getRecognizerProperties
method, an application does not need to cast the return value.
The RecognizerProperties
are available in any state of
an Engine
. However, changes only take effect once an
engine reaches the ALLOCATED
state.
RecognizerProperties
object for this enginepublic SpeakerManager getSpeakerManager() throws SecurityException
Recognizer
. Returns null
if the
Recognizer
does not store speaker data - that is,
if it is a speaker-independent recognizer in which
all speakers are handled the same.
A getSpeakerManager
returns successfully in any
state of a Recognizer
. The
SpeakerManager
methods that list speakers and set
the current speaker operate in any Recognizer
state
but only take effect in the ALLOCATED
state.
This allows an application can set the initial speaker
prior to allocating the engine. Other methods of the
SpeakerManager
only operate in the
ALLOCATED
state.
SpeakerManager
for this Recognizer
accessSpeakerProfiles
permissionpublic Grammar readVendorGrammar(InputStream input) throws VendorDataException, IOException, EngineStateError
If a grammar of the same name already exists, it is over-written.
The readVendorGrammar
method operates as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
input
- InputStream
from which grammar is loadedRecognizer
Recognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic void writeVendorGrammar(OutputStream output, Grammar grammar) throws IOException, EngineStateError
readVendorGrammar
method.
The output format will be specific to the type of recognizer that writes it. For example, data written by an Acme Command and Control Recognizer will be readable only by another Acme Command and Control Recognizer or by other recognizers that understand it's format. When portability is required, use the Java Speech Grammar Format.
Why is a Vendor grammar format useful? The recognizer can store
information that makes reloading of the grammar faster than
when JSGF is used. The recognizer may also store additional
information (e.g. pronunciation, statistical and acoustic data)
that improve recognition using this grammar.
The writeVendorGrammar
method operates as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
output
- OutputStream
where grammar is written
grammar
- Grammar
to be writtenRecognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic Result readVendorResult(InputStream output) throws VendorDataException, IOException, EngineStateError
Result
object from a stream in a vendor-specific format.
The return value will include the best-guess tokens, and may
include N-best results, audio data, timing data, training information and
other data the is optionally provided with a finalized Result
.
The call returns null
upon failure.
Because result objects are stored in a vendor-specific format
they cannot normally be loaded by incompatible recognizers.
The readVendorResult
method operates as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
input
- InputStream
from which Result
is loadedRecognizer
Recognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statespublic void writeVendorResult(OutputStream output, Result result) throws IOException, ResultStateError, EngineStateError
Result
object in a vendor-specific format so
that it can be re-loaded in a future session. All the current
information associated with the result is stored. If the application
will not need audio data or training information in a future session,
they should release that information (through the FinalResult
interface) before writing the result to reduce storage requirements.
The writeVendorGrammar
method operates as defined when
the Recognizer
is in the ALLOCATED
state.
The call blocks if the Recognizer
in the
ALLOCATING_RESOURCES
state and completes when the engine
reaches the ALLOCATED
state. An error is thrown
if the Recognizer
is in the DEALLOCATED
or
DEALLOCATING_RESOURCES
state.
output
- OutputStream
where the result is written
result
- Result
to be writtenResult
is not in a finalized stateRecognizer
in the DEALLOCATED
or
DEALLOCATING_RESOURCES
statesOverview | Package | Class | Tree | Index | Help | |||
PREV CLASS | NEXT CLASS | FRAMES | NO FRAMES | ||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
JavaTM Speech API
Copyright 1997-1998 Sun Microsystems, Inc. All rights reserved
Send comments to javaspeech-comments@sun.com