net.beadsproject.beads.data

Class Sample

java.lang.Object

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

Constructors

Constructor and Description
Sample(double length) Instantiates a new writable sample with specified length and default audio format: 44.1KHz, float, stereo.
Sample(double length, int nChannels) Instantiates a new writable sample with specified length and number of channels and default audio format: 44.1KHz, float.
Sample(double length, int nChannels, float sampleRate) 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

Modifier and Type	Method and Description
void	clear() Clears the (writeable) sample.
java.lang.Class<? extends AudioFileReader>	getAudioFileReaderClass() Gets the current AudioFileReaderClass.
java.lang.Class<? extends AudioFileWriter>	getAudioFileWriterClass() Gets the current AudioFileWriterClass.
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() Return length of sample in ms
int	getNumChannels() Get the number of channels
long	getNumFrames() Get the number of frames
float	getSampleRate() Get the sample rate
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	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	setAudioFileReaderClass(java.lang.Class<? extends AudioFileReader> audioFileReaderClass) Set the audioFileReaderClass.
void	setAudioFileWriterClass(java.lang.Class<? extends AudioFileWriter> audioFileWriterClass) Set the audioFileWriterClass.
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, AudioFileType type) This records the sample to a file with the specified AudioFile.Type.
void	write(java.lang.String fn, AudioFileType type, SampleAudioFormat saf) 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, float, stereo.

Parameters:

length - the length in ms.

Sample

public Sample(double length,
              int nChannels)

Instantiates a new writable sample with specified length and number of channels and default audio format: 44.1KHz, float.

Parameters:

length - the length in ms.

nChannels - the number of channels.

Sample

public Sample(double length,
              int nChannels,
              float sampleRate)

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:

length - The length of the sample in ms.

nChannels - The number of channels

sampleRate - The sampleRate

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:

javax.sound.sampled.UnsupportedAudioFileException

java.io.IOException

AudioFileUnsupportedException

Method Detail

getAudioFileReaderClass

public java.lang.Class<? extends AudioFileReader> getAudioFileReaderClass()

Gets the current AudioFileReaderClass. This is an instantiation of a class that implements AudioFileReader that Sample will use for file reading operations. If unset or set to null Sample will use a default.

Returns:

getAudioFileWriterClass

public java.lang.Class<? extends AudioFileWriter> getAudioFileWriterClass()

Gets the current AudioFileWriterClass. This is an instantiation of a class that implements AudioFileWriter that Sample will use for file writing operations. If unset or set to null Sample will use a default.

Returns:

setAudioFileReaderClass

public void setAudioFileReaderClass(java.lang.Class<? extends AudioFileReader> audioFileReaderClass)

Set the audioFileReaderClass. This is an instantiation of a class that implements AudioFileReader that Sample will use for file reading operations. If unset or set to null Sample use a default.

Parameters:

audioFileReaderClass -

setAudioFileWriterClass

public void setAudioFileWriterClass(java.lang.Class<? extends AudioFileWriter> audioFileWriterClass)

Set the audioFileWriterClass. This is an instantiation of a class that implements AudioFileWriter that Sample will use for file writing operations. If unset or set to null Sample use a default.

Parameters:

audioFileWriterClass -

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.io.IOException

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.

write

public void write(java.lang.String fn,
                  AudioFileType type)
           throws java.io.IOException

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.

write

public void write(java.lang.String fn,
                  AudioFileType type,
                  SampleAudioFormat saf)
           throws java.io.IOException

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.)

saf - The SampleAudioFormat

Throws:

java.io.IOException - Signals that an I/O exception has occurred.

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.

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.

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.

getSampleRate

public float getSampleRate()

Get the sample rate

Returns:

getNumChannels

public int getNumChannels()

Get the number of channels

Returns:

getNumFrames

public long getNumFrames()

Get the number of frames

Returns:

getLength

public double getLength()

Return length of sample in ms

Returns: