javax.speech.recognition
Interface SpeakerManager

public interface SpeakerManager

Provides management of speaker-specific data for a Recognizer. The SpeakerManager for a Recognizer is obtained through its getSpeakerManager method. Recognizers that do not maintain SpeakerProfiles (e.g., some speaker-independent Recognizers) return null for this method.

Speaker-specific data is identified with a SpeakerProfile that is associated with information about an enrollment of a speaker (user) with the Recognizer. The speaker data allows the Recognizer to adapt to the characteristics of the speaker under various conditions with the goal of improving performance and recognition accuracy. For example, the Recognizer might adjust to vocabulary preferences and accent.

The SpeakerManager provides access to the known SpeakerProfiles, enables storage and loading of the speaker data once a Recognizer is running, and provides other management functions (e.g., creation, deletion, etc). The SpeakerManager maintains a "current" SpeakerProfile to identify the speaker data currently used by the Recognizer.

Speaker Data

Except for the properties of the SpeakerProfile, speaker data is not accessible to an application. Speaker data may include:

• Speaker information: full name, age, gender etc.
• Speaker preferences: including settings of the RecognizerProperties
• Language models: data about the words and word patterns of the speaker
• Word models: data about the pronunciation of words by the speaker
• Acoustic models: data about the speaker's voice
• Training information and usage history

Storing and Loading

Speaker data is typically persistent - a speaker will want their profile to be available from session to session. An application must explicitly request a Recognizer to save speaker data. It is good practice to check with a speaker before storing their data in case it becomes corrupted.

The SpeakerManager interface provides a revert method which requests the Recognizer to restore the speaker data last saved (possibly loaded at the start of a session).

The speaker data is potentially large, so loading, saving, reverting, and changing speaker data may all be slow operations.

The SpeakerManager for a Recognizer can be obtained in any state of the Recognizer. However, some methods of the SpeakerManager operate correctly only when the Recognizer is in the ALLOCATED state.

The getCurrentSpeaker, setCurrentSpeaker and listKnownSpeakers methods operate in any Recognizer state. This allows an initial SpeakerProfile to be loaded before calling the Recognizer allocate method.

See Also:

getSpeakerManager, SpeakerProfile, getSpeakerProfiles, EngineManager, allocate

Method Summary

void	createSpeaker(SpeakerProfile speaker) Creates new speaker data for a SpeakerProfile.
void	deleteSpeaker(SpeakerProfile speaker) Deletes the speaker data for a SpeakerProfile.
SpeakerProfile	getCurrentSpeaker() Gets the current SpeakerProfile.
SpeakerManagerUI	getSpeakerManagerUI() Returns a user interface object for managing speaker data and training.
SpeakerProfile[]	listKnownSpeakers() Lists the SpeakerProfiles known to this SpeakerManager.
void	renameSpeaker(SpeakerProfile oldSpeaker, SpeakerProfile newSpeaker) Associates existing speaker data with a new SpeakerProfile.
void	restoreCurrentSpeaker() Restores the speaker data for the current SpeakerProfile to the last saved version.
void	saveCurrentSpeaker() Saves the speaker data for the current SpeakerProfile.
void	setCurrentSpeaker(SpeakerProfile speaker) Sets the current SpeakerProfile.

Method Detail

deleteSpeaker

void deleteSpeaker(SpeakerProfile speaker)
                   throws IllegalArgumentException

Deletes the speaker data for a SpeakerProfile. If the deleted SpeakerProfile is the current SpeakerProfile, the current SpeakerProfile is set to SpeakerProfile.DEFAULT.

SpeakerProfile.DEFAULT may not be deleted.

After a successful call to this method, the deleted SpeakerProfile is no longer returned by listKnownSpeakers.

Parameters:

speaker - the SpeakerProfile to delete

Throws:

IllegalArgumentException - if the SpeakerProfile is not known or is the DEFAULT

See Also:

createSpeaker, SpeakerProfile.DEFAULT, listKnownSpeakers

getSpeakerManagerUI

SpeakerManagerUI getSpeakerManagerUI()

Returns a user interface object for managing speaker data and training. If this SpeakerManager has no default user interface, the return value is null and the application is responsible for providing an appropriate user interface.

Note: because the interface is provided by the Recognizer, it may allow the management of additional properties that are not otherwise accessible.

Returns:

a user interface object

getCurrentSpeaker

SpeakerProfile getCurrentSpeaker()

Gets the current SpeakerProfile. SpeakerProfile.DEFAULT is returned if no other SpeakerProfile is known.

Returns:

the current SpeakerProfile.

See Also:

setCurrentSpeaker, SpeakerProfile.DEFAULT, listKnownSpeakers

listKnownSpeakers

SpeakerProfile[] listKnownSpeakers()

Lists the SpeakerProfiles known to this SpeakerManager. Returns an array containing SpeakerProfile.DEFAULT if there are no other known SpeakerProfiles.

The createSpeaker, deleteSpeaker, and renameSpeaker methods affect the list returned.

Returns:

the list of known SpeakerProfiles

See Also:

createSpeaker(javax.speech.recognition.SpeakerProfile), deleteSpeaker(javax.speech.recognition.SpeakerProfile), renameSpeaker(javax.speech.recognition.SpeakerProfile, javax.speech.recognition.SpeakerProfile), setCurrentSpeaker, SpeakerProfile.DEFAULT

createSpeaker

void createSpeaker(SpeakerProfile speaker)
                   throws IllegalArgumentException

Creates new speaker data for a SpeakerProfile. Speaker data is identified with a SpeakerProfile. This method creates Recognizer-specific data to associate with the SpeakerProfile. This method does not change the current SpeakerProfile.

After a successful call to this method, the SpeakerProfile is returned by listKnownSpeakers.

The speaker parameter must be non-null, contain non-null values, and must not be equal to any currently known SpeakerProfiles as returned by listKnownSpeakers.

Parameters:

speaker - a SpeakerProfile for new speaker data

Throws:

IllegalArgumentException - if speaker is null, contains invalid values, or is already known

See Also:

setCurrentSpeaker, deleteSpeaker, listKnownSpeakers, SpeakerProfile.equals(java.lang.Object)

renameSpeaker

void renameSpeaker(SpeakerProfile oldSpeaker,
                   SpeakerProfile newSpeaker)
                   throws IllegalArgumentException

Associates existing speaker data with a new SpeakerProfile. This allows an update of the SpeakerProfile information associated with the speaker data.

This method behaves like createSpeaker followed by deleteSpeaker except that newSpeaker is initialized with speaker data from oldSpeaker rather than default data. Also, if oldSpeaker is the current speaker, then newSpeaker becomes the current speaker.

The listKnownSpeakers method returns a list of known SpeakerProfiles. oldSpeaker must be a known SpeakerProfile. newSpeaker must be non-null, contain non-null values, and must not be equal to any currently known SpeakerProfiles.

SpeakerProfile.DEFAULT may not be renamed.

Parameters:

oldSpeaker - a SpeakerProfile for existing speaker data

newSpeaker - the new SpeakerProfile for the speaker data

Throws:

IllegalArgumentException - if either SpeakerProfile is null or invalid, oldSpeaker is not known, or newSpeaker is already known

See Also:

createSpeaker, deleteSpeaker, setCurrentSpeaker, listKnownSpeakers, SpeakerProfile.DEFAULT

restoreCurrentSpeaker

void restoreCurrentSpeaker()
                           throws EngineStateException

Restores the speaker data for the current SpeakerProfile to the last saved version. If the speaker data has not been saved during the session, the restored version will be the version loaded at the start of the session. If speaker data has never been saved for the current SpeakerProfile, then default values are restored.

Because of the potentially large size of the speaker data, this may be a slow operation.

Throws:

EngineStateException - if the engine is not ALLOCATED

See Also:

saveCurrentSpeaker, Engine.ALLOCATED

saveCurrentSpeaker

void saveCurrentSpeaker()
                        throws EngineStateException

Saves the speaker data for the current SpeakerProfile. The speaker data is stored internally by the SpeakerManager and should be available for future sessions.

Use setCurrentSpeaker or restoreCurrentSpeaker to load previously stored speaker data.

Because of the potentially large size of the speaker data, this may be a slow operation.

Throws:

EngineStateException - if the engine is not ALLOCATED

See Also:

restoreCurrentSpeaker, setCurrentSpeaker, getCurrentSpeaker, Engine.ALLOCATED

setCurrentSpeaker

void setCurrentSpeaker(SpeakerProfile speaker)
                       throws IllegalArgumentException

Sets the current SpeakerProfile. The SpeakerProfile identifies speaker data and should be one of the objects returned by the listKnownSpeakers method.

If set before calling Recognizer.allocate, then any speaker data for this SpeakerProfile is loaded during allocation. Otherwise, restoreCurrentSpeaker may be used to load the associated speaker data.

Because speaker data may store preferred user settings for the RecognizerProperties, those properties may change as a result of this call.

If a speaker has not previously been set, the default is SpeakerProfile.DEFAULT.

Parameters:

speaker - a SpeakerProfile to set

Throws:

IllegalArgumentException - if the SpeakerProfile is not known

See Also:

getCurrentSpeaker, listKnownSpeakers, saveCurrentSpeaker, restoreCurrentSpeaker, RecognizerProperties, allocate, SpeakerProfile.DEFAULT