javax.speech
Interface AudioManager

public interface AudioManager

The AudioManager is provided by subclasses of Engine to allow an application to control audio input/output and to monitor audio-related events. The getAudioManager method for an Engine returns its AudioManager.

The following example shows how to redirect synthesizer output to a file. Redirection to a recognizer is similar, except that the recognizer reads audio from the file instead of writing to the file.

 Synthesizer synth = ...                             // see Synthesizer for creation options
 AudioManager am = synth.getAudioManager();
 am.setMediaLocator("file:///user/smith/hello.wav"); // can throw AudioException or SecurityException
 synth.allocate();                                   // after setMediaLocator to avoid error
 synth.speak("hello world", null);                   // speak, redirecting audio to file
 

Media Locator

The media locator description is based on JSR-135. This JSR uses only the audio part.

Media locators are specified in URI syntax which is defined in the form:

<scheme>:<scheme-specific-part>}

The <scheme> part of the locator string identifies the name of the protocol being used to deliver the data.

The locator syntax for (1) Live-media Capture, (2) RTP Streaming, and (3) Standard Schemes is defined as follows:

1. Locators for Live-media Capture

The locators for capturing live media are defined by the following syntax in Augmented BNF notations:

     "capture://" device [ "?" params]
     "playback://" device [ "?" params]
     "stream://" device [ "?" params]
 

The "stream" scheme supports directionless media locators associated with setMediaLocator and AudioSegments.

A. Identifying the type or the specific name of the device:

     device       = "audio" / dev_name / logical_name
     dev_name     = alphanumeric
     alphanumeric = 1*( ALPHA / DIGIT )
     logical_name = "microphone" / "speaker" / "headset"
 

B. Describing the media and capture parameters:

     params = audio_params / custom_params
 

C. Describing the audio media format:

     audio_params = audio_param *( "&" audio_param )
     audio_param  = 1*( "encoding=" audio_enc / "rate=" rate /
                        "bits=" bits / "channels=" channels /
                        "endian=" endian / "signed=" signed )
     audio_enc    = "pcm" / "ulaw" / "alaw" / "gsm"
     rate         = "96000" / "48000" / "44100" / "22050" / "16000" /
                    "11025" / "8000"
     bits         = "8" / "16" / "24"
     channels     = pos_integer
     endian       = "little" / "big"
     signed       = "signed" / "unsigned"
     pos_integer  = 1*DIGIT
   

   Note: alaw is required for SSML, but is an extension of JSR-135.
   

   Example:
     encoding=pcm&rate=11025&bits=16&channels=1
 

D. Describing some custom media parameters:

     custom_params = param *( "&" param )
     param         = key "=" value
     key           = alphanumeric
     value         = alphanumeric
   

   Examples:
     capture://audio  (default input audio)
     playback://audio (default output audio, other capture examples apply)
     capture://audio?encoding=pcm   (default audio audio in PCM format)
     capture://devmic0?encoding=pcm&rate=11025&bits=16&channels=1
             (audio from a specific device--devmic0)
     

     capture://mydev?myattr=123   (custom device with custom param)
 

2. Locators for RTP Streaming

RTP is a public standard for streaming media. The locator syntax for specifying RTP sessions is:

     "rtp://" address [ ":" port ] [ "/" type ]
   

   where:
   

     address and port define the RTP session.  The
     address and port usage is similar to the host and port
     usage as defined in the 
     URI syntax.
     

     type = "audio"
 

3. Locators with Standard Schemes

Standard schemes may be used to specify media locators. The <scheme-specific-part> in this case is defined by the standard URI syntax. Examples include

• "http://webserver/test.wav"
• "file:///tmp/audio.wav"

Media locators may also be relative

• "/org/jsapi2/examples/audiodemo/example.wav"
• "example.wav"

The EngineProperties.getBase method is used while resolving relative locators. An exception is thrown if resolution fails.

A special "resource:" scheme may be used to force resolution with getResourceAsStream. This avoids unintended redirection of references that begin with "/" by EngineProperties.setBase. See that method for details. The following example locator illustrates the "resource:" scheme:

• "resource:/org/jsapi2/examples/audiodemo/example.wav"

See Also:

Engine, getAudioManager, getBase, setBase, AudioSegment, getResourceAsStream

Method Summary

