Overview | Package | Class | Tree | Index | Help | |||
PREV CLASS | NEXT CLASS | FRAMES | NO FRAMES | ||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
DictationGrammar
and RuleGrammar
.
A Grammar
defines a set of tokens (words) that may be
spoken and the patterns in which those tokens may be spoken.
Different grammar types (dictation vs. rule) define the words and the
patterns in different ways.
The core functionality provided through the Grammar
interface
includes:
Recognizer
has a unique name.
GrammarListeners
for grammar-related events.
ResultListeners
to receive result events
for results matching the Grammar
.
Recognizer
that owns the grammar
Each Grammar
is associated with a specific Recognizer
.
All grammars are located, created and managed through the Recognizer
interface. The basic steps in using any Grammar
are:
Grammar
or get a reference to an existing grammar
through the Recognizer
interface.
ResultListener
to get results.
Grammar
as required
by the application's context.
Grammar
when it is no longer needed.
Grammar Types
There are two types of Grammar
:
DictationGrammar
and RuleGrammar
Both are defined by interfaces that extend the Grammar
interface. All recognizers support RuleGrammars
.
A recognizer may optionally support a DictationGrammar
.
The RuleGrammar
and DictationGrammar
interfaces define specialized mechanisms for controlling and modifying
those types of grammar.
When a Grammar
is active, the Recognizer
listens to incoming audio for speech that matches that Grammar
.
To be activated, an application must first set the enabled
property to true
(enable activation) and set the
activationMode
property to indicate the
activation conditions.
There are three activation modes: RECOGNIZER_FOCUS
,
RECOGNIZER_MODAL
and GLOBAL
. For each
mode a certain set of activation conditions must be met for the
grammar to be activated for recognition. The activation
conditions are determined by Recognizer
focus and
possibly by the activation of other grammars. Recognizer
focus is managed with the
requestFocus and
releaseFocus
methods of a Recognizer
.
The modes are listed here by priority. Always use the lowest priority mode possible.
GLOBAL
activation mode: if enabled
,
the Grammar
is always active irrespective of
whether the Recognizer
of this application
has focus.
RECOGNIZER_MODAL
activation mode: if enabled
,
the Grammar
is always active when the
Recognizer
of this application has focus.
Furthermore, enabling a modal grammar deactivates
any grammars in the same Recognizer
with the
RECOGNIZER_FOCUS
activation mode.
RECOGNIZER_FOCUS
activation mode (default):
if enabled
, the Grammar
is active when
the Recognizer
of this application has focus. The
exception is that if any other grammar of this application is
enabled with RECOGNIZER_MODAL
activation mode, then
this grammar is not activated.
The current activation state of a grammar can be tested with the
isActive
method. Whenever a grammar's activation changes
either a GRAMMAR_ACTIVATED
or
GRAMMAR_DEACTIVATED
event is issued to each
attached GrammarListener
.
An application may have zero, one or many grammar enabled at any time. As the conventions below indicate, well-behaved applications always minimize the number of active grammars.
The activation and deactivation of grammars is independent of
PAUSED
and RESUMED
states of the
Recognizer
. However, when a Recognizer
is PAUSED
, audio input to the Recognizer
is turned off, so speech can't be detected. Note that just after
pausing a recognizer there may be some remaining audio in the input
buffer that could contain recognizable speech and thus an active
grammar may continue to receive result events.
Well-behaved applications adhere to the following conventions to minimize impact on other applications and other components of the same application:
GLOBAL
activation mode to
a DictationGrammar
.
RECOGNIZER_FOCUS
unless there is a good reason to use another mode.
RECOGNIZER_MODAL
when certain
that deactivating RECOGNIZER_FOCUS
grammars
will not adversely affect the user interface.
RuleGrammars
with GLOBAL
activation mode.
Grammars can be dynamically changed and enabled and disabled.
Changes may be necessary as the application changes context,
as new information becomes available and so on. As with graphical
interface programming most grammar updates occur during processing
of events. Very often grammars are updated in response to
speech input from a user (a ResultEvent
).
Other asynchronous events (e.g., AWTEvents
)
are another common trigger of grammar changes. Changing
grammars during normal operation of a recognizer is usually
necessary to ensure natural and usable speech-enabled applications.
Different grammar types allow different types of run-time change.
RuleGrammars
can be created and deleted
during normal recognizer operation. Also, any aspect of a created
RuleGrammar
can be redefined: rules can be modified,
deleted or added, imports can be changed an so on. Certain
properties of a DictationGrammar
can be changed:
the context can be updated and the vocabulary modified.
For any grammar changes to take effect they must be committed. Committing changes builds the grammars into a format that can be used by the internal processes of the recognizer and applies those changes to the processing of incoming audio.
There are two ways in which a commit takes place:
commitChanges
method of the Recognizer
. The documentation for the
method describes when and how changes are committed when called.
(The commitChanges
method is typically used in
conjunction with the suspend
method of
Recognizer
.)
RESULT_ACCEPTED
or RESULT_REJECTED
event).
This simplifies the common scenario in which grammars are changed
during result finalization process because the user's input
has changed the application's state. (This implicit commit
is deferred following a call to suspend
and until a call to commitChanges
.)
Recognizer
issues a CHANGES_COMMITTED
event to signal that changes have been committed. This event signals
a transition from the SUSPENDED
state to the
LISTENING
state. Once in the LISTENING
state
the Recognizer
resumes the processing of incoming
audio with the newly committed grammars.
Also each changed Grammar
receives a
GRAMMAR_CHANGES_COMMITTED
through attached
GrammarListeners
whenever changes to it are
committed.
The commit changes mechanism has two important properties:
Recognizer
so all changes to all
Grammars
are committed at once. Again, there
are no intermediate states in which some, but not all,
changes have been applied.
Grammar and Result Listeners
An application can attach one or more GrammarListeners
to any Grammar
. The listener is notified of
status changes for the Grammar
: when changes are
committed and when activation changes.
An application can attach one or more ResultListener
objects to each Grammar
. The listener is notified of
all events for all results that match this grammar. The listeners
receive ResultEvents
starting with the
GRAMMAR_FINALIZED
event (not the preceding
RESULT_CREATED
or RESULT_UPDATED
events).
Field Summary | |
static int | GLOBAL
Value of activation mode in which the Grammar
is active for recognition irrespective of the focus state
of the Recognizer .
|
static int | RECOGNIZER_FOCUS
Default value of activation mode that requires the Recognizer
have focus and that there be no enabled grammars with
RECOGNIZER_MODAL mode for the grammar to be
activated. |
static int | RECOGNIZER_MODAL
Value of activation mode that requires the Recognizer
have focus for the grammar to be activated.
|
Method Summary | |
void | addGrammarListener(GrammarListener listener)
Request notifications of events of related to this Grammar .
|
void | addResultListener(ResultListener listener)
Request notifications of events from any Result
that matches this Grammar . |
int | getActivationMode()
Return the current activation mode for a Grammar .
|
String | getName()
Get the name of a grammar. |
Recognizer | getRecognizer()
Returns a reference to the Recognizer that
owns this grammar. |
boolean | isActive()
Test whether a Grammar is currently active for recognition.
|
boolean | isEnabled()
Return the enabled property of a Grammar .
|
void | removeGrammarListener(GrammarListener listener)
Remove a listener from this Grammar .
|
void | removeResultListener(ResultListener listener)
Remove a ResultListener from this Grammar .
|
void | setActivationMode(int mode)
Set the activation mode of a Grammar as
RECOGNIZER_FOCUS , RECOGNIZER_MODAL ,
or GLOBAL . |
void | setEnabled(boolean enabled)
Set the enabled property of a Grammar . |
Field Detail |
public static final int RECOGNIZER_FOCUS
Recognizer
have focus and that there be no enabled grammars with
RECOGNIZER_MODAL
mode for the grammar to be
activated. This is the lowest priority activation mode
and should be used unless there is a user interface design
reason to use another mode.
The activation conditions
for the RECOGNIZER_FOCUS
mode are describe above.
public static final int RECOGNIZER_MODAL
Recognizer
have focus for the grammar to be activated.
The activation conditions
for the RECOGNIZER_MODAL
mode are describe above.
public static final int GLOBAL
Grammar
is active for recognition irrespective of the focus state
of the Recognizer
.
The activation conditions
for the GLOBAL
mode are describe above.
Method Detail |
public Recognizer getRecognizer()
Recognizer
that
owns this grammar.public String getName()
Grammar names are used with a RuleGrammar
for resolving imports and references between grammars.
The name of a RuleGrammar
is set when the grammar
is created (either by loading a JSGF document or creating
a new RuleGrammar
).
The name of a DictationGrammar
should reflect the language
domain it supports. For example: com.acme.dictation.us.general
for general US Dictation from Acme corporation. Since a DictationGrammar
is built into a Recognizer
, its name is determined by
the Recognizer
.
public void setEnabled(boolean enabled)
Grammar
. A change
in the enabled property takes effect only after
grammar changes are committed.
Once a grammar is enabled and when the
activation conditions are met, it
is activated for recognition. When a grammar is activated, the
Recognizer
listens to incoming audio for speech
that matches the grammar and produces a Result
when
matching speech is detected.
The enabled property of a grammar is tested with the isEnabled
method.
The activation state of a grammar is tested with the isActive
method.
The RuleGrammar
interface extends the enabling property
to allow individual rules to be enabled and disabled.
public boolean isEnabled()
enabled
property of a Grammar
.
More specialized behaviour is specified by the
RuleGrammar
interface.
public void setActivationMode(int mode) throws IllegalArgumentException
Grammar
as
RECOGNIZER_FOCUS
, RECOGNIZER_MODAL
,
or GLOBAL
. The role of the activation mode
in the activation conditions
for a Grammar
are described above.
The default activation mode - RECOGNIZER_FOCUS
-
should be used unless there is a user interface design
reason to use another mode.
The individual rules of a RuleGrammar
can
be separately enabled and disabled. However, all rules
share the same ActivationMode
since the
mode is a property of the complete Grammar
.
A consequence is that all enabled rules of a RuleGrammar
are activated and deactivated together.
A change in activation mode only takes effect once changes are committed. For some recognizers changing the activation mode is computationally expensive.
The activation mode of a grammar can be tested by the
getActivationMode
method.
[Note: future releases may modify the set of activation modes.]
GLOBAL
mode for a DictationGrammar
public int getActivationMode()
Grammar
.
The default value for a grammar is RECOGNIZER_FOCUS
.
public boolean isActive()
Grammar
is currently active for recognition.
When a grammar is active, the recognizer is matching incoming audio
against the grammar (and other active grammars) to detect speech
that matches the grammar.
A Grammar
is activated for recognition if the
enabled
property is set to true
and
the activation conditions are met.
Activation is not directly controlled by applications and so can
only be tested (there is no setActive
method).
Rules of a RuleGrammar
can be individuallly enabled
and disabled. However all rules share the same ActivationMode
and the same activation state. Thus, when a RuleGrammar
is
active, all the enabled rules of the grammar are active for recognition.
Changes in the activation state are indicated by
GRAMMAR_ACTIVATED
and GRAMMAR_DEACTIVATED
events issued to the GrammarListener
. A change in
activation state can follow these RecognizerEvents
:
CHANGES_COMMITTED
event that applies a
change in the enabled
state or
ActivationMode
of this or another Grammar
.
FOCUS_GAINED
or FOCUS_LOST
event.
public void addGrammarListener(GrammarListener listener)
Grammar
.
An application can attach multiple listeners to a Grammar
.
public void removeGrammarListener(GrammarListener listener)
Grammar
.
public void addResultListener(ResultListener listener)
Result
that matches this Grammar
. An application
can attach multiple ResultListeners to a Grammar
.
A listener is removed with the removeResultListener
method.
A ResultListener
attached to a Grammar
receives result events starting from the GRAMMAR_FINALIZED
event - the event which indicates that the matched grammar is
known. A ResultListener
attached to a
Grammar
will never receive a RESULT_CREATED
event and does not receive any RESULT_UPDATED
events that occurred before the GRAMMAR_FINALIZED
event. A ResultListener
attached to a Grammar
is guaranteed to receive a result finalization event -
RESULT_ACCEPTED
or RESULT_REJECTED
-
some time after the GRAMMAR_FINALIZED
event.
ResultListener
objects can also be attached to
a Recognizer
and to any Result
.
A listener attached to the Recognizer
receives
all events for all results produced by that Recognizer
.
A listener attached to a Result
receives
all events for that result from the time at which the listener
is attached.
public void removeResultListener(ResultListener listener)
ResultListener
from this Grammar
.
Overview | 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