dmAudioRateConverterSetParams(3dm)          dmAudioRateConverterSetParams(3dm)



NAME
     dmAudioRateConverterSetParams - set rate converter parameter values


SYNOPSIS
     #include <dmedia/dmaudioutil.h>
     #include <dmedia/dmaudio.h>
     #include <dmedia/dmparams.h>

     DMstatus dmAudioRateConverterSetParams(DMaudiorateconverter handle,
                                   DMparams *params)


PARAMETER
     handle   DMaudiorateconverter structure, created by
              dmAudioRateConverterCreate(3dm).


     params   List of parameters for specification/query. Null (0) value ok.


RETURNED VALUE
     Returns DMSUCCESS or DMFAILURE.


DESCRIPTION
     dmAudioRateConverterSetParams(3dm) sets state of converter with params.
     Unrecognized parameters are ignored.


     The set of parameters for params are, defined in dmedia/dm_audioutil.h:


     DMAUDIORCINPUTRATE
     DMAUDIORCOUTPUTRATE

     Audio Util rate conversion input, output rate parameters (rate given in
     Hz).  The corresponding values for the rates are doubles.  The jitter-
     free algorithm supports sampling rate conversion between any two of the
     following rates in the set {8000, 11025, 16000, 22050, 32000, 44100,
     48000} (sample frames/second or Hertz).  Polynomial_order_{1,3}
     algorithms support arbitrary input and output rate.



     DMAUDIORCALGORITHM
          DM_AUDIO_RC_JITTER_FREE      DM_AUDIO_RC_POLYNOMIAL_ORDER_1
          DM_AUDIO_RC_POLYNOMIAL_ORDER_3







                                                                        Page 1

dmAudioRateConverterSetParams(3dm)          dmAudioRateConverterSetParams(3dm)



     Currently, the algorithms supported are jitter-free, which is at least
     one integer interpolator / integer decimator stage, polynomial-order-1,
     which is linear interpolation between 2 proximal samples, and
     polynomial-order-3, which is rate convert block by 3rd order polynomial
     interpolation between four proximal samples.


     DMAUDIORCJITTERFREESTOPBANDATTENUATION
          DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION_78_DB
          DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION_96_DB
          DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION_120_DB

     The parameter is specific to the jitter free rate converter filter
     stopband attenuation.  The values are limited to set {78, 96, 120}. 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.


     DMAUDIORCJITTERFREETRANSITIONBANDWIDTH
          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

     The parameter is specific to the jitter free rate converter filter
     transition bandwidth.  The values are limited to set {1, 10, 20}. The
     values correspond to the % of the high frequency response of the output
     signal lost in the conversion process.  Lower percentages correspond to
     better high frequency response.


     Parameters for query only:

     DMAUDIORCATOMICINLENGTH
     DMAUDIORCATOMICOUTLENGTH

     The rate convert algorithm processes blocks of a fixed length determined
     by the conversion process parameters.  The input and output lengths must
     be a multiple of DMAUDIORCATOMICINLENGTH and
     DMAUDIORCATOMICOUTLENGTH, respectively.  Query these parameters on a
     configured converter can also be done by using
     dmAudioRateConverterGetParams(3dm).


     DMAUDIORCGROUPDELAY Type DM_TYPE_FLOAT

     The group delay measured in output samples.

     These sampling rate conversion algorithms use filter operations that
     convolve a N past input samples with a filter M-coefficient array to
     create N+M-1 output samples.  Note that he filtered signal contains more



                                                                        Page 2

dmAudioRateConverterSetParams(3dm)          dmAudioRateConverterSetParams(3dm)



     samples than the unfiltered signal.

     We use linear phase filters with a constant group delay G = (M-1)/2
     samples.  In real time operation, convolution simply delays the output by
     G samples.  In file conversion expecting N samples in and out, the output
     signal is offset by G samples from the first sample thus omits the last G
     samples from the output file.  Multiple conversions compound the delays
     and data loss.

     SGI audio applications manage the above problems by omitting the first G
     samples while computing more than N+G samples.  In practice, G is rounded
     to the nearest sample and thus sample time alignment is occasionally
     ahead or behind one sample.  G specifies the number of output samples to
     omit.

     Query DMAUDIORCGROUPDELAY on a configured converter can also be done
     by using dmAudioRateConverterGetParams(3dm).


NOTE
     dmAudioRateConverterSetParams(3dm) calls dmAudioRateConverterReset(3dm)
     internally.

     Files converted using jitter-free algorithm with decibels set to 96 and
     bandwidth set to 10 will sound most excellent.  For the highest quality
     conversion algorithm, however, you can set decibels to 120 and bandwidth
     to 1.  By decreasing decibels and increasing bandwidth, you increase the
     speed of the rate conversion at a loss of high frequency response.

     The following table shows the relationships between the bandwidth
     parameter, and the pass band ripple:

     bandwidth    % final     passband
     parameter    bandwidth   ripple
                  tapered

     20           20%         +/- 0.05   dB
     10           10%         +/- 0.05   dB
      1           1%          +/- 0.0005 dB


SEE ALSO
     dmAudioRateConverterCreate(3dm), dmAudioRateConvert(3dm),
     dmAudioRateConverterGetParams(3dm).











                                                                        Page 3