javax.speech
Class AudioEvent

Object
  SpeechEvent
      AudioEvent

public class AudioEvent
extends SpeechEvent

Describes events associated with audio input/output for an Engine. The event source is an Engine object.

Audio Events

AUDIO_LEVEL events provide values suitable for display in a visual "VU meter" (like the bar on stereo systems which goes up and down with the volume). Different colors are often used to indicate the different levels: for example, red for loud, green for normal, and blue for background.

Maintaining audio quality is important for reliable recognition. A common problem is a user speaking too loudly or too quietly. The color on a VU meter is one way to provide feedback to the user. Note that a quiet level (AUDIO_LEVEL_QUIET) does not necessarily indicate that the user is speaking too quietly. The input is also quiet when the user is not speaking.

AUDIO_STARTED and AUDIO_STOPPED events indicate the state of the audio stream. The AUDIO_CHANGED event indicates a change in the audio stream.

See Also:

AudioManager, AudioListener

Field Summary

static int	AUDIO_CHANGED Event issued when the AudioManager has detected a change in the audio stream.
static int	AUDIO_LEVEL Event issued when the next volume level value of the incoming audio becomes available.
static int	AUDIO_LEVEL_LOUD The threshold for loud audio.
static int	AUDIO_LEVEL_MAX The maximum audio level.
static int	AUDIO_LEVEL_MIN The minimum audio level.
static int	AUDIO_LEVEL_QUIET The threshold for quiet audio.
static int	AUDIO_STARTED Event issued when the AudioManager has opened the audio stream.
static int	AUDIO_STOPPED Event issued when the AudioManager has detected the end of an audio stream that it previously indicated with an AUDIO_STARTED event.
static int	DEFAULT_MASK The default mask for events in this class.

Fields inherited from class SpeechEvent

DISABLE_ALL, ENABLE_ALL

Constructor Summary

AudioEvent(Engine source, int id)
Constructs an AUDIO_STARTED or AUDIO_STOPPED AudioEvent.

AudioEvent(Engine source, int id, int audioLevel)
Constructs an AUDIO_LEVEL AudioEvent.

AudioEvent(Engine source, int id, String locator)
Constructs an AUDIO_CHANGED AudioEvent.

Method Summary

int	getAudioLevel() Gets the audio input level for the AUDIO_LEVEL AudioEvent.
String	getMediaLocator() Gets the media locator for the AUDIO_CHANGED AudioEvent.
String	paramString() Returns a parameter String that contains the event identifier in text form.
String	toString() Returns a printable String.

Methods inherited from class SpeechEvent

getId, getSource

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

AUDIO_LEVEL_MIN

public static final int AUDIO_LEVEL_MIN

The minimum audio level.

See Also:

getAudioLevel, Constant Field Values

AUDIO_LEVEL_QUIET

public static final int AUDIO_LEVEL_QUIET

The threshold for quiet audio. Audio is considered quiet below this threshold.

See Also:

getAudioLevel, Constant Field Values

AUDIO_LEVEL_LOUD

public static final int AUDIO_LEVEL_LOUD

The threshold for loud audio. Audio is considered loud above this threshold.

See Also:

getAudioLevel, Constant Field Values

AUDIO_LEVEL_MAX

public static final int AUDIO_LEVEL_MAX

The maximum audio level.

See Also:

getAudioLevel, Constant Field Values

AUDIO_STARTED

public static final int AUDIO_STARTED

Event issued when the AudioManager has opened the audio stream. Applications may use this event to display visual feedback to a user indicating that the audio stream is active.

This event is issued even if the audio stream has no data (e.g., a zero-length stream).

See Also:

audioUpdate, AUDIO_STOPPED, getId, audioStart, AudioManager, Constant Field Values

AUDIO_STOPPED

public static final int AUDIO_STOPPED

Event issued when the AudioManager has detected the end of an audio stream that it previously indicated with an AUDIO_STARTED event.

Data may end due to a finite-length stream (including zero-length) or a call to audioStop.

This event always follows an AUDIO_STARTED event.

See Also:

audioUpdate, AUDIO_STARTED, getId, audioStop, AudioManager, Constant Field Values

AUDIO_CHANGED

public static final int AUDIO_CHANGED

Event issued when the AudioManager has detected a change in the audio stream. A call to setMediaLocator triggers this event. This event can also happen due to hardware related changes such as attaching a different microphone or speaker.

See Also:

audioUpdate, AUDIO_STARTED, AUDIO_STOPPED, getId, getMediaLocator, AudioManager.setMediaLocator, AudioManager, Constant Field Values

AUDIO_LEVEL

public static final int AUDIO_LEVEL

Event issued when the next volume level value of the incoming audio becomes available. The getAudioLevel method describes audio levels in more detail.

This event is not enabled by default. It may be enabled with setAudioMask.

See Also:

getAudioLevel, audioUpdate, getId, setAudioMask, Constant Field Values

DEFAULT_MASK

public static final int DEFAULT_MASK

The default mask for events in this class.

The following events are delivered by default: AUDIO_STARTED, AUDIO_STOPPED, and AUDIO_CHANGED.

The AUDIO_LEVEL event occurs relatively frequently and may be enabled if needed with setAudioMask.

See Also:

AUDIO_STARTED, AUDIO_STOPPED, AUDIO_CHANGED, AUDIO_LEVEL, setAudioMask, Constant Field Values

Constructor Detail

AudioEvent

public AudioEvent(Engine source,
                  int id)
           throws IllegalArgumentException

Constructs an AUDIO_STARTED or AUDIO_STOPPED AudioEvent.

Parameters:

source - Engine that produced the event

id - the event identifier

Throws:

IllegalArgumentException - if called with an inappropriate event identifier

See Also:

AUDIO_STARTED, AUDIO_STOPPED

AudioEvent

public AudioEvent(Engine source,
                  int id,
                  String locator)
           throws IllegalArgumentException

Constructs an AUDIO_CHANGED AudioEvent.

Parameters:

source - Engine that produced the event

id - the event identifier

locator - the new locator

Throws:

IllegalArgumentException - if called with an inappropriate event identifier

See Also:

AUDIO_CHANGED, getMediaLocator()

AudioEvent

public AudioEvent(Engine source,
                  int id,
                  int audioLevel)
           throws IllegalArgumentException

Constructs an AUDIO_LEVEL AudioEvent.

Parameters:

source - Engine that produced the event

id - the event identifier

audioLevel - the audio level for this event

Throws:

IllegalArgumentException - if called with an inappropriate event identifier or if audioLevel is not between AUDIO_LEVEL_MIN and AUDIO_LEVEL_MAX

See Also:

AUDIO_LEVEL, getAudioLevel

Method Detail

getAudioLevel

public int getAudioLevel()

Gets the audio input level for the AUDIO_LEVEL AudioEvent. AUDIO_LEVEL_MIN represents complete silence. A value below AUDIO_LEVEL_QUIET indicates quiet input. A value above AUDIO_LEVEL_LOUD indicates loud input. AUDIO_LEVEL_MAX represents the maximum level.

Values between AUDIO_LEVEL_QUIET and AUDIO_LEVEL_LOUD represent the normal operating range.

AUDIO_LEVEL events are provided periodically. The exact period is up to the implementation, but should be approximately every 100 milliseconds to support a VU meter. It is possible to receive the same value twice in a row.

A default value of AUDIO_LEVEL_MIN is returned for any other AudioEvent.

This event is not part of the DEFAULT_MASK. Use setAudioMask to enable this event.

Returns:

the audio input level

See Also:

AUDIO_LEVEL, AUDIO_STARTED, AUDIO_STOPPED, AUDIO_LEVEL_MIN, AUDIO_LEVEL_QUIET, AUDIO_LEVEL_LOUD, AUDIO_LEVEL_MAX, DEFAULT_MASK, setAudioMask

getMediaLocator

public String getMediaLocator()

Gets the media locator for the AUDIO_CHANGED AudioEvent. The AUDIO_CHANGED description provides more detail.

This method returns null for any other AudioEvent.

Returns:

a String representing the media locator value

See Also:

AUDIO_CHANGED

paramString

public String paramString()

Returns a parameter String that contains the event identifier in text form.

The method toString may provide more detail. This method is useful for event-logging and for debugging.

Specified by:

paramString in class SpeechEvent

Returns:

a String that contains the event identifier in text form.

See Also:

toString

toString

public String toString()

Returns a printable String. Useful for event-logging and debugging.

The method paramString also provides printable information.

Specified by:

toString in class SpeechEvent

Returns:

A printable string.

See Also:

paramString