Overview | Package | Class | Tree | Index | Help
PREV CLASS | NEXT CLASS FRAMES  | NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD

Interface javax.speech.recognition.ResultToken


public abstract interface ResultToken
A token (usually a word) contained by a Result representing something heard by a recognizer. For a result of a RuleGrammar a ResultToken contains the same string as the defining RuleToken in the RuleGrammar. For a result of a DictationGrammar, the tokens are defined by the recognizer.

For any result, best guess finalized tokens are obtained from the getBestToken and getBestTokens methods of the Result interface. For a finalized result matching a RuleGrammar or a finalized result matching a DictationGrammar alternative guesses are available through the getAlternativeTokens methods of the FinalRuleResult and FinalDictationResult interfaces respectively.

The ResultToken provides the following information:

Spoken vs. Written Form

The distinction between spoken and written forms of a ResultToken applies only to results for a DictationGrammar. For a result matching a RuleGrammar, the written and spoken forms are identical.

The spoken form is a printable string that indicates what the recognizer heard the user say. In a dictation application, the spoken form is typically used when displaying unfinalized tokens.

The written form is a printable string that indicates how the recognizer thinks the token should be printed in text. In a dictation application, the written form is typically used when displaying finalized tokens.

For example, in English, a recognizer might return "twenty" for the spoken form and "20" for the written form.

Recognizers perform the conversion from spoken to written form on a per-token basis. For example, "nineteen thirty eight" is three tokens. The written form would also be three tokens: "19 30 8". Applications may use additional processing to convert such token sequences to "1938".

For some ResultTokens, the written form is a single Unicode character. Amongst these are the following important formatting characters (shown here as spoken form for US English, written form as a Unicode character number):

The following are examples of punctuation characters given with sample spoken forms and the corresponding written form. The spoken form may vary between recognizers and one recognizer may even allow one punctuation character to be spoken multiple ways. Also the set of characters may be engine-specific and language-specific. Presentation Hints

Note: results for rule grammars do not provide presentation hints. Default values are returns for both SpacingHint and CapitalizationHint.

Applications use the presentation hints as a guide to rendering the written-form tokens into complete strings. The two hints are SpacingHint and CapitalizationHint.

SpacingHint is an int with several flags indicating how the token should be spaced.

The ATTACH_GROUP is the least obvious flag. In English, a common use of this flag is for sequence of digits. If the user says four tokens "3" "point" "1" "4" (point='.'), and these tokens all have the ATTACH_GROUP flag set, then they are joined. The presentation string is "3.14". The name of the flag implies that tokens in the same "group" should have no spaces between them.

"previous" means the previously spoken token in the sequence of tokens - that is, previous in time. For left-to-right languages (e.g. English, German) ATTACH_PREVIOUS means left attachment - no space to the left. For right-to-left languages (e.g. Arabic, Hebrew) ATTACH_PREVIOUS means right attachment - no space to the right. The converse is true for ATTACH_FOLLOWING.

The spacing flags are OR'ed (Java '|' operator on integers). A legal value might be (ATTACH_PREVIOUS | ATTACH_FOLLOWING). The SEPARATE value is 0 (zero). A flag can be tested by the following code:

   // if attach previous ...
   if ((token.getSpacingHint() & ResultToken.ATTACH_PREVIOUS) != 0)
     ...
 
capitalizationHint indicates how the written form of the following token should be capitalized. The options are The Internationalized case conversion methods of the java.lang.String are recommended for implementing the capitalization hints.

Null Written Form

