Miles Sound System SDK 7.2a

AIL_open_stream

The function AIL_open_stream opens a stream handle based on a supported file (.WAV, Ogg Vorbis, XMA, or MP3, and others).

HSTREAM AIL_open_stream(
  HDIGDRIVER dig,
  char const * name,
  S32 stream_mem
);

In Parameters

dig: specifies the digital driver handle to use.
name: specifies the name of the file to stream. The streaming API supports .WAV, Ogg Vorbis, XMA, and MP3 files, among other possible formats.
stream_mem: specifies the amount of memory to use for streaming. Normally, you will pass a zero for this parameter which tells MSS to determine the optimal amount of memory to use. You may want to increase this parameter if you plan on increasing the playback rate.

Returns

A handle to the new stream, or NULL if the open failed.

Discussion

Currently-supported file types include uncompressed .WAV files, IMA ADPCM compressed .WAV files, Xbox 360 XMA-compressed .WAV files, Ogg Vorbis files (mono, stereo, and multichannel), .WAV-wrapped MP3 files, standard MP3 files, and Xbox ADPCM wave files. A stream is similar to a digital sample, but instead of the entire file being loaded into memory, only a small portion of the file is loaded at once.

To stream data files that are embedded within other packed files or libraries, you can mark up the filename to tell MSS how to access it. Simply use a filename string of the form


                *my_large_packed_file.pak*3141592*271828.mp3

to access (for example) a 3,141,592-byte .mp3 file that resides within a container file at byte offset 271,828. When creating a subfile descriptor string, only the suffix portion of the original filename (.mp3 in this case) is needed.

It's also possible to force MSS to use an existing open file handle supplied by your application, but this method is platform-specific and very error prone. Email RAD Game Tools for help with this feature if you really need it, but be aware that it's been deprecated and will not be supported in future versions of MSS.

On the Playstation 2, you can also stream audio from IOP or SPU memory using this function. To load from IOP memory, you can create a special file handle to use with the RAD_IOPGetFileHandleToIOPMemory macro. To load from SPU memory, you use the RAD_IOPGetFileHandleToIOPMemory macro. For example, to play 32768 bytes at IOP memory address 0x12340, you'd do something like:


char load_handle[ 32 ];
sprintf( load_handle, "\\\\\\\\%d,32768", RAD_IOPGetFileHandleToIOPMemory( 0x12340 ) );
stream = AIL_open_stream( load_handle, 0, 0 );

Of course, you can also override the I/O functions that Miles uses to read from the stream with the AIL_set_file_callbacks function, if you don't want to bother composing a subfile descriptor or using the (deprecated) ASCII-encoded file handle technique. On platforms that support asynchronous file access, you should also call AIL_set_file_async_callbacks. Note, however, that most applications are better off letting Miles do its own file access, even with packed files that your application has already opened. Unless you have a very specific reason for overriding Miles's file I/O calls, we recommend against doing so.

Under Windows, streams are automatically serviced in the background by default. You can service the buffers manually with the AIL_service_stream and AIL_auto_service_stream functions.

Under MacOS 9, Wii and PS2, streams are automatically serviced with background asynchronous reads.

Under DOS, you must always service the stream manually with the AIL_service_stream function.

If the total size of the streaming buffers is greater than or equal to the total stream size, then the MSS will preload all of the data automatically, so you'll never use more memory than a normal sample would take.

This function doesn't actually load any of the streaming buffers - the only routine in the streaming API that performs the file reading is AIL_service_stream.

Under DOS, Wii, PS2 and MacOS 9, this function must not be invoked from an interrupt-based callback function.

Monaural-source streams may be steered to multiple output speakers via AIL_stream_sample_handle and the various volume/pan and channel-level control functions. Additionally, multichannel (> 2-channel) Ogg Vorbis files may be streamed with full channel/speaker routing capabilities via AIL_set_sample_channel_levels. Consult the How do I use multi-channel sound output in Miles? FAQ for an overview of multichannel audio support.

Example files that use this function: Demo.C, Streamer.C, FileHndl.C

Group: Digital Audio Streaming Services
Related Sections: Memory management under PlayStation 2
Related Functions: AIL_auto_service_stream, AIL_close_stream, AIL_register_stream_callback, AIL_service_stream, AIL_set_file_async_callbacks, AIL_set_file_callbacks, AIL_set_sample_channel_levels, AIL_set_stream_loop_count, AIL_stream_sample_handle, RAD_IOPGetFileHandleToIOPMemory
Related Basic Types: HDIGDRIVER, HSTREAM, S32, char const *
Related FAQs: How do I access files from a big packed file?, How do I stream a file off a hard disk or CD?, How do I use multi-channel sound output in Miles?, On the Sony PS2, how can I use the IOP or SPU memory to hold my audio?