afGetCompression(3dm) afGetCompression(3dm) NAME afGetCompression, afGetCompressionParams - get the compression type and parameters for an audio track from an AFfilehandle structure SYNOPSIS #include <dmedia/audiofile.h> int afGetCompression(AFfilehandle file, int trackid) int afGetCompressionParams(AFfilehandle file, int trackid, int *compression, AUpvlist pvlist, int numitems) PARAMETER file expects an AFfilehandle structure, previously created by a call to afOpenFile(3dm). trackid is an integer which identifies an audio track in the 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. compression is a pointer to an integer which will be filled in with the symbolic constant indicating which compression scheme used for the specified audio track. pvlist is an AUpvlist structure previously created via a call to AUpvnew(3dm), initialized with parameters and parameter types using AUpvsetparam(3dm) and AUpvsetvaltype(3dm). It will be filled with parameter values related to the compression scheme of the specified audio track. numitems is the number of valid entries in the pvlist. RETURN VALUE afGetCompression() returns a positive symbolic integer constant which describes the type of audio compression used for the specified audio track, or -1 on failure. afGetCompressionParams() returns the same symbolic integer in compression. Additionally, the codec-specific parameters of pvlist are scanned up to numitems and the values are filled in. DESCRIPTION Both afGetCompression() and afGetCompressionParams() are obsolete, having been replaced by afGetFormatParams(3dm), which uses the newer DMparams(3dm) parameter lists. These older routines remain for backwards compatibility. afGetCompression() returns the type of audio compression used for an audio track. Valid compression identifiers include: AF_COMPRESSION_NONE no compression AF_COMPRESSION_G711_ULAW 64kbps CCITT G.711 ulaw encoding, 8 kHz 16-bit AF_COMPRESSION_G711_ALAW 64 kbps CCITT G.711 alaw encoding, 8kHz 16-bit AF_COMPRESSION_G722 64 kbps CCITT G.722 ADPCM, 16 kHz 16-bit AF_COMPRESSION_G726 16, 24, 32, or 40 kbps CCITT G.726 ADPCM, 8 kHz 16-bit AF_COMPRESSION_G728 16 kbps CCITT G.728 ADPCM, 8 kHz 16-bit AF_COMPRESSION_GSM 13 kbps European GSM 06.10 encoding, 8 kHz 16-bit AF_COMPRESSION_DVI_AUDIO 32 kbps DVI ADPCM, 8 kHz 16-bit AF_COMPRESSION_FS1016 48, 72, or 96 kbps US Federal Standard 1016 CELP, 8 kHz, 16-bit AF_COMPRESSION_MPEG1 ISO/MPEG-1 Layers I and II. AF_COMPRESSION_AWARE_MULTIRATE Aware, Inc's MultiRate I near-lossless or lossless algorithm. AF_COMPRESSION_APPLE_ACE3 not supported on SGI systems AF_COMPRESSION_APPLE_ACE8 not supported on SGI systems AF_COMPRESSION_APPLE_MAC3 not supported on SGI systems AF_COMPRESSION_APPLE_MAC6 not supported on SGI systems The four Apple compression algorithms listed above are Apple-proprietary, and are not supported by the SGI Audio File Library. afGetCompressionParams() returns, via the pvlist argument, a list of compression parameters and their values associated with the current compression scheme. The parameters will be a subset of the following. Parameter type is AU_PVTYPE_LONG unless otherwise noted: AF_MPEG_PARAM_LAYER indicates MPEG layer: AF_MPEG_LAYER_I AF_MPEG_LAYER_II (default) AF_MPEG_PARAM_CHANNEL_POLICY / AF_AWARE_PARAM_CHANNEL_POLICY indicates how multiple channels are treated: AF_MPEG_STEREO / AF_AWARE_STEREO indicates that the channels are part of a single multi-channel signal. This includes 4-channel, etc.; AF_MPEG_JOINT_STEREO (default) indicates that the algorithm may have attempted to exploit redundancy between channels for greater coding gain; Not valid for MultiRate. AF_MPEG_INDEPENDENT / AF_AWARE_INDEPENDENT indicates that the separate channels are unrelated and were processed separately, such as multi-lingual sound tracks. Note that all of these settings only have meaning for a multi channel signal. AF_MPEG_PARAM_BITRATE_TARGET (not for Aware MultiRate) indicates the bitrate for all channels of compressed data, in bits per second. Note that for some schemes such as MPEG's maxrate (not implemented) this is treated as an upper limit, whereas for MPEG's fixrate, this is strictly achieved as a constant rate. The following is a list of valid bitrates for MPEG. Layer 1: 32000, 64000, 96000, 128000, 160000, 192000, 224000, 256000, 288000, 320000, 352000, 384000, 416000, and 448000. Layer 2: 32000, 48000, 56000, 64000, 80000, 96000, 112000, 128000, 160000, 192000, 224000, 256000, 320000, and 384000. Default value is 192 kbps / channel for layer 1 and 128 kbps / channel for layer 2. AF_MPEG_PARAM_BITRATE_POLICY / AF_AWARE_PARAM_BITRATE_POLICY The mode of bit assignment: The valid values depend on the algorithm, as indicated below. AF_MPEG_PARAM_BITRATE_POLICY (SGI MPEG): AF_MPEG_FIXED_RATE (default) Fixed bitrate per second. The Compression ratio is determined by value of AF_MPEG_PARAM_BITRATE_TARGET. AF_MPEG_CONST_QUAL Bitrate is driven by the psychoacoustic model. Enough bits are assigned so that a constant Mask to Noise ratio is attained. See AF_MPEG_PARAM_CONST_QUAL_NMR. AF_AWARE_PARAM_BITRATE_POLICY (Aware MultiRate): AF_AWARE_CONST_QUAL Enough bits are assigned so that the signal is 90+ dB above the quantization noise. Compression ratios are typically between 2.5:1 and 4:1. AF_AWARE_LOSSLESS Enough bits are assigned to provide for perfect reconstruction. Compression ratios are typically between 2:1 and 3:1. AF_MPEG_PARAM_CONST_QUAL_NMR (not for Aware MultiRate) For SGI MPEG with AF_AWARE_CONST_QUAL, indicates the constant quality mode noise-to-mask ratio in dB. Zero indicates a theoretic psychoacoustic imperceptible compression. Positive values indicate more compression and audible noise. Negative values indicate less compression and less perceptible noise. The type of value of this parameter is AU_PVTYPE_DOUBLE. IMPORTANT NOTE Because this routine has been obsoleted, it only returns compression parameters associated with MPEG1 and Aware, Inc. MultiRate compression schemes. All other compression schemes' parameters must be retrieved via afGetCompressionParams(3dm). CAVEATS In future releases, new compression methods will be supported, so the same warnings that apply to afGetSampleFormat(3dm) (see the CAVEATS section of afGetSampleFormat(3dm) for these important notes) apply here. Because the library transparently decompresses input data and compresses output data regardless of the form of compression in the file, this may not seem like an issue. All currently defined codecs convert the compressed data to and from AF_SAMPFMT_TWOSCOMP, 16-bit data. However, this is by no means guaranteed for future compression types. So when reading or writing a file (even an AIFF-C file) containing compressed data, a program must call afGetSampleFormat(3dm) to get the "native" sample format of the codec, and check that the program is able to read/write using this sample format. The "native" sample format of a codec is defined as the sample format of the data produced on decompression or expected for compression. All currently-released codecs in the Audio File Library will not change their native sample format, if the documentation currently specifies what that codec's native sample format is. So, for example, if a programmer knows that the file format is AF_COMPRESSION_G711_ULAW, then the programmer can assume that the native format for that codec is AF_SAMPFMT_TWOSCOMP, 16 because this was stated in the documentation. This is done to provide backwards compatibility. However, it is not guaranteed that all future supported codecs will generate 16-bit signed integer data natively, nor is it guaranteed that all future codecs will have a single native sample format (some may be configurable or may vary depending on what kind of data was originally compressed). In every case though, the programmer can call afGetSampleFormat(3dm) to retrieve the sample format for the current codec on the file corresponding to the given AFfilehandle. There is a means by which an application can request the transparent conversion of whatever the native sample format of the codec is to the user's desired sample format. See afSetVirtualSampleFormat(3dm) for a detailed explanation. The library offers a runtime query of all of the supported compression methods, their textual names, their compression ratios (if available), and any other info that may be useful in making a runtime choice of codec. SEE ALSO afOpenFile(3dm), afReadFrames(3dm), afInitCompression(3dm), afInitCompressionParams(3dm), aware(5), AUpvnew(3dm) Page 5