File Doc Category Size Date Package
GainControl.java API Doc JMF 2.1.1e 6163 Mon May 12 12:20:36 BST 2003 javax.media

GainControl

public interface GainControl implements 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: GainChangeEvent
see: GainChangeListener
see: Control
version: 1.2, 02/08/21

Fields Summary
Constructors Summary
Methods Summary
public void addGainChangeListener(javax.media.GainChangeListener listener)
Register for gain change update events. A GainChangeEvent is posted when the state of the GainControl changes.
param
listener The object to deliver events to.
public float getDB()
Get the current gain set for this object in dB.
return
The gain in dB.
public float getLevel()
Get the current gain set for this object as a value between 0.0 and 1.0
return
The gain in the level scale (0.0-1.0).
public boolean getMute()
Get the mute state of the signal associated with this GainControl.
return
The mute state.
public void removeGainChangeListener(javax.media.GainChangeListener listener)
Remove interest in gain change update events.
param
listener The object that has been receiving events.
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.
param
gain The new gain in dB.
return
The gain that was actually set.
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.
param
level The new gain value specified in the level scale.
return
The level that was actually set.
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.
param
mute Specify true to mute the signal, false to unmute the signal.