BASS_StreamCreateFileUser
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
);
Parameters
| system | File system to use, one of the following.
| STREAMFILE_NOBUFFER | Unbuffered.
| | STREAMFILE_BUFFER | Buffered.
| | STREAMFILE_BUFFERPUSH | Buffered, with the data pushed to BASS via BASS_StreamPutFileData.
|
|
| flags | A combination of these flags.
| BASS_SAMPLE_FLOAT | Use 32-bit floating-point sample data. See Floating-point channels for info.
| | BASS_SAMPLE_MONO | Decode/play the file (OGG/MP3/MP2/MP1 only) in mono. This flag is automatically applied if BASS_DEVICE_MONO was specified when calling BASS_Init.
| | BASS_SAMPLE_3D | Enable 3D functionality. The stream must be mono. The SPEAKER flags cannot be used together with this flag.
| | BASS_SAMPLE_LOOP | Loop the file. This flag can be toggled at any time using BASS_ChannelFlags. This flag is ignored when streaming in blocks (BASS_STREAM_BLOCK).
| | BASS_STREAM_PRESCAN | Pre-scan the file for accurate seek points and length reading in MP3/MP2/MP1 files and chained OGG files (has no effect on normal OGG files). This can significantly increase the time taken to create the stream, particularly with a large file and/or slow storage media. This flag only applies when using the STREAMFILE_NOBUFFER system.
| | BASS_STREAM_RESTRATE | Restrict the "download" rate of the file, according to the BASS_CONFIG_NET_RESTRATE config setting. If this flag is not used then the file will be downloaded as quickly as possible. This flag only has effect when using the STREAMFILE_BUFFER system.
| | BASS_STREAM_BLOCK | Only keep a block of the file in memory, determined by the BASS_CONFIG_NET_BUFFER config setting, rather than the whole file. This uses a lot less memory than otherwise, but it is not possible to seek or loop the stream. This flag will be applied automatically when the file length is unknown or over 2GB. This flag has no effect when using the STREAMFILE_NOBUFFER system.
| | BASS_STREAM_AUTOFREE | Automatically free the stream when playback ends.
| | BASS_STREAM_DECODE | Decode the sample data, without playing it. Use BASS_ChannelGetData to retrieve decoded sample data. The BASS_SAMPLE_3D, BASS_STREAM_AUTOFREE and SPEAKER flags cannot be used together with this flag.
| | BASS_SPEAKER_xxx | Speaker assignment flags. These flags have no effect when the stream is more than stereo.
| | BASS_ASYNCFILE | Read the file asynchronously. When enabled, the file is read and buffered in parallel with the decoding, to reduce the chances of the decoder being affected by I/O delays. This can be particularly useful with slow storage media and/or low latency output. The size of the file buffer is determined by the BASS_CONFIG_ASYNCFILE_BUFFER config option. This flag only applies when using the STREAMFILE_NOBUFFER system.
|
|
| procs | The user defined file functions.
|
| user | User instance data to pass to the callback functions.
|
Return value
If successful, the new stream's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.
Error codes
| BASS_ERROR_INIT | BASS_Init has not been successfully called.
|
| BASS_ERROR_NOTAVAIL | The BASS_STREAM_AUTOFREE flag cannot be combined with the BASS_STREAM_DECODE flag.
|
| BASS_ERROR_ILLPARAM | system is not valid.
|
| BASS_ERROR_FILEFORM | The file's format is not recognised/supported.
|
| BASS_ERROR_UNSTREAMABLE | The file cannot be streamed using the buffered file system. This could be because an MP4 file's "mdat" atom comes before its "moov" atom.
|
| BASS_ERROR_NOTAUDIO | The file does not contain audio, or it also contains video and videos are disabled.
|
| BASS_ERROR_CODEC | The file uses a codec that is not available/supported. This can apply to WAV and AIFF files.
|
| BASS_ERROR_FORMAT | The sample format is not supported.
|
| BASS_ERROR_SPEAKER | The specified SPEAKER flags are invalid.
|
| BASS_ERROR_MEM | There is insufficient memory.
|
| BASS_ERROR_NO3D | Could not initialize 3D support.
|
| BASS_ERROR_UNKNOWN | Some other mystery problem!
|
Remarks
The 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. When streaming in blocks, it may be possible to reset the stream via BASS_ChannelSetPosition with the BASS_POS_RESET flag, so that it is ready to process new data.
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-specific
On Windows, 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 macOS, CoreAudio codecs are supported, including support for AAC and ALAC. Android's media codecs are also supported on Android 9 and above (Android 5 for AAC/ADTS). In all cases, the OS's codecs are only tried after BASS's 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, while they are supported via ACM and CoreAudio codecs on Windows and macOS/iOS.
See also
BASS_ChannelGetInfo, BASS_ChannelGetLength, BASS_ChannelGetTags, BASS_ChannelPlay, BASS_ChannelSetAttribute, BASS_ChannelSetDSP, BASS_ChannelSetFX, BASS_StreamCreateFile, BASS_StreamCreateURL, BASS_StreamFree, BASS_StreamGetFilePosition, BASS_StreamPutFileData, BASS_FILEPROCS structure, BASS_CONFIG_NET_BUFFER