afReadFrames(3dm)                                            afReadFrames(3dm)


NAME
     afReadFrames - read sample frames from a specified audio track in an
     audio file

SYNOPSIS
     #include <dmedia/audiofile.h>

     int afReadFrames(const AFfilehandle file, int track,
                      void *samples, const int count)

PARAMETER
     file      is the AFfilehandle structure for the audio file from which
               audio sample data will be read.  This structure is usually the
               returned value of a call to afOpenFile(3dm).

     track     is an integer which identifies an audio track in a file.

               Since all currently supported file formats allow at most one
               audio track per file, the value AF_DEFAULT_TRACK should always
               be used for this argument for now.

     samples   is a pointer to a buffer into which you want to transfer the
               samples read from the audio file.  Note that the data type of
               the samples in this buffer can vary depending on the sample
               format and sample width of the file.

     count     is the number of sample frames to be read from the audio track.

               For monaural data a sample frame is a single sample; for stereo
               data a sample frame is a pair of samples, etc.

RETURN VALUE
     afReadFrames() returns the number of sample frames actually read from the
     file. In the event of error, -1 is returned and oserror(3C) will be set
     to the appropriate error code.

DESCRIPTION
     afReadFrames() transfers data from the specified track of an audio file
     to the samples buffer.  samples should be of type char*, short*, int*,
     unsigned int*, float*, or double* depending on the width and format of
     the samples in the audio track as retrieved using afGetSampleFormat(3dm),
     or the virtual format specified by afSetVirtualSampleFormat(3dm).
     afReadFrames() attempts to read count sample frames from the file,
     starting at the current location of the file read pointer.

     When a file is opened with read access by afOpenFD(3dm),
     afOpenNamedFD(3dm), or afOpenFile(3dm), the file pointer for each audio
     track is initialized to point to the first sample frame in the audio
     track. The pointer may be moved to any sample frame location within a
     specified track by a call to afSeekFrame(3dm).


     Before returning, afReadFrames() automatically updates the read pointer
     for track  so that it points to the sample frame following the last one
     copied into samples.

     Note that the data type of the samples in this buffer can vary depending
     on the sample format and sample width of the samples in the track.  The
     samples buffer is interpreted differently depending on the current
     configuration of the audio track.  The sampwidth parameter returned by
     afGetSampleFormat(3dm) may or may not be meaningful, depending on the
     value of sampfmt.  See afGetSampleFormat(3dm) for a full explanation of
     sample representations.

     afReadFrames() automatically decompresses data which was encoded with the
     CCITT G.722, CCITT G.711, MPEG, and Aware compression.  By default, the
     data for all currently supported compression formats is presented to
     application programs in the standard two's complement linear PCM format,
     but this is by no means guaranteed for future compression types.  See
     afGetCompression(3dm) and afSetVirtualSampleFormat for further
     information.  To achieve real-time G.722 compression, the application
     process may require non-degrading scheduling priority (see schedctl(2) or
     npri(1))

     If an audio track contains data for more than a single audio channel, the
     data returned in the samples buffer will be interleaved.  For stereo
     data, the samples are always grouped in left/right pairs (sample frames).
     For reference, interleave conventions for files containing multichannel
     data are stated in the AIFF-C spec.

EXAMPLE
     To read 10000 stereo sample frames (i.e., 20000 individual audio samples)
     from a stereo AIFF-C file which contains G.722-encoded data, declare
     samples to be a short[] buffer (since G.722 encodes 16-bit data) with at
     least 20000 locations, and call afReadFrames() with count set to 10000.

CAVEATS
     This routine will not function correctly if the user changes the file
     position on the file descriptor for the AFfilehandle being manipulated.
     See afSaveFilePosition(3dm) and the section CAVEATS FOR USING THE
     HANDLE'S FILE DESCRIPTOR in afIntro(3dm) for some important information
     about how to deal with this situation.

SEE ALSO
     afOpenFile(3dm), afSeekFrame(3dm), afGetSampleFormat(3dm),
     afWriteFrames(3dm), afGetCompression(3dm), afSetVirtualSampleFormat(3dm),
     afGetVirtualSampleFormat(3dm)


                                                                        Page 2