Manual: Recordable

[ javadoc | examples ]

The Recordable interface defines functionality that provides a program with floating point samples of the audio passing through it. It does this using AudioListeners. You add listeners to the Recordable and then the Recordable will call the appropriate samples method of all its listeners when it has a new buffer of samples. It is also possible to query a Recordable object for its buffer size, type (mono or stereo), and audio format. Sample values are between -1 and 1, inclusive. Recordable is implemented by AudioSource and SignalSplitter.

Adding and Removing AudioListeners

addListener(AudioListener al)
removeListener(AudioListener al)

The above methods can be called on a Recordable to add or remove an instance of a class that implements AudioListener. When a listener has been added to a Recordable, one of it’s samples methods will be called each time the Recordable generates a new buffer of samples or receives a new buffer of samples. This is the best way to monitor input or output. An AudioListener cannot be added more than once to a Recordable.

Code Sample (online example)

/**
  * This sketch demonstrates how to use the <code>removeListener</code> method of a <code>Recordable</code> class.
  * The class used here is <code>AudioPlayer</code>, but you can also remove listeners from <code>AudioInput</code>,
  * <code>AudioOutput</code>, and <code>AudioSample</code> objects. The class defined in waveform.pde implements
  * the <code>AudioListener</code> interface and can therefore be removed as a listener to <code>groove</code>.
  * The waveform renderer starts off not added to the player, so you will initially not see any waveforms drawn.
  * <p>
  * Press 'a' to add the waveform renderer to the player.<br />
  * Press 'r' to remove the waveform renderer from the player.<br />
  * <br />
  * You'll see that when you remove the waveform renderer as a listener of the player, the waveform freezes. This is
  * because the waveform is drawing the last buffer of samples that it received from the player.
  */
 
import ddf.minim.*;
 
Minim minim;
AudioPlayer groove;
WaveformRenderer waveform;
 
void setup()
{
  size(512, 200, P3D);
 
  minim = new Minim(this);
  groove = minim.loadFile("groove.mp3", 2048);
  groove.loop();
  waveform = new WaveformRenderer();
}
 
void draw()
{
  background(0);
  // see waveform.pde for an explanation of how this works
  waveform.draw();
}
 
void keyPressed()
{
  if ( key == 'a' )
  {
    groove.addListener(waveform);
  }
  if ( key == 'r' )
  {
    groove.removeListener(waveform);
  }
}
 
void stop()
{
  // always close Minim audio classes when you are done with them
  groove.close();
  // always stop Minim before exiting.
  minim.stop();
 
  super.stop();
}

The format of a Recordable

A Recordable object can give you information about the kind of audio that it represents. These properties are accessed by the following methods:

int bufferSize()
int sampleRate()
int type()
AudioFormat getFormat()

bufferSize() returns the length of the float buffers sent to AudioListeners. sampleRate() returns the sample rate, in Hz, of the audio that the Recordable represents, such as 44100 or 96000. type() returns the number of channels in the audio, which will be either 1 or 2 and can be compared to Minim.MONO and Minim.STEREO for readability. getFormat() returns an AudioFormat object that contains the sample rate and type, as well as some extra information. Specifically, getFormat().getChannels() will return the same value as type() and getFormat().getSampleRate() will return the same value as sampleRate().

Code Sample (online example)

/**
  * This sketch demonstrates how to use the <code>getFormat</code> method of a <code>Recordable</code> class.
  * The class used here is <code>AudioOutput</code>, but you can also get the format of <code>AudioInput</code>,
  * <code>AudioPlayer</code>, and <code>AudioSample</code> objects. The <code>getFormat</code> method returns
  * an object of type <code>AudioFormat</code> which is a class defined in the JavaSound API. An <code>AudioFormat</code>
  * is a container for information about an audio source, such as the framerate, encoding and so forth. The following
  * methods are available on an <code>AudioFormat</code> object and all are demonstrated in this sketch.
  *
  * <pre>
    int getChannels()
      Obtains the number of channels.
 
    AudioFormat.Encoding getEncoding()
      Obtains the type of encoding for sounds in this format.
 
    float getFrameRate()
      Obtains the frame rate in frames per second.
 
    int getFrameSize()
      Obtains the frame size in bytes.
 
    float getSampleRate()
      Obtains the sample rate.
 
    int getSampleSizeInBits()
      Obtains the size of a sample.
 
    boolean isBigEndian()
      Indicates whether the audio data is stored in big-endian or little-endian byte order.
 
    boolean matches(AudioFormat format)
      Indicates whether this format matches the one specified.
 
    String toString()
      Returns a string that describes the format, such as: "PCM SIGNED 22050 Hz 16 bit mono big-endian".
    </pre>
  */
 
import ddf.minim.*;
 
Minim minim;
AudioOutput out;
 
void setup()
{
  size(760, 140, P3D);
  textFont(loadFont("CourierNewPSMT-12.vlw"));
  textMode(SCREEN);
 
  minim = new Minim(this);
  // this should give us a stereo output with a 1024 sample buffer, 
  // a sample rate of 44100 and a bit depth of 16
  out = minim.getLineOut();
}
 
void draw()
{
  background(0);
  text("The output has " + out.getFormat().getChannels() + " channels.", 5, 15);
  text("The output's encoding is " + out.getFormat().getEncoding() + ".", 5, 30);
  text("The output's frame rate is " + out.getFormat().getFrameRate() + " frames per second.", 5, 45);
  text("The output's frame size is " + out.getFormat().getFrameSize() + " bytes.", 5, 60);
  text("The output's sample rate is " + out.getFormat().getSampleRate() + " Hz.", 5, 75);
  text("The output's sample size is " + out.getFormat().getSampleSizeInBits() + " bits.", 5, 90);
  String endianess = out.getFormat().isBigEndian() ? "big-endian" : "little-endian";
  text("The output's byte order is " + endianess + ".", 5, 105);
  text("The output's format as a string is " + out.getFormat(), 5, 120);
}
 
void stop()
{
  // always close Minim audio classes when you are done with them
  out.close();
  // always stop Minim before exiting.
  minim.stop();
 
  super.stop();
}