Code Log

[ javadoc | examples ]

Minim is the name of the audio library you are reading about. Minim is a class in the library that contains a bunch of static methods that you can call to get audio resources from the system. It also has one method you must always call:

start(PApplet p)

One of the first lines that you should have in setup is a call to start, passing this as the argument. You must do this so that Minim can initialize some things and have access to the data folder of your sketch.

Code Sample

import ddf.minim.*;
 
void setup()
{
  size(100, 100);
  Minim.start(this);
}
 
void draw()
{
}

Obtaining Audio Resources From Minim

There are four things you can do with Minim: play an audio file, play synthesized audio, monitor audio input, and record audio to disk. All of these things are handled by different classes in the library and instances of those classes are all obtained by calling the appropriate methods of Minim.

Loading An Audio File

There are three different classes for playing an audio file, each designed to address a particular kind of playback. I will devote a section to each class, so for now just know that they are: AudioSnippet, AudioSample, and AudioPlayer. Rather than creating new instances of these classes by using the new keyword, you create them by calling one of the methods of Minim. They are as follows:

loadSnippet(String filename)
loadSample(String filename)
loadSample(String filename, int bufferSize)
loadFile(String filename)
loadFile(String filename, int bufferSize)

loadSnippet returns an AudioSnippet, loadSample returns an AudioSample, and loadFile returns an AudioPlayer. In all cases filename is either the name of an audio file in your sketch’s data folder, an absolute path to an audio file, or a URL that returns an audio file (like an mp3 file on a server or even the URL of an internet radio station). bufferSize is how large you want the sample buffers of the returned object to be. The size of the actual audio buffer used by the system will be proportional to bufferSize, so you can achieve somewhat lower latency by requesting smaller buffers. A good value for bufferSize is 1024, which is how large the sample buffers will be if you do not specify a size.

Code Sample

import ddf.minim.*;
 
AudioPlayer in;
 
void setup()
{
  size(512, 200);
  // always start Minim first
  Minim.start(this);
  // load a file, default sample buffer size is 1024
  in = Minim.loadFile("music.mp3");
  // play the file
  in.play();
}
 
void draw()
{
  // do whatever you do here
}
 
void stop()
{
  // always close audio I/O classes
  in.close();
  super.stop();
}

Getting An AudioOutput

Minim provides the class AudioOutput for the playback of synthesized audio. This is audio that is created on the fly by your program and then fed to the speakers. AudioOutput can handle both mono and stereo audio and you can indicate which kind you will be synthesizing when you call one of the methods of Minim that is used to obtain an AudioOutput. Those methods are as follows:

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

type indicates whether you want a stereo or mono AudioOuput. You should use either Minim.MONO or Minim.STEREO as the value for this argument. The default value for type (i.e. what will be used in the case of the method with no arguments) is Minim.STEREO. bufferSize, as above, is how large you want the sample buffers to be. The default value of bufferSize is 1024. sampleRate is what the sample rate of your synthesized audio will be. The default value for sampleRate is 44100. bitDepth is what the bit depth of your synthesized audio will be. Currently, the only acceptable values for bitDepth are 8 and 16. The default value for bitDepth is 16.

Sample Code

import ddf.minim.*;
import ddf.minim.signals.*;
 
AudioOutput out;
SineWave sine;
 
void setup()
{
  size(512, 200);
  // always start Minim before you do anything with it
  Minim.start(this);
  // get a line out from Minim, 
  // default sample rate is 44100, bit depth is 16
  out = Minim.getLineOut(Minim.STEREO, 512);
  // create a sine wave Oscillator, set to 440 Hz, at 0.5 amplitude, 
  // sample rate 44100 to match the line out
  sine = new SineWave(440, 0.5, 44100);
  // add the oscillator to the line out
  out.addSignal(sine);
}
 
void draw()
{
  // do whatever you are going to do
}
 
void stop()
{
  // always closes audio I/O classes
  out.close();
  super.stop();
}

Getting An AudioInput

Minim provides the class AudioInput for monitoring the user’s current record source (this is often set in the sound card control panel). There is currently no way to request a specific input, such as the microphone or the line-in, and what you actually get a handle on is not entirely consistent across platforms. Nevertheless, the methods for obtaining an AudioIutput look almost exactly like the ones for obtaining an AudioOutput:

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

type indicates whether you want a stereo or mono AudioInput. You should use either Minim.MONO or Minim.STEREO as the value for this argument. The default value for type (i.e. what will be used in the case of the method with no arguments) is Minim.STEREO. bufferSize is how large you want the sample buffers to be. The default value of bufferSize is 1024. sampleRate is what the sample rate of your synthesized audio will be. The default value for sampleRate is 44100. bitDepth is what the bit depth of your synthesized audio will be. Currently, the only acceptable values for bitDepth are 8 and 16. The default value for bitDepth is 16.

Sample Code

import ddf.minim.*;
 
AudioInput in;
 
void setup()
{
  size(512, 200);
  // always start Minim before you do anything with it
  Minim.start(this);
  // get a line out from Minim, 
  // default sample rate is 44100, bit depth is 16
  in = Minim.getLineIn(Minim.STEREO, 512);
}
 
void draw()
{
  // do whatever you are going to do
}
 
void stop()
{
  // always close audio I/O classes
  in.close();
  super.stop();
}

Creating An AudioRecorder

Minim provides the class AudioRecorder for recording audio data to disk. The details for how to use this class will be covered later, here is the method used to obtain an AudioRecorder:

createRecorder(Recordable source, String name, boolean buffered)

source is the Recordable object that you want to use as the record source. name is the name of the file, including the extension, to save to. buffered indicates whether you want to use buffered recording or not (see the AudioRecorder section).

Sample Code

import ddf.minim.*;
 
AudioInput in;
AudioRecorder fout;
 
void setup()
{
  size(512, 400);
 
  // always start Minim before you do anything with it
  Minim.start(this);
 
  // get a stereo line-in: sample buffer length of 512
  // default sample rate is 44100, default bit depth is 16
  in = Minim.getLineIn(Minim.STEREO, 512);
  // get a recorder that will record from in to the 
  // filename specified using buffered recording
  fout = Minim.createRecorder(in, "myrecording.wav", true);
}
 
void draw()
{
  // do whatever you’re going to do
}
 
void keyReleased()
{
  // maybe set up keybindings to start and stop recording
  // and then save to disk
}
 
void stop()
{
  // always close audio I/O classes
  in.close();
  super.stop();
}