de.sciss.io
Class AudioFileDescr

java.lang.Object
  de.sciss.io.AudioFileDescr

public class AudioFileDescr
extends java.lang.Object

An AudioFileDescr is a data structure that describes the format of an AudioFile. It was public readable fields for common parameters such as sample rate and bitdepth. More specific features such as markers or gain chunks are stored using a Map object being accessed throught the setProperty and getProperty methods. A corresponding GUI element, the AudioFileFormatPane exists which presents the common fields to the user.

Version:

0.29, 10-Sep-08

Author:

Hanns Holger Rutz

See Also:

AudioFile, AudioFileFormatPane

Todo:

all files are considered big endian at the moment which might be inconvenient on non mac systems because there are for example different endian versions for ircam and we cannot read the little endian one. aiff however is per se big endian and should therefore cause no trouble.

Field Summary

java.lang.String	appCode application (creator) code
int	bitsPerSample bits per sample
int	channels number of channels (interleaved)
java.io.File	file This denotes a corresponding file on a harddisk.
static int	FORMAT_FLOAT sampleFormat type : pcm floating point
static int	FORMAT_INT sampleFormat type : linear pcm integer
static java.lang.String	KEY_APPCODE property key : application specific code. value class = byte[]; note that AbstractApplication.getApplication().getMacOSCreator() is used to write the app chunk, and when reading anything but app-code from the current application is skipped!
static java.lang.String	KEY_COMMENT property key : comment text. value class = String;
static java.lang.String	KEY_GAIN property key : playback gain (multiplier). value class = Float
static java.lang.String	KEY_LOOP property key : loop region. value class = Region
static java.lang.String	KEY_MARKERS property key : marker list. value class = (java.util.)List whose elements are of class Marker
static java.lang.String	KEY_REGIONS property key : region list. value class = (java.util.)List whose elements are of class Region
long	length sound file length in sample frames
double	rate sampling rate in hertz
int	sampleFormat sample number format, FORMAT_INT or FORMAT_FLOAT
int	type file format such as TYPE_AIFF
static int	TYPE_AIFF type value : apple aiff sound file format
static int	TYPE_IRCAM type value : ircam sound file format
static int	TYPE_RAW type value : raw (headerless) file format
static int	TYPE_SND type value : sun/next file format .au aka .snd
static int	TYPE_UNKNOWN type value : undefined audio file format
static int	TYPE_WAVE type value : wave (riff) sound file format
static int	TYPE_WAVE64 type value : sony wave64 sound file format

Constructor Summary

AudioFileDescr()
Construct a new AudioFileDescr whose fields are all undefined

AudioFileDescr(AudioFileDescr orig)
Construct a new AudioFileDescr whose common fields are copied from a template (type, channels, rate, bitsPerSample, sampleFormat, length, properties).

Method Summary

void	addPropertyChangeListener(java.beans.PropertyChangeListener l)
java.lang.String	getFormat() Create a human readable text string describing the audio file format.
static StringItem[]	getFormatItems() Gets a list of items suitable to attaching to a PrefComboBox, describing the supported audio file formats.
static java.lang.String	getFormatSuffix(int type) Gets the suffix commonly used for attaching to a file name of the given format.
java.lang.Object	getProperty(java.lang.Object key) Gets a specific property
int	getType() Returns the file format type
boolean	isPropertySupported(java.lang.String key) Reports if a sound file format can handle a particular property.
static double	millisToSamples(AudioFileDescr afd, double ms) Utility method to convert milliseconds to sample frames according to the given audio file format
void	removePropertyChangeListener(java.beans.PropertyChangeListener l)
static double	samplesToMillis(AudioFileDescr afd, long samples) Utility method to convert sample frames to milliseconds according to the given audio file format
void	setProperty(java.lang.Object source, java.lang.String key, java.lang.Object value) Sets a specific property and dispatches a PropertyChangeEvent to registered listeners
void	setProperty(java.lang.String key, java.lang.Object value) Sets a specific property.

Methods inherited from class java.lang.Object

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

Field Detail

TYPE_UNKNOWN

public static final int TYPE_UNKNOWN

type value : undefined audio file format

See Also:

Constant Field Values

TYPE_AIFF

public static final int TYPE_AIFF

type value : apple aiff sound file format

See Also:

Constant Field Values

TYPE_SND

public static final int TYPE_SND

type value : sun/next file format .au aka .snd

See Also:

Constant Field Values

TYPE_IRCAM

public static final int TYPE_IRCAM

type value : ircam sound file format

See Also:

Constant Field Values

TYPE_WAVE

public static final int TYPE_WAVE

type value : wave (riff) sound file format

See Also:

Constant Field Values

TYPE_RAW

public static final int TYPE_RAW

type value : raw (headerless) file format

See Also:

Constant Field Values

TYPE_WAVE64

public static final int TYPE_WAVE64

type value : sony wave64 sound file format

See Also:

Constant Field Values

FORMAT_INT

public static final int FORMAT_INT

sampleFormat type : linear pcm integer

See Also:

Constant Field Values

FORMAT_FLOAT

public static final int FORMAT_FLOAT

sampleFormat type : pcm floating point

See Also:

Constant Field Values

