ddf.minim

Class AudioOutput

java.lang.Object

ddf.minim.Controller

ddf.minim.AudioSource

ddf.minim.AudioOutput

All Implemented Interfaces:

Effectable, Polyphonic, Recordable

public class AudioOutput
extends AudioSource
implements Polyphonic

An AudioOutput is a connection to the output of a computer's sound card. Typically the computer speakers are connected to this. You can use an AudioOutput to do real-time sound synthesis by patching UGens to an output object. You can get an AudioOutput object from Minim using one of five methods:

 AudioOutput getLineOut()
 
 // specifiy either Minim.MONO or Minim.STEREO for type
 AudioOutput getLineOut(int type)
 
 // bufferSize is the size of the left, right,
 // and mix buffers of the output you get back
 AudioOutput getLineOut(int type, int bufferSize)
 
 // sampleRate is a request for an output of a certain sample rate
 AudioOutput getLineOut(int type, int bufferSize, float sampleRate)
 
 // bitDepth is a request for an output with a certain bit depth
 AudioInput getLineOut(int type, int bufferSize, float sampleRate, int bitDepth)
 

In the event that an output doesn't exist with the requested parameters, Minim will spit out an error and return null. In general, you will want to use one of the first two methods listed above.

In addition to directly patching UGens to the output, you can also schedule "notes" to be played by the output at some time in the future. This can be very powerful when writing algorithmic music and sound. See the playNote method for more information.

Author:

Damien Di Fede

Field Summary

Fields inherited from class ddf.minim.AudioSource

left, mix, right

Fields inherited from class ddf.minim.Controller

BALANCE, GAIN, MUTE, PAN, SAMPLE_RATE, VOLUME

Constructor Summary

Constructors

Constructor and Description
AudioOutput(ddf.minim.spi.AudioOut out) Constructs an AudioOutput that will use out to generate sound.

Method Summary

Modifier and Type	Method and Description
void	addSignal(AudioSignal signal) Deprecated.
void	clearSignals() Deprecated.
void	disableSignal(AudioSignal signal) Deprecated.
void	disableSignal(int i) Deprecated.
void	enableSignal(AudioSignal signal) Deprecated.
void	enableSignal(int i) Deprecated.
float	getDurationFactor() Return the current value of the duration factor for this output.
float	getNoteOffset() Return the current value of the note offset for this output.
AudioSignal	getSignal(int i) Deprecated.
float	getTempo() Return the current tempo of the AudioOuput.
boolean	hasSignal(AudioSignal signal) Deprecated.
boolean	isEnabled(AudioSignal signal) Deprecated.
boolean	isSounding() Deprecated.
void	noSound() Deprecated.
void	pauseNotes() An AudioOutput processes its note queue in its own Thread, so if you are going to queue up a lot of notes at once you will want to use the pauseNotes method before queuing them.
void	playNote() Schedule a "note" to played by the output that uses the default Instrument, has a duration of 1 beat, is played immediately, and has a pitch of "A4".
void	playNote(float hz) Schedule a "note" to played by the output that uses the default Instrument, has a duration of 1 beat, and is played immediately.
void	playNote(float startTime, float hz) Schedule a "note" to played by the output that uses the default Instrument and has a duration of 1 beat.
void	playNote(float startTime, float duration, float hz) Schedule a "note" to played by the output that uses the default Instrument.
void	playNote(float startTime, float duration, Instrument instrument) playNote is a method of scheduling a "note" to be played at some time in the future (or immediately), where a "note" is an instance of a class that implements the Instrument interface.
void	playNote(float startTime, float duration, java.lang.String pitchName) Schedule a "note" to played by the output that uses the default Instrument.
void	playNote(float startTime, java.lang.String pitchName) Schedule a "note" to played by the output that uses the default Instrument and has a duration of 1 beat.
void	playNote(java.lang.String pitchName) Schedule a "note" to played by the output that uses the default Instrument, has a duration of 1 beat, and is played immediately.
void	removeSignal(AudioSignal signal) Deprecated.
AudioSignal	removeSignal(int i) Deprecated.
void	resumeNotes() Resume note processing.
void	setDurationFactor(float durationFactor) The duration factor of an AudioOutput defines how durations passed to playNote calls are scaled before being queued.
void	setNoteOffset(float noteOffset) When writing out musical scores in code, it is often nice to think about music in sections, where all of the playNote calls have start times relative to the beginning of the section.
void	setTempo(float tempo) The tempo of an AudioOutput controls how it will interpret the start time and duration arguments of playNote methods.
int	signalCount() Deprecated.
void	sound() Deprecated.

Methods inherited from class ddf.minim.AudioSource

addEffect, addListener, bufferSize, clearEffects, close, disableEffect, disableEffect, effectCount, effects, enableEffect, enableEffect, getEffect, getFormat, hasEffect, isEffected, isEnabled, noEffects, removeEffect, removeEffect, removeListener, sampleRate, type

Methods inherited from class ddf.minim.Controller

