Audio file format is typically indicated by header information preceding the actual data that describes the nature of the data in that file. The file format of an audio file constrains the data format of each of its tracks to one of a set of track formats supported by that file format, but you do not necessarily know which one. You must therefore set and query the track format for each of an audio file's tracks independently of its file format. It is often possible and desirable to write your application so that it queries only the data format(s) of the track(s) (instead of querying the file format) of the audio files it opens.

Audio tracks contain the recorded samples that produce sound when sent to the audio hardware. These samples are stored linearly for mono recordings and as interleaved left-right pairs (left channel in even locations, right channel in odd locations) for stereo recordings. These pairs are called sample frames (this term is also used for mono tracks, but a sample frame is the same thing as a sample when mono data is used).

Audio tracks also contain track markers, which can be set to point to arbitrary locations in the audio track. These markers, which are identified by a long integer ID number and (optionally) a name string, point to locations between sample frames.

Data format information, including sample rate, sample format, sample width, and sample compression type is stored as part of the audio track. Several kinds of compression are supported (you can also choose not to use compression). The AF Library automatically compresses samples being written to a file and decompresses samples read from a file. The ability of the AF Library to perform compression/decompression of audio data in real time is dependent on system overhead. To guarantee real-time performance, you should make use of scheduling control as described in “Using Scheduling Control to Give Audio High Priority” in Chapter 6.

Instrument configurations contain a set of parameters that define the aspects of a sampler, including detuning, key velocity, and gain. They also contain loop markers, which identify the beginning and ending points of loops that allow all or part of the audio track to be repeated. These loop markers point to previously created audio track markers, which in turn refer to locations in the audio track that comprise the beginning and ending of the loop. AIFF and AIFF-C files support two kinds of loops, sustain and release, each with a beginning and ending marker, which can be used in audio tracks and track markers.

Silicon Graphics has adopted AIFF-C as its standard digital audio file format. AIFF-C is based on Apple Computer's Audio Interchange File Format (AIFF), which conforms to the EA IFF 85 Standard for Interchange Format Files developed by Electronic Arts. Unlike the older AIFF standard, AIFF-C files can store compressed sample data as well as two's complement linear PCM sample data.

AIFF-C provides a standard file format for storing sampled sounds on magnetic media. The format can store any number of channels of sampled sound at a variety of sample rates and sample widths. The format is extensible, allowing future support of new compression types and application-specific data, while maintaining backward compatibility.

An AIFF-C file is composed of a series of different kinds of data chunks. For the most part, the AF Library API handles low-level chunk manipulation. For complete information on the types of chunks supported by AIFF-C, see the Audio Interchange File Format with Compression (AIFF-C) Specification.

Both AIFF and AIFF-C files consist of similar component structures. The chunks in an AIFF-C file are grouped together inside a special container chunk. The EA IFF 85 specification defines several types of container chunks, but the kind used by AIFF-C is of type 'FORM'.

Table 7-1 shows the mapping between the Audio File Library API functional components and the low-level AIFF-C/AIFF data chunks.

The AF Library requires that you specify the sample rate for a new file before you pass the AFfilesetup structure to AFopenfile().

AFinitrate() configures the sample rate in Hz for an audio track in an AFfilesetup structure. Its function prototype is:

void AFinitrate(AFfilesetup setup, long trackid, double rate)

where setup is the AFfilesetup structure, trackid is a long integer that identifies an audio track in setup, and rate is a positive double-precision integer that specifies the sample rate in Hz. For example, to configure setup for a CD-quality AIFF-C file, initialize the rate for AF_DEFAULT_TRACK to 44100.0.

AFinitsampfmt() initializes the sample format and width parameters for an audio track in an AFfilesetup structure. Its function prototype is:

void AFinitsampfmt(AFfilesetup setup, long trackid, long fmt,
                   long width)

where setup is the AFfilesetup structure, trackid is a long integer that identifies an audio track in setup, and fmt is a long integer constant that denotes a sample format. Currently, only one format is supported: AF_SAMPFMT_TWOSCOMP. width is a positive long integer value from 1 to 32 that specifies the width (in bits) of the sample data. See “Getting Audio Track Sample Format and Sample Width” for more details about sample format and sample width.

---

Note: If the audio track in an AIFF-C file is configured for compression, fmt and width should match the data format specified by the compression algorithm. See Table 7-4 for a list of compression algorithms.

---

AFinitchannels() configures the number of interleaved audio channels for an audio track within an AFfilesetup structure. This information is then used by AFopenfile() when it is called with the AFfilesetup structure as an argument. Its function prototype is:

void AFinitchannels(AFfilesetup setup, long trackid,
                    long channels)

where setup is the AFfilesetup structure, trackid is a long integer that identifies an audio track in setup, and channels is a long integer representing the number of interleaved audio channels. Valid values for channels are 1 (mono) or 2 (stereo); the default value is 2.

AES channel status bytes are embedded in AES audio samples to provide additional information about that data, such as whether an emphasis has been added to a sample. For example, on early CD recordings, high frequencies were sometimes emphasized to compensate for the nature of CD players. You might want to reverse compensate for that emphasis if you are loading AES stream data directly from a CD player through the AES serial input of your workstation for playback on a different source, such as DAT. See the AES3-1985 (ANSI S4.40-1985) document for more information about AES channel status bytes.

AFinitaeschanneldata() sets a flag, which is off by default, in an AFfilesetup structure to indicate that space should be reserved for the 24 AES channel status bytes that are embedded in all AES data. Its function prototype is:

void AFinitaeschanneldata(AFfilesetup setup, long trackid)

where setup is the AFfilesetup structure, and trackid is a long integer that identifies an audio track in setup.

AFsetaeschanneldata() sets the values of the AES channel status bytes. Its function prototype is:

void AFsetaeschanneldata(AFfilehandle file, long trackid,
                         unsigned char buf[24])

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), trackid is the ID for the audio track (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_TRACK), and buf is a 24-element array that specifies the AES channel status bytes. If no header space has been reserved in the file (by calling AFinitaeschanneldata() before creating the file), AFsetaeschanneldata() ignores the data and returns without error.

AFinitcompression() and AFinitcompressionparams() let you configure an audio track in an AFfilesetup structure to store compressed audio data. All compression encoding is handled automatically by AFwriteframes(); therefore your application program need only work with linear PCM data.

---

Note: AIFF files do not support compression. It is an error to try to open an AIFF file using an AFfilesetup whose compression setting is other than AF_COMPRESSION_NONE.

---

AFinitcompression() lets you select from among several built-in default codec (compressor-decompressor) configurations that are preconfigured. If you use AFinitcompression() to select one of the default codecs that are built in to the Audio File Library, you don't have to worry about setting the individual compression parameters, because they are automatically set to the proper values for each default configuration.

AFinitcompressionparams() lets you chose the codec configuration and set the associated codec-specific compression parameters yourself, although it does supply the defaults listed in Table 7-4. If you use AFinitcompressionparams(), you have to create and fill in an Audio Utility Library parameter-value list (AUpvlist), as described in “Using the Audio Utility Library to Initialize Parameter Lists”.

You may also select from additional audio codecs from Aware, Inc. that provide ISO/MPEG I and Aware MultiRate I audio compression, which are built in to the Audio File Library and can be accessed under license from Aware, Inc. by using the parameters in Table 7-4. See Appendix B, “Aware Scalable Audio Compression Software,” for more information.

The function prototypes are:

void AFinitcompression( AFfilesetup setup, long track,
                        long compression)
long AFinitcompressionparams( AFfilesetup setup, long track,
                              long compression,
                              AUpvlist pvlist, long numitems)

where:

Table 7-4 lists the valid compression values that you can set for AIFF-C files; compression must be AF_COMPRESSION_NONE for AIFF files.

Audio track marker structures store sample frame locations in the track for looping and other purposes. Markers are identified by a long integer ID number and (optionally) a name string. Markers point to a location between two samples in the audio track: position 0 is before the first sample, position 1 is between the first and second sample, and so on. You can assign positions to the markers by calling AFsetmarkpos(). By default, AFnewfilesetup() allocates space for four markers, which is sufficient to store the beginning and end points for both a sustain loop and a release loop.

AFinitmarkids() initializes a list of unique marker IDs corresponding to marker structures in a given audio track. Its function prototype is:

void AFinitmarkids(AFfilesetup setup, long trackid,
                   long markids[], long nmarks)

where setup is the AFfilesetup structure, trackid is a long integer that identifies an audio track in setup, markids is an array of unique positive long integers that will be used as handles for the marker structures in the file opened with setup, nmarks is a long integer that specifies the number of marker IDs in the markids array, that is, the total number of marker structures that will be allocated for the audio track. AIFF-C (and AIFF) files can contain up to 65535 markers in a track.

AFinitmarkname() specifies a name string for a marker structure. Marker names default to empty strings. Its function prototype is:

void AFinitmarkname(AFfilesetup setup, long trackid,
                    long markid, char *name)

where setup is the AFfilesetup structure, trackid is a long integer that identifies an audio track in setup, markid is a positive long integer that identifies a marker structure configured previously by AFinitmarkids(), name is a string that will be written into the marker structure when an audio file is created by passing setup to AFopenfile().

Use AUpvnew() to create an empty AUpvlist with the specified number of blank structures. Its function prototype is:

AUpvlist AUpvnew(int numitems)

where:

AUpvnew() returns an empty AUpvlist structure. If an error occurs— either because numitems is less than or equal to zero, or because of a memory allocation error—a null pointer, AU_NULL_PVLIST, is returned.

When an AUpvlist is no longer needed, you should free the memory associated with it by calling AUpvfree(). Its function prototype is:

int AUpvfree(AUpvlist pvlist)

where pvlist is the structure for which memory should be freed.

Use the AUpvlist structure when setting and getting a parameter, its type, and its value. The “set” routines fill in the structure entries for the designated list item with the specified information; the “get” routines return the requested information in pointers corresponding to the item being queried.

Table 7-6 lists and describes the AU Library get and set routines.

The function prototypes of the routines in Table 7-6 are:

int AUpvgetmaxitems(AUpvlist pvlist)
int AUpvgetparam(AUpvlist pvlist, int item, int *param_ptr)
int AUpvgetval(AUpvlist pvlist, int item, void *val_ptr)
int AUpvgetvaltype(AUpvlist pvlist, int item, int *type_ptr)
int AUpvsetparam(AUpvlist pvlist, int item, int param)
int AUpvsetval(AUpvlist pvlist, int item, void *val_ptr)
int AUpvsetvaltype(AUpvlist pvlist, int item, int type)

Use AUchecklicense() to verify whether a license for a particular audio product is available. Its function prototype is:

int AUchecklicense(int product, int *errorval,
                   char **message)

where:

On successful completion, AUchecklicense() returns AU_LICENSE_OK. If product is unknown, then AU_BAD_PRODUCT is returned. If a NetLS error occurs, then AU_LICENSE_ERR is returned and *errorval and *message are set, describing the error. See Appendix B for more information about NetLS.

Example 7-1 contains a listing of a portion of code from the aifcinfo.c demo program that is provided in /usr/people/4Dgifts/examples/dmedia/soundfile. This portion of code creates an AUpvlist with 3 items, fills those items with the pertinent information, then frees the memory associated with the AUpvlist when it is no longer required.

{
AUpvnew(&pvlist, 3);

AUpvsetparam(pvlist, 0, AF_AWARE_PARAM_LAYER);
AUpvsetvaltype(pvlist, 0, AU_PVTYPE_LONG);
AUpvsetparam(pvlist, 1, AF_AWARE_PARAM_BITRATE_POLICY);
AUpvsetvaltype(pvlist, 1, AU_PVTYPE_LONG);
AUpvsetparam(pvlist, 2, AF_AWARE_PARAM_BITRATE_TARGET);
AUpvsetvaltype(pvlist, 2, AU_PVTYPE_LONG);

AFgetcompressionparams(file, AF_DEFAULT_TRACK,
&track_desc->compressiontype, pvlist, 3);
AUpvgetval(pvlist, 0, &track_desc->aware_desc.layer);
AUpvgetval(pvlist, 1,
&track_desc->aware_desc.bitratepolicy);
AUpvgetval(pvlist, 2,
&track_desc->aware_desc.bitratetarget);

AUpvfree(pvlist);
}

AFgetrate() returns the sample rate of an audio track in an opened audio file. Its function prototype is:

double AFgetrate(AFfilehandle file, long trackid)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), and trackid is the ID for the audio track (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_TRACK).

AFgetrate() returns a double-precision floating point value that describes in Hz the audio sampling rate of the audio track.

AFgetsampfmt() retrieves the sample format and sample width for an audio track in an opened audio file. Its function prototype is:

void AFgetsampfmt(AFfilehandle file, long trackid,
                  long *sampfmt, long *width)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), trackid is the ID for the audio track (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_TRACK), sampfmt is a pointer to a long integer denoting the format of the sample data (for AIFF and AIFF-C files, this value is always AF_SAMPFMT_TWOSCOMP), and width is a pointer to a long integer that denotes the sample width in bits (for AIFF and AIFF-C files, this value is between 1 and 32).

---

