AudioOutputPort

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.ocap.hardware.device
Class AudioOutputPort

    java.lang.Object
      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 `VideoOutputPort`s 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 `VideoOutputPort`s whose audio is controlled by this `AudioOutputPort` instance.

  Returns:
    The set of controlled `VideoOutputPort`s as an `Enumeration`.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD