Package de.sciss.io

Class 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.
    See Also:
    AudioFile, AudioFileFormatPane

    • Field Summary

      Fields 
      Modifier and Type Field Description
      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.
      static java.lang.String KEY_COMMENT
      property key : comment text.
      static java.lang.String KEY_GAIN
      property key : playback gain (multiplier).
      static java.lang.String KEY_LOOP
      property key : loop region.
      static java.lang.String KEY_MARKERS
      property key : marker list.
      static java.lang.String KEY_REGIONS
      property key : region list.
      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

      Constructors 
      Constructor Description
      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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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 synchronization: must be called in the event thread
      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). Warning: things like the marker list are not duplicated, they refer to the same instance
        Parameters:
        orig - a preexisting description whose values will be copied to the newly constructed description

    • 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 synchronization: must be called in the event thread
        Parameters:
        key - the key of the property to set
        value - the properties value.
        See Also:
        addPropertyChangeListener( PropertyChangeListener )

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