org.ocap.hardware.device
Class AudioOutputPort

java.lang.Object
  extended by org.ocap.hardware.device.AudioOutputPort

public class AudioOutputPort
extends Object

Represents an individually controllable audio output port of the host device. A single instance of this class MAY represent the audio outputs for one or more video output ports depending upon the output port configuration of the device. If a host device is capable of outputting multiple AV streams to multiple output devices simultaneously, the device MAY have multiple instances of this class, each representing an individually controllable audio output.

The interpretation of audio gain measured in level and decibel scales is as for javax.media.GainControl.

The volume controlled via an instance of java.media.GainControl, if supported, SHALL be relative to the volume controlled by an appropriate instance of AudioOutputPort.

See Also:
GainControl, HostSettings.getAudioOutputs(), HostSettings.setSystemVolumeKeyControl(boolean), HostSettings.setSystemMuteKeyControl(boolean), HostSettings.setSystemVolumeRange(int)

Field Summary
static int COMPRESSION_HEAVY
          Constant representing heavy audio level compression.
static int COMPRESSION_LIGHT
          Constant representing light audio level compression.
static int COMPRESSION_MEDIUM
          Constant representing medium audio level compression.
static int COMPRESSION_NONE
          Constant representing no audio compression.
static int ENCODING_AC3
          Constant representing AC3 digital audio encoding.
static int ENCODING_DISPLAY
          Constant representing a platform-selected digital audio encoding format.
static int ENCODING_NONE
          Constant representing lack of digital audio output.
static int ENCODING_PCM
          Constant representing pulse-code modulation (PCM) digital audio encoding.
static int STEREO_MODE_MONO
          Constant representing single channel (monoaural or mono) audio.
static int STEREO_MODE_STEREO
          Constant representing two-channel stereo audio.
static int STEREO_MODE_SURROUND
          Constant representing multi-channel stereo surround audio.
 
Method Summary
 int getCompression()
          Get the current audio level compression of the audio device.
 Enumeration getConnectedVideoOutputPorts()
          Get the set of VideoOutputPorts whose audio is controlled by this AudioOutputPort instance.
 float getDB()
          Get the current gain set for this AudioOutputPort in decibels.
 int getEncoding()
          Get the current encoding format for digital audio output for this audio device.
 float getLevel()
          Get the current gain set for this AudioOutputPort as a value between 0.0 and 1.0.
 float getMaxDB()
          Get the maximum gain in decibels for this AudioOutputPort.
 float getMinDB()
          Get the minimum gain in decibels for this AudioOutputPort.
 float getOptimalLevel()
          Get the gain level that is optimal for stereo playback.
 int getStereoMode()
          Get the current stereo mode of the audio device.
 int[] getSupportedCompressions()
          Get the set of compression levels supported by this audio device.
 int[] getSupportedEncodings()
          Get the set of encoding formats supported by this audio device.
 int[] getSupportedStereoModes()
          Get the set of stereo modes supported by this audio device.
 boolean isLoopThru()
          Get the current loop-thru setting of the audio device.
 boolean isMuted()
          Get the mute state of the audio signal associated with this host.
 void setCompression(int compression)
          Set the compression level of the audio device.
 float setDB(float db)
          Set the gain in decibels for this AudioOutputPort.
 void setEncoding(int encoding)
          Set the desired encoding format for digital audio output for this audio device.
 float setLevel(float level)
          Set the gain using a floating point scale with values between 0.0 and 1.0.
 void setLoopThru(boolean loopthru)
          Set the loop-thru setting for the audio device.
 void setMuted(boolean mute)
          Mute or unmute the signal associated with this AudioOutputPort.
 void setStereoMode(int mode)
          Set the stereo mode of the audio device.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

STEREO_MODE_MONO

public static final int STEREO_MODE_MONO
Constant representing single channel (monoaural or mono) audio.

See Also:
Constant Field Values

STEREO_MODE_STEREO

public static final int STEREO_MODE_STEREO
Constant representing two-channel stereo audio.

See Also:
Constant Field Values

STEREO_MODE_SURROUND

public static final int STEREO_MODE_SURROUND
Constant representing multi-channel stereo surround audio.

See Also:
Constant Field Values

ENCODING_NONE

public static final int ENCODING_NONE
Constant representing lack of digital audio output.

See Also:
Constant Field Values

ENCODING_DISPLAY

public static final int ENCODING_DISPLAY
Constant representing a platform-selected digital audio encoding format.

See Also:
Constant Field Values

ENCODING_PCM

