afGetCompression(3dm) afGetCompression(3dm)
afGetCompression, afGetCompressionParams - get the compression type and
parameters for an audio track from an AFfilehandle structure
#include <dmedia/audiofile.h>
int afGetCompression(AFfilehandle file, int trackid)
int afGetCompressionParams(AFfilehandle file, int trackid,
int *compression, AUpvlist pvlist, int numitems)
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.
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.
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)
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 [Toc] [Back]
indicates MPEG layer:
AF_MPEG_LAYER_I
Page 2
afGetCompression(3dm) afGetCompression(3dm)
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.
Page 3
afGetCompression(3dm) afGetCompression(3dm)
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.
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).
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
Page 4
afGetCompression(3dm) afGetCompression(3dm)
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.
afOpenFile(3dm), afReadFrames(3dm), afInitCompression(3dm),
afInitCompressionParams(3dm), aware(5), AUpvnew(3dm)
afGetCompression(3dm) afGetCompression(3dm)
afGetCompression, afGetCompressionParams - get the compression type and
parameters for an audio track from an AFfilehandle structure
#include <dmedia/audiofile.h>
int afGetCompression(AFfilehandle file, int trackid)
int afGetCompressionParams(AFfilehandle file, int trackid,
int *compression, AUpvlist pvlist, int numitems)
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.
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.
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)
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 [Toc] [Back]
indicates MPEG layer:
AF_MPEG_LAYER_I
Page 2
afGetCompression(3dm) afGetCompression(3dm)
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.
Page 3
afGetCompression(3dm) afGetCompression(3dm)
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.
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).
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
Page 4
afGetCompression(3dm) afGetCompression(3dm)
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.
afOpenFile(3dm), afReadFrames(3dm), afInitCompression(3dm),
afInitCompressionParams(3dm), aware(5), AUpvnew(3dm)
PPPPaaaaggggeeee 5555 [ Back ]
|
