net.beadsproject.beads.data
Class Sample

java.lang.Object
  extended by net.beadsproject.beads.data.Sample

public class Sample
extends java.lang.Object

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.

Author:
Beads Team
See Also:
SampleManager, RecordToSample

Constructor Summary
Sample(AudioFile af)
          Create a sample from an Audio File, using the default buffering scheme.
Sample(double length)
          Instantiates a new writable sample with specified length and default audio format: 44.1KHz, 16 bit, stereo.
Sample(java.io.InputStream is)
          Create a sample from an input stream.
Sample(SampleAudioFormat 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(java.lang.String filename)
          Create a sample from a file.
 
Method Summary
 void clear()
          Clears the (writeable) sample.
 AudioFile getAudioFile()
           
 java.lang.Class<? extends AudioFile> getAudioFileHandlerClass()
          Gets the current AudioFileHandlerClass.
 SampleAudioFormat 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.
 double getLength()
           
 int getNumChannels()
           
 long getNumFrames()
           
 float getSampleRate()
           
 java.lang.String getSimpleName()
          Gets the simple name.
 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.
 double samplesToMs(double sampleTime)
          Converts from samples to milliseconds based on the sample rate specified by audioFormat.
 void setAudioFileHandlerClass(java.lang.Class<? extends AudioFile> audioFileHandlerClass)
          Set the audioFileHandlerClass.
 void setSimpleName(java.lang.String simpleName)
          Sets the simple name.
 java.lang.String toString()
           
 void write(java.lang.String fn)
          This records the sample to a WAV format audio file.
 void write(java.lang.String fn, AudioFile.Type type)
          This records the sample to a file with the specified AudioFile.Type.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Sample

public Sample(double length)
Instantiates a new writable sample with specified length and default audio format: 44.1KHz, 16 bit, stereo.

Parameters:
length - the length in ms.

Sample

public Sample(SampleAudioFormat 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(java.lang.String filename)
       throws java.io.IOException
Create a sample from a file. This constructor immediately loads the entire audio file into memory.

Throws:
UnsupportedAudioFileException
java.io.IOException
AudioFileUnsupportedException

Sample

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

Throws:
UnsupportedAudioFileException
java.io.IOException
AudioFileUnsupportedException

Sample

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

Throws:
UnsupportedAudioFileException
java.io.IOException
AudioFileUnsupportedException
Method Detail

getAudioFileHandlerClass

public java.lang.Class<? extends AudioFile> getAudioFileHandlerClass()
Gets the current AudioFileHandlerClass. This is an instantiation of AudioFile that Sample will use for file IO operations. If unset or set to null Sample will attempt to find a default implementation: JavaSoundAudioFile.

Returns:

setAudioFileHandlerClass

public void setAudioFileHandlerClass(java.lang.Class<? extends AudioFile> audioFileHandlerClass)
Set the audioFileHandlerClass. This is an instantiation of AudioFile that Sample will use for file IO operations. If unset or set to null Sample will attempt to find a default implementation: JavaSoundAudioFile.

Parameters:
audioFileHandlerClass -

getFrame

public void getFrame(int frame,
                     float[] frameData)
Return a single frame. If the data is not readily available this doesn't do anything to frameData.

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 doesn't do anything.

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.lang.Exception
This records the sample to a WAV 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.
java.lang.Exception

write

public void write(java.lang.String fn,
                  AudioFile.Type type)
           throws java.lang.Exception
This records the sample to a file with the specified AudioFile.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.
java.lang.Exception

resize

public void resize(long frames)
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)
Just like resize(long) but initialises the new frames with zeros.

Parameters:
frames - The total number of frames the sample should have.

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

getFileName

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

Returns:
the file path.

getSimpleName

public java.lang.String getSimpleName()
Gets the simple name.

Returns:
the name.

setSimpleName

public void setSimpleName(java.lang.String simpleName)
Sets the simple name.

Parameters:
simpleName - the name.

getAudioFile

public AudioFile getAudioFile()

getAudioFormat

public SampleAudioFormat 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 double getLength()

getSampleRate

public float getSampleRate()