ddf.minim
Class Minim

java.lang.Object
  ddf.minim.Minim

public class Minim
extends java.lang.Object

The Minim class is how you get what you want from JavaSound. There are methods for obtaining objects for playing audio files: AudioSample, AudioSnippet, and AudioPlayer. There are methods for obtaining an AudioRecorder, which is how you record audio to disk. There are methods for obtaining an AudioInput, which is how you can monitor the computer's line-in or microphone, depending on what the user has set as the record source. Finally there are methods for obtaining an AudioOutput, which is how you can play audio generated by your program. All of these classes are given AudioStreams by Minim, which are Threads that do the actual work of audio I/O. Because of this, you should always call the close method of an AudioXXX when you are finished with it.

Minim needs to know about your sketch so that it can load files from the sketch's data directory. For this reason, you must pass a PApplet to the constructor.

Author:

Damien Di Fede

Field Summary

static javax.sound.sampled.AudioFileFormat.Type	AIFC The .aifc file format.
static javax.sound.sampled.AudioFileFormat.Type	AIFF The .aiff file format.
static javax.sound.sampled.AudioFileFormat.Type	AU The .au file format.
static int	LOOP_CONTINUOUSLY
static int	MONO Specifies that you want a MONO AudioInput or AudioOutput
static javax.sound.sampled.AudioFileFormat.Type	SND The .snd file format.
static int	STEREO Specifies that you want a STEREO AudioInput or AudioOutput
static javax.sound.sampled.AudioFileFormat.Type	WAV The .wav file format.

Constructor Summary

Minim(processing.core.PApplet parent)
Creates an instance of Minim that will use the Javasound implementation.

Minim(processing.core.PApplet parent, MinimServiceProvider msp)
Creates an instance of Minim that will use the provided implementation for audio.

Method Summary

AudioRecorder	createRecorder(Recordable source, java.lang.String fileName, boolean buffered) Creates an AudioRecorder that will use source as its record source and that will save to the file name specified.
AudioSample	createSample(float[] samples, javax.sound.sampled.AudioFormat format) Creates an AudioSample using the provided samples and AudioFormat, with an output buffer size of 1024 samples.
AudioSample	createSample(float[] samples, javax.sound.sampled.AudioFormat format, int bufferSize) Creates an AudioSample using the provided samples and AudioFormat, with the desired output buffer size.
AudioSample	createSample(float[] left, float[] right, javax.sound.sampled.AudioFormat format) Creates an AudioSample using the provided left and right channel samples with an output buffer size of 1024.
AudioSample	createSample(float[] left, float[] right, javax.sound.sampled.AudioFormat format, int bufferSize) Creates an AudioSample using the provided left and right channel samples.
static void	debug(java.lang.String s) Displays a debug message, but only if debugOn() has been called.
void	debugOff() Turns off debug messages.
void	debugOn() Turns on debug messages.
static void	error(java.lang.String s) Used internally to report error messages.
AudioStream	getInputStream(int type, int bufferSize, float sampleRate, int bitDepth) Get the input as an AudioStream that you can read from yourself, rather than wrapped in an AudioInput that does that work for you.
AudioInput	getLineIn() Gets an AudioInput, to which you can attach AudioEffects.
AudioInput	getLineIn(int type) Gets an AudioInput, to which you can attach AudioEffects.
AudioInput	getLineIn(int type, int bufferSize) Gets an AudioInput, to which you can attach AudioEffects.
AudioInput	getLineIn(int type, int bufferSize, float sampleRate) Gets an AudioInput, to which you can attach AudioEffects.
AudioInput	getLineIn(int type, int bufferSize, float sampleRate, int bitDepth) Gets an AudioInput, to which you can attach AudioEffects.
AudioOutput	getLineOut() Gets an AudioOutput, to which you can attach AudioSignals and AudioEffects.
AudioOutput	getLineOut(int type) Gets an AudioOutput, to which you can attach AudioSignals and AudioEffects.
AudioOutput	getLineOut(int type, int bufferSize) Gets an AudioOutput, to which you can attach AudioSignals and AudioEffects.
AudioOutput	getLineOut(int type, int bufferSize, float sampleRate) Gets an AudioOutput, to which you can attach AudioSignals and AudioEffects.
AudioOutput	getLineOut(int type, int bufferSize, float sampleRate, int bitDepth) Gets an AudioOutput, to which you can attach AudioSignals and AudioEffects.
AudioPlayer	loadFile(java.lang.String filename) Loads the requested file into an AudioPlayer with a buffer size of 1024 samples.
AudioPlayer	loadFile(java.lang.String filename, int bufferSize) Loads the requested file into an AudioPlayer with the request buffer size.
AudioRecordingStream	loadFileStream(java.lang.String filename, int bufferSize, boolean inMemory) Creates and AudioRecordingStream that you can use to read from the file yourself, rather than wrapping it in an AudioPlayer that does the work for you.
AudioSample	loadSample(java.lang.String filename) Loads the requested file into an AudioSample.
AudioSample	loadSample(java.lang.String filename, int bufferSize) Loads the requested file into an AudioSample.
AudioSnippet	loadSnippet(java.lang.String filename) Deprecated.
void	playNote() Play the note A4 (or random?) right now for 1 second.
void	playNote(float frequency) Play a note at the given frequency right now for 1 second.
void	playNote(float duration, float frequency) Play a note for the given duration, starting right now, at the given frequency.
void	playNote(float startTime, float duration, float frequency) Play a note startTime seconds from now, for the given duration, at the given frequency.
void	playNote(float startTime, float duration, Instrument instrument) Play a note startTime seconds from now, for the given duration, using the given instrument.
void	setInputMixer(javax.sound.sampled.Mixer mixer) Sets the Javasound Mixer that will be used for obtaining input sources such as AudioInputs.
void	setOutputMixer(javax.sound.sampled.Mixer mixer) Sets the Javasound Mixer that will be used for obtain output destinations such as those required by AudioOuput, AudioPlayer, AudioSample, and so forth.
void	stop() Stops Minim.