file

public java.io.File file

This denotes a corresponding file on a harddisk. It may be null

type

public int type

file format such as TYPE_AIFF

channels

public int channels

number of channels (interleaved)

rate

public double rate

sampling rate in hertz

bitsPerSample

public int bitsPerSample

bits per sample

sampleFormat

public int sampleFormat

sample number format, FORMAT_INT or FORMAT_FLOAT

length

public long length

sound file length in sample frames

appCode

public java.lang.String appCode

application (creator) code

KEY_LOOP

public static final java.lang.String KEY_LOOP

property key : loop region. value class = Region

See Also:

Region, Constant Field Values

KEY_MARKERS

public static final java.lang.String KEY_MARKERS

property key : marker list. value class = (java.util.)List whose elements are of class Marker

See Also:

Marker, Constant Field Values

KEY_REGIONS

public static final java.lang.String KEY_REGIONS

property key : region list. value class = (java.util.)List whose elements are of class Region

See Also:

Region, Constant Field Values

KEY_GAIN

public static final java.lang.String KEY_GAIN

property key : playback gain (multiplier). value class = Float

See Also:

Constant Field Values

KEY_APPCODE

public static final java.lang.String KEY_APPCODE

property key : application specific code. value class = byte[]; note that AbstractApplication.getApplication().getMacOSCreator() is used to write the app chunk, and when reading anything but app-code from the current application is skipped!

See Also:

Constant Field Values

KEY_COMMENT

public static final java.lang.String KEY_COMMENT

property key : comment text. value class = String;

See Also:

Constant Field Values

Constructor Detail

AudioFileDescr

public AudioFileDescr()

Construct a new AudioFileDescr whose fields are all undefined

AudioFileDescr

public AudioFileDescr(AudioFileDescr orig)

Construct a new AudioFileDescr whose common fields are copied from a template (type, channels, rate, bitsPerSample, sampleFormat, length, properties).

Parameters:

orig - a preexisting description whose values will be copied to the newly constructed description

Warning:

things like the marker list are not duplicated, they refer to the same instance

Method Detail

getType

public int getType()

Returns the file format type

Returns:

the type of the file, e.g. TYPE_AIFF

getProperty

public java.lang.Object getProperty(java.lang.Object key)

Gets a specific property

Parameters:

key - the key of the property to query, such as KEY_MARKERS

Returns:

the property's value or null if this property doesn't exist. the class of the property varies depending on the property type. see the key's description to find out what kind of object is returned

setProperty

public void setProperty(java.lang.String key,
                        java.lang.Object value)

Sets a specific property. Use the isPropertySupported method to find out if the chosen file format can store the property.

Parameters:

key - the key of the property to set

value - the properties value. Note that the value is not checked at all. It is the callers responsibility to ensure the value's class is the one specified for the particular key.

See Also:

isPropertySupported( String )

setProperty

public void setProperty(java.lang.Object source,
                        java.lang.String key,
                        java.lang.Object value)

Sets a specific property and dispatches a PropertyChangeEvent to registered listeners

Parameters:

key - the key of the property to set

value - the properties value.

See Also:

addPropertyChangeListener( PropertyChangeListener )

Synchronization:

must be called in the event thread

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener l)

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener l)

isPropertySupported

public boolean isPropertySupported(java.lang.String key)

Reports if a sound file format can handle a particular property.

Parameters:

key - the key of the property to check

Returns:

true the sound file format given by getType() supports the property. false if not. Note that if a property is not supported, it is no harm to set it using setProperty, it just won't be written to the sound file's header.

getFormat

public java.lang.String getFormat()

Create a human readable text string describing the audio file format.

Returns:

a text string containing information about the file format, resolution and sample rate, channel number. Suitable for copying to a GUI text label.

getFormatItems

public static StringItem[] getFormatItems()

Gets a list of items suitable to attaching to a PrefComboBox, describing the supported audio file formats.

Returns:

a list of items for a PrefComboBox which list all supported audio file formats.

See Also:

PrefComboBox to learn about the use of StringItems

getFormatSuffix

public static java.lang.String getFormatSuffix(int type)

Gets the suffix commonly used for attaching to a file name of the given format.

Parameters:

type - format such as TYPE_AIFF, TYPE_RAW etc.

Returns:

the suffix string such as "aif", "raw" or null if the type was invalid.

millisToSamples

public static double millisToSamples(AudioFileDescr afd,
                                     double ms)

Utility method to convert milliseconds to sample frames according to the given audio file format

Parameters:

afd - the audio file description whose rate field is used to do the conversion

ms - arbitrary offset in milliseconds. note that this doesn't have to be within the range of the current length of the audio file.

Returns:

the time offset which was specified in milliseconds, converted to sample frames (round to integer value if needed).

samplesToMillis

public static double samplesToMillis(AudioFileDescr afd,
                                     long samples)

Utility method to convert sample frames to milliseconds according to the given audio file format

Parameters:

afd - the audio file description whose rate field is used to do the conversion

samples - arbitrary offset in sample frames. note that this doesn't have to be within the range of the current length of the audio file.

Returns:

the time offset which was specified in sample frames, converted to milliseconds (round to integer value if needed).