afInitCompression(3dm) afInitCompression(3dm)
NAME
afInitCompression, afInitCompressionParams, afAware - configure the audio
compression type and parameters in an AFfilesetup structure for an audio
track
SYNOPSIS
#include <dmedia/audiofile.h>
void afInitCompression(AFfilesetup setup, int track, int compression)
void afInitCompressionParams(AFfilesetup setup, int track,
int compression, AUpvlist pvlist, int numitems)
PARAMETER
setup is an AFfilesetup structure, previously created by a call
to afNewFileSetup(3dm).
track is a positive integer which identifies an audio track in a
file configuration.
Since all currently supported file formats contain one
audio track per file, the constant value AFDEFAULTTRACK
should always be used here.
compression is a positive integer symbolic constant which indicates the
type of audio compression for the audio track.
pvlist is an AUpvlist structure, previously created by a call to
AUpvnew(3dm), initialized with parameters, parameter types,
and parameter values using AUpvsetparam(3dm),
AUpvsetvaltype(3dm), and AUpvsetval(3dm).
numitems is the number of valid entries in the pvlist as set via
AUpvnew(3dm).
DESCRIPTION
afInitCompression() and afInitCompressionParams() allows you to
configure audio tracks for compressed data. afInitCompression() allows a
one-parameter compression scheme to set up a default codec configuration
with a set of default compression parameters. afInitCompressionParams()
allows not only the choice of codec, but also for a list of codec
specific compression parameters to be set.
afInitCompressionParams() is now obsolete, having been replaced by
afInitFormatParams(3dm). It exists only for backwards compatibility.
The only compression schemes which have parameters handled via
afInitCompressionParams() are MPEG1 and the Aware, Inc. MultiRate. All
other compression schemes which have parameters must be handled via
DMparams(3dm) using afInitFormatParams(3dm).
Page 1
afInitCompression(3dm) afInitCompression(3dm)
Fifteen values for compression may currently be passed to
afInitCompression() or afInitCompressionParams()
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. Equivalent to
AFCOMPRESSIONDEFAULTMPEGII.
AFCOMPRESSIONAWAREMULTIRATE
Aware, Inc's MultiRate I near-lossless or
lossless algorithm. Equivalent to
AFCOMPRESSIONAWAREDEFAULTMULTIRATE.
AFCOMPRESSIONDEFAULTMPEGI
ISO/MPEG-1-audio layer I, joint-stereo, fixed
rate at 192 Kbps/channel
AFCOMPRESSIONDEFAULTMPEGII
ISO/MPEG-1-audio layer II, joint-stereo, fixed
rate at 128 Kbps/channel
AFCOMPRESSIONAWAREDEFAULTMULTIRATE
Aware, Inc. MultiRate I operating in near-
lossless mode.
AFCOMPRESSIONAWAREDEFAULTLOSSLESS
Aware, Inc. MultiRate I operating in lossless
mode.
For afInitCompressionParams(), the parameters and values passed in pvlist
should be taken from the following. Parameter type is AUPVTYPELONG
unless otherwise noted.
Page 2
afInitCompression(3dm) afInitCompression(3dm)
AFMPEGPARAMLAYER
selects which MPEG layer:
AFMPEGLAYERI
AFMPEGLAYERII (default)
AFMPEGPARAMCHANNELPOLICY / AFAWAREPARAMCHANNELPOLICY
chooses how multiple channels should be 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 attempt to exploit redundancy
between channels for greater coding gain; Not valid for
MultiRate.
AFMPEGINDEPENDENT / AFAWAREINDEPENDENT
indicates that the separate channels are unrelated and should
be processed separately, such as multi-lingual sound tracks.
Note that all of these settings are equivalent for single channel
input.
AFMPEGPARAMBITRATETARGET (not for Aware MultiRate)
specifies the desired 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
Provides for different modes of bit assignment: The valid values
depend on the algorithm, as indicated below.
AFMPEGPARAMBITRATEPOLICY (SGI MPEG):
Page 3
afInitCompression(3dm) afInitCompression(3dm)
AFMPEGFIXEDRATE (default)
Fixed bitrate per second.
The Compression ratio is determined by value of
AFMPEGPARAMBITRATETARGET.
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, sets the constant quality
mode noise-to-mask ratio in dB. Zero yields a theoretic
psychoacoustic imperceptible compression. Positive values provide
more compression and noise becomes audible. Negative values cause
less compression and less perceptible noise. The type of value of
this parameter is AUPVTYPEDOUBLE.
All compression encoding is handled automatically by afWriteFrames(3dm).
An application program only needs to work with linear PCM data.
AIFF files do not support compression, so the configuration parameter
compression will be ignored by afOpenFile(3dm), and the value
AFCOMPRESSIONNONE will automatically be associated with the audio data.
VALID INPUT AUDIO DATA FORMATS
Many compression schemes have restrictions on sampling rates and channel
counts:
Sampling rates for MPEG must be 32 kHz, 44.1 kHz, or 48 kHz.
Sampling rates for MultiRate must be 8 kHz, 11.025 kHz, 16 kHz, 22.05
kHz, 32 kHz, 44.1 kHz, or 48 kHz.
Both MPEG and MultiRate must have 1- or 2-channel input.
G728 and GSM compression must always be 8 kHz sampling rate.
Page 4
afInitCompression(3dm) afInitCompression(3dm)
G726, G728, and GSM compression must have 1-channel input.
CAVEATS
The Audio File Library will continue to support additional file formats
and compression types. Be aware of this. Not all file formats are able
to store audio data with all of the supported compression types. For
example, AIFF-C can store compressed data whereas AIFF can't. See
afGetCompression(3dm) for more information.
SEE ALSO
afNewFileSetup(3dm), afOpenFile(3dm), afWriteFrames(3dm),
afGetCompression(3dm), AwareIntro(3dm), afInitFormatParams(3dm)
Page 5