com.softsynth.jsyn
Class SynthSample

java.lang.Object
  java.util.Observable
      com.softsynth.jsyn.SynthObject
          com.softsynth.jsyn.SynthChannelData
              com.softsynth.jsyn.SynthSample

Direct Known Subclasses:

PluckSample, SynthSampleAIFF, SynthSampleWAV

public class SynthSample
extends SynthChannelData

The SynthSample class is a container for digital audio data.
The actual data may need to reside in memory that is accessible to DMA or to a DSP so we cannot assume that it is in main memory. We also need to maintain cache coherence if the data is going to be read or written by hardware other than the CPU. For this reason, Samples cannot use memory allocated by, or accessable to the application.

Version:

JSyn Version 005

Author:

(C) 1997 Phil Burk, SoftSynth.com, All Rights Reserved

See Also:

Synth, SynthTable, SampleReader_16V1, SampleReader_16F1, SampleReader_16F2, SampleWriter_16F1, SampleWriter_16F2, DelayUnit

Field Summary

static int	AIFF
byte[]	byteData Used to store raw bytes temporarily when parsing a sample file.
static int	UNRECOGNIZED
static int	WAV

Fields inherited from class com.softsynth.jsyn.SynthChannelData

cuePoints

Constructor Summary

SynthSample()

SynthSample(int numFrames)
Create a monophonic sample with the specified number of frames.

SynthSample(int maxFrames, int channelsPerFrame)

SynthSample(SynthContext synthContext)
Create an empty sample.

SynthSample(SynthContext synthContext, int maxFrames)

SynthSample(SynthContext synthContext, int maxFrames, int channelsPerFrame)
Create a digital audio sample with the specified number of frames, and channels per frame.

Method Summary

void	allocate(int numFrames, int channelsPerFrame) Allocate low level sample resources and memory to hold sample data.
void	clear()
void	clear(int firstSampleFrame, int numFrames) Clear part of a SynthSample.
java.lang.String	dump()
double	getBaseFrequency() The best frequency to associate with the perceived pitch of the instrument when played at the recorded SampleRate.
int	getChannelsPerFrame()
long	getFileSize() This can be read by another thread when load()ing a sample to determine how many bytes need to be read.
static int	getFileType(java.lang.String fileName) Determine file type based on suffix, case insensitive.
long	getNumBytesRead() This can be read by another thread when load()ing a sample to determine how many bytes have been read so far.
long	getOffset() Return number of bytes from beginning of stream where sound data resides.
double	getSampleRate()
void	load(java.io.InputStream stream)
void	load(java.io.InputStream stream, boolean ifLoadData) Load the sample from the given stream.
short[]	loadShorts(java.io.InputStream stream, boolean ifLoadData)
void	read(int firstSampleFrame, short[] data, int firstDataIndex, int numFrames) Read from the SynthSample into an array of shorts.
void	read(short[] data)
void	setBaseFrequency(double baseFrequency)
void	setHighAmplitude(double highestAmplitude)
void	setHighFrequency(double highestFrequency)
void	setLowAmplitude(double lowestAmplitude) Set range of Amplitudes for which this sample could be chosen when doing MultiSample selection.
void	setLowFrequency(double lowestFrequency) Set range of Amplitudes for which this sample could be chosen when doing MultiSample selection.
void	setSampleRate(double sampleRate) Set rate at which sample was recorded.
void	write(int firstSampleFrame, short[] data, int firstDataIndex, int numFrames) Write data from an array of shorts to the Samples internal storage area.
void	write(short[] data)

Methods inherited from class com.softsynth.jsyn.SynthChannelData

findCuePoint, findCuePosition, getMaxFrames, getNumFrames, getReleaseBegin, getReleaseEnd, getReleaseSize, getSustainBegin, getSustainEnd, getSustainSize, insertSortedCue, setNumFrames, setReleaseLoop, setSustainLoop

Methods inherited from class com.softsynth.jsyn.SynthObject

delete, deleteAll, enableDeletionByGarbageCollector, enableTracking, getPeer, getSynthContext, isTrackingEnabled, toString, track

Methods inherited from class java.util.Observable

addObserver, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

UNRECOGNIZED

public static final int UNRECOGNIZED

See Also:

Constant Field Values

AIFF

public static final int AIFF

See Also:

Constant Field Values

WAV

public static final int WAV

See Also:

Constant Field Values

byteData

public byte[] byteData

Used to store raw bytes temporarily when parsing a sample file.

Constructor Detail

SynthSample

public SynthSample(SynthContext synthContext)

Create an empty sample. You must call allocate() before using the sample.

SynthSample

public SynthSample()

SynthSample

public SynthSample(SynthContext synthContext,
                   int maxFrames,
                   int channelsPerFrame)
            throws SynthException

Create a digital audio sample with the specified number of frames, and channels per frame.

Parameters:

maxFrames - Number of sample frames to allocate.

channelsPerFrame - Number of channels in a frame, eg. 1 for mono, 2 for stereo.

Throws:

SynthException - If there is insufficient memory.

SynthSample

public SynthSample(int maxFrames,
                   int channelsPerFrame)
            throws SynthException

Throws:

SynthException

SynthSample

public SynthSample(SynthContext synthContext,
                   int maxFrames)

SynthSample

public SynthSample(int numFrames)
            throws SynthException

Create a monophonic sample with the specified number of frames. Since it is monophonic, the number of frames equals the number of samples.

Throws:

SynthException - If there is insufficient memory.

Method Detail

getFileType

public static int getFileType(java.lang.String fileName)

Determine file type based on suffix, case insensitive. Returns SynthSample.AIFF for ".aiff", ".aif", "AIFF", or "AIF". Returns SynthSample.WAV for ".wave", ".wav", ".WAVE" or ".WAV". Returns SynthSample.UNRECOGNIZED for anything else.

Returns:

integer indicating file type.

allocate

public void allocate(int numFrames,
                     int channelsPerFrame)
              throws SynthException

Allocate low level sample resources and memory to hold sample data.

Throws:

SynthException - If there is insufficient memory.

write

public void write(int firstSampleFrame,
                  short[] data,
                  int firstDataIndex,
                  int numFrames)
           throws SynthException

Write data from an array of shorts to the Samples internal storage area. The internal storage might be in main memory, or it might be located on a sound card and only accessable by DMA.

Parameters:

firstSampleFrame - = Index of first frame of sample to be written to. A frame in a mono sample is one short. A frame in a stereo sample is two shorts.

data - = array of shorts containing sample data.

firstDataIndex - = index of first element in data array to write from. Note that for stereo samples, the firstDataIndex is twice the equivalent frame index.

numFrames - = number of frames to write.

Throws:

SynthException - If frames are out of range.

write

public void write(short[] data)
           throws SynthException

Throws:

SynthException

clear

public void clear(int firstSampleFrame,
                  int numFrames)

Clear part of a SynthSample.

Parameters:

firstSampleFrame - = Index of first frame of sample to clear. A frame in a mono sample is one short. A frame in a stereo sample is two shorts.

numFrames - = number of frames to clear.

Throws:

SynthException - If frames are out of range.

clear

public void clear()

read

public void read(int firstSampleFrame,
                 short[] data,
                 int firstDataIndex,
                 int numFrames)
          throws SynthException

Read from the SynthSample into an array of shorts.

Parameters:

firstSampleFrame - = Index of first frame of sample to be read from. A frame in a mono sample is one short. A frame in a stereo sample is two shorts.

data - = array of shorts containing sample data.

firstDataIndex - = index of first element in data array to read into. Note that for stereo samples, the firstDataIndex is twice the equivalent frame index.

numFrames - = number of frames to write.

Throws:

SynthException - If frames are out of range.

read

public void read(short[] data)
          throws SynthException

Throws:

SynthException

setSampleRate

public void setSampleRate(double sampleRate)

Set rate at which sample was recorded.

getSampleRate

public double getSampleRate()

setBaseFrequency

public void setBaseFrequency(double baseFrequency)

getBaseFrequency

public double getBaseFrequency()

The best frequency to associate with the perceived pitch of the instrument when played at the recorded SampleRate. Sounds are often unpitched or enharmonic so this may not always be a meaningful measure.

getChannelsPerFrame

public int getChannelsPerFrame()

setLowFrequency

public void setLowFrequency(double lowestFrequency)

Set range of Amplitudes for which this sample could be chosen when doing MultiSample selection.

setHighFrequency

public void setHighFrequency(double highestFrequency)

setLowAmplitude

public void setLowAmplitude(double lowestAmplitude)

Set range of Amplitudes for which this sample could be chosen when doing MultiSample selection.

setHighAmplitude

public void setHighAmplitude(double highestAmplitude)

dump

public java.lang.String dump()

getOffset

public long getOffset()

Return number of bytes from beginning of stream where sound data resides. Combined with load( inStream, false ) lets you parse a sample, then read the data later using a RandomAccessFile.

Returns:

Offset in bytes.

load

public void load(java.io.InputStream stream)
          throws SynthException,
                 java.io.IOException

Throws:

SynthException

java.io.IOException

load

public void load(java.io.InputStream stream,
                 boolean ifLoadData)
          throws SynthException,
                 java.io.IOException

Load the sample from the given stream. Calls loadShorts then writes the data to the SynthSample. This method does nothing in the SynthSample base class. Use SynthSampleAIFF or other format specific classes to actually load the sample.

Parameters:

stream - May be any stream from a file, a URL, a byte array, etc.

ifLoadData - If true, sample data will be loaded into memory.

Throws:

SynthException - If parsing fails, or there is insufficient memory.

java.io.IOException

loadShorts

public short[] loadShorts(java.io.InputStream stream,
                          boolean ifLoadData)
                   throws SynthException,
                          java.io.IOException

Throws:

SynthException

java.io.IOException

getNumBytesRead

public long getNumBytesRead()

This can be read by another thread when load()ing a sample to determine how many bytes have been read so far.

getFileSize

public long getFileSize()

This can be read by another thread when load()ing a sample to determine how many bytes need to be read.