dmACSetParams(3dm) dmACSetParams(3dm)
NAME
dmACSetParams, dmACGetParams - set/get the Audio Converter parameter
values
SYNOPSIS
#include <dmedia/dmaudioconvert.h>
#include <dmedia/dmaudioutil.h>
DMstatus dmACSetParams(
DMaudioconverter converter,
DMparams *sourceparams,
DMparams *destparams,
DMparams *conversionparams)
DMstatus dmACGetParams(
DMaudioconverter converter,
DMparams *sourceparams,
DMparams *destparams,
DMparams *conversionparams)
PARAMETERS
converter is a DMaudioconverter handle created by a previous
call to the creation method dmACCreate(3dm).
sourceparams is a DMparams list describing the audio format of the
data to be converted.
destparams is a DMparams list describing the audio format into
which the data is to be converted. Any parameter not
specified will default to the input value, with some
exceptions (see below).
conversionparams is an optional DMparams list describing specific
parameters relating to the conversion process itself.
RETURNED VALUE
Returns DMSUCCESS if the operation succeeds. If DMFAILURE is returned,
the error number and/or message can be retrieved via dmGetError(3dm).
DESCRIPTION
The handle passed to this routine is declared as follows:
typedef struct DMaudioconverter *DMaudioconverter;
dmACSetParams(3dm) configures an DMaudioconverter handle, created via a
call to dmACCreate(3dm). The configuration is done via three DMparams
lists, created by dmParamsCreate(3dm). The first param list specifies
the format of the audio data to be converted. There are no defaults for
the input format. The input specification must be complete or the call
will fail.
The second parameter list specifies the format into which the data is to
Page 1
dmACSetParams(3dm) dmACSetParams(3dm)
be converted. Any parameter not specified here will default to the value
present in the input parameter list, except DMAUDIOCOMPRESSION, which
defaults to DMAUDIOUNCOMPRESSED, and the DMAUDIOPCMMAP parameters,
which default to the appropriate values for the specified (or default)
audio format.
dmACGetParams(3dm) queries a previously-configured DMaudioconverter
handle for parameters relating to the audio conversion process.
AUDIO FORMAT PARAMETERS
DMAUDIOFORMAT Must be one of:
DMAUDIOTWOSCOMPLEMENT
DMAUDIOUNSIGNED
DMAUDIOFLOAT
DMAUDIODOUBLE
DMAUDIOWIDTH Must be an integer between 1 and 32. It is ignored
if DMAUDIOFORMAT is not set to one of the first
two values.
DMAUDIOBYTEORDER Must be one of:
DMAUDIOBIGENDIAN
DMAUDIOLITTLEENDIAN
DMAUDIOCHANNELS Must be an integer greater than 0.
DMAUDIORATE Must be a double-precision floating point (type
DMTYPEFLOAT) greater than 0.0.
DMAUDIOCOMPRESSION The following parameter values are currently
supported:
DMAUDIOUNCOMPRESSED
DMAUDIOG711ULAW
DMAUDIOG711ALAW
DMAUDIOMPEG1
DMAUDIOMULTIRATE
DMAUDIOG722
DMAUDIOG726
DMAUDIOG728
DMAUDIODVI
DMAUDIOFS1016
DMAUDIOGSM
DMAUDIODV
All compression-specific parameters such as DMAUDIOBITRATE are also
settable and queryable. See the man pages for the standalone compression
routines (such as dmG722EncoderSetParams(3dm)) for the details for each
codec.
Page 2
dmACSetParams(3dm) dmACSetParams(3dm)
PCM MAPPING PARAMETERS
An additional optional PCM mapping parameter set may be specified for the
output or (rarely) for the input in addition to the above. The following
must either all be specified or none should be specified:
DMAUDIOPCMMAPSLOPE
DMAUDIOPCMMAPINTERCEPT
DMAUDIOPCMMAPMAXCLIP
DMAUDIOPCMMAPMINCLIP
The default input and output values of these four are set automatically
by the configuration routine to match the specified input and output
sample formats. They should only be specified if you have special mapping
requirements, such as input data with a fixed offset (DC bias). See the
afIntro(3dm) manual page for a complete explanation of PCM Mapping.
CONVERSION PARAMETERS
Dithering Parameters
When performing conversions from larger into smaller data types (i.e.,
floating point to 16-bit integer or 16-bit integer to 8-bit integer), a
dithering algorithm may be applied to reduce the quantization error
distortion inherent in such conversions. This parameter is ignored if
such a conversion is not happening:
DMAUDIODITHERALGORITHM
DMAUDIODITHERNONE (default)
DMAUDIODITHERLSBTPDF (LSB TPDF dither)
Rate Conversion Parameters
These affect the rate conversion algorithm, and are only used when the
output sampling rate is not equal to the input rate:
DMAUDIORCALGORITHM
DMAUDIORCJITTERFREE (default)
DMAUDIORCPOLYNOMIALORDER1
DMAUDIORCPOLYNOMIALORDER3
DMAUDIORCJITTERFREESTOPBANDATTENUATION
DMAUDIORCJITTERFREESTOPBANDATTENUATION78DB (default)
DMAUDIORCJITTERFREESTOPBANDATTENUATION96DB
DMAUDIORCJITTERFREESTOPBANDATTENUATION120DB
Page 3
dmACSetParams(3dm) dmACSetParams(3dm)
DMAUDIORCJITTERFREETRANSITIONBANDWIDTH
DMAUDIORCJITTERFREETRANSITIONBANDWIDTH1PERCENT
DMAUDIORCJITTERFREETRANSITIONBANDWIDTH10PERCENT
DMAUDIORCJITTERFREETRANSITIONBANDWIDTH20PERCENT
Channel Conversion Parameters (Channel Matrix)
Allows specification of input to output channel routing via a matrix of
values.
DMAUDIOCHANNELMATRIX
This is a type DMfloatarray which must be set and retrieved via
dmParamsSetFloatArray(3dm) and dmParamsGetFloatArray(3dm), respectively.
The data itself is a one-dimensional array of double-precision floating
point numbers arranged as if it were an n x m matrix of values, where
rows == output_channels and columns == input_channels. See the
afSetChannelMatrix(3dm) manual page for a detailed explanation of this.
Converter Mode Parameters
These parameters describe the manner in which the converter handles the
input and output buffers.
DMAUDIOPROCESSMODE
This is queried to determine which mode the converter will run in for the
given set of parameters:
DMAUDIOPROCESSPUSH Converter will be processing a fixed number of
input frames, producing a (possibly) variable
amount of output.
DMAUDIOPROCESSPULL Converter will be producing a fixed number of
output frames, processing a (possibly) variable
amount of input.
Buffer Length Parameters
These are used to query the converter for the minimum allowable output
buffer length in frames for a given input buffer length:
DMAUDIOMAXREQUESTLEN An integer value > 0. This is a set-only
value.
DMAUDIOMININPUTLEN An integer value, query-only. This will be the
minimum allowable input buffer length in a
pull-mode operation.
Page 4
dmACSetParams(3dm) dmACSetParams(3dm)
DMAUDIOMINOUTPUTLEN An integer value, query-only. This will be the
minimum allowable output buffer length in a
push-mode operation.
These only need be set and queried if the audio data is being compressed,
decompressed, or rate-converted. In all other cases, the output buffer
length in frames will and must equal the input length. If an application
wishes to query this parameter before each call to dmACConvert, it may
use the two auxiliary functions dmACGetMinOutputSize(3dm) or
dmACGetMinInputSize(3dm) to retrieve this information. This eliminates
the overhead of parsing DMparams lists.
SEE ALSO
dmACCreate(3dm), dmACConvert(3dm), dmACReset(3dm), dmACDestroy(3dm),
dmACGetMinOutputSize(3dm), dmACGetMinInputSize(3dm)
Page 5