Miles Sound System SDK 7.2a

AIL_set_named_sample_file

The function AIL_set_named_sample_file initializes a sample's address, length, type, and flags to prepare for playback of a memory-resident sound data.

S32 AIL_set_named_sample_file(
  HSAMPLE S,
  char const * filename_ext,
  void const * file_image,
  U32 file_size,
  S32 block
);

In Parameters

S: indicates the sample to prepare for file playback.
filename_ext: is a filename whose extension determines what ASI decoder to use. For example, to use the MPEG Layer 3 decoder, you would specify ".mp3" (or any string with ".mp3" in it). Future decoders will have their own extensions.
file_image: points to the start of the file image in memory.
file_size: specifies the size of the file image.
block: specifies a block number to play in the file. block is ignored with formats for which MSS does not support multiple blocks, such as the .WAV format. Use 0 as a default value for most applications.

Returns

0 if the file could not be parsed or if the desired block was not found; otherwise, a non-zero return value indicates the sample handle was successfully prepared for file playback.

Discussion

This function can parse a VOC file, uncompressed .WAV file, IMA ADPCM compressed .WAV file, MPEG Layer 3 file, mono or stereo Ogg Vorbis file, or any other supported ASI-compressed file (or Xbox ADPCM on the original Xbox).

This function is very similar to AIL_set_sample_file, except that it requires a filename extension to figure out what decoder to use. It can work with .MP3 files directly without a .WAV wrapper.

It is not necessary to call AIL_init_sample, AIL_set_sample_playback_rate, or AIL_set_sample_address when using this function. The HSAMPLE is initialized automatically by the system, just as if AIL_init_sample had been called explicitly.

Failure of this function, especially when working with MP3 files, usually means that the AIL_set_redist_directory function has not been called prior to AIL_startup, or that your MSS distribution does not include the MP3 decoder module.

Group: Digital Audio Services
Related Functions: AIL_allocate_sample_handle, AIL_init_sample, AIL_set_redist_directory, AIL_set_sample_3D_position, AIL_set_sample_address, AIL_set_sample_file, AIL_set_sample_info, AIL_set_sample_playback_rate, AIL_start_sample, AIL_startup
Related Basic Types: HSAMPLE, S32, U32, char const *, void const *
Related FAQs: How can I play two HSAMPLEs from the same memory address?, How do I play a digital sound?, How do I set a DSP filter on a sample?, How do I use multi-channel sound output in Miles?, I can't get Miles to play an MP3, XMA, or Ogg Vorbis file - what's going on?, What is MPEG Audio and MP3?, What's the best way to port my older Miles application to MSS 7?, When can I free the memory I gave to MSS?