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

static javax.sound.sampled.FloatControl.Type	BALANCE The balance control type.
static javax.sound.sampled.FloatControl.Type	GAIN The gain control type.
static javax.sound.sampled.BooleanControl.Type	MUTE The mute control type.
static javax.sound.sampled.FloatControl.Type	PAN The pan control type.
static javax.sound.sampled.FloatControl.Type	SAMPLE_RATE The sample rate control type.
static javax.sound.sampled.FloatControl.Type	VOLUME The volume control type.

Constructor Summary

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

Method Summary

javax.sound.sampled.FloatControl	balance() Gets the balance control for the Line, if it exists.
javax.sound.sampled.FloatControl	gain() Gets the gain control for the Line, if it exists.
float	getBalance() Returns the current balance of the line.
javax.sound.sampled.Control	getControl(javax.sound.sampled.Control.Type type)
javax.sound.sampled.Control[]	getControls() Returns an array of all the available Controls for the DataLine being controlled.
float	getGain() Returns the current gain.
float	getPan() Returns the current pan value.
float	getVolume() Returns the current volume.
boolean	hasControl(javax.sound.sampled.Control.Type type) Returns whether or not the particular control type is supported by the Line being controlled.
boolean	isMuted() Returns true if the line is muted.
void	mute() Mutes the line.
javax.sound.sampled.FloatControl	pan() Gets the pan control for the Line, if it exists.
void	printControls() Prints the available controls and their ranges to the console.
void	setBalance(float v) Sets the balance of the line to v.
void	setGain(float v) Sets the gain to v.
void	setPan(float v) Sets the pan of the line to v.
void	setVolume(float v) Sets the volume to v.
void	shiftBalance(float from, float to, int millis) Shifts the value of the balance from from to to in the space of millis milliseconds.
void	shiftGain(float from, float to, int millis) Shifts the value of the gain from from to to in the space of millis
void	shiftPan(float from, float to, int millis) Shifts the value of the pan from from to to in the space of millis milliseconds.
void	shiftVolume(float from, float to, int millis) Shifts the value of the volume from from to to in the space of millis milliseconds.
void	unmute() Unmutes the line.
javax.sound.sampled.FloatControl	volume() Gets the volume control for the Line, if it exists.

Methods inherited from class java.lang.Object

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

Field Detail

VOLUME

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

The volume control type.

GAIN

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

The gain control type.

BALANCE

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

The balance control type.

PAN

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

The pan control type.

SAMPLE_RATE

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

The sample rate control type.

MUTE

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

The mute control type.

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()

Prints the available controls and their ranges to the console. Not all lines have all of the controls available on them so this is a way to find out what is available.

hasControl

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

Returns whether or not the particular control type is supported by the Line being controlled.

Returns:

true if the control is available

See Also:

VOLUME, GAIN, BALANCE, PAN, SAMPLE_RATE, MUTE

getControls

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

Returns an array of all the available Controls for the DataLine being controlled. You can use this if you want to access the controls directly, rather than using the convenience methods provided by this class.

Returns:

an array of all available controls

getControl

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

volume

public javax.sound.sampled.FloatControl volume()

Gets the volume control for the Line, if it exists. You should check for the availability of a volume control by using hasControl(javax.sound.sampled.Control.Type) before calling this method.

Returns:

the volume control

gain

public javax.sound.sampled.FloatControl gain()

Gets the gain control for the Line, if it exists. You should check for the availability of a gain control by using hasControl(javax.sound.sampled.Control.Type) before calling this method.

Returns:

the gain control

balance

public javax.sound.sampled.FloatControl balance()

Gets the balance control for the Line, if it exists. You should check for the availability of a balance control by using hasControl(javax.sound.sampled.Control.Type) before calling this method.

Returns:

the balance control

pan

public javax.sound.sampled.FloatControl pan()

Gets the pan control for the Line, if it exists. You should check for the availability of a pan control by using hasControl(javax.sound.sampled.Control.Type) before calling this method.

Returns:

the pan control

mute

public void mute()

Mutes the line.

unmute

public void unmute()

Unmutes the line.

isMuted

public boolean isMuted()

Returns true if the line 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 v)

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

Parameters:

v - the new value for the volume

shiftVolume

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

Shifts the value of the volume from from to to in the space of millis milliseconds.

Parameters:

from - the starting volume

to - the ending volume

millis - the length of the transition

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!

Returns:

the current gain or zero if a gain control is unavailable

setGain

public void setGain(float v)

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

Parameters:

v - the new value for the gain

shiftGain

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

Shifts the value of the gain from from to to in the space of millis

Parameters:

from - the starting volume

to - the ending volume

millis - the length of the transition

getBalance

public float getBalance()

Returns the current balance of the line. This will be in the range [-1, 1]. If a balance control is not available, this will do nothing.

Returns:

the current balance or zero if a balance control is unavailable

setBalance

public void setBalance(float v)

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

Parameters:

v - the new value for the balance

shiftBalance

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

Shifts the value of the balance from from to to in the space of millis milliseconds.

Parameters:

from - the starting volume

to - the ending volume

millis - the length of the transition

getPan

public float getPan()

Returns the current pan value. This will be in the range [-1, 1]. If the pan control is not available

Returns:

the current pan or zero if a pan control is unavailable

setPan

public void setPan(float v)

Sets the pan of the line to v. The provided value should be in the range [-1, 1].

Parameters:

v - the new value for the pan

shiftPan

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

Shifts the value of the pan from from to to in the space of millis milliseconds.

Parameters:

from - the starting pan

to - the ending pan

millis - the length of the transition