net.beadsproject.beads.data.audiofile
Class AudioFile

java.lang.Object
  net.beadsproject.beads.data.audiofile.AudioFile

Direct Known Subclasses:

JavaSoundAudioFile

public abstract class AudioFile
extends java.lang.Object

An AudioFile provides a handle to an audio file located either on disk or online. AudioFile is used by Sample, however if you want to use it, then AudioIO.getAudioFile will return an audio file. Depending on the AudioIO implementation different audio file types may or may not be available.

Author:

ben

Nested Class Summary

static class

AudioFile.OperationUnsupportedException Thrown if an operation is unsupported for this AudioFile.

Field Summary

protected AudioFormat	audioFormat The format of the decoded audio data.
protected java.util.Map<java.lang.String,java.lang.Object>	audioInfo Additional properties of this AudioFile.
protected float	length Length of the file in milliseconds If <0 then it is unknown.
protected java.lang.String	name The name of this audiofile.
protected long	nFrames The total number of frames.
protected boolean	trace Advanced.

Constructor Summary

AudioFile()

Method Summary

abstract void	close() Close the audio file.
AudioFormat	getFormat()
int	getFrameSize()
java.lang.String	getInformation()
float	getLength()
java.lang.String	getName()
int	getNumChannels()
long	getNumFrames()
java.util.Map<java.lang.String,java.lang.Object>	getProperties()
abstract boolean	isClosed() Is the file stream closed?
boolean	isOpen() Is the file stream open?
abstract void	open() Opens the audio file.
abstract int	read(byte[] buffer) Read bytes from this audiofile.
abstract int	read(float[][] buffer) Read decoded audio data in a non-interleaved, Beads-friendly format.
void	reset() Reset the audio input stream.
void	seek(int frame) Seek to a specific frame number.
protected void	setLength(float length)
protected void	setNumFrames(long nFrames)
void	setTrace(boolean trace) A debugging tool.
void	skip(long frames) Skips a number of frames.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

name

protected java.lang.String name

The name of this audiofile. Corresponds to the name of file, url, or a inputstream generated id

audioFormat

protected AudioFormat audioFormat

The format of the decoded audio data.

nFrames

protected long nFrames

The total number of frames. If it equals -1 then the length is unknown.

length

protected float length

Length of the file in milliseconds If <0 then it is unknown.

audioInfo

protected java.util.Map<java.lang.String,java.lang.Object> audioInfo

Additional properties of this AudioFile. For example, an .mp3 file may have mp3 tags that get stored in this map.

trace

protected boolean trace

Advanced. Trace the open, closing, and resetting of this audio file. Useful to debug and tune the parameters of AudioFile and Sample.

Constructor Detail

AudioFile

public AudioFile()

Method Detail

reset

public void reset()
           throws AudioFile.OperationUnsupportedException

Reset the audio input stream. For some audio formats, this may involve re-opening the associated file.

Throws:

OperationUnsupported

AudioFile.OperationUnsupportedException

skip

public void skip(long frames)
          throws AudioFile.OperationUnsupportedException

Skips a number of frames. For some audio formats, this may involve re-opening the associated file.

Throws:

OperationUnsupported

AudioFile.OperationUnsupportedException

seek

public void seek(int frame)
          throws AudioFile.OperationUnsupportedException

Seek to a specific frame number. Note that seeking is slower than skipping forward.

Parameters:

frame - The frame number, relative to the start of the audio data.

Throws:

OperationUnsupported

AudioFile.OperationUnsupportedException

open

public abstract void open()
                   throws javax.sound.sampled.UnsupportedAudioFileException,
                          java.io.IOException

Opens the audio file.

Throws:

javax.sound.sampled.UnsupportedAudioFileException

java.io.IOException

getName

public java.lang.String getName()

Returns:

The name of the audio file.

getInformation

public java.lang.String getInformation()

Returns:

Information about this audio file. The file should be open if specific information is required.

close

public abstract void close()
                    throws java.io.IOException

Close the audio file. Can be re-opened.

Throws:

java.io.IOException

isOpen

public boolean isOpen()

Is the file stream open?

isClosed

public abstract boolean isClosed()

Is the file stream closed?

getFormat

public AudioFormat getFormat()

Returns:

The AudioFormat of this AudioFile. If the file is encoded, the AudioFormat is of the decoded data.

read

public abstract int read(byte[] buffer)

Read bytes from this audiofile. The bytes will be in an interleaved format. It is the responsibility of the caller to interpret this data correctly. The number of bytes read is equal to the size of the byte buffer. If that many bytes aren't available the buffer will only be partially filled.

Parameters:

buffer - A buffer to fill.

Returns:

The number of bytes read. A value of -1 indicates the file has no data left.

read

public abstract int read(float[][] buffer)

Read decoded audio data in a non-interleaved, Beads-friendly format. This function mainly exists for debugging purposes, and is extremely slow. @{link Sample} provides a much faster way to access data from an AudioFile.

Parameters:

buffer - The buffer to fill. After execution buffer[i][j] will contain the sample in channel i, frame j. Buffer has size (numChannels,numFramesRequested).

Returns:

The number of frames read.

getProperties

public java.util.Map<java.lang.String,java.lang.Object> getProperties()

Returns:

Any additional properties associated with this AudioFile.

getNumChannels

public int getNumChannels()

Returns:

The number of channels of audio data.

setNumFrames

protected void setNumFrames(long nFrames)

getNumFrames

public long getNumFrames()

Returns:

The length of this audio file in number of frames. If -1 then the length is unknown.

setLength

protected void setLength(float length)

getLength

public float getLength()

Returns:

The length of this audio file in millseconds. If < 0 then the length is unknown.

getFrameSize

public int getFrameSize()

Returns:

The size of each frame in bytes

setTrace

public void setTrace(boolean trace)

A debugging tool.

Parameters:

trace - Enable or disable a trace of file accesses. Useful for debugging.