Previous Topic Index Next Topic
[API function]

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.
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. If FMOD is using ASPI then it can only access the first CD device it finds.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

See Also

FSOUND_MODES , FSOUND_Stream_Close , FSOUND_Stream_GetLength , FSOUND_Stream_GetLengthMs , FSOUND_Stream_GetOpenState , FSOUND_Stream_Net_GetBufferProperties , FSOUND_Stream_Net_GetInfo , FSOUND_Stream_Net_GetLastServerStatus , FSOUND_Stream_Net_GetStatus , FSOUND_Stream_Net_SetBufferProperties , FSOUND_Stream_Net_SetMetadataCallback , FSOUND_Stream_Net_SetProxy , FSOUND_Stream_Open , FSOUND_Stream_Play , FSOUND_Stream_PlayEx , FSOUND_Stream_SetBufferSize , FSOUND_Stream_SetSubStream , FSOUND_Stream_Stop

This document copyright ©Firelight Technologies, Pty, Ltd, 1999-2002. All rights reserved.
Generated Thu Apr 22 17:08:53 2004 by SourceDoc v0.10, the automated source code documenter.