ddf.minim

Class Controller

java.lang.Object

ddf.minim.Controller

Direct Known Subclasses:

AudioSnippet, AudioSource

public class Controller
extends java.lang.Object

Controller is the base class of all Minim classes that deal with audio I/O. It provides control over the underlying DataLine, which is a low-level JavaSound class that talks directly to the audio hardware of the computer. This means that you can make changes to the audio without having to manipulate the samples directly. The downside to this is that when outputting sound to the system (such as with an AudioOutput), these changes will not be present in the samples made available to your program.

The volume(), gain(), pan(), and balance() methods return objects of type FloatControl, which is a class defined by the JavaSound API. A FloatControl represents a control of a line that holds a float value. This value has an associated maximum and minimum value (such as between -1 and 1 for pan), and also a unit type (such as dB for gain). You should refer to the FloatControl Javadoc for the full description of the methods available.

Not all controls are available on all objects. Before calling the methods mentioned above, you should call hasControl(javax.sound.sampled.Control.Type) with the control type you want to use. Alternatively, you can use the get and set methods, which will simply do nothing if the control you are trying to manipulate is not available.

Author:

Damien Di Fede

Field Summary

Fields

Modifier and Type	Field and Description
static javax.sound.sampled.FloatControl.Type	BALANCE Deprecated.
static javax.sound.sampled.FloatControl.Type	GAIN Deprecated.
static javax.sound.sampled.BooleanControl.Type	MUTE Deprecated.
static javax.sound.sampled.FloatControl.Type	PAN Deprecated.
static javax.sound.sampled.FloatControl.Type	SAMPLE_RATE Deprecated.
static javax.sound.sampled.FloatControl.Type	VOLUME Deprecated.

Constructor Summary

Constructors

Constructor and Description
Controller(javax.sound.sampled.Control[] cntrls) Constructs a Controller for the given Line.

Method Summary

Modifier and Type	Method and Description
javax.sound.sampled.FloatControl	balance() Deprecated.
javax.sound.sampled.FloatControl	gain() Deprecated.
float	getBalance() Returns the current balance.
javax.sound.sampled.Control	getControl(javax.sound.sampled.Control.Type type) Deprecated.
javax.sound.sampled.Control[]	getControls() Deprecated.
float	getGain() Returns the current gain.
float	getPan() Returns the current pan.
float	getVolume() Returns the current volume.
boolean	hasControl(javax.sound.sampled.Control.Type type) Deprecated.
boolean	isMuted() Returns true if the sound is muted.
void	mute() Mutes the sound.
javax.sound.sampled.FloatControl	pan() Deprecated.
void	printControls()
void	setBalance(float value) Sets the balance.
void	setGain(float value) Sets the gain.
void	setPan(float value) Sets the pan.
void	setVolume(float value) Sets the volume.
void	shiftBalance(float from, float to, int millis) Transitions the balance from one value to another.
void	shiftGain(float from, float to, int millis) Transitions the gain from one value to another.
void	shiftPan(float from, float to, int millis) Transitions the pan from one value to another.
void	shiftVolume(float from, float to, int millis) Transitions the volume from one value to another.
void	unmute() Unmutes the sound.
javax.sound.sampled.FloatControl	volume() Deprecated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VOLUME

@Deprecated
public static javax.sound.sampled.FloatControl.Type VOLUME

Deprecated.

GAIN

@Deprecated
public static javax.sound.sampled.FloatControl.Type GAIN

Deprecated.

BALANCE

@Deprecated
public static javax.sound.sampled.FloatControl.Type BALANCE

Deprecated.

PAN

@Deprecated
public static javax.sound.sampled.FloatControl.Type PAN

Deprecated.

SAMPLE_RATE

@Deprecated
public static javax.sound.sampled.FloatControl.Type SAMPLE_RATE

Deprecated.

MUTE

@Deprecated
public static javax.sound.sampled.BooleanControl.Type MUTE

Deprecated.

Constructor Detail

Controller

public Controller(javax.sound.sampled.Control[] cntrls)

Constructs a Controller for the given Line.

Parameters:

cntrls - an array of Controls that this Controller will manipulate

Method Detail

printControls

public void printControls()

