FSOUND_Stream

FSOUND_Stream_Open

Opens an audio file/url/cd ready for streaming.
This opens the file in preparation for playback in real-time, without needing to decode the whole file into memory first.

FSOUND_STREAM * F_API FSOUND_Stream_Open(
const char *name_or_data,
unsigned int mode,
int offset,
int length
);

Parameters

name_or_data	Name of the file to open, or pointer to data if FSOUND_LOADMEMORY is used.
mode	Simple description of how to play the file. For all formats except raw PCM, FSOUND_LOOP*, FSOUND_HW3D, FSOUND_HW2D, FSOUND_2D, FSOUND_LOADMEMORY, FSOUND_LOADRAW, FSOUND_MPEGACCURATE, FSOUND_NONBLOCKING flags are the only ones supported.
offset	Optional. 0 by default. If > 0, this value is used to specify an offset in a file, so fmod will seek before opening. length must also be specified if this value is used.
length	Optional. 0 by default. If > 0, this value is used to specify the length of a memory block when using FSOUND_LOADMEMORY, or it is the length of a file or file segment if the offset parameter is used. On PlayStation 2 this must be 16 byte aligned for memory loading.

Return Value

On success, a pointer to an opened stream is returned.
On failure, NULL is returned.

Remarks

WAV support supports windows codec compressed WAV files.
--------------
FSOUND_MPEGACCURATE is to be used cautiously. To open a file with this mode turned on, it has to scan the whole MP3 first. This can take several seconds if the file is big, or the harddisk/cpu is slow.
A way to speed up this process would be to load the compressed mp3 into memory first, and use the FSOUND_LOADMEMORY flag with this function.
--------------
NOTE : Internet stream limitations
- URLs must start with "http://".
- The only supported formats for HTTP streams are MP3 (must have .mp3 extension) and OggVorbis (must have .ogg extension).
--------------
FSB streaming is not supported if the format from FSBank is 'Retain original format'. On PC platforms, only PCM and ADPCM FSB files are allowed.
--------------
Note, on PlayStation 2 you cannot use FSOUND_LOADMEMORY, you may use FSOUND_LOADMEMORYIOP though.
--------------
When opening with the FSOUND_NONBLOCKING flag, this function always succeeds at the point of being called.
It will always return a valid channel handle, even though the file might fail to open. To determine any error in non blocking mode use FSOUND_Stream_GetOpenState.
--------------
NOTE: CDDA Streaming (Win32 only!)
To open a CD for CDDA streaming, specify the drive letter of a CD drive e.g. FSOUND_Stream_Open("d:", 0, 0, 0); FSOUND_Stream_Open will create a stream with multiple substreams, one for each CD track. Use FSOUND_Stream_SetSubStream to select which CD track to play.
A number of options can be passed to FSOUND_Stream_Open along with the drive letter. They are :
*? e.g. FSOUND_Stream_Open("d:*?", 0, 0, 0); This option will cause a tag field called "CD_DEVICE_INFO" to be attached to the stream. This tag field contains information on the specified CD device.
*! e.g. FSOUND_Stream_Open("d:*!", 0, 0, 0); This option will cause the stream to be opened in "quick open" mode. When a stream is opened in this mode, calls to FSOUND_Stream_SetSubStream will return immediately making it quick to select each substream in turn and get the length of each CD track. Note that a stream in quick open mode cannot be played! Use quick open mode to get track lengths and then re-open the stream without quick open mode to actually play it.
*j e.g. FSOUND_Stream_Open("d:*j", 0, 0, 0); This option turns jitter correction OFF.
*a e.g. FSOUND_Stream_Open("d:*a", 0, 0, 0); This option will force FMOD to use ASPI to access the specified CD drive as opposed to NTSCSI. It should generally only be used as a last resort if FMOD is unable to access drives that are known to be working with other programs.
Options can be combined like so: FSOUND_Stream_Open("d:*?!j", 0, 0, 0);
If a nonblocking CDDA stream fails to open, a tag field called "CD_ERROR" will be attached to the stream. This tag field contains a textual description of why the stream failed to open.
NOTE: FMOD will always try to use native NTSCSI support to communicate with CD devices before trying to use ASPI, unless the "*a" option is specified, in which case FMOD will only try to use ASPI. Unlike in pre-3.73 versions, FMOD can now access all CD drives when using ASPI.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

[API function]

FSOUND_Stream_Open

Parameters

Return Value

Remarks

See Also