void	addAudioListener(AudioListener listener) Requests notifications of AudioEvents to an AudioListener.
void	audioStart() Starts the audio for this AudioManager.
void	audioStop() Stops the audio for this AudioManager.
int	getAudioMask() Gets the mask to filter events for added AudioListeners.
String	getMediaLocator() Returns the media locator for this AudioManager.
String[]	getSupportedMediaLocators(String mediaLocator) Gets the set of supported audio media locator descriptions given a locator template.
boolean	isSameChannel(AudioManager audioManager) Tests for equivalent audio sources or destinations.
boolean	isSupportedMediaLocator(String mediaLocator) Tests a media locator to see if it is supported.
void	removeAudioListener(AudioListener listener) Removes an AudioListener from this AudioManager.
void	setAudioMask(int mask) Sets the mask to filter events for added AudioListeners.
void	setMediaLocator(String locator) Sets the locator for this AudioManager.
void	setMediaLocator(String locator, InputStream stream) Sets the input audio source for this AudioManager.
void	setMediaLocator(String locator, OutputStream stream) Sets the output audio source for this AudioManager.

Method Detail

getAudioMask

int getAudioMask()

Gets the mask to filter events for added AudioListeners.

See setAudioMask for details.

The event mask can be set and retrieved in any Engine state.

Returns:

the current mask for AudioEvents

See Also:

AudioEvent, AudioListener, setAudioMask

setAudioMask

void setAudioMask(int mask)

Sets the mask to filter events for added AudioListeners.

It can improve efficiency to mask events that are not used. Events of interest can be seen by using the logical OR of the event constants defined in the AudioEvent class. AudioEvent.DEFAULT_MASK is the initial value.

The event mask can be set and retrieved in any Engine state. This method affects filtering of all attached AudioListeners.

Parameters:

mask - the mask for AudioEvents

See Also:

AudioEvent, AudioEvent.DEFAULT_MASK, AudioListener, getAudioMask

getMediaLocator

String getMediaLocator()

Returns the media locator for this AudioManager.

This locator specifies characteristics about the current audio stream including the sample rate and encoding.

Returns:

a media locator description String.

See Also:

setMediaLocator

getSupportedMediaLocators

String[] getSupportedMediaLocators(String mediaLocator)
                                   throws IllegalArgumentException

Gets the set of supported audio media locator descriptions given a locator template.

The locators are returned as Strings that identify which locators can be used with an associated Engine. The locators indicate the scheme and can indicate associated devices and media formats.

The argument provides a template that can specify a subset of all possible schemes, devices, and audio media formats. For example, if the given media locator is "capture://audio?encoding=pcm", then the supported media formats that can be used in an Engine might be

 "capture://audio?encoding=pcm&rate=11025&bits=16&channels=1" and
 "capture://audio?encoding=pcm&rate=8000&bits=16&channels=1".
 

Some locator sources include the media format information internally. For example, the audio source "file:///user/smith/audio.wav" includes information such as the sample rate within the header.

If null is passed in as the media locator, all the supported protocols for this Engine will be returned. The returned array should be non-empty.

If the given media locator is unsupported, then an empty array will be returned.

Parameters:

mediaLocator - a media locator description.

Returns:

An array of supported audio media locator descriptions in the form of an array of URI locators.

Throws:

IllegalArgumentException - if the given media locator is invalid

See Also:

isSupportedMediaLocator

isSupportedMediaLocator

boolean isSupportedMediaLocator(String mediaLocator)
                                throws IllegalArgumentException

Tests a media locator to see if it is supported. This method returns true if a call to getSupportedMediaLocators with the same media locator would return a non-empty list. This provides a convenient way to test for supported features without constructing a potentially large list.

Parameters:

mediaLocator - a media locator description.

Returns:

true if the media locator description is supported

Throws:

IllegalArgumentException - if the given media locator is invalid

See Also:

getSupportedMediaLocators

setMediaLocator

void setMediaLocator(String locator)
                     throws AudioException,
                            IllegalStateException,
                            IllegalArgumentException,
                            SecurityException

Sets the locator for this AudioManager. Audio must be stopped when this method is called.

In some cases, the media content may contain its own format information (e.g., within a header). In this case, the format description may be ignored.

If null is passed as the locator, the default locator will be used. This includes the device and format.

If successful and the audio channel changes, this method results in an AUDIO_CHANGED event.

Parameters:

locator - a media locator description.

Throws:

AudioException - if the locator is not supported.

IllegalStateException - if audio is not stopped.

IllegalArgumentException - if the given media locator is invalid.

SecurityException - if the application does not have permission.

See Also:

getMediaLocator, isSupportedMediaLocator(java.lang.String), isSameChannel, audioStop, AUDIO_STARTED, AUDIO_CHANGED

Required permission:

javax.speech.AudioManager.control

setMediaLocator

void setMediaLocator(String locator,
                     InputStream stream)
                     throws AudioException,
                            IllegalStateException,
                            IllegalArgumentException,
                            SecurityException

Sets the input audio source for this AudioManager. Audio must be stopped when this method is called. An IllegalArgumentException is thrown if the Engine does not expect an InputStream (i.e., it produces output audio).

The locator scheme must be "stream" or "capture" and the parameters specify the encoding of the stream. For example:

   "stream://audio?encoding=pcm&rate=8000&bits=16&channels=1"
 

