Creates a sample stream from an MP3, MP2, MP1, OGG, WAV, AIFF or plugin supported file via user callback functions.
HSTREAM BASS_StreamCreateFileUser( DWORD system, DWORD flags, BASS_FILEPROCS *procs, void *user );
|system||File system to use, one of the following.
|flags||A combination of these flags.|
|procs||The user defined file functions.|
|user||User instance data to pass to the callback functions.|
Return valueIf successful, the new stream's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.
|BASS_ERROR_INIT||BASS_Init has not been successfully called.|
|BASS_ERROR_NOTAVAIL||Only decoding channels (BASS_STREAM_DECODE) are allowed when using the "no sound" device. The BASS_STREAM_AUTOFREE flag is also unavailable to decoding channels.|
|BASS_ERROR_ILLPARAM||system is not valid.|
|BASS_ERROR_FILEFORM||The file's format is not recognised/supported.|
|BASS_ERROR_CODEC||The file uses a codec that is not available/supported. This can apply to WAV and AIFF files, and also MP3 files when using the "MP3-free" BASS version.|
|BASS_ERROR_FORMAT||The sample format is not supported by the device/drivers. If the stream is more than stereo or the BASS_SAMPLE_FLOAT flag is used, it could be that they are not supported.|
|BASS_ERROR_SPEAKER||The specified SPEAKER flags are invalid. The device/drivers do not support them, they are attempting to assign a stereo stream to a mono speaker or 3D functionality is enabled.|
|BASS_ERROR_MEM||There is insufficient memory.|
|BASS_ERROR_NO3D||Could not initialize 3D support.|
|BASS_ERROR_UNKNOWN||Some other mystery problem!|
RemarksThe buffered file system (STREAMFILE_BUFFER) is what is used by BASS_StreamCreateURL. As the name suggests, data from the file is buffered so that it is readily available for decoding; BASS creates a thread dedicated to "downloading" the data. This is ideal for when the data is coming from a source that has high latency, like the internet. It is not possible to seek in buffered file streams, until the download has reached the requested position; it is not possible to seek at all if it is being streamed in blocks.
The push buffered file system (STREAMFILE_BUFFERPUSH) is the same, except that instead of the file data being pulled from the FILEREADPROC function in a "download" thread, the data is pushed to the stream via BASS_StreamPutFileData. A FILEREADPROC function is still required, to get the initial data used in the creation of the stream.
The unbuffered file system (STREAMFILE_NOBUFFER) is what is used by BASS_StreamCreateFile. In this system, BASS does not do any intermediate buffering; it simply requests data from the file as and when it needs it. This means that reading (FILEREADPROC) must be quick, otherwise the decoding will be delayed and playback buffer underruns (old data repeated) are a possibility. It is not so important for seeking (FILESEEKPROC) to be fast, as that is generally not required during decoding, except when looping a file.
In all cases, BASS will automatically stall playback of the stream when insufficient data is available, and resume it when enough data does become available.
A copy is made of the procs callback function table, so it does not need to persist beyond this function call.
Platform-specificAway from Windows, all mixing is done in software (by BASS), so the BASS_SAMPLE_SOFTWARE flag is unnecessary. The BASS_SAMPLE_FX flag is also ignored.
On Windows and Windows CE, ACM codecs are supported with compressed WAV files. Media Foundation codecs are also supported on Windows 7 and updated versions of Vista, including support for AAC and WMA. On iOS and OSX, CoreAudio codecs are supported, including support for AAC and ALAC. Media Foundation and CoreAudio codecs are only tried after the built-in decoders and any plugins have rejected the file. Built-in support for IMA and Microsoft ADPCM WAV files is provided on Linux/Android/Windows CE, while they are supported via ACM and CoreAudio codecs on Windows and OSX/iOS.