public static final int ENCODING_PCM
Constant representing pulse-code modulation (PCM) digital audio encoding.

See Also:
Constant Field Values

ENCODING_AC3

public static final int ENCODING_AC3
Constant representing AC3 digital audio encoding.

See Also:
Constant Field Values

COMPRESSION_NONE

public static final int COMPRESSION_NONE
Constant representing no audio compression.

See Also:
Constant Field Values

COMPRESSION_LIGHT

public static final int COMPRESSION_LIGHT
Constant representing light audio level compression.

See Also:
Constant Field Values

COMPRESSION_MEDIUM

public static final int COMPRESSION_MEDIUM
Constant representing medium audio level compression.

See Also:
Constant Field Values

COMPRESSION_HEAVY

public static final int COMPRESSION_HEAVY
Constant representing heavy audio level compression.

See Also:
Constant Field Values
Method Detail

getStereoMode

public int getStereoMode()
Get the current stereo mode of the audio device.

Returns:
The current stereo mode. SHALL be one of STEREO_MODE_MONO, STEREO_MODE_STEREO or STEREO_MODE_SURROUND.
See Also:
setStereoMode(int), getSupportedStereoModes()

setStereoMode

public void setStereoMode(int mode)
                   throws IllegalArgumentException,
                          FeatureNotSupportedException
Set the stereo mode of the audio device.

Parameters:
mode - The desired stereo mode.
Throws:
IllegalArgumentException - if mode is not one of STEREO_MODE_MONO, STEREO_MODE_STEREO or STEREO_MODE_SURROUND
FeatureNotSupportedException - if the given setting is not supported
See Also:
getStereoMode(), getSupportedStereoModes()

getSupportedStereoModes

public int[] getSupportedStereoModes()
Get the set of stereo modes supported by this audio device. The returned values SHALL NOT produce a FeatureNotSupportedException when provided to setStereoMode(int).

Returns:
a non-null array containing the set of supported compression level settings
See Also:
setStereoMode(int), getStereoMode()

getCompression

public int getCompression()
Get the current audio level compression of the audio device.

Returns:
The current compression level. SHALL be one of COMPRESSION_NONE, COMPRESSION_LIGHT, COMPRESSION_MEDIUM or COMPRESSION_HEAVY
See Also:
setCompression(int), getSupportedCompressions()

setCompression

public void setCompression(int compression)
                    throws IllegalArgumentException,
                           FeatureNotSupportedException
Set the compression level of the audio device. Compression reduces the dynamic range of an audio signal by reducing the gain when the signal level is higher than a given threshold.

The compression levels correspond to implementation-specific ratios of input level to output gain. The following table describes the compression levels.

Level Description
COMPRESSION_NONE Always a 1:1 ratio of input level to output gain. No compression is applied to the output signal
COMPRESSION_LIGHT The lightest level of compression. Example ratio would be 2:1, where a 2dB change in input level is required to effect a 1dB change in output, above the threshold.
COMPRESSION_MEDIUM An equal or higher level of compression than COMPRESSION_LIGHT
COMPRESSION_HEAVY The highest level of compression. This may be a high enough level so as to be considered limiting.

Other attributes of audio level compression (e.g., threshold, attack, and release) are implementation-specific and not exposed by this API.

Parameters:
compression - The desired compression level.
Throws:
IllegalArgumentException - if compression is not one of COMPRESSION_NONE, COMPRESSION_LIGHT, COMPRESSION_MEDIUM or COMPRESSION_HEAVY
FeatureNotSupportedException - if the given setting is not supported
See Also:
getCompression(), getSupportedCompressions()

getSupportedCompressions

public int[] getSupportedCompressions()
Get the set of compression levels supported by this audio device. The returned values SHALL NOT produce a FeatureNotSupportedException when provided to setCompression(int).

Returns:
a non-null array containing the set of supported compression level settings
See Also:
setCompression(int), getCompression()

getEncoding

public int getEncoding()
Get the current encoding format for digital audio output for this audio device.

This method will never return ENCODING_DISPLAY. Instead, the current platform-selected encoding will be returned. The platform selects such an encoding based upon the device connected to this audio output port.

Returns:
The current encoding format. SHALL be one of ENCODING_NONE, ENCODING_PCM or ENCODING_AC3
See Also:
setEncoding(int), getSupportedEncodings()

setEncoding

public void setEncoding(int encoding)
                 throws IllegalArgumentException,
                        FeatureNotSupportedException
Set the desired encoding format for digital audio output for this audio device.