Some spoken directives to recognizers produce tokens that have no printable form. These tokens return null for the written form. Typically, these directives give explicit capitalization or spacing hints. The spoken forms of these tokens should be non-null (to allow the application to provide appropriate feedback to a user. Example directives for English might include:

For these tokens, the interpretation of the capitalization and spacing hints is specialized. If the spacing hint differs from the default, SEPARATE, it overrides the spacing hint of the next non-null token. If the capitalization hint differs from the default, CAP_AS_IS, it overrides the capitalization hints of previous non-null token (which in fact applies to the following token also).

Example

This example shows how a string of result tokens should be processed to produce a single printable string. The following is a sequence of tokens in a FinalDictationResult shown as spoken form, written form, and spacing and capitalization hints.

  1. "NEW_LINE", "\u000A", SEPARATE, CAP_FIRST
  2. "the", "the", SEPARATE, CAP_AS_IS
  3. "UPPERCASE_NEXT", "", SEPARATE, UPPERCASE
  4. "index", "index", SEPARATE, CAP_AS_IS
  5. "is", "is" SEPARATE, CAP_AS_IS
  6. "seven", "7", ATTACH_GROUP, CAP_AS_IS
  7. "-", "-", ATTACH_GROUP, CAP_AS_IS
  8. "two", "2", ATTACH_GROUP, CAP_AS_IS
  9. "period", ".", ATTACH_PREVIOUS, CAP_FIRST
that could be converted to "\nThe INDEX is 7-2."

See Also:
Result, FinalResult, FinalDictationResult, FinalRuleResult

Field Summary
static int ATTACH_FOLLOWING
          A SpacingHint flag set true when a token should be attached to the following token.
static int ATTACH_GROUP
          A SpacingHint flag set true when a token should be attached to preceding and/or following tokens which also have the ATTACH_GROUP flag set true.
static int ATTACH_PREVIOUS
          A SpacingHint flag set true when a token should be attached to the preceding token.
static int CAP_AS_IS
          A CapitalizationHint indicating that the following word should be presented without changes in capitalization.
static int CAP_FIRST
          A CapitalizationHint indicating that the following word should be presented with the first character in uppercase.
static int LOWERCASE
          A CapitalizationHint indicating that the following word should be presented in lowercase.
static String NEW_LINE
          Special token representing the written form of the "New Line" directive.
static String NEW_PARAGRAPH
          Special token representing the written form of the "New Paragraph" directive.
static int SEPARATE
          A SpacingHint returned when a token should be presented separately from surrounding tokens (preceding and following spaces).
static int UPPERCASE
          A CapitalizationHint indicating that the following word should be presented in uppercase.
 
Method Summary
int getCapitalizationHint()
          Get the capitalization hint.
long getEndTime()
          Get the approximate end time for the token.
Result getResult()
          Return a reference to the result that contains this token.
int getSpacingHint()
          Get the spacing hints.
String getSpokenText()
          Get the spoken text of a token.
long getStartTime()
          Get the approximate start time for the token.
String getWrittenText()
          Get the written form of a spoken token.
 

Field Detail

NEW_PARAGRAPH

public static final String NEW_PARAGRAPH
Special token representing the written form of the "New Paragraph" directive. Equal to "\u2029". The spoken form of a "New Paragraph" directive may vary between recognizers.

NEW_LINE

public static final String NEW_LINE
Special token representing the written form of the "New Line" directive. Equal to "\\n". The spoken form of a "New Line" directive may vary between recognizers.

SEPARATE

public static final int SEPARATE
A SpacingHint returned when a token should be presented separately from surrounding tokens (preceding and following spaces). Returned when ATTACH_PREVIOUS, ATTACH_FOLLOWING, and ATTACH_GROUP are all false. (See the description above.)

SEPARATE is the default spacing hint value.

Example:

     if (resultToken.getSpacingHint() == ResultToken.SEPARATE)
       ...;
 
See Also:
getSpacingHint

ATTACH_PREVIOUS

public static final int ATTACH_PREVIOUS
A SpacingHint flag set true when a token should be attached to the preceding token. (See the description above.)

Example:

     if ((resultToken.getSpacingHint() & ResultToken.ATTACH_PREVIOUS) != 0)
       ...;
 
See Also:
getSpacingHint

ATTACH_FOLLOWING

public static final int ATTACH_FOLLOWING
A SpacingHint flag set true when a token should be attached to the following token. (See the description above.)

Example:

     if ((resultToken.getSpacingHint() & ResultToken.ATTACH_FOLLOWING) != 0)
       ...;
 
See Also:
getSpacingHint

ATTACH_GROUP

public static final int ATTACH_GROUP
A SpacingHint flag set true when a token should be attached to preceding and/or following tokens which also have the ATTACH_GROUP flag set true. (See the description above.)

Example:

     if (((thisToken.getSpacingHint() & ResultToken.ATTACH_GROUP) != 0)
         && ((prevToken.getSpacingHint() & ResultToken.ATTACH_GROUP) != 0))
       ...;
 
See Also:
getSpacingHint

CAP_AS_IS

public static final int CAP_AS_IS
A CapitalizationHint indicating that the following word should be presented without changes in capitalization. This is the default value. (See the description above.)

CAP_FIRST

public static final int CAP_FIRST
A CapitalizationHint indicating that the following word should be presented with the first character in uppercase. (See the description above.)

UPPERCASE

public static final int UPPERCASE
A CapitalizationHint indicating that the following word should be presented in uppercase. (See the description above.)

LOWERCASE

public static final int LOWERCASE
A CapitalizationHint indicating that the following word should be presented in lowercase. (See the description above.)
Method Detail

getResult

public Result getResult()
Return a reference to the result that contains this token.

getSpokenText

public String getSpokenText()
Get the spoken text of a token. In dictation, the spoken form is typically used when displaying unfinalized tokens. The difference between spoken and written forms is discussed above.

getWrittenText

public String getWrittenText()
Get the written form of a spoken token. Spoken and written forms are discussed above.

getCapitalizationHint

public int getCapitalizationHint()
Get the capitalization hint. (See description above.) Values are CAP_AS_IS (the default), CAP_FIRST, UPPERCASE, LOWERCASE. Tokens from a RuleGrammar result always return CAP_AS_IS.

getSpacingHint

public int getSpacingHint()
Get the spacing hints. (See description above.) The value equals SEPARATE (the default) if the token should be presented with surrounding spaces. Otherwise any or all of the following flags can be true: ATTACH_FOLLOWING, ATTACH_PREVIOUS, ATTACH_GROUP. Tokens from a RuleGrammar result always return SEPARATE.

getStartTime

public long getStartTime()
Get the approximate start time for the token. The value is matched to the System.currentTimeMillis() time.

The start time of a token is always greater than or equal to the the end time of a preceding token. The values will be different if the tokens are separated by a pause.

Returns -1 if timing information is not available. Not all recognizers provide timing information. Timing information is not usually available for unfinalized or finalized tokens in a Result that is not yet finalized. Even if timing information is available for the best-guess tokens, it might not be available for alternative tokens.

See Also:
currentTimeMillis

getEndTime

public long getEndTime()
Get the approximate end time for the token. The value is matched to the System.currentTimeMillis() time.

The end time of a token is always less than or equal to the the end time of a preceding token. The values will be different if the tokens are separated by a pause.

Returns -1 if timing information is not available. Not all recognizers provide timing information. Timing information is not usually available for unfinalized or finalized tokens in a Result that is not yet finalized. Even if timing information is available for the best-guess tokens, it might not be available for alternative tokens.

See Also:
currentTimeMillis

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