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 AFDEFAULTTRACK 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:
Page 1
afGetCompression(3dm) afGetCompression(3dm)
AFCOMPRESSIONNONE no compression
AFCOMPRESSIONG711ULAW 64kbps CCITT G.711 ulaw encoding, 8 kHz
16-bit
AFCOMPRESSIONG711ALAW 64 kbps CCITT G.711 alaw encoding, 8kHz
16-bit
AFCOMPRESSIONG722 64 kbps CCITT G.722 ADPCM, 16 kHz 16-bit
AFCOMPRESSIONG726 16, 24, 32, or 40 kbps CCITT G.726
ADPCM, 8 kHz 16-bit
AFCOMPRESSIONG728 16 kbps CCITT G.728 ADPCM, 8 kHz 16-bit
AFCOMPRESSIONGSM 13 kbps European GSM 06.10 encoding, 8
kHz 16-bit
AFCOMPRESSIONDVIAUDIO 32 kbps DVI ADPCM, 8 kHz 16-bit
AFCOMPRESSIONFS1016 48, 72, or 96 kbps US Federal Standard
1016 CELP, 8 kHz, 16-bit
AFCOMPRESSIONMPEG1 ISO/MPEG-1 Layers I and II.
AFCOMPRESSIONAWAREMULTIRATE Aware, Inc's MultiRate I near-lossless
or lossless algorithm.
AFCOMPRESSIONAPPLEACE3 not supported on SGI systems
AFCOMPRESSIONAPPLEACE8 not supported on SGI systems
AFCOMPRESSIONAPPLEMAC3 not supported on SGI systems
AFCOMPRESSIONAPPLEMAC6 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
AUPVTYPELONG unless otherwise noted:
AFMPEGPARAMLAYER
indicates MPEG layer:
AFMPEGLAYERI
Page 2
afGetCompression(3dm) afGetCompression(3dm)
AFMPEGLAYERII (default)
AFMPEGPARAMCHANNELPOLICY / AFAWAREPARAMCHANNELPOLICY
indicates how multiple channels are treated:
AFMPEGSTEREO / AFAWARESTEREO
indicates that the channels are part of a single multi-channel
signal. This includes 4-channel, etc.;
AFMPEGJOINTSTEREO (default)
indicates that the algorithm may have attempted to exploit
redundancy between channels for greater coding gain; Not valid
for MultiRate.
AFMPEGINDEPENDENT / AFAWAREINDEPENDENT
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.
AFMPEGPARAMBITRATETARGET (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.
AFMPEGPARAMBITRATEPOLICY / AFAWAREPARAMBITRATEPOLICY
The mode of bit assignment: The valid values depend on the
algorithm, as indicated below.
AFMPEGPARAMBITRATEPOLICY (SGI MPEG):
AFMPEGFIXEDRATE (default)
Fixed bitrate per second.
The Compression ratio is determined by value of
AFMPEGPARAMBITRATETARGET.
Page 3
afGetCompression(3dm) afGetCompression(3dm)
AFMPEGCONSTQUAL
Bitrate is driven by the psychoacoustic model. Enough
bits are assigned so that a constant Mask to Noise ratio
is attained. See AFMPEGPARAMCONSTQUALNMR.
AFAWAREPARAMBITRATEPOLICY (Aware MultiRate):
AFAWARECONSTQUAL
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.
AFAWARELOSSLESS
Enough bits are assigned to provide for perfect
reconstruction.
Compression ratios are typically between 2:1 and 3:1.
AFMPEGPARAMCONSTQUALNMR (not for Aware MultiRate)
For SGI MPEG with AFAWARECONSTQUAL, 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 AUPVTYPEDOUBLE.
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 AFSAMPFMTTWOSCOMP, 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 AFCOMPRESSIONG711ULAW, then the
programmer can assume that the native format for that codec is
Page 4
afGetCompression(3dm) afGetCompression(3dm)
AFSAMPFMTTWOSCOMP, 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