This method MAY be used to control the desired encoding format for digital audio output for this audio device. The following table describes the supported values for the encoding parameter:

Value Description
ENCODING_PCM Pulse code modulation digital audio encoding.
ENCODING_AC3 AC-3 digital audio encoding.
ENCODING_DISPLAY No explicit format is specified, instead the Host device will select the preferred output format.

Parameters:
encoding - The desired digital encoding format.
Throws:
IllegalArgumentException - if encoding is not one of ENCODING_DISPLAY, ENCODING_PCM or ENCODING_AC3
FeatureNotSupportedException - if the given setting is not supported
See Also:
getEncoding(), getSupportedEncodings()

getSupportedEncodings

public int[] getSupportedEncodings()
Get the set of encoding formats supported by this audio device. The returned values SHALL NOT produce a FeatureNotSupportedException when provided to setEncoding(int).

Returns:
a non-null array containing the set of supported digital encoding formats
See Also:
setEncoding(int), getEncoding()

getDB

public float getDB()
Get the current gain set for this AudioOutputPort in decibels.

Returns:
The gain in dB.
See Also:
setDB(float)

setDB

public float setDB(float db)
Set the gain in decibels for this AudioOutputPort. Setting the gain to 0.0 (the default) implies that the audio signal is neither amplified nor attenuated. Positive values amplify the audio signal and negative values attenuate the signal.

Parameters:
db - The new gain in dB.
Returns:
The gain that was actually set.
See Also:
GainControl, getDB(), getMaxDB(), getMinDB(), setLevel(float)

getMaxDB

public float getMaxDB()
Get the maximum gain in decibels for this AudioOutputPort. Calling setDB(float) with values greater than those returned by this API will have no effect.

Returns:
The maximum gain in decibels.

getMinDB

public float getMinDB()
Get the minimum gain in decibels for this AudioOutputPort. Calling setDB(float) with values less than those returned by this API will have no effect.

Returns:
The minimum gain in decibels.

getLevel

public float getLevel()
Get the current gain set for this AudioOutputPort as a value between 0.0 and 1.0.

Returns:
The gain in the level scale (0.0-1.0).
See Also:
setLevel(float)

setLevel

public float setLevel(float level)
Set the gain using a floating point scale with values between 0.0 and 1.0. 0.0 is silence; 1.0 is the loudest useful level that this AudioOutputPort supports.

Parameters:
level - The new gain value specified in the level scale.
Returns:
The level that was actually set.
See Also:
GainControl, getLevel(), getDB(), setDB(float)

getOptimalLevel

public float getOptimalLevel()
Get the gain level that is optimal for stereo playback. Selection of this gain level (using setLevel(float)) will reduce audio distortion on televisions that contain stereo decoders.

Where a fixed volume level is desired, it is recommended that the optimal level returned by this method be used.

Returns:
The optimal volume level.
See Also:
setLevel(float)

isMuted

public boolean isMuted()
Get the mute state of the audio signal associated with this host.

Returns:
The current mute state: true if muted and false otherwise.
See Also:
setMuted(boolean)

setMuted

public void setMuted(boolean mute)
Mute or unmute the signal associated with this AudioOutputPort. Redundant invocations of this method are ignored. The mute state does not effect the gain (as represented by getLevel() or getDB().

Parameters:
mute - The new mute state: true mutes the signal and false unmutes the signal.
See Also:
isMuted()

isLoopThru

public boolean isLoopThru()
Get the current loop-thru setting of the audio device.

Returns:
The currentloop-thru state: true if loop-thru is enabled and false otherwise.
See Also:
setLoopThru(boolean)

setLoopThru

public void setLoopThru(boolean loopthru)
                 throws FeatureNotSupportedException
Set the loop-thru setting for the audio device.

Audio loop-thru refers to a mechanism that allows audio from other devices (e.g., DVD player or VCR) to connect to a home theater or TV through this Host device when this AudioOutputPort is otherwise not in use. When loop-thru is enabled, audio inputs associated with this AudioOutputPort will be routed through this AudioOutputPort.

Parameters:
loopthru - The new loop-thru state: (true enables loop-thru and false disables loop-thru.
Throws:
FeatureNotSupportedException - if the requested loop-thru setting can not be achieved by the device
See Also:
isLoopThru()

getConnectedVideoOutputPorts

public Enumeration getConnectedVideoOutputPorts()
Get the set of VideoOutputPorts whose audio is controlled by this AudioOutputPort instance.

Returns:
The set of controlled VideoOutputPorts as an Enumeration.