For the "capture" scheme, the audio stream is read continuously. For the "stream" scheme, the audio stream is only read in the the RESUMED state. These two schemes support live input and test input, respectively.

An AudioException is thrown if the Engine does not support the stream with the specified locator. The isSupportedMediaLocator can be used to test the locator in advance.

If successful and the audio channel changes, this method results in an AUDIO_CHANGED event.

Parameters:

locator - a media locator description

stream - an input audio source

Throws:

AudioException - if the locator and stream are not supported

IllegalStateException - if audio is not stopped.

IllegalArgumentException - if the given media locator is invalid, InputStream is not expected, or either argument is null

SecurityException - if the application does not have permission

See Also:

getMediaLocator, isSupportedMediaLocator(java.lang.String), isSameChannel, audioStop, AUDIO_STARTED, AUDIO_CHANGED, RESUMED

Required permission:

javax.speech.AudioManager.control

setMediaLocator

void setMediaLocator(String locator,
                     OutputStream stream)
                     throws AudioException,
                            IllegalStateException,
                            IllegalArgumentException,
                            SecurityException

Sets the output audio source for this AudioManager. Audio must be stopped when this method is called. An IllegalArgumentException is thrown if the Engine does not expect an OutputStream (i.e., it consumes input audio).

The locator scheme must be "stream" or "playback" and the parameters specify the encoding of the stream. For example:

   "stream://audio?encoding=pcm&rate=8000&bits=16&channels=1"
 

For the "playback" scheme, data is written with considerations for real-time output. For the "stream" scheme, data may be written as it becomes available. These two schemes support live output and test output, respectively.

An AudioException is thrown if the Engine does not support the stream with the specified locator. The isSupportedMediaLocator can be used to test the locator in advance.

If successful and the audio channel changes, this method results in an AUDIO_CHANGED event.

Parameters:

locator - a media locator description

stream - an output audio sink

Throws:

AudioException - if the locator and stream are not supported

IllegalStateException - if audio is not stopped.

IllegalArgumentException - if the given media locator is invalid, OutputStream is not expected, or either argument is null

SecurityException - if the application does not have permission

See Also:

getMediaLocator, isSupportedMediaLocator(java.lang.String), isSameChannel, audioStop, AUDIO_STARTED, AUDIO_CHANGED

Required permission:

javax.speech.AudioManager.control

addAudioListener

void addAudioListener(AudioListener listener)

Requests notifications of AudioEvents to an AudioListener. An application can attach multiple AudioListeners to an AudioManager.

Individual events may be filtered with setAudioMask.

Parameters:

listener - a listener for AudioEvents

See Also:

AudioEvent, AudioListener, removeAudioListener, setAudioMask

removeAudioListener

void removeAudioListener(AudioListener listener)

Removes an AudioListener from this AudioManager.

Parameters:

listener - a listener for AudioEvents

See Also:

AudioEvent, AudioListener, addAudioListener

audioStart

void audioStart()
                throws SecurityException,
                       AudioException,
                       EngineStateException

Starts the audio for this AudioManager.

Note that an Engine will normally start and stop an audio channel. This method provides additional control, especially when combined with audioStop.

If successful, this method results in an AUDIO_STARTED event.

Throws:

SecurityException - if the application does not have permission

EngineStateException - if the Engine is not in the PAUSED state

AudioException - if the request fails

See Also:

audioStop, AUDIO_STARTED, PAUSED

Required permission:

javax.speech.AudioManager.control

audioStop

void audioStop()
               throws SecurityException,
                      AudioException,
                      EngineStateException

Stops the audio for this AudioManager.

This method may be used to effectively mute the audio. For "live" audio, incoming audio is discarded while stopped. Likewise, for outgoing audio, no audio is transmitted.

Engines may buffer audio and include pending results or operations. Applications should take appropriate action depending on the type of Engine and the processing goals.

If successful, this method results in an AUDIO_STOPPED event.

Throws:

SecurityException - if the application does not have permission

EngineStateException - if the Engine is not in the PAUSED state

AudioException - if the request fails

See Also:

audioStart, AUDIO_STOPPED, PAUSED

Required permission:

javax.speech.AudioManager.control

isSameChannel

boolean isSameChannel(AudioManager audioManager)

Tests for equivalent audio sources or destinations.

This method returns true if this AudioManager represents the same source or destination as the specified AudioManager. In addition to counting equal media locator Strings as equal, AudioManagers may represent the same channel if

• partially specified media locators are the same after considering defaults,
• an AudioManager is able to convert differences such as sample rate for the same channel,
• there is more than one logical name for the same physical device.

Parameters:

audioManager - the AudioManager to compare with this AudioManager

Returns:

true if the AudioManagers represent the same source or destination