Methods inherited from class java.lang.Object

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

Field Detail

MONO

public static final int MONO

Specifies that you want a MONO AudioInput or AudioOutput

See Also:

Constant Field Values

STEREO

public static final int STEREO

Specifies that you want a STEREO AudioInput or AudioOutput

See Also:

Constant Field Values

LOOP_CONTINUOUSLY

public static final int LOOP_CONTINUOUSLY

See Also:

Constant Field Values

WAV

public static javax.sound.sampled.AudioFileFormat.Type WAV

The .wav file format.

AIFF

public static javax.sound.sampled.AudioFileFormat.Type AIFF

The .aiff file format.

AIFC

public static javax.sound.sampled.AudioFileFormat.Type AIFC

The .aifc file format.

AU

public static javax.sound.sampled.AudioFileFormat.Type AU

The .au file format.

SND

public static javax.sound.sampled.AudioFileFormat.Type SND

The .snd file format.

Constructor Detail

Minim

public Minim(processing.core.PApplet parent)

Creates an instance of Minim that will use the Javasound implementation.

Parameters:

parent - the PApplet that will be used for loading files

Minim

public Minim(processing.core.PApplet parent,
             MinimServiceProvider msp)

Creates an instance of Minim that will use the provided implementation for audio.

Parameters:

parent - the PApplet that will be used for loading files

msp - the MinimServiceProvider that will be used for returning audio resources

Method Detail

error

public static void error(java.lang.String s)

Used internally to report error messages. These error messages will appear in the console area of the PDE if you are running a sketch from the PDE, otherwise they will appear in the Java Console.

Parameters:

s - the error message to report

debug

public static void debug(java.lang.String s)

Displays a debug message, but only if debugOn() has been called. The message will be displayed in the console area of the PDE, if you are running your sketch from the PDE. Otherwise, it will be displayed in the Java Console.

Parameters:

s - the message to display

See Also:

debugOn()

debugOn

public void debugOn()

Turns on debug messages.

debugOff

public void debugOff()

Turns off debug messages.

stop

public void stop()

Stops Minim. A call to this method should be placed inside of the stop() function of your sketch. We expect that implemenations of the Minim interface made need to do some cleanup, so this is how we tell them it's time.

setInputMixer

public void setInputMixer(javax.sound.sampled.Mixer mixer)

Sets the Javasound Mixer that will be used for obtaining input sources such as AudioInputs. This will do nothing if you have provided your own MinimServiceProvider.

Parameters:

mixer - The Mixer we should try to acquire inputs from.

setOutputMixer

public void setOutputMixer(javax.sound.sampled.Mixer mixer)

Sets the Javasound Mixer that will be used for obtain output destinations such as those required by AudioOuput, AudioPlayer, AudioSample, and so forth. This will do nothing if you have provided your own MinimServiceProvider.

Parameters:

mixer - The Mixer we should try to acquire outputs from.

createSample

public AudioSample createSample(float[] samples,
                                javax.sound.sampled.AudioFormat format)

Creates an AudioSample using the provided samples and AudioFormat, with an output buffer size of 1024 samples.

Parameters:

samples - the samples to use

format - the format to play the samples back at

createSample

public AudioSample createSample(float[] samples,
                                javax.sound.sampled.AudioFormat format,
                                int bufferSize)

Creates an AudioSample using the provided samples and AudioFormat, with the desired output buffer size.

Parameters:

samples - the samples to use

format - the format to play them back at

bufferSize - the output buffer size to use

createSample

public AudioSample createSample(float[] left,
                                float[] right,
                                javax.sound.sampled.AudioFormat format)

Creates an AudioSample using the provided left and right channel samples with an output buffer size of 1024.

Parameters:

left - the left channel of the sample

right - the right channel of the sample

format - the format the sample should be played back with

createSample

public AudioSample createSample(float[] left,
                                float[] right,
                                javax.sound.sampled.AudioFormat format,
                                int bufferSize)

Creates an AudioSample using the provided left and right channel samples.

Parameters:

left - the left channel of the sample

right - the right channel of the sample

format - the format the sample should be played back with

bufferSize - the output buffer size desired

loadSample

public AudioSample loadSample(java.lang.String filename)

Loads the requested file into an AudioSample.

Parameters:

filename - the file or URL that you want to load

Returns:

an AudioSample with a 1024 sample buffer

See Also:

loadSample(String, int), AudioSample

loadSample

public AudioSample loadSample(java.lang.String filename,
                              int bufferSize)

Loads the requested file into an AudioSample.

Parameters:

filename - the file or URL that you want to load

bufferSize - the sample buffer size you want

Returns:

an AudioSample with a sample buffer of the requested size

loadSnippet

public AudioSnippet loadSnippet(java.lang.String filename)

Deprecated.

loadFile

public AudioPlayer loadFile(java.lang.String filename)

Loads the requested file into an AudioPlayer with a buffer size of 1024 samples.

Parameters:

filename - the file or URL you want to load

Returns:

an AudioPlayer with a 1024 sample buffer

See Also:

loadFile(String, int)

loadFile

public AudioPlayer loadFile(java.lang.String filename,
                            int bufferSize)

Loads the requested file into an AudioPlayer with the request buffer size.

Parameters:

filename - the file or URL you want to load

bufferSize - the sample buffer size you want

Returns:

an AudioPlayer with a sample buffer of the requested size

loadFileStream

public AudioRecordingStream loadFileStream(java.lang.String filename,
                                           int bufferSize,
                                           boolean inMemory)

Creates and AudioRecordingStream that you can use to read from the file yourself, rather than wrapping it in an AudioPlayer that does the work for you.

Parameters:

filename - the file to load

bufferSize - the bufferSize to use

inMemory - whether or not the file should be cached in memory as it is read

Returns:

and AudioRecordingStream that you can use to read from the file.

createRecorder

public AudioRecorder createRecorder(Recordable source,
                                    java.lang.String fileName,
                                    boolean buffered)

Creates an AudioRecorder that will use source as its record source and that will save to the file name specified. The format of the file will be inferred from the extension in the file name. If the extension is not a recognized file type, this will return null. Be aware that if you choose buffered recording the call to AudioRecorder.save() will block until the entire buffer is written to disk. In the event that the buffer is very large, your sketch will noticably hang.

Parameters:

source - the Recordable object you want to use as a record source

fileName - the name of the file to record to

buffered - whether or not to use buffered recording

Returns:

an AudioRecorder for the record source

getLineIn

public AudioInput getLineIn()

Gets an AudioInput, to which you can attach AudioEffects.

Returns:

an STEREO AudioInput with a 1024 sample buffer, a sample rate of 44100 and a bit depth of 16

See Also:

getLineIn(int, int, float, int)

getLineIn

public AudioInput getLineIn(int type)

Gets an AudioInput, to which you can attach AudioEffects.

Parameters:

type - Minim.MONO or Minim.STEREO

Returns:

an AudioInput with the requested type, a 1024 sample buffer, a sample rate of 44100 and a bit depth of 16

See Also:

getLineIn(int, int, float, int)

getLineIn

public AudioInput getLineIn(int type,
                            int bufferSize)

Gets an AudioInput, to which you can attach AudioEffects.

Parameters:

type - Minim.MONO or Minim.STEREO

