dmACSetParams(3dm)dmACSetParams(3dm)NAME
dmACSetParams, dmACGetParams - set/get the Audio Converter parameter
values
SYNOPSIS
#include <dmedia/dm_audioconvert.h>
#include <dmedia/dm_audioutil.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 DM_SUCCESS if the operation succeeds. If DM_FAILURE 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 DM_AUDIO_COMPRESSION, which
defaults to DM_AUDIO_UNCOMPRESSED, and the DM_AUDIO_PCM_MAP 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
DM_AUDIO_FORMAT Must be one of:
DM_AUDIO_TWOS_COMPLEMENT
DM_AUDIO_UNSIGNED
DM_AUDIO_FLOAT
DM_AUDIO_DOUBLE
DM_AUDIO_WIDTH Must be an integer between 1 and 32. It is ignored
if DM_AUDIO_FORMAT is not set to one of the first
two values.
DM_AUDIO_BYTE_ORDER Must be one of:
DM_AUDIO_BIG_ENDIAN
DM_AUDIO_LITTLE_ENDIAN
DM_AUDIO_CHANNELS Must be an integer greater than 0.
DM_AUDIO_RATE Must be a double-precision floating point (type
DM_TYPE_FLOAT) greater than 0.0.
DM_AUDIO_COMPRESSION The following parameter values are currently
supported:
DM_AUDIO_UNCOMPRESSED
DM_AUDIO_G711_ULAW
DM_AUDIO_G711_ALAW
DM_AUDIO_MPEG1
DM_AUDIO_MULTIRATE
DM_AUDIO_G722
DM_AUDIO_G726
DM_AUDIO_G728
DM_AUDIO_DVI
DM_AUDIO_FS1016
DM_AUDIO_GSM
DM_AUDIO_DV
All compression-specific parameters such as DM_AUDIO_BITRATE 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:
DM_AUDIO_PCM_MAP_SLOPE
DM_AUDIO_PCM_MAP_INTERCEPT
DM_AUDIO_PCM_MAP_MAXCLIP
DM_AUDIO_PCM_MAP_MINCLIP
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:
DM_AUDIO_DITHER_ALGORITHM
DM_AUDIO_DITHER_NONE (default)
DM_AUDIO_DITHER_LSB_TPDF (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:
DM_AUDIO_RC_ALGORITHM
DM_AUDIO_RC_JITTER_FREE (default)
DM_AUDIO_RC_POLYNOMIAL_ORDER_1
DM_AUDIO_RC_POLYNOMIAL_ORDER_3
DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION
DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION_78_DB (default)
DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION_96_DB
DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION_120_DB
Page 3
dmACSetParams(3dm)dmACSetParams(3dm)
DM_AUDIO_RC_JITTER_FREE_TRANSITION_BANDWIDTH
DM_AUDIO_RC_JITTER_FREE_TRANSITION_BANDWIDTH_1_PERCENT
DM_AUDIO_RC_JITTER_FREE_TRANSITION_BANDWIDTH_10_PERCENT
DM_AUDIO_RC_JITTER_FREE_TRANSITION_BANDWIDTH_20_PERCENT
Channel Conversion Parameters (Channel Matrix)
Allows specification of input to output channel routing via a matrix of
values.
DM_AUDIO_CHANNEL_MATRIX
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.
DM_AUDIO_PROCESS_MODE
This is queried to determine which mode the converter will run in for the
given set of parameters:
DM_AUDIO_PROCESS_PUSH Converter will be processing a fixed number of
input frames, producing a (possibly) variable
amount of output.
DM_AUDIO_PROCESS_PULL 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:
DM_AUDIO_MAX_REQUEST_LEN An integer value > 0. This is a set-only
value.
DM_AUDIO_MIN_INPUT_LEN 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)
DM_AUDIO_MIN_OUTPUT_LEN 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 ALSOdmACCreate(3dm), dmACConvert(3dm), dmACReset(3dm), dmACDestroy(3dm),
dmACGetMinOutputSize(3dm), dmACGetMinInputSize(3dm)
Page 5
