Package de.sciss.io

Class AudioFile

  • All Implemented Interfaces:
    InterleavedStreamFile
    public class AudioFile
extends java.lang.Object
implements InterleavedStreamFile
    The AudioFile allows reading and writing of sound files. It wraps a RandomAccessFile and delegates the I/O to subclasses which deal with the specific sample format and endianess.

    Currently supported formats are: AIFF, IRCAM, NeXT/Sun (.au), WAVE, and Wave64. Supported resolutions are 8/16/24/32 bit integer and 32/64 bit floating point. However not all audio formats support all bit depths.

    Not all format combinations are supported, for example the rather exotic little-endian AIFF, but also little-endian SND, WAVE 8-bit.

    In order to simplify communication with CSound, raw output files are supported, raw input files however are not recognized.

    To create a new AudioFile you call one of its static methods openAsRead or openAsWrite. The format description is handled by an AudioFileDescr object. This object also contains information about what special tags are read/written for which format. For example, AIFF can read/write markers, and application-specific chunk, and a gain tag. WAVE can read/write markers and regions, and a gain tag, etc.

    The AudioFile implements the generic interface InterleavedStreamFile (which is likely to be modified in the future) to allow clients to deal more easily with different sorts of streaming files, not just audio files.

    See Also:
    AudioFileDescr

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void cleanUp()
      Flushes and closes the file.
      void close()
      Flushes and closes the file
      void copyFrames​(InterleavedStreamFile target, long length)
      Copies sample frames from a source sound file to a target file (either another sound file or any other class implementing the InterleavedStreamFile interface).
      void flush()
      Flushes pending buffer content, and updates the sound file header information (i.e.
      int getChannelNum()
      Returns the number of channels in the file.
      AudioFileDescr getDescr()
      Returns a description of the audio file's format.
      java.io.File getFile()
      Returns the file that was used to open the audio file.
      long getFrameNum()
      Returns the number of frames in the file.
      long getFramePosition()
      Returns the current file pointer in sample frames
      protected static java.lang.String getResourceString​(java.lang.String key)  
      static AudioFile openAsRead​(java.io.File f)
      Opens an audio file for reading.
      static AudioFile openAsWrite​(AudioFileDescr afd)
      Opens an audio file for reading/writing.
      void readAppCode()
      Reads application specific code into the audio file description if there is such code.
      void readFrames​(float[][] data, int offset, int length)
      Reads sample frames from the current position
      void readMarkers()
      Reads markers into the audio file description if there are any.
      static int retrieveType​(java.io.File f)
      Determines the type of audio file.
      void seekFrame​(long frame)
      Moves the file pointer to a specific frame.
      void setFrameNum​(long frame)  
      void truncate()
      Truncates the file to the size represented by the current file position.
      void writeFrames​(float[][] data, int offset, int length)
      Writes sample frames to the file starting at the current position.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • raf

        protected final java.io.RandomAccessFile raf

      • fch

        protected final java.nio.channels.FileChannel fch

      • byteBuf

        protected java.nio.ByteBuffer byteBuf

      • bytesPerFrame

        protected int bytesPerFrame

      • frameBufCapacity

        protected int frameBufCapacity

      • channels

        protected int channels

    • Method Detail

      • openAsRead

        public static AudioFile openAsRead​(java.io.File f)
                            throws java.io.IOException
        Opens an audio file for reading.
        Parameters:
        f - the path name of the file
        Returns:
        a new AudioFile object whose header is already parsed and can be obtained through the getDescr method.
        Throws:
        java.io.IOException - if the file was not found, could not be read or has an unknown or unsupported format

      • openAsWrite

        public static AudioFile openAsWrite​(AudioFileDescr afd)
                             throws java.io.IOException
        Opens an audio file for reading/writing. The pathname is determined by the file field of the provided AudioFileDescr. If a file denoted by this path already exists, it will be deleted before opening.

        Note that the initial audio file header is written immediately. Special tags for the header thus need to be set in the AudioFileDescr before calling this method, including markers and regions. It is not possible to write markers and regions after the file has been opened (since the header size has to be constant).

        Parameters:
        afd - format and resolution of the new audio file. the header is immediatly written to the harddisc
        Throws:
        java.io.IOException - if the file could not be created or the format is unsupported

      • retrieveType

        public static int retrieveType​(java.io.File f)
                        throws java.io.IOException
        Determines the type of audio file.
        Parameters:
        f - the path name of the file
        Returns:
        the type code as defined in AudioFileDescr, e.g. TYPE_AIFF. Returns TYPE_UNKNOWN if the file could not be identified.
        Throws:
        java.io.IOException - if the file could not be read

      • getDescr

        public AudioFileDescr getDescr()
        Returns a description of the audio file's format. Fields which are guaranteed to be filled in, are the type (use getType), channels, bitsPerSample, sampleFormat, rate and length. Warning: the returned description is not immutable but should be considered read only, do not modify it. the fields may change dynamically if the file is modified, e.g. the length field for a writable file.
        Returns:
        an AudioFileDescr describing this audio file.

      • getFile

        public java.io.File getFile()
        Returns the file that was used to open the audio file. Note that this simply returns getDescr().file, so it's not a good idea to modify this field after opening the audio file.
        Specified by:
        getFile in interface InterleavedStreamFile
        Returns:
        the File that was used in the static constructor methods. Can be used to query the pathname or to delete the file after it has been closed

      • seekFrame

        public void seekFrame​(long frame)
               throws java.io.IOException
        Moves the file pointer to a specific frame.
        Specified by:
        seekFrame in interface InterleavedStreamFile
        Parameters:
        frame - the sample frame which should be the new file position. this is really the sample index and not the physical file pointer.
        Throws:
        java.io.IOException - when a seek error occurs or you try to seek past the file's end.

      • flush

        public void flush()
           throws java.io.IOException
        Flushes pending buffer content, and updates the sound file header information (i.e. length fields). Usually you will not have to call this method directly, unless you pause writing for some time and want the file information to appear as accurate as possible.
        Specified by:
        flush in interface InterleavedStreamFile
        Throws:
        java.io.IOException

      • getFramePosition

        public long getFramePosition()
                      throws java.io.IOException
        Returns the current file pointer in sample frames
        Specified by:
        getFramePosition in interface InterleavedStreamFile
        Returns:
        the sample frame index which is the offset for the next read or write operation.
        Throws:
        java.io.IOException - when the position cannot be queried

      • readFrames

        public void readFrames​(float[][] data,
                       int offset,
                       int length)
                throws java.io.IOException
        Reads sample frames from the current position
        Specified by:
        readFrames in interface InterleavedStreamFile
        Parameters:
        data - buffer to hold the frames read from harddisc. the samples will be deinterleaved such that data[0][] holds the first channel, data[1][] holds the second channel etc. ; it is allowed to have null arrays in the data (e.g. data[0] == null), in which case these channels are skipped when reading
        offset - offset in the buffer in sample frames, such that he first frame of the first channel will be placed in data[0][offset] etc.
        length - number of continuous frames to read.
        Throws:
        java.io.IOException - if a read error or end-of-file occurs.

      • writeFrames

        public void writeFrames​(float[][] data,
                        int offset,
                        int length)
                 throws java.io.IOException
        Writes sample frames to the file starting at the current position. If you write past the previous end of the file, the length field of the internal AudioFileDescr is updated. Since you get a reference from getDescr and not a copy, using this reference to the description will automatically give you the correct file length.
        Specified by:
        writeFrames in interface InterleavedStreamFile
        Parameters:
        data - buffer holding the frames to write to harddisc. the samples must be deinterleaved such that data[0][] holds the first channel, data[1][] holds the second channel etc.
        offset - offset in the buffer in sample frames, such that he first frame of the first channel will be read from data[0][offset] etc.
        length - number of continuous frames to write.
        Throws:
        java.io.IOException - if a write error occurs.

      • getFrameNum

        public long getFrameNum()
                 throws java.io.IOException
        Returns the number of frames in the file.
        Specified by:
        getFrameNum in interface InterleavedStreamFile
        Returns:
        the number of sample frames in the file. includes pending buffer content
        Throws:
        java.io.IOException - this is never thrown but declared as of the InterleavedStreamFile interface

      • setFrameNum

        public void setFrameNum​(long frame)
                 throws java.io.IOException
        Specified by:
        setFrameNum in interface InterleavedStreamFile
        Throws:
        java.io.IOException

      • getChannelNum

        public int getChannelNum()
        Returns the number of channels in the file.
        Specified by:
        getChannelNum in interface InterleavedStreamFile
        Returns:
        the number of channels

      • truncate

        public void truncate()
              throws java.io.IOException
        Truncates the file to the size represented by the current file position. The file must have been opened in write mode. Truncation occurs only if frames exist beyond the current file position, which implicates that you have set the position using seekFrame to a location before the end of the file. The header information is immediately updated.
        Specified by:
        truncate in interface InterleavedStreamFile
        Throws:
        java.io.IOException - if truncation fails

      • copyFrames

        public void copyFrames​(InterleavedStreamFile target,
                       long length)
                throws java.io.IOException
        Copies sample frames from a source sound file to a target file (either another sound file or any other class implementing the InterleavedStreamFile interface). Both files must have the same number of channels.
        Specified by:
        copyFrames in interface InterleavedStreamFile
        Parameters:
        target - to file to copy to from this audio file
        length - the number of frames to copy. Reading and writing begins at the current positions of both files.
        Throws:
        java.io.IOException - if a read or write error occurs

      • close

        public void close()
           throws java.io.IOException
        Flushes and closes the file
        Specified by:
        close in interface InterleavedStreamFile
        Throws:
        java.io.IOException - if an error occurs during buffer flush or closing the file.

      • cleanUp

        public void cleanUp()
        Flushes and closes the file. As opposed to close(), this does not throw any exceptions but simply ignores any errors.
        See Also:
        close()

      • readMarkers

        public void readMarkers()
                 throws java.io.IOException
        Reads markers into the audio file description if there are any. This method sets the KEY_MARKERS property of the afd, if markers are available. It sets the KEY_LOOP property if a loop span is available.
        Throws:
        java.io.IOException - if a read or parsing error occurs
        See Also:
        getDescr(), AudioFileDescr.KEY_MARKERS, AudioFileDescr.KEY_LOOP

      • readAppCode

        public void readAppCode()
                 throws java.io.IOException
        Reads application specific code into the audio file description if there is such code. This method sets the KEY_APPCODE property of the afd. The caller can check the appCode field of the afd to ensure that potential app code is relevant to it.
        Throws:
        java.io.IOException - if a read or parsing error occurs
        See Also:
        getDescr(), AudioFileDescr.KEY_APPCODE, AudioFileDescr.appCode

      • getResourceString

        protected static final java.lang.String getResourceString​(java.lang.String key)