bufferSize - how long you want the AudioInput's sample buffer to be

Returns:

an AudioInput with the requested attributes, a sample rate of 44100 and a bit depth of 16

See Also:

getLineIn(int, int, float, int)

getLineIn

public AudioInput getLineIn(int type,
                            int bufferSize,
                            float sampleRate)

Gets an AudioInput, to which you can attach AudioEffects.

Parameters:

type - Minim.MONO or Minim.STEREO

bufferSize - how long you want the AudioInput's sample buffer to be

sampleRate - the desired sample rate in Hertz (typically 44100)

Returns:

an AudioInput with the requested attributes and a bit depth of 16

See Also:

getLineIn(int, int, float, int)

getLineIn

public AudioInput getLineIn(int type,
                            int bufferSize,
                            float sampleRate,
                            int bitDepth)

Gets an AudioInput, to which you can attach AudioEffects.

Parameters:

type - Minim.MONO or Minim.STEREO

bufferSize - how long you want the AudioInput's sample buffer to be

sampleRate - the desired sample rate in Hertz (typically 44100)

bitDepth - the desired bit depth (typically 16)

Returns:

an AudioInput with the requested attributes

getInputStream

public AudioStream getInputStream(int type,
                                  int bufferSize,
                                  float sampleRate,
                                  int bitDepth)

Get the input as an AudioStream that you can read from yourself, rather than wrapped in an AudioInput that does that work for you.

Parameters:

type - Minim.MONO or Minim.STEREO

bufferSize - how long you want the AudioInput's sample buffer to be

sampleRate - the desired sample rate in Hertz (typically 44100)

bitDepth - the desired bit depth (typically 16)

Returns:

an AudioStream that reads from the input source of the soundcard.

getLineOut

public AudioOutput getLineOut()

Gets an AudioOutput, to which you can attach AudioSignals and AudioEffects.

Returns:

a STEREO AudioOutput with a 1024 sample buffer, a sample rate of 44100 and a bit depth of 16

See Also:

getLineOut(int, int, float, int)

getLineOut

public AudioOutput getLineOut(int type)

Gets an AudioOutput, to which you can attach AudioSignals and AudioEffects.

Parameters:

type - Minim.MONO or Minim.STEREO

Returns:

an AudioOutput with the requested type, a 1024 sample buffer, a sample rate of 44100 and a bit depth of 16

See Also:

getLineOut(int, int, float, int)

getLineOut

public AudioOutput getLineOut(int type,
                              int bufferSize)

Gets an AudioOutput, to which you can attach AudioSignals and AudioEffects.

Parameters:

type - Minim.MONO or Minim.STEREO

bufferSize - how long you want the AudioOutput's sample buffer to be

Returns:

an AudioOutput with the requested attributes, a sample rate of 44100 and a bit depth of 16

See Also:

getLineOut(int, int, float, int)

getLineOut

public AudioOutput getLineOut(int type,
                              int bufferSize,
                              float sampleRate)

Gets an AudioOutput, to which you can attach AudioSignals and AudioEffects.

Parameters:

type - Minim.MONO or Minim.STEREO

bufferSize - how long you want the AudioOutput's sample buffer to be

sampleRate - the desired sample rate in Hertz (typically 44100)

Returns:

an AudioOutput with the requested attributes and a bit depth of 16

See Also:

getLineOut(int, int, float, int)

getLineOut

public AudioOutput getLineOut(int type,
                              int bufferSize,
                              float sampleRate,
                              int bitDepth)

Gets an AudioOutput, to which you can attach AudioSignals and AudioEffects.

Parameters:

type - Minim.MONO or Minim.STEREO

bufferSize - how long you want the AudioOutput's sample buffer to be

sampleRate - the desired sample rate in Hertz (typically 44100)

bitDepth - the desired bit depth (typically 16)

Returns:

an AudioOutput with the requested attributes

playNote

public void playNote()

Play the note A4 (or random?) right now for 1 second.

playNote

public void playNote(float frequency)

Play a note at the given frequency right now for 1 second.

Parameters:

frequency -

playNote

public void playNote(float duration,
                     float frequency)

Play a note for the given duration, starting right now, at the given frequency.

Parameters:

duration -

frequency -

playNote

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

Play a note startTime seconds from now, for the given duration, at the given frequency.

Parameters:

startTime -

duration -

frequency -

playNote

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

Play a note startTime seconds from now, for the given duration, using the given instrument.

Parameters:

startTime -

duration -

instrument -