net.beadsproject.beads.data
Class Sample

java.lang.Object
  extended by net.beadsproject.beads.data.Sample
All Implemented Interfaces:
java.lang.Runnable

public class Sample
extends java.lang.Object
implements java.lang.Runnable

A Sample encapsulates audio data, either loaded from an audio file (such as an MP3) or written by a Recorder.
The typical use of a Sample is through SampleManager. For example, to load an mp3, you would do the following.

Sample wicked = SampleManager.sample("wickedTrack.mp3");

Samples are usually played with a SamplePlayer. Sample data can also be accessed through the methods: getFrame, getFrameLinear, and getFrames. Sample data can be written with: putFrame or putFrames. However you can only write into a sample if the sample isWriteable(), which occurs if the buffering regime is a Total Regime or has been created with the empty sample constructor.

The buffering regime of the Sample determines how the data is stored and how it is buffered. The TOTAL regime is the default. Under this regime, the sample loads all the data from the audio file and stores it in Beads' native format. This is appropriate for most small samples.For longer samples or compressed audio consider using a TimedRegime.

A set of handy factory methods for handling common situations is also provided. These are:

Current Issues:

Author:
Beads Team
See Also:
SampleManager, Recorder

Nested Class Summary
static class Sample.Regime
           
static class Sample.TimedRegime
           A TimedRegime stores only some parts of the audio file in memory at a time.
static class Sample.TotalRegime
          A sample with a TotalRegime reads and stores all the audio data upon initialisation.
 
Field Summary
static java.util.concurrent.Executor regionMaster
           
 
Constructor Summary
Sample(AudioFile af)
          Create a sample from an Audio File, using the default buffering scheme.
Sample(AudioFile af, Sample.Regime r)
          Create a sample from an Audio File, using the buffering scheme suggested.
Sample(javax.sound.sampled.AudioFormat audioFormat, double length)
          Instantiates a new writeable Sample with the specified audio format and length; The sample isn't initialised, so may contain junk.
Sample(javax.sound.sampled.AudioFormat audioFormat, double length, Sample.Regime br)
           
Sample(java.io.InputStream is)
          Create a sample from an input stream.
Sample(java.io.InputStream is, Sample.Regime r)
          Create a sample from a file, using the buffering scheme suggested.
Sample(java.lang.String filename)
          Create a sample from a file.
Sample(java.lang.String filename, Sample.Regime r)
          Create a sample from a file, using the buffering scheme suggested.
 
Method Summary
 void clear()
          Clears the (writeable) sample.
 AudioFile getAudioFile()
           
 javax.sound.sampled.AudioFormat getAudioFormat()
           
 int getBytesPerSample()
           
 java.lang.String getFileName()
          Gets the full file path.
 void getFrame(int frame, float[] frameData)
          Return a single frame.
 void getFrameCubic(double posInMS, float[] result)
          Retrieves a frame of audio using cubic interpolation.
 void getFrameLinear(double posInMS, float[] result)
          Retrieves a frame of audio using linear interpolation.
 void getFrameNoInterp(double posInMS, float[] result)
          Retrieves a frame of audio using no interpolation.
 void getFrames(int frame, float[][] frameData)
          Get a series of frames.
 float getLength()
           
 int getNumberOfRegionsLoaded()
           
 int getNumChannels()
           
 long getNumFrames()
           
 float getSampleRate()
           
 java.lang.String getSimpleFileName()
          Gets the simple file name.
 boolean isWriteable()
          A Sample needs to be writeable in order to be recorded into.
 double msToSamples(double msTime)
          Converts from milliseconds to samples based on the sample rate specified by audioFormat.
 void printAudioFormatInfo()
          Prints audio format info to System.out.
 void putFrame(int frame, float[] frameData)
          Write a single frame into this sample.
 void putFrames(int frame, float[][] frameData)
          Write multiple frames into the sample.
 void putFrames(int frame, float[][] frameData, int offset, int numFrames)
          Write multiple frames into the sample.
 void resize(long frames)
          Advanced Change the number of frames in the (writeable) sample.
 void resizeWithZeros(long frames)
          Just like resize(long) but initialises the new frames with zeros.
 void run()
          Internal: This method is called internally by the region master.
 double samplesToMs(double sampleTime)
          Converts from samples to milliseconds based on the sample rate specified by audioFormat.
 java.lang.String toString()
           
 void write(java.lang.String fn)
          This records the sample to an AIFF format audio file.
 void write(java.lang.String fn, javax.sound.sampled.AudioFileFormat.Type type)
          This records the sample to a file with the specified AudioFileFormat.Type.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

regionMaster

public static java.util.concurrent.Executor regionMaster
Constructor Detail

Sample

public Sample(javax.sound.sampled.AudioFormat audioFormat,
              double length)
Instantiates a new writeable Sample with the specified audio format and length; The sample isn't initialised, so may contain junk. Use clear() to clear it.

Parameters:
audioFormat - the audio format.
length - The length of the sample in ms.

Sample

public Sample(javax.sound.sampled.AudioFormat audioFormat,
              double length,
              Sample.Regime br)

Sample

public Sample(java.lang.String filename)
       throws java.io.IOException,
              javax.sound.sampled.UnsupportedAudioFileException
Create a sample from a file. This constructor immediately loads the entire audio file into memory.

Throws:
javax.sound.sampled.UnsupportedAudioFileException
java.io.IOException

Sample

public Sample(java.io.InputStream is)
       throws java.io.IOException,
              javax.sound.sampled.UnsupportedAudioFileException
Create a sample from an input stream. This constructor immediately loads the entire audio file into memory.

Throws:
javax.sound.sampled.UnsupportedAudioFileException
java.io.IOException

Sample

public Sample(AudioFile af)
       throws java.io.IOException,
              javax.sound.sampled.UnsupportedAudioFileException
Create a sample from an Audio File, using the default buffering scheme.

Throws:
javax.sound.sampled.UnsupportedAudioFileException
java.io.IOException

Sample

public Sample(AudioFile af,
              Sample.Regime r)
       throws java.io.IOException,
              javax.sound.sampled.UnsupportedAudioFileException
Create a sample from an Audio File, using the buffering scheme suggested.

Throws:
javax.sound.sampled.UnsupportedAudioFileException
java.io.IOException

Sample

public Sample(java.lang.String filename,
              Sample.Regime r)
       throws java.io.IOException,
              javax.sound.sampled.UnsupportedAudioFileException
Create a sample from a file, using the buffering scheme suggested.

Throws:
javax.sound.sampled.UnsupportedAudioFileException
java.io.IOException

Sample

public Sample(java.io.InputStream is,
              Sample.Regime r)
       throws java.io.IOException,
              javax.sound.sampled.UnsupportedAudioFileException
Create a sample from a file, using the buffering scheme suggested.

Throws:
javax.sound.sampled.UnsupportedAudioFileException
java.io.IOException
Method Detail

getFrame

public void getFrame(int frame,
                     float[] frameData)
Return a single frame. If the data is not readily available this function blocks until it is.

Parameters:
frame - Must be in range, else framedata is unchanged.
frameData -

getFrameNoInterp

public void getFrameNoInterp(double posInMS,
                             float[] result)
Retrieves a frame of audio using no interpolation. If the frame is not in the sample range then zeros are returned.

Parameters:
posInMS - The frame to read -- will take the last frame before this one.
result - The framedata to fill.

getFrameLinear

public void getFrameLinear(double posInMS,
                           float[] result)
Retrieves a frame of audio using linear interpolation. If the frame is not in the sample range then zeros are returned.

Parameters:
posInMS - The frame to read -- can be fractional (e.g., 4.4).
result - The framedata to fill.

getFrameCubic

public void getFrameCubic(double posInMS,
                          float[] result)
Retrieves a frame of audio using cubic interpolation. If the frame is not in the sample range then zeros are returned.

Parameters:
posInMS - The frame to read -- can be fractional (e.g., 4.4).
result - The framedata to fill.

getFrames

public void getFrames(int frame,
                      float[][] frameData)
Get a series of frames. FrameData will only be filled with the available frames. It is the caller's responsibility to count how many frames are valid. min(nFrames - frame, frameData[0].length) frames in frameData are valid. If the data is not readily available this function blocks until it is.

Parameters:
frame - The frame number (NOTE: This parameter is in frames, not in ms!)
frameData -

clear

public void clear()
Clears the (writeable) sample.


putFrame

public void putFrame(int frame,
                     float[] frameData)
Write a single frame into this sample. Takes care of format conversion. This only makes sense if this.isWriteable() returns true. If isWriteable() is false, the behaviour is undefined/unstable.

Parameters:
frame - The frame to write into. Must be >=0 and frameData - The frame data to write.

putFrames

public void putFrames(int frame,
                      float[][] frameData)
Write multiple frames into the sample. This only makes sense if this.isWriteable() returns true. If isWriteable() is false, the behaviour is undefined/unstable.

Parameters:
frame - The frame to write into.
frameData - The frames to write.

putFrames

public void putFrames(int frame,
                      float[][] frameData,
                      int offset,
                      int numFrames)
Write multiple frames into the sample. This only makes sense if this.isWriteable() returns true. If isWriteable() is false, the behaviour is undefined/unstable.

Parameters:
frame - The frame to write into.
frameData - The frames to write.
offset - The offset into frameData
numFrames - The number of frames from frameData to write

write

public void write(java.lang.String fn)
           throws java.io.IOException
This records the sample to an AIFF format audio file. It is BLOCKING.

Parameters:
fn - The filename (should have the .aif extension).
Throws:
java.io.IOException - Signals that an I/O exception has occurred.

write

public void write(java.lang.String fn,
                  javax.sound.sampled.AudioFileFormat.Type type)
           throws java.io.IOException
This records the sample to a file with the specified AudioFileFormat.Type. It is BLOCKING.

Parameters:
fn - The filename.
type - The type (AIFF, WAVE, etc.)
Throws:
java.io.IOException - Signals that an I/O exception has occurred.

resize

public void resize(long frames)
            throws java.lang.Exception
Advanced Change the number of frames in the (writeable) sample. This is slow and so should be used sparingly. The new frames may contain garbage, but see resizeWithZeros(long).

Parameters:
frames - The total number of frames the sample should have.
Throws:
java.lang.Exception - Thrown if the sample isn't writeable.

resizeWithZeros

public void resizeWithZeros(long frames)
                     throws java.lang.Exception
Just like resize(long) but initialises the new frames with zeros.

Parameters:
frames - The total number of frames the sample should have.
Throws:
java.lang.Exception - Thrown if the sample isn't writeable.

printAudioFormatInfo

public void printAudioFormatInfo()
Prints audio format info to System.out.


msToSamples

public double msToSamples(double msTime)
Converts from milliseconds to samples based on the sample rate specified by audioFormat.

Parameters:
msTime - the time in milliseconds.
Returns:
the time in samples.

samplesToMs

public double samplesToMs(double sampleTime)
Converts from samples to milliseconds based on the sample rate specified by audioFormat.

Parameters:
sampleTime - the time in samples.
Returns:
the time in milliseconds.

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

isWriteable

public boolean isWriteable()
A Sample needs to be writeable in order to be recorded into. Currently buffered samples are not writeable, but TOTAL (file or empty) samples are.


getFileName

public java.lang.String getFileName()
Gets the full file path.

Returns:
the file path.

getSimpleFileName

public java.lang.String getSimpleFileName()
Gets the simple file name.

Returns:
the file name.

getAudioFile

public AudioFile getAudioFile()

getAudioFormat

public javax.sound.sampled.AudioFormat getAudioFormat()

getNumChannels

public int getNumChannels()

getNumFrames

public long getNumFrames()

getBytesPerSample

public int getBytesPerSample()
Returns:
The number of bytes this sample uses to store each sample. May be different than audioFile.audioFormat.

getLength

public float getLength()

getSampleRate

public float getSampleRate()

getNumberOfRegionsLoaded

public int getNumberOfRegionsLoaded()
Returns:
The number of regions currently loaded. Only valid if bufferingRegime is region-based.

run

public void run()
Internal: This method is called internally by the region master. It loads the next queued region.

Specified by:
run in interface java.lang.Runnable