javax.media
Interface GainControl


public abstract interface GainControl
extends Control

GainControl is an interface for manipulating audio signal gain.

Gain and Gain Measures

Gain is a multiplicative value applied to an audio signal that modifies the amplitude of the signal. This interface allows the gain to be specified in either decibels or using a floating point value that varies between 0.0 and 1.0.

Specifying Gain in Decibels

The decibel scale is valid over all float values. A gain of 0.0 dB implies that the audio signal is neither amplified nor attenuated. Positive values amplify the audio signal, negative values attenuate the audio signal. The relationship between a linear gain multiplier and the gain specified in decibels is:

value = pow(10.0, gainDB/20.0)

Specifying Gain in the Level Scale

The level scale ranges from 0.0 to 1.0, where 0.0 represents a gain that is virtually indistinguishable from silence and 1.0 represents the value that is, in some sense, the maximum gain. In other words, 1.0 represents the highest gain value that produces "useful" results. The mapping for producing a linear multiplicative value is implementation dependent.

Decibel and Level Interactions

The dB and level scales are representations of the same gain value. Calling setLevel will affect subsequent getDB invocations. Level and dB are interrelated in the following ways:

Defaults

Gain defaults to a value of 0.0 dB. The corresponding level is implementation dependent. Note that for some implementations, the default level might change on a per-instance basis.

Mute

Muting is independent of the gain. If mute is true, no audio signal is produced by this object; if mute is false an audio signal is produced and the gain is applied to the signal.

Gain Change Events

When the state of the GainControl changes, a GainChangeEvent is posted. This event is delivered through an object that implements GainChangeListener and has been registered as a listener with the GainControl using addGainChangeListener.

See Also:
GainChangeEvent, GainChangeListener, Control

Method Summary
 void addGainChangeListener(GainChangeListener listener)
          Register for gain change update events.
 float getDB()
          Get the current gain set for this object in dB.
 float getLevel()
          Get the current gain set for this object as a value between 0.0 and 1.0
 boolean getMute()
          Get the mute state of the signal associated with this GainControl.
 void removeGainChangeListener(GainChangeListener listener)
          Remove interest in gain change update events.
 float setDB(float gain)
          Set the gain in decibels.
 float setLevel(float level)
          Set the gain using a floating point scale with values between 0.0 and 1.0.
 void setMute(boolean mute)
          Mute or unmute the signal associated with this GainControl.
 
Methods inherited from interface javax.media.Control
getControlComponent
 

Method Detail

setMute

public void setMute(boolean mute)
Mute or unmute the signal associated with this GainControl. Calling setMute(true) on an object that is already muted is ignored, as is calling setMute(false) on an object that is not currently muted. Going from a muted to an unmuted state doesn't effect the gain.
Parameters:
mute - Specify true to mute the signal, false to unmute the signal.

getMute

public boolean getMute()
Get the mute state of the signal associated with this GainControl.
Returns:
The mute state.

setDB

public float setDB(float gain)
Set the gain in decibels. 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:
gain - The new gain in dB.
Returns:
The gain that was actually set.

getDB

public float getDB()
Get the current gain set for this object in dB.
Returns:
The gain in dB.

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 GainControl supports.
Parameters:
level - The new gain value specified in the level scale.
Returns:
The level that was actually set.

getLevel

public float getLevel()
Get the current gain set for this object as a value between 0.0 and 1.0
Returns:
The gain in the level scale (0.0-1.0).

addGainChangeListener

public void addGainChangeListener(GainChangeListener listener)
Register for gain change update events. A GainChangeEvent is posted when the state of the GainControl changes.
Parameters:
listener - The object to deliver events to.

removeGainChangeListener

public void removeGainChangeListener(GainChangeListener listener)
Remove interest in gain change update events.
Parameters:
listener - The object that has been receiving events.