Miles Sound System SDK 7.2a

AIL_set_sample_playback_rate

The function AIL_set_sample_playback_rate sets a sample's playback rate in hertz.

void AIL_set_sample_playback_rate(
  HSAMPLE S,
  S32 playback_rate
);

In Parameters

S: indicates the sample whose playback rate is to be set.
playback_rate: specifies the number of samples per second at which to play the sample data.

Discussion

An individual audio data sample may be played by the application at any desired rate, which imply that a number of sample points are skipped or repeated during playback, respectively. Undersampling is used when the playback rate is greater than the recorded rate, and results in a "fast-forward" effect because a number of sample points must be skipped to achieve the higher playback rate. Conversely, oversampling occurs when the playback rate is lower than the recorded rate. In this case, some sample bytes or words must be played more than once before moving on to the next sample point, causing a "dragging" or slowdown effect.

Internally, MSS uses oversampling and undersampling to resolve differences between application data rates and hardware rates. Distortion due to oversampling, in particular, may result when low-frequency data is played at high hardware data rates. Abrupt transitions between repeated sample point values can introduce unwanted high-frequency components which are not effectively attenuated by the hardware's antialiasing filters. On the other hand, the same antialiasing filters may clip treble frequencies from the sample data if the hardware's rate is significantly lower than the application's data rate.

For the reasons mentioned above, the best audio quality will always be achieved when the driver's hardware data rate is matched as closely as possible to the application's sample data rate. If most of an application's sample data was recorded at a rate of 11025 Hz, for example, it would be a good idea to use 11025 Hz in the call to AIL_open_digital_driver. This will ensure that most of the samples are played without introducing distortion or attenuating treble frequencies. Any samples played at frequencies other than 11025 Hz will be undersampled or oversampled to conform to the hardware rate of 11025 Hz established by the AIL_set_preference call. If the hardware or driver in use does not support a 11025 Hz rate, the closest supported hardware rate will be selected, and the application's data will be resampled accordingly.

It is not necessary to call this function if AIL_set_named_sample_file, AIL_set_sample_file, or AIL_set_sample_info is used to play memory-resident .VOC or .WAV files directly.

Example files that use this function: SSTEST.C

Group: Digital Audio Services
Related Functions: AIL_calculate_3D_channel_levels, AIL_open_digital_driver, AIL_sample_buffer_available, AIL_sample_playback_rate, AIL_set_named_sample_file, AIL_set_preference, AIL_set_sample_address, AIL_set_sample_file, AIL_set_sample_info
Related Basic Types: HSAMPLE, MILES_PREFERENCES, S32, void