|8.2.2. Libaudiofile: The Audiofile Library
For uncompressed audio, a track within an audio file consists of a sequence of frames, each of which contains a number of samples equal to the number of channels in the track. For example, in a stereo track, every frame contains two samples.
To read from a file containing audio data, the following sequence of function calls are typically used:
afOpenFile afReadFrames afCloseFile
To write to a file, a similar sequence of commands is typically employed:
afNewFileSetup afOpenFile afWriteFrames afCloseFile
Data format transparency is achieved in the Audio File Library by providing the data in a virtual format. The virtual format consists of a virtual byte order and a virtual sample format. Virtual byte order is by default set to the host byte order and does not depend on the native byte order of the file format being used. Virtual sample format is by default in an uncompressed format.
The current Audio File Library does not support the concept of a virtual sampling rate, but this may be supported in the future.
At the present, the Audio File Library supports only CCITT G.711 mu-law/A-law compression.
|22.214.171.124. Programming Paradigm
|126.96.36.199. Main Functions
#include <audiofile.h> int afReadFrames (const AFfilehandle file, int track, void *samples, const int count)
file is the AFfilehandle structure for the audio file from which audio sample data will be read.
track is the track number within the audio file referred to by file. track should be set to the default value of AF_DEFAULT_TRACK at the present time.
samples is a pointer to a buffer capable of storing count frames read from the file referred to by file.
count is the number of sample frames to be read from the track specified by track within the file specified by file.
afReadFrames returns the number of frames successfully read from file into the array referred to by samples.
Possible errors include (old school): AF_BAD_READ AF_BAD_FILEHANDLE AF_BAD_LSEEK AF_BAD_TRACKID (the track parameter differs from AF_DEFAULT_TRACK) AF_BAD_AIFF_SSND
(new school--unsupported): AF_ERR_BAD_READ AF_ERR_BAD_LSEEK
#include <audiofile.h> int afWriteFrames(AFfilehandle file, int track, void *samples, AFframecount frameCount);
file is a valid file handle.
track is always use AF_DEFAULT_TRACK for now.
samples is a pointer to the array of sample frames to be written to the file. frameCount is the number of frames from samples to be written.
afWriteFrames can return these possible errors: AF_BAD_WRITE AF_BAD_LSEEK AF_BAD_TRACKID
#include <audiofile.h> AFframecount afGetFrameCount (AFfilehandle file, int track); AFfileoffset afGetTrackBytes (AFfilehandle file, int track); AFfileoffset afGetDataOffset (AFfilehandle file, int track);
file is an AFfilehandle that has been created by a previous call to afOpenFile.
track is an integer which specifies an audio track within file. All supported file formats contain exactly one audio track per file, so the constant AF_DEFAULT_TRACK should always be used.
afGetFrameCount returns the total number of sample frames contained within the specified track of the specified file.
Each sample frame of audio consists of a fixed number of samples (equal to the number of audio channels in the file, equal to the value returned by afGetChannels for the particular track and file). For monaural data, a sample frame consists of one audio sample. For stereophonic data, a sample frame consists of a stereo pair.
afGetTrackBytes returns the total number of bytes of raw audio data (i.e., prior to decompression) in track. This is useful for determining raw file seek points, etc.
afGetDataOffset returns the offset in bytes of the start of the audio data contained within the specified track of the specified file.
afGetFrameCount returns the total number of sample frames in track. afGetTrackBytes() returns the total number of bytes of audio data in track. afGetDataOffset() returns the offset in bytes to the beginning of the audio data in track.
If an error occurs, -1 is returned by all of these routines.
#include <audiofile.h> int afCloseFile (AFfilehandle file);
#include <audiofile.h> float afGetFrameSize (AFfilehandle file, int track, int expand3to4);
track is an integer which refers to a specific audio track in the file. At present no supported audio file format allows for more than one audio track within a file, so track should always be AF_DEFAULT_TRACK.
If expand3to4 is a non-zero value, then 3-byte frames will be treated as taking up 4 bytes in memory. This is useful for calculating how much memory will be needed to store audio data suitable for playback since 24-bit audio data is typically aligned on 32-bit boundaries. (At least that's how it's done on SGI systems; I know of no other computer system that has support for 24-bit audio.)
A sample frame consists of one or more samples. For a monaural track, a sample frame will always contain one sample. For a stereophonic track, a sample frame will always contain two samples, one for the left channel and one for the right channel.
The parameter expand3to4 is ignored unless the specified audio track contains 24-bit sampled audio data.
#include <audiofile.h> AFfilesetup afNewFileSetup(void);
afNewFileSetup returns, upon success, a valid AFfilesetup structure.
Upon failure, afNewFileSetup returns a null AFfilesetup (AF_NULL_FILESETUP). This case should only occur when no memory is available.
The opaque AFfilesetup structure returned by afNewFileSetup can be used to specify parameters for a file to be opened for writing by afOpenFile.
#include <audiofile.h> AFfilehandle afOpenFile(const char *path, const char *mode, const AFfilesetup seutp);
Upon failure, afOpenFile returns a null file handle (AF_NULL_FILEHANDLE).
afCloseFile is used to close the file when it is no longer needed.
#include <audiofile.h> AUpvlist afQuery (int querytype, int arg1, int arg2, int arg3, int arg4); long afQueryLong (int querytype, int arg1, int arg2, int arg3, int arg4); double afQueryDouble (int querytype, int arg1, int arg2, int arg3, int arg4); void *afQueryPointer (int querytype, int arg1, int arg2, int arg3, int arg4);
For AF_QUERYTYPE_FILEFMT, the following selectors are valid values for arg1:
AF_QUERY_LABEL - Request a short label string for the format (e.g., "aiff").
AF_QUERY_NAME - Request a short name for the format (e.g., "MS RIFF WAVE").
AF_QUERY_DESC - Request a descriptive name for the format (e.g., "Audio Interchange File Format").
AF_QUERY_IMPLEMENTED - Request a boolean value indicating whether the format is implemented for reading and writing in the Audio File Library.
AF_QUERY_ID_COUNT - Request the total number of formats implemented.
AF_QUERY_IDS - Request an integer array of the id token values of all implemented file formats.
AF_QUERY_COMPRESSION_TYPES - Used with the selector AF_QUERY_VALUE_COUNT in arg2, this will return a long integer containing the number of compression schemes available for use within the format specified in arg3. Used with selector AF_QUERY_VALUES, it returns a pointer to an integer array containing the compression id values of the compression schemes supported by the format specified in arg3.
AF_QUERY_SAMPLE_FORMATS - Used with the selector AF_QUERY_DEFAULT in arg2, this will return the default sample format for the file format specified in arg3.
AF_QUERY_SAMPLE_SIZES - Used with selector AF_QUERY_DEFAULT in arg2, this will return the default sample width for the file format specified in arg3.
#include <audiofile.h> int afReadMisc (const AFfilehandle file, int miscid, void *buffer, int nbytes); int afWriteMisc (const AFfilehandle file, int miscid, void *buffer, int nbytes); int afSeekMisc (const AFfilehandle file, int chunkid, int offbytes);
afReadMisc returns the number of bytes read from the specified miscellaneous chunk into the buffer referred to by buffer.
afWriteMisc returns the number of bytes written to the specified miscellaneous chunk from the buffer referred to by buffer.
afSeekMisc returns the new location of the logical file pointer as measured as an offset in bytes from the beginning of the miscellaneous chunk's data area.
afTellFrame retrieves current value of a file read or write pointer.
#include <audiofile.h> AFframecount afSeekFrame (const AFfilehandle file, int track, AFframecount frameoffset); AFframecount afTellFrame (const AFfilehandle file, int track);
file is an AFfilehandle structure which has been created by afOpenFile.
track is an integer which refers to an audio track within a file. The constant AF_DEFAULT_TRACK should always be used for this parameter since no currently supported file formats support more than one track per file.
frameoffset is an offset measured in sample frames. This value must be greater than or equal to zero and strictly less than the number of sample frames contained within the specified audio track. If frameoffset is -1, afSeekFrame() will return the current frame.
On successful completion, the value returned from afSeekFrame and afTellFrame is the current file pointer location as measured in sample frames from the start of the audio track.
The following errors could be generated by afSeekFrame or afTellFrame: AF_BAD_LSEEK
#include <audiofile.h> AFerrfunc afSetErrorHandler (AFerrfunc errorFunction);
errorFunction is a pointer to an error handling function which has the following prototype: void error (long, char *, ...);
The value returned from afSetErrorHandler is a pointer to the previous error handling function.
The afSetErrorHandler() library function allows the user to override the default error handling function.
The arguments are a long indicating an error code and a string (which may have printf-style formatting) followed by a variable argument list which contains any arguments for the format string.
#include <audiofile.h> int afSetVirtualSampleFormat (AFfilehandle file, int track, int sampleFormat, int sampleWidth); int afSetVirtualByteOrder (AFfilehandle file, int track, int byteOrder); int afSetVirtualChannels (AFfilehandle file, int track, int channels); int afSetVirtualRate (AFfilehandle file, int track, double rate); int afSetVirtualPCMMapping (AFfilehandle file, int track, double slope, double intercept, double minclip, double maxclip);
These functions return 0 for success and -1 for failure.
At present, afSetVirtualRate is not implemented.