AFopenRead

AFopenRead(3tsp)                                              AFopenRead(3tsp)



Routine
       AFILE *AFopenRead (const char Fname[], long int *Nsamp, long int
           *Nchan, float *Sfreq, FILE *fpinfo)

Purpose
       Open an audio file for reading

Description
       This routine opens an audio file for reading.  The companion routine
       AFreadData reads data from the file.  Routine AFclose should be used to
       close the file.

       This routine reads the audio file header and optionally prints the
       header information.  Several file header formats are supported.  For
       files with no header or an unrecognized header, the file format can be
       declared by calling routine AFsetNHpar.  A banner identifying the audio
       file and its parameters is printed.

       AU audio file:
           8-bit mu-law, 8-bit A-law, 8-bit integer, 16-bit integer, 24-bit
           integer, 32-bit integer, 32-bit IEEE floating-point, and 64-bit
           IEEE floating-point data formats are supported.
       WAVE file:
           8-bit mu-law, 8-bit A-law, offset-binary 1-bit to 8-bit integer,
           9-bit to 32-bit integer, 32-bit IEEE floating-point, and 64-bit
           IEEE floating-point data formats are supported.
       AIFF or AIFF-C sound file:
           8-bit mu-law, 8-bit A-law, 1-bit to 32-bit integer,  32-bit IEEE
           floating-point, and 64-bit IEEE floating-point data formats are
           supported.
       NIST SPHERE audio file:
           8-bit mu-law and 16-bit integer data formats are supported.
       IRCAM soundfile:
           8-bit mu-law, 8-bit A-law, 8-bit integer, 16-bit integer, 32-bit
           integer, and 32-bit floating-point data formats are supported.
       ESPS sampled data feature file:
           16-bit integer, 32-bit integer, 32-bit floating-point, and 64-bit
           floating-point data formats are supported.
       SPPACK sampled data file:
           8-bit mu-law, 8-bit A-law and 16-bit integer data formats are
           supported.
       INRS-Telecommunications audio file:
           16-bit integer format is supported.
       Cadence SPW Signal file:
           8-bit integer, 16-bit integer, 32-bit floating-point, 64-point
           floating-point, and text formats are supported.
       CSL NSP file:
           16-bit integer format is supported.
       Text audio file:
           Data in character format (usually representing 16-bit integer
           values).
       Headerless audio file:
           The data format is specified by calling routine AFsetNHpar.

       For the fixed point file data representations, read operations return
       data values as follows.
          format            returned values
         8-bit mu-law   - [ -32124, +32124 ]
         8-bit A-law    - [ -32256, +32256 ]
         8-bit integer  - [ -16384, +16256 ]
         16-bit integer - [ -32768, +32767 ]
         24-bit integer - [ -32768, +32768 )
         32-bit integer - [ -32768, +32768 )
       Floating-point data in the input audio file are scaled by 32768 (except
       for ESPS sample data feature files).  For file float data values
       between -1 and +1, the returned values will be in the range [ -32768,
       +32768 ].

       File type determination:
           The default behaviour is to determine the file type from the header
           of the input file.  However this requires look-ahead and is not
           possible with files that are not random access (for instance a file
           stream from a pipe).  For both random access and sequential access
           files, the file type can be specified explicitly with a call to
           routine AFsetFileType, obviating the need to determine the file
           type from the header.

       Number of samples:
           In some types of audio file types, the number of samples is
           specified in the file header.  In others, the number of samples is
           known only if the file size can be determined, specifically if the
           file random access.  For input from a stream which does not allow
           random access (for instance a file stream from a pipe), the file
           size cannot be determined for those files without that information
           in the file header.
                             no. samples
            file type         in header
            AU                  yes
            WAVE                yes
            AIFF or AIFF-C      yes
            NIST SPHERE         yes
            IRCAM               no
            ESPS                yes
            SPPACK              yes
            INRS-Telecom        no
            Cadence SPW         no
            CSL NSP             yes
            Text file           no
            Headerless          no
       Notes:
       - Some AU audio files and some ESPS audio files do not specify the
           number of samples.
       - AIFF/AIFF-C files with a perverse header cannot be opened for non-
           random access.

       On encountering an error, the default behaviour is to print an error
       message and halt execution.

Parameters
       <-  AFILE *AFopenRead
           Audio file pointer for the audio file..  The file name "-" means
           standard input.
        -> const char Fname[]
           Character string specifying the file name
       <-  long int *Nsamp
           Total number of samples in the file (all channels)
       <-  long int *Nchan
           Number of channels
       <-  float *Sfreq
           Sampling frequency
        -> FILE *fpinfo
           File pointer for printing audio file information.  If fpinfo is not
           NULL, information about the audio file is printed on the stream
           selected by fpinfo.

Author / revision
       P. Kabal / Revision 1.85  2003/01/30

See Also
       AFreadData, AFsetNHpar, AFclose, libtsp



                                TSP (libtsp/AF)               AFopenRead(3tsp)