Miles Sound System SDK 7.2a

AIL_start_sample

The function AIL_start_sample starts playback of a sample from its beginning.

void AIL_start_sample(
  HSAMPLE S
);

In Parameters

S: indicates the sample to start playing.

Discussion

If a conventional single-buffered sample is already playing, it will be restarted from the beginning by this function. To begin playback at a specific position, set the position with AIL_set_sample_position and call AIL_resume_sample instead of AIL_start_sample.

At a minimum, the sample handle must be initialized with AIL_init_sample, AIL_set_sample_info, AIL_set_sample_file, or AIL_set_named_sample_file prior to starting playback. If you used AIL_init_sample to initialize a handle to a raw data sample, the sample's address and length should be specified with a call to AIL_set_sample_address. If any of the other sample-initialization functions were called, however, only AIL_start_sample needs to be called in order to begin playback.

After submitting low-level streaming data with AIL_load_sample_buffer, it's necessary to call AIL_start_sample at least once to initiate playback of the submitted buffers. There's no need to check the playback status first in this case -- AIL_start_sample has no effect when called on a low-level streamed sample that's already playing. (This behavior is new in MSS 7.)

Under Win32 and Win64 on waveOut, the MSS architecture permits a sound effect to be started with essentially zero latency as long as no other sound effects are currently being played. On the other hand, latency times incurred for samples which must be injected into an already-running mixer stream may be much higher than even the worst figures obtained in the DOS version of MSS. Consequently, it is important when beginning video playback or any other latency-critical activity to ensure that no previous digital audio effects have been played for at least a few hundred milliseconds prior to starting playback of the critical sound effect or stream.

On a Win32 or Win64 system with a native DirectSound driver installed, MSS will take advantage of the high-performance Microsoft DirectSound buffer mechanism to eliminate these latency problems.

On MacOS, Miles has been written so that digital latency will rarely (if ever) exceed 100 milliseconds and will never exceed 140 milliseconds regardless of the speed of your machine. Just like waveOut, though, Sound Manager imposes some amount of its own latency as well (exactly how much depends on the machine and version of Sound Manager).

Example files that use this function: SSTEST.C, DBTEST.C, DIGPLAY.C, EXAMMS.CPP

Group: Digital Audio Services
Related Functions: AIL_allocate_sample_handle, AIL_end_sample, AIL_get_DirectSound_info, AIL_init_sample, AIL_load_sample_buffer, AIL_register_EOS_callback, AIL_register_SOB_callback, AIL_resume_sample, AIL_sample_buffer_available, AIL_set_named_sample_file, AIL_set_sample_address, AIL_set_sample_file, AIL_set_sample_info, AIL_set_sample_position, AIL_start_sample, AIL_stop_sample
Related Basic Types: HSAMPLE, void
Related FAQs: How do I play a digital sound?, How do I start an audio file somewhere in the middle?, What's the best way to port my older Miles application to MSS 7?