hasControl

@Deprecated
public boolean hasControl(javax.sound.sampled.Control.Type type)

Deprecated.

Parameters:

type - the Control.Type to query for

Returns:

true if the control is available

See Also:

VOLUME, GAIN, BALANCE, PAN, SAMPLE_RATE, MUTE

getControls

@Deprecated
public javax.sound.sampled.Control[] getControls()

Deprecated.

Returns:

an array of all available controls

getControl

@Deprecated
public javax.sound.sampled.Control getControl(javax.sound.sampled.Control.Type type)

Deprecated.

volume

@Deprecated
public javax.sound.sampled.FloatControl volume()

Deprecated.

Returns:

the volume control

gain

@Deprecated
public javax.sound.sampled.FloatControl gain()

Deprecated.

Returns:

the gain control

balance

@Deprecated
public javax.sound.sampled.FloatControl balance()

Deprecated.

Returns:

the balance control

pan

@Deprecated
public javax.sound.sampled.FloatControl pan()

Deprecated.

Returns:

the pan control

mute

public void mute()

Mutes the sound.

unmute

public void unmute()

Unmutes the sound.

isMuted

public boolean isMuted()

Returns true if the sound is muted.

Returns:

the current mute state

getVolume

public float getVolume()

Returns the current volume. If a volume control is not available, this returns 0. Note that the volume is not the same thing as the level() of an AudioBuffer!

Returns:

the current volume or zero if a volume control is unavailable

setVolume

public void setVolume(float value)

Sets the volume. If a volume control is not available, this does nothing.

Parameters:

value - float: the new value for the volume, usually in the range [0,1].

shiftVolume

public void shiftVolume(float from,
                        float to,
                        int millis)

Transitions the volume from one value to another.

Parameters:

from - float: the starting volume

to - float: the ending volume

millis - int: the length of the transition in milliseconds

getGain

public float getGain()

Returns the current gain. If a gain control is not available, this returns 0. Note that the gain is not the same thing as the level() of an AudioBuffer! Gain describes the current volume of the sound in decibels, which is a logarithmic, rather than linear, scale. A gain of 0dB means the sound is not being amplified or attenuated. Negative gain values will reduce the volume of the sound, and positive values will increase it.

See: http://wikipedia.org/wiki/Decibel

Returns:

float: the current gain or zero if a gain control is unavailable. the gain is expressed in decibels.

setGain

public void setGain(float value)

Sets the gain. If a gain control is not available, this does nothing.

Parameters:

value - float: the new value for the gain, expressed in decibels.

shiftGain

public void shiftGain(float from,
                      float to,
                      int millis)

Transitions the gain from one value to another.

Parameters:

from - float: the starting gain

to - float: the ending gain

millis - int: the length of the transition in milliseconds

getBalance

public float getBalance()

Returns the current balance. This will be in the range [-1, 1]. Usually balance will only be available for stereo audio sources, because it describes how much attenuation should be applied to the left and right channels. If a balance control is not available, this will do nothing.

Returns:

float: the current balance or zero if a balance control is unavailable

setBalance

public void setBalance(float value)

Sets the balance. The value should be in the range [-1, 1]. If a balance control is not available, this will do nothing.

Parameters:

value - float: the new value for the balance

shiftBalance

public void shiftBalance(float from,
                         float to,
                         int millis)

Transitions the balance from one value to another.

Parameters:

from - float: the starting balance

to - float: the ending balance

millis - int: the length of the transition in milliseconds

getPan

public float getPan()

Returns the current pan. Usually pan will be only be available on mono audio sources because it describes a mono signal's position in a stereo field. This will be in the range [-1, 1], where -1 will place the sound only in the left speaker and 1 will place the sound only in the right speaker.

Returns:

float: the current pan or zero if a pan control is unavailable

setPan

public void setPan(float value)

Sets the pan. The provided value should be in the range [-1, 1]. If a pan control is not present, this does nothing.

Parameters:

value - float: the new value for the pan

shiftPan

public void shiftPan(float from,
                     float to,
                     int millis)

Transitions the pan from one value to another.

Parameters:

from - float: the starting pan

to - float: the ending pan

millis - int: the length of the transition in milliseconds