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; 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 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. 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 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. 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 ALSO dmACCreate(3dm), dmACConvert(3dm), dmACReset(3dm), dmACDestroy(3dm), dmACGetMinOutputSize(3dm), dmACGetMinInputSize(3dm) Page 5