javax.speech
Interface VocabularyManager

public interface VocabularyManager

Interface for management of Words used by a speech Engine. The VocabularyManager for an Engine is returned by the getVocabularyManager method of the Engine interface. Engines are not required support a VocabularyManager - the getVocabularyManager method may return null.

Words, corresponding to normal words in written text, are provided to the VocabularyManager with optional information about their spoken form, grammatical role, pronunciation, and audio pronunciation.

The VocabularyManager typically provides a speech Engine with information on problematic words - usually words for which the Engine is unable to properly derive a pronunciation. The getPronunciations method provides a way to test pronunciations for debugging purposes.

Example uses include adding pronunciations for medical terms, pronunciations for game terminology (e.g. "Klingon"), or simply compensating for a very small dictionary.

Words in the VocabularyManager can improve the accuracy of recognition and affect the quality of synthesis.

See Also:

Engine, getVocabularyManager, Word, getPronunciations

Method Summary

void	addWord(Word word) Adds a Word to this VocabularyManager.
void	addWords(Word[] words) Adds an array of Words to this VocabularyManager.
String[]	getPronunciations(String text, SpeechLocale locale) Returns the pronunciations corresponding to plain text for the given locale.
Word[]	getWords(String text, SpeechLocale locale) Returns Words matching the specified written-form text and locale.
void	removeWord(Word word) Removes a Word from the VocabularyManager.
void	removeWords(Word[] words) Removes an array of Words from the VocabularyManager.

Method Detail

addWord

void addWord(Word word)
             throws EngineStateException,
                    SecurityException

Adds a Word to this VocabularyManager.

Words added by the application take priority over words with the same written-form text already known to an Engine internally. Words added multiple times with the same written-form text are considered in order of addition with the most recent having highest priority. In this case, the Engine may use one or more of the pronunciations.

Added Words remain for the lifetime of the VocabularyManager. However, they may be removed by the removeWord method. Subsequent use of the corresponding written-form text will behave as it did before the Word was added to the VocabularyManager.

Parameters:

word - a Word object to add

Throws:

EngineStateException - when not in the standard Conditions for Operation

SecurityException - if the application does not have permission

See Also:

addWords(Word[]), removeWord

Required permission:

javax.speech.VocabularyManager.update

addWords

void addWords(Word[] words)
              throws EngineStateException,
                     SecurityException

Adds an array of Words to this VocabularyManager. The addWord(Word) method provides additional detail.

Parameters:

words - an array of Word objects to add

Throws:

EngineStateException - when not in the standard Conditions for Operation

SecurityException - if the application does not have permission

See Also:

addWord(Word)

Required permission:

javax.speech.VocabularyManager.update

getPronunciations

String[] getPronunciations(String text,
                           SpeechLocale locale)
                           throws EngineStateException

Returns the pronunciations corresponding to plain text for the given locale. The returned pronunciations use the International Phonetic Alphabet subset of Unicode. An empty array is returned if pronunciations cannot be provided.

This method provides access to pronunciations that will be used. Pronunciations are determined as follows:

• Any added Words that match and include pronunciations
• Entries in internal lexicons
• Pronunciations from letter to sound rules (if supported)

The preferred pronunciation appears first in the list.

The input text is expected to be simple plain text (for example, a word or short phrase that may be found in a lexicon). The text is not expected to contain any markup or punctuation between words such as periods or commas. The text may contain characters such as hyphens and apostrophes where expected within words.

The locale parameter specifies the SpeechLocale of this Word. It may be null or partially specified. The description of getSpeechLocale provides more detail.

Limited lexical text normalization is performed on the text. For example, the input "100" may result in the pronunciations corresponding to "one hundred".

Parameters:

text - plain text for the requested pronunciations

locale - the requested SpeechLocale

Returns:

the pronunciations of text or an empty array

Throws:

EngineStateException - when not in the standard Conditions for Operation

See Also:

getSpeechLocale, getPronunciations, getSupportsLetterToSound

getWords

Word[] getWords(String text,
                SpeechLocale locale)
                throws EngineStateException

Returns Words matching the specified written-form text and locale. Returns a zero-length array if there are no matches.

The text and locale parameters are compared with the corresponding written-form text and SpeechLocale of each Word. null text and locale parameters are ignored in matching. If the locale parameter is non-null, all Strings in the locale must match each returned Word.

This method only returns Words that have been added by the addWord or addWords methods - it does not provide access to the Engine's internal lexicon or pronunciations.

Parameters:

text - requested written-form text

locale - requested SpeechLocale

Returns:

array of matching Word objects

Throws:

EngineStateException - when not in the standard Conditions for Operation

See Also:

getText, getSpeechLocale, addWord, addWords, getPronunciations

removeWord

void removeWord(Word word)
                throws EngineStateException,
                       IllegalArgumentException,
                       SecurityException

Removes a Word from the VocabularyManager.

Only Words added with addWord or addWords may be removed. Subsequent use of the corresponding written-form text by an Engine will behave as it did before the Word was added to the VocabularyManager.

Parameters:

word - a Word object to remove

Throws:

EngineStateException - when not in the standard Conditions for Operation

IllegalArgumentException - if Word is not known to the VocabularyManager.

SecurityException - if the application does not have permission

See Also:

removeWords(Word[]), addWord, addWords

Required permission:

javax.speech.VocabularyManager.update

removeWords

void removeWords(Word[] words)
                 throws EngineStateException,
                        IllegalArgumentException,
                        SecurityException

Removes an array of Words from the VocabularyManager. The removeWord(Word) method provides additional detail.

To remove a set of words for a given written-form text it is often useful to also use getWords:

   removeWords(getWords("matching", null));
 

Parameters:

words - an array of Words to remove

Throws:

EngineStateException - when not in the standard Conditions for Operation

IllegalArgumentException - a Word is not known to the VocabularyManager.

SecurityException - if the application does not have permission

See Also:

removeWord(Word), getWords

Required permission:

javax.speech.VocabularyManager.update