balance, gain, getBalance, getControl, getControls, getGain, getPan, getVolume, hasControl, isMuted, mute, pan, printControls, setBalance, setGain, setPan, setVolume, shiftBalance, shiftGain, shiftPan, shiftVolume, unmute, volume

Methods inherited from class java.lang.Object

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

Constructor Detail

AudioOutput

public AudioOutput(ddf.minim.spi.AudioOut out)

Constructs an AudioOutput that will use out to generate sound.

Parameters:

out - the AudioOut that does most of our work

Method Detail

addSignal

public void addSignal(AudioSignal signal)

Deprecated.

Description copied from interface: Polyphonic

Adds an signal to the signals chain.

Specified by:

addSignal in interface Polyphonic

Parameters:

signal - the AudioSignal to add

getSignal

public AudioSignal getSignal(int i)

Deprecated.

Description copied from interface: Polyphonic

Returns the ith signal in the signal chain. This method is not required to do bounds checking and may throw an ArrayOutOfBoundsException if i is larger than Polyphonic.signalCount().

Specified by:

getSignal in interface Polyphonic

Parameters:

i - which signal to return

Returns:

the requested signal

removeSignal

public void removeSignal(AudioSignal signal)

Deprecated.

Description copied from interface: Polyphonic

Removes signal from the signals chain.

Specified by:

removeSignal in interface Polyphonic

Parameters:

signal - the AudioSignal to remove

removeSignal

public AudioSignal removeSignal(int i)

Deprecated.

Description copied from interface: Polyphonic

Removes and returns the ith signal in the signal chain.

Specified by:

removeSignal in interface Polyphonic

Parameters:

i - which signal to remove

Returns:

the removed AudioSignal

clearSignals

public void clearSignals()

Deprecated.

Description copied from interface: Polyphonic

Removes all signals from the signal chain.

Specified by:

clearSignals in interface Polyphonic

disableSignal

public void disableSignal(int i)

Deprecated.

Description copied from interface: Polyphonic

disables the i^th signal in the signal chain.

Specified by:

disableSignal in interface Polyphonic

Parameters:

i - the index of the signal to disable

disableSignal

public void disableSignal(AudioSignal signal)

Deprecated.

Description copied from interface: Polyphonic

Disables signal if it is in the chain.

Specified by:

disableSignal in interface Polyphonic

Parameters:

signal - the AudioSignal to disable

enableSignal

public void enableSignal(int i)

Deprecated.

Description copied from interface: Polyphonic

Enables the i^th signal in the signal chain.

Specified by:

enableSignal in interface Polyphonic

Parameters:

i - the index of the signal to enable

enableSignal

public void enableSignal(AudioSignal signal)

Deprecated.

Description copied from interface: Polyphonic

Enables signal if it is in the chain.

Specified by:

enableSignal in interface Polyphonic

Parameters:

signal - the AudioSignal to enable

isEnabled

public boolean isEnabled(AudioSignal signal)

Deprecated.

Description copied from interface: Polyphonic

Returns true if signal is in the chain and is also enabled.

Specified by:

isEnabled in interface Polyphonic

Parameters:

signal - the AudioSignal to check the status of

Returns:

true if signal is in the chain and is enabled

isSounding

public boolean isSounding()

Deprecated.

Description copied from interface: Polyphonic

Returns true if at least one signal in the chain is enabled.

Specified by:

isSounding in interface Polyphonic

Returns:

true if at least one signal in the signal chain is enabled

noSound

public void noSound()

Deprecated.

Description copied from interface: Polyphonic

Disables all signals currently attached to this. If you want to disable only a single signal, use Polyphonic.disableSignal(int).

Specified by:

noSound in interface Polyphonic

signalCount

public int signalCount()

Deprecated.

Description copied from interface: Polyphonic

Returns the number of signals in the chain.

Specified by:

signalCount in interface Polyphonic

Returns:

the number of signals in the chain

sound

public void sound()

Deprecated.

Description copied from interface: Polyphonic

Enables all signals currently attached to this. If you want to enable only a single signal, use Polyphonic.enableSignal(int).

Specified by:

sound in interface Polyphonic

hasSignal

public boolean hasSignal(AudioSignal signal)

Deprecated.

Specified by:

hasSignal in interface Polyphonic

playNote

public void playNote(float startTime,
                     float duration,
                     Instrument instrument)

playNote is a method of scheduling a "note" to be played at some time in the future (or immediately), where a "note" is an instance of a class that implements the Instrument interface. The Instrument interface requires you to implement a noteOn method that accepts a float duration value and is called when that Instrument should begin making sound, and a noteOff method that is called when that Instrument should stop making sound.

Versions of playNote that do not have an Instrument argument will create an instance of a default Instrument that plays a sine tone based on the parameters passed in.

To facilitate writing algorithmic music, the start time and duration of a note is expressed in beats and not in seconds. By default, the tempo of an AudioOutput will be 60 BPM (beats per minute), which means that beats are equivalent to seconds. If you want to think in seconds when writing your note playing code, then simply don't change the tempo of the output.

Another thing to keep in mind is that the AudioOutput processes its note queue in its own Thread, so if you are going to queue up a lot of notes at once you will want to use the pauseNotes method before queuing them. If you don't, the timing will be slightly off because the "now" that the start time of each note is an offset from will change from note to note. Once all of your notes have been added, you call resumeNotes to allow the AudioOutput to process notes again.

Parameters:

startTime - float: when the note should begin playing, in beats

duration - float: how long the note should be, in beats

instrument - the Instrument that will play the note

playNote

public void playNote(float startTime,
                     float duration,
                     float hz)

Schedule a "note" to played by the output that uses the default Instrument.

Parameters:

startTime - float: when the note should begin playing, in beats

duration - float: how long the note should be, in beats

hz - float: the frequency, in Hertz, of the note to be played

See Also:

playNote(float, float, Instrument)

playNote

public void playNote(float startTime,
                     float duration,
                     java.lang.String pitchName)

Schedule a "note" to played by the output that uses the default Instrument.

Parameters:

startTime - float: when the note should begin playing, in beats

duration - float: how long the note should be, in beats

pitchName - String: the pitch name of the note to be played (e.g. "A4" or "Bb3")

See Also:

playNote(float, float, Instrument)

playNote

public void playNote(float startTime,
                     float hz)

Schedule a "note" to played by the output that uses the default Instrument and has a duration of 1 beat.

Parameters:

startTime - float: when the note should begin playing, in beats

hz - float: the frequency, in Hertz, of the note to be played

See Also:

playNote(float, float, Instrument)

playNote

public void playNote(float startTime,
                     java.lang.String pitchName)

Schedule a "note" to played by the output that uses the default Instrument and has a duration of 1 beat.

Parameters:

startTime - float: when the note should begin playing, in beats

pitchName - String: the pitch name of the note to be played (e.g. "A4" or "Bb3")

See Also:

playNote(float, float, Instrument)

playNote

public void playNote(float hz)

Schedule a "note" to played by the output that uses the default Instrument, has a duration of 1 beat, and is played immediately.

Parameters:

hz - float: the frequency, in Hertz, of the note to be played

See Also:

playNote(float, float, Instrument)

playNote

public void playNote(java.lang.String pitchName)

Schedule a "note" to played by the output that uses the default Instrument, has a duration of 1 beat, and is played immediately.

Parameters:

pitchName - String: the pitch name of the note to be played (e.g. "A4" or "Bb3")

See Also:

playNote(float, float, Instrument)

playNote

public void playNote()

Schedule a "note" to played by the output that uses the default Instrument, has a duration of 1 beat, is played immediately, and has a pitch of "A4". This is good to use if you just want to generate some test tones.

See Also:

playNote(float, float, Instrument)

setTempo

public void setTempo(float tempo)

The tempo of an AudioOutput controls how it will interpret the start time and duration arguments of playNote methods. By default the tempo of an AudioOutput is 60 BPM (beats per minute), which means that one beat lasts one second. Setting the tempo to 120 BPM means that one beat lasts half of a second. When the tempo is changed, it will only effect playNote calls made after the change.

Parameters:

tempo - float: the new tempo for the AudioOutput, in BPM (beats per minute)

getTempo

public float getTempo()

Return the current tempo of the AudioOuput. Tempo is expressed in BPM (beats per minute).

Returns:

float: the current tempo

setNoteOffset

public void setNoteOffset(float noteOffset)

When writing out musical scores in code, it is often nice to think about music in sections, where all of the playNote calls have start times relative to the beginning of the section. The setNoteOffset method facilitates this by letting you set a time from which all start times passed to playNote calls will add on to. So, if you set the note offset to 16, that means all playNote start times will be relative to the 16th beat from "now".

By default, note offset is 0.

Parameters:

noteOffset - float: the amount of time added to all start times passed to playNote calls.

getNoteOffset

public float getNoteOffset()

Return the current value of the note offset for this output.

Returns:

float: the current note offset

setDurationFactor

public void setDurationFactor(float durationFactor)

The duration factor of an AudioOutput defines how durations passed to playNote calls are scaled before being queued. If your duration factor is 0.5 and you queue a note with a duration of 2, the actual duration will become 1. This might be useful if you want to queue a string of notes first with long durations and then very short durations.

By default the duration factor is 1.

Parameters:

durationFactor - float: the duration factor

getDurationFactor

public float getDurationFactor()

Return the current value of the duration factor for this output.

Returns:

float: the current duration factor

pauseNotes

public void pauseNotes()

An AudioOutput processes its note queue in its own Thread, so if you are going to queue up a lot of notes at once you will want to use the pauseNotes method before queuing them. If you don't, the timing will be slightly off because the "now" that the start time of each note is an offset from will change from note to note. Once all of your notes have been added, you call resumeNotes to allow the AudioOutput to process notes again.

resumeNotes

public void resumeNotes()

Resume note processing.

See Also:

pauseNotes()