Tip: Do not assume that AF_SAMPFMT_TWOSCOMP is the only value that can be returned by AFgetsampfmt(). Write your application so that it rejects files with sample formats it does not support.

---

Sample width may or may not have meaning, depending on the value of sampfmt. For AF_SAMPFMT_TWOSCOMP data, you can use the sample width value to determine the data type used to pass samples to AFwriteframes() and from AFreadframes(): 1–8 bit samples are packed into chars, 9–16 bit samples are packed into shorts, and 17–32 bit samples are packed into longs. Data formats whose sample width is not a multiple of eight are augmented by zero-bit-padding on the right (see Figure 7-1).

There is a special case for reading 24-bit integer data. The AF automatically converts 3-byte data into 4-byte quantities in a manner that is compatible with the Audio Library (AL) by sign-extending the left-most bits of 17 to 24–bit data.

Figure 7-1 shows the data packing for twos complement integer data (AF_SAMPFMT_TWOSCOMP).

Figure 7-1. Audio Data Packing Formats

---

Tip: Don't assume that the maximum size of integers in files opened by the AF Library is 32 bits or that the number of bits will be a multiple of 8. Even for AIFF files, the sample width is not necessarily a multiple of 8. Generally, this can be ignored, because audio samples that do not take up an integral number of bytes are left-justified inside the next larger integral number of bytes (with the remaining bits set to 0). But you should write your application so that it does not assume the sample width is a multiple of 8, as demonstrated in Example 7-2.

---

Example 7-2 checks for the audio track sample format, and then classifies integer data according to its sample width.

#include <dmedia/audiofile.h>
...
AFfilehandle h = AFopenfile(....);
if (!h) return;

AFgetsampfmt(h, AF_DEFAULT_TRACK, &sampfmt, &sampwidth);

if (sampfmt != AF_SAMPFMT_TWOSCOMP)
    {
    printf("This program can't read audio files of this "
           sample format");
           exit(0);
           }
/* round sampwidth up to nearest number of bytes */
int nbytes = ( (sampwidth-1) / 8 ) + 1;
switch (nbytes)
    {
    case 1:  do_8_thing(); break;
    case 2: do_16_thing(); break;
    case 3: do_24_thing(); break;
    case 4: do_32_thing(); break;
    default:
        printf("This program can't read audio files of this "
               sample width %d\n", sampwidth);
               exit(0);
               }

The number of channels in an audio track is initially set by AFinitchannels() before the file is created.

AFgetchannels() returns the number of interleaved audio channels in the audio track of an opened audio file. Its function prototype is:

long AFgetchannels(AFfilehandle file, long trackid)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), and trackid is the ID for the audio track (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_TRACK). AFgetchannels() returns 1 if trackid is monaural, 2 if it is stereo, or any other positive integer (even for AIFF/AIFF-C files).

---

Tip: Your application should be able to handle audio files containing an arbitrary number of channels. For example, the application could reject a file that has more than the supported number of channels, or it could combine channels selectively or use certain channels while ignoring others.

---

AFgetaeschanneldata() retrieves AES channel status information from an opened audio file. Its function prototype is:

long AFgetaeschanneldata(AFfilehandle file, long trackid,
                         unsigned char buf[24])

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), trackid is the ID for the audio track (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_TRACK), and buf is a 24-element array that receives the AES channel status bytes.

AFgetaeschanneldata() returns a 1 if there is AES channel data, or a 0 if there is no data.

---

Tip: There is no guarantee whether a given file format will contain AES data, so your application should call AFgetaeschanneldata() to determine whether AES channel bytes are encoded in an audio file.

---

This section describes routines that let you get compression information for an audio track from an AFfilehandle structure.

When reading or writing a file (even an AIFF-C file) containing compressed data, first call AFgetsampfmt() to get the native sample format of the codec, and check that it is able to be read/written using that format. The native sample format of a codec is the sample format of the data it produces on decompression or expects on compression.

---

Tip: Your application should reject compressed files with native sample formats it does not support. Check for an unrecognized format rather than a defined format. The currently defined codecs all convert the compressed data to and from 16-bit AF_SAMPFMT_TWOSCOMP data, but you should not assume that a certain format is guaranteed for future codecs. For example, if you know that the file is AF_COMPRESSION_G711_ULAW, then the native format for that codec is 16-bit AF_SAMPFMT_TWOSCOMP. However, you should call AFgetsampfmt() in any case, to allow for the possibility of future codecs whose native sample format is something other than 16-bit signed integer or which have more than one native sample format (some may be configurable or may vary depending on what kind of data was originally compressed).

---

AFgetcompression() and AFgetcompressionparams() return the compression type used in the audio track of an opened audio file. In addition, AFgetcompressionparams() scans a requested number of items and returns codec-specific parameters for the audio track. AFgetcompression() returns a long integer representing the compression algorithm used for the audio track's data; AFgetcompressionparams() returns this value in the compression pointer.

The function prototypes are:

long AFgetcompression(AFfilehandlefile file, long trackid)
long AFgetcompressionparams(AFfilehandle file, long trackid,
           long *compression, AUpvlist pvlist, long numitems)

where:

Table 7-7 lists the valid return values for AIFF-C files. AIFF files always return AF_COMPRESSION_NONE.

The Audio File Library provides built-in codec support for five compression algorithms: CCITT G.722, CCITT G.711 μ-law and A-law, and the Aware, Inc. ISO/MPEG I-audio and MultiRate I algorithms. To get more specific information about the Aware algorithms, such as MPEG I layers, see Appendix B, “Aware Scalable Audio Compression Software.”

---

Note: The four Apple compression algorithms listed in Table 7-7 are proprietary to Apple Computer Inc., and are not currently supported by the Audio File Library.

---

AFgetcompressionname() returns a null-terminated string containing the name of the compression algorithm used for an audio track in an opened audio file. Its function prototype is:

char *AFgetcompressionname(AFfilehandle file, long trackid)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), and trackid is the ID for the audio track (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_TRACK).

If compression is not used, as is the case with AIFF files, AFgetcompressionname() returns a null string.

AFgetframecnt() returns the total number of sample frames in the audio track of an opened audio file. Its function prototype is:

long AFgetframecnt(AFfilehandle file, long trackid)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(). trackid is the ID for the audio track (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_TRACK).

AFgetframecnt() returns a long integer value that is the current total of sample frames in the track.

This section describes functions that get information about the markers in a given audio track and explains how to set the position of those markers. Markers point to positions between adjacent sample frames. For a track containing n sample frames, position 0 is before the first sample frame, and position n is after the last sample frame in the track.

AFgetmarkids() retrieves an array of marker IDs from a given audio track in an opened audio file. It returns the number of marker structures in the specified audio track. Its function prototype is:

long AFgetmarkids(AFfilehandle file, long trackid,
                  long markids[])

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), trackid is the ID for the audio track (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_TRACK), and markids is an array of long integers that receives the marker IDs for the marker structures in the audio track.

AFgetmarkids() returns a non-negative integer value specifying the number of marker structures in the given audio track.

---

Tip: Check for unrecognized mark return values rather than recognized values. Write your application so that it expects any number of marks and any type of mark (not just the currently defined types) and rejects files containing marks it does not support.

---

Typically, you call AFgetmarkids() twice. The first time, you pass markids a null pointer and check the return value of the function. This value tells you how many locations to allocate in the markids array, which you pass back to AFgetmarkids() to obtain the list of marker IDs.

AFgetmarkname() returns the name string of a given marker within the audio track of an opened audio file. Its function prototype is:

char *AFgetmarkname(AFfilehandle file, long trackid,
                    long markid)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), trackid is the ID for the audio track (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_TRACK), and markid is the ID of the marker whose name you want to retrieve.

AFgetmarkname() returns a null-terminated character string that is the name associated with the given markid.

AFgetmarkpos() returns the frame location of a given marker in the audio track of an opened audio file. Its function prototype is:

long AFgetmarkpos(AFfilehandle file, long trackid, long markid)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), trackid is the ID for the audio track (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_TRACK), and markid is the ID of the marker whose position you want to discover.

AFgetmarkpos() returns a non-negative long integer value indicating the position of the marker in the track.

AFsetmarkpos() sets the frame location of a given marker in the audio track of an audio file opened for write access. Its function prototype is:

void AFsetmarkpos(AFfilehandle file, long track, long markid,
                  long markpos)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), trackid is the ID for the audio track (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_TRACK), markid is the ID of the marker whose position you want to move, and markpos is a non-negative long integer that describes the position to which you want to move the marker in the track.

When a file is opened for read access by AFopenfile() or AFopenfd(), the logical track pointer for the audio track is initialized to point to the first frame in the track. This location can be changed by calling AFseekframe(). Before returning, AFreadframes() moves the logical track pointer so that it points to the frame following the one last copied into frames.

---

Caution: The logical track pointer is not the same thing as the IRIX file pointer which you position by calling the IRIX lseek(2) command.

---

AFseekframe() moves the logical track pointer in the audio track of an audio file opened for read-only access to a specified frame. Its function prototype is:

long AFseekframe(AFfilehandle file, long trackid,
                 long offset)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), trackid is the ID for the audio track (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_TRACK), and offset is the number of frames from the beginning of the track that the pointer will be moved to. This value is between 0 and the total number of frames in the track, minus 1. The total number of frames in the track can be determined by calling AFgetframecnt().

When AFseekframe() succeeds, it returns the actual offset value; otherwise, it returns a negative value.

AFreadframes() copies sample frames from an audio file opened for reading to a buffer. Its function prototype is:

long AFreadframes(AFfilehandle file, long trackid,
                  void *frames, long count) 

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), trackid is the ID for the audio track (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_TRACK), frames is a pointer to a buffer into which you want to transfer copies of sample frames from file, and count is the number of sample frames you want to read from file.

AFreadframes() returns a long value indicating the number of frames successfully read from the audio track.

The data copied into frames must be interpreted according to the sample format and sample width parameter returned by AFgetsampfmt() and channel count returned by AFgetchannels(), as described in “Getting Audio Track Sample Format and Sample Width”. For AF_SAMPFMT_TWOSCOMP, AFreadframes() copies the frames to the buffer using the smallest data type (char, short, or long) that capable of holding the data. AFreadframes() automatically decompresses data encoded using any of the supported compression algorithms. (For Aware compression, an Aware license must be installed.)

---

Tip: Query for the sample format, sample width, and channels. Don't assume that a particular file format determines the sample format, sample width, or number of channels. Provide a mechanism for detecting and handling unsupported file configurations.

---

When a file is opened for write access by AFopenfile() or AFopenfd(), the logical track pointer for the file's audio track is initialized to point to the first frame in the track. Before returning, AFwriteframes() moves the logical track pointer so that it points to the frame following the one last copied into samples.

---

Caution: The logical track pointer is not the same thing as the IRIX file pointer which you position by calling the IRIX lseek(2) command.

---

AFwriteframes() copies frames from a buffer to an audio file opened for writing. Its function prototype is:

long AFwriteframes(const AFfilehandle file, long track,
                   void samples, const long count) 

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), track is a long integer which identifies the audio track (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_TRACK), samples is a pointer to a buffer containing sample frames that you want to write to file, and count is the number of sample frames you want to write to file.

For AF_SAMPFMT_TWOSCOMP data, AFwriteframes() expects the frames to be buffered using the smallest data type (char, short, or long) capable of holding the data. AFwriteframes() automatically compresses data encoded using any of the supported compression algorithms.

AFwriteframes() returns a long value indicating the number of frames successfully written to the audio track. The return value is normally greater than or equal to 0; however, when a codec is being used and buffered data cannot be written to disk, that data is lost. In such a case, AFwriteframes() returns a negative value, indicating the number of sample frames lost.

Use the functions described in this section to retrieve and set the instrument configuration parameters of an audio file. The parameters can be read from any opened audio file and written to any audio file opened as write-only.

AFgetinstids() retrieves an array of instrument IDs corresponding to the instrument chunks in a given audio file. It returns the number of instrument chunks in the file. Its function prototype is:

long AFgetinstids(AFfilehandle file, long instids[])

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), and instids is an array of long integer instrument IDs that reference instrument chunks within the file.

Typically, you call AFgetinstids() twice. The first time, you pass instids a null pointer and check the return value of the function. This value tells you how many locations to allocate in the instids array, which you pass back to AFgetinstids() to obtain the list of instrument IDs.

---

Note: The AF Library currently supports only AIFF and AIFF-C file types, so the number of instrument chunks is always either 0 or 1. If the file does contain an instrument chunk, its ID will always be AF_DEFAULT_INST for AIFF and AIFF-C files. But other instrument configurations could be returned in future releases of the AF Library.

---

---

Tip: Write your application so that it checks for and rejects instrument configurations that you don't want to support.

---

AFgetinstparamlong() retrieves a long instrument configuration parameter value from an instrument configuration in an open audio file. Its function prototype is:

long AFgetinstparamlong(AFfilehandle file, long instid,
                        long param)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(). instid is the instrument ID for the instrument configuration chunk (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_INST). param is a symbolic constant that identifies an instrument parameter. See Table 7-3 and Table 7-8 for a list of valid parameter constants and values associated with them.

AFgetinstparamlong() returns the long integer value associated with the parameter specified in param. If instid or param is not valid, the value returned is 0.

Table 7-8 lists the instrument parameter constants and their valid values.

---

Tip: Check for unrecognized instrument configuration and parameters rather than recognized types. Write your application so that it expects any type of instrument configuration (not just the currently defined types) and rejects files containing instruments it does not recognize.

---

AFsetinstparamlong() writes a long instrument configuration parameter value to a given instrument configuration chunk in an audio file that has been opened for writing. Its function prototype is:

void AFsetinstparamlong(AFfilehandle file, long instid,
                        long param, long value)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), instid is the instrument ID for the instrument configuration chunk (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_INST), param is a symbolic constant that identifies an instrument parameter, and value is the long integer value you want to assign to parameter named by param. See Table 7-3 and Table 7-8 for a list of valid parameter constants and values associated with them.

This section describes functions that retrieve and set the positions of instrument loops within an opened audio file. The loop information may be read from any opened audio file and written to any audio file opened as write-only. To get and set instrument loop IDs, use AFgetinstparamlong() and AFsetinstparamlong(), as described in “Reading and Writing Instrument Configurations”.

AFgetloopmode() returns the loop mode of a given loop in the instrument configuration of an opened audio file. Its function prototype is:

long AFgetloopmode(AFfilehandle file, long instid, long loopid)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), instid is the instrument ID for the instrument configuration chunk (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_INST), and loopid is the ID number associated with the loop whose mode you wish to read.

AFgetloopmode() returns a long integer value representing the loop mode. Current valid values for loop mode are:

AFsetloopmode() sets the loop mode of a given loop in the instrument configuration of an audio file opened as write-only. Its function prototype is:

void AFsetloopmode(AFfilehandle file, long instid,
                   long loopid, long mode)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), instid is the instrument ID for the instrument configuration chunk (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_INST), loopid is the ID number associated with the loop whose mode you wish to write, and mode is the long integer value you wish to set for the loop mode. See AFgetloopmode() for the list of valid mode values.

AFgetloopstart() returns an audio track marker ID associated with the starting point of a given instrument loop. Its function prototype is:

long AFgetloopstart(AFfilehandle file, long instid, long loopid)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), instid is the instrument ID for the instrument configuration chunk (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_INST), and loopid is the ID number associated with the loop whose starting point you wish to read.

AFgetloopstart() returns a long integer value, which is a marker ID in the audio track. See “Getting and Setting Audio Track Markers” in “Reading and Writing Audio Track Information” for information on how to manipulate the position of the markers referred to by the marker IDs.

AFsetloopstart() causes an audio track marker ID to be associated with the starting point of a given instrument loop. Its function prototype is:

void AFsetloopstart(AFfilehandle file, long instid,
                    long loopid, long markid)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), instid is the instrument ID for the instrument configuration chunk (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_INST), loopid is the ID number associated with the loop whose starting point you wish to write, and markid is the audio track marker that you wish to assign as the starting point of the given loop.

AFgetloopend() returns an audio track marker ID associated with the ending point of a given instrument loop. Its function prototype is:

long AFgetloopend(AFfilehandle file, long instid, long loopid)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), instid is the instrument ID for the instrument configuration chunk (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_INST), and loopid is the ID number associated with the loop whose ending point you wish to read.

AFgetloopend() returns a long integer value which is a marker ID in the audio track. See “Getting and Setting Audio Track Markers” in “Reading and Writing Audio Track Information” for information on how to manipulate the position of the markers referred to by the marker IDs.

AFsetloopend() causes an audio track marker ID to be associated with the ending point of a given instrument loop. Its function prototype is:

void AFsetloopend(AFfilehandle file, long instid,
                  long loopid, long markid)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), instid is the instrument ID for the instrument configuration chunk (for AIFF and AIFF-C files, this value should always be AF_DEFAULT_INST), loopid is the ID number associated with the loop whose ending point you wish to write, and markid is the audio track marker that you wish to assign as the ending point of the given loop.

---

Tip: Loop queries can return any configuration of loops within an instrument, not just the fixed value of 2 in AIFF/AIFF-C files. Have your application check for and reject loop configurations it does not support.

---

This section describes functions that get information about the number, size and type of miscellaneous data chunks in an opened audio file.

AFgetmiscids() returns the number of miscellaneous data chunks in a file and an array containing the IDs of each miscellaneous chunk. Its function prototype is:

long AFgetmiscids(AFfilehandle file, long miscids[])

file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(). miscids is an array of positive long integers that contains the IDs for the miscellaneous data chunks in file.

AFgetmiscids() returns a long integer value equal to the number of miscellaneous data chunks in file.

To fill the miscids array with the corresponding IDs, you first call AFgetmiscids() with a null miscids pointer, and then allocate a miscids buffer according to the return value. You can then call AFgetmiscids() again, passing the properly dimensioned miscids buffer to obtain the list of IDs.

AFgetmisctype() returns the type of a given miscellaneous chunk. Its function prototype is:

long AFgetmisctype(AFfilehandle file, long chunkid)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), and chunkid is a positive long integer miscellaneous chunk ID from the miscids array returned by AFgetmiscids().

AFgetmisctype() returns a long integer constant that describes the chunk type. See Table 7-5 for the list of valid chunk types and constants. If the chunk is not of any of the types listed in Table 7-5, AFgetmisctype() will return the value AF_MISC_AIFF_UNRECOGNIZED.

---

Tip: The set of chunk types may expand at any time. Check for unrecognized chunk types rather than recognized chunk types. Write your application so that it expects any type of MISC chunk (not just the currently defined types) and rejects miscellaneous chunks it does not recognize.

---

AFgetmiscsize() returns the size of a given miscellaneous data chunk in bytes. Its function prototype is:

long AFgetmiscsize(AFfilehandle file, long chunkid)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), and chunkid is a positive long integer miscellaneous chunk ID from the miscids array returned by AFgetmiscids().

AFgetmiscsize() returns a long integer value that describes the size of the data in the chunk in bytes. This number does not take into account null-terminators in strings, so you will need to add one to the value returned when actually reading string data (see AFreadmisc()).

This section describes functions that read and write miscellaneous data and to position the read/write location pointer within the data portion of a miscellaneous chunk. The AFfilehandle structure maintains a logical read/write pointer for each miscellaneous data chunk in the file. Each pointer is initialized to point at the first data byte with the chunk when the AFfilehandle structure is created.

---

Tip: To avoid file corruption, don't copy MISC chunks from one file to another unless the content of those chunks is known. A chunk can contain references to other parts of the file that have been modified by the application, in which case attempting to copy it without properly modifying its contents would cause an error.

---

AFreadmisc() reads data from a given miscellaneous chunk into a buffer, and returns the number of bytes read. Its function prototype is:

long AFreadmisc(AFfilehandle file, long chunkid,
                void *buf, long nbytes)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), chunkid is a positive long integer miscellaneous chunk ID from the miscids array returned by AFgetmiscids(), buf is a pointer to a buffer that will receive the data from the miscellaneous chunk, and nbytes is the number of bytes you want to read from the audio file into buf, beginning at the current position of file's logical read pointer for the data in miscid. AFreadmisc() will not read past the end of the chunk's data area. After reading the data, AFreadmisc() updates the position of the read/write pointer to point to the data byte following the last one read.

AFwritemisc() writes data from a buffer to a given miscellaneous chunk, and returns the number of bytes successfully written. Its function prototype is:

long AFwritemisc(AFfilehandle file, long chunkid,
                 void *buf, long nbytes)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), chunkid is a positive long integer miscellaneous chunk ID from the miscids array returned by AFgetmiscids(), buf is a pointer to a buffer that contains the data you want to write to the miscellaneous chunk, and nbytes is the number of bytes you want to write to the audio file from buf, beginning at the current position of file's logical write pointer for the data in miscid. AFwritemisc() will not write past the end of the chunk's data area. After writing the data, AFreadmisc() updates the position of the read/write pointer to point to the data byte following the last one written.

It is up to the application to fill the data area of a chunk with consistent information (for example, if you don't use all the bytes you allocated in a MIDI data chunk, you need to fill the remaining bytes with no-ops).

AFseekmisc() moves the logical read/write pointer for a miscellaneous chunk to a specified offset from the beginning of the chunk's data area. Its function prototype is:

void AFseekmisc(AFfilehandle file, long chunkid, long offset)

where file is the AFfilehandle structure previously created by a call to AFopenfile() or AFopenfd(), chunkid is a positive long integer miscellaneous chunk ID from the miscids array returned by AFgetmiscids(), offset is a non-negative long integer specifying the number of bytes past the start of the data area the read/write pointer should be moved, and offset should always be less than the size of the total data area (in bytes).

AFseekmisc() returns the new location of the logical read/write pointer, measured as the number of bytes from the beginning of the chunk data area.