afSetConversionParams(3dm)afSetConversionParams(3dm)NAME
afSetConversionParams, afGetConversionParams - set/get the parameters
associated with format conversion for a specified audio track via
dmParams
SYNOPSIS
#include <dmedia/dm_audio.h>
#include <dmedia/audiofile.h>
DMstatus afSetConversionParams(AFfilehandle file, int track,
DMparams *params)
DMstatus afGetConversionParams(AFfilehandle file, int track,
DMparams *params)
PARAMETER
file is an AFfilehandle structure, previously created by a call to
afOpenFile(3dm) or its equivalent.
track is an integer which identifies an audio track in file.
Since all currently supported file formats contain only one
audio track, the value AF_DEFAULT_TRACK should be used here for
now.
params a DMparams list, previously created by a call to
dmParamsCreate(3dm).
RETURN VALUEafSetConversionParams() and afGetConversionParams() return DM_SUCCESS on
success, otherwise they return DM_FAILURE.
DESCRIPTION
When some type of format conversion takes place during afReadFrames() or
afWriteFrames() due to a difference between the track and the virtual
format, the precise mechanism for this conversion may be controlled via a
set of parameters.
afSetConversionParams() sets all parameters associated with the
conversion of audio data to or from an audio track from or to an audio
buffer.
afGetConversionParams() allows an application to retrieve the complete
set of conversion parameters currently contained within an AFfilehandle
structure for a given audio track.
The following parameters are defined in dmedia/dm_audio.h and may be set
or retrieved via params:
DM_AUDIO_RC_ALGORITHM
The converson algorithm to be used if rate conversion is being
performed. Its possible values are:
Page 1
afSetConversionParams(3dm)afSetConversionParams(3dm)
DM_AUDIO_RC_JITTER_FREE Jitter-Free is the highest quality rate
conversion available, and is the default for
all sampling rate ratios which it can support.
This includes all standard rate conversions
(i.e., 44.1k to 8k, 48k to 22.05k, etc.).
DM_AUDIO_RC_POLYNOMIAL_ORDER_3
A third-order polynomial interpolating
algorithm. It is the default for all sampling
rate ratios not covered by Jitter-Free.
DM_AUDIO_RC_POLYNOMIAL_ORDER_1
A simple linear-interpolating algorithm. This
is the least CPU-intensive, but also generated
the most distortion.
DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION
The parameter is specific to the jitter free rate converter
algorithm. The values correspond to the minimum attenuation
level of the out-of-band frequencies, those frequencies which do
not fit in the smaller of the output or input bandwidths. Higher
values correspond to better noise suppression. Supported values
are:
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
DM_AUDIO_RC_JITTER_FREE_TRANSITION_BANDWIDTH
This parameter is specific to the jitter free rate converter
algorithm. The values correspond to the percent of the high
frequency response of the output signal lost in the conversion
process. Lower percentages correspond to better high frequency
response. Supported values are:
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 (default)
DM_AUDIO_DITHER_ALGORITHM
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 inherant in such conversions. This
parameter is ignored if such a conversion is not happening.
Supported values are:
DM_AUDIO_DITHER_NONE (default)
DM_AUDIO_DITHER_LSB_TPDF (LSB TPDF dither)
Page 2
afSetConversionParams(3dm)afSetConversionParams(3dm)
DM_AUDIO_CHANNEL_MATRIX
Allows specification of input to output channel routing via a
matrix of values.
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.
SEE ALSOafWriteFrames(3dm), afInitFormatParams(3dm),
afSetVirtualFormatParams(3dm), dmACSetParams(3dm)
Page 3
