javax.media
Interface GainControl

public 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:

• Level Silence Threshold. After setLevel(0.0), getDB returns the value for which smaller values are not usefully distinguishable from silence. Calling setDB with values equal to or less than this silence threshold causes getLevel to return a value of 0.0.
• Level Maximum Threshold. After setLevel(1.0), getDB returns the value for which larger values are not useful. Calling setDB with values equal to or greater than this threshold causes getLevel to return a value of 1.0.
• The decibel interface is not limited to the thresholds described by the level interface. For example, if you call setDB with a value that is greater than the maximum level threshold and then immediately call getDB, getDB returns the gain that was returned by the setDB, not the value that would be returned if you called setLevel(1.0) and then called getDB.
• Both measures increase gain monotonically with increasing measure values.

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.