BASS_StreamCreateFile

Creates a sample stream from an MP3, MP2, MP1, OGG, WAV, AIFF or plugin supported file.

HSTREAM BASS_StreamCreateFile(
    BOOL mem,
    void *file,
    QWORD offset,
    QWORD length,
    DWORD flags
);

Parameters

mem

TRUE = stream the file from memory.

file

Filename (mem = FALSE) or a memory location (mem = TRUE).

offset

File offset to begin streaming from (only used if mem = FALSE).

length

Data length... 0 = use all data up to the end of the file (if mem = FALSE).

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.
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. BASS_ChannelSetPosition can be used to scan the file after stream creation instead.
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 is ignored when streaming from memory (mem = TRUE).
BASS_UNICODE	file is in UTF-16 form. Otherwise it is ANSI on Windows and UTF-8 on other platforms.

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	The length must be specified when streaming from memory.
BASS_ERROR_FILEOPEN	The file could not be opened.
BASS_ERROR_FILEFORM	The file's format is not recognised/supported.
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

BASS has built-in support for MPEG, OGG, WAV and AIFF files. Support for additional formats is available through BASS_PluginLoad.

MPEG 1.0, 2.0 and 2.5 layer 3 (MP3) files are supported, layers 1 (MP1) and 2 (MP2) are also supported. Standard RIFF and RF64 WAV files are supported. All PCM formats from 8 to 32-bit are supported in WAV and AIFF files, but the output will be restricted to 16-bit unless the BASS_SAMPLE_FLOAT flag is used. 64-bit floating-point WAV and AIFF files are also supported, but they are rendered in 16-bit or 32-bit floating-point depending on the flags. The file's original resolution is available from BASS_ChannelGetInfo.

Chained OGG files containing multiple logical bitstreams are supported, but they will need to be scanned to get their length or to seek in them. That scanning will be done at stream creation or at the first BASS_ChannelGetLength or BASS_ChannelSetPosition call, depending on whether the BASS_CONFIG_OGG_PRESCAN option is enabled (or the BASS_STREAM_PRESCAN flag is used). The BASS_POS_OGG "mode" can be used with BASS_ChannelGetLength to get the number of bitstreams and with BASS_ChannelSetPosition to seek to a particular one. A BASS_SYNC_OGG_CHANGE sync can be set via BASS_ChannelSetSync to be informed of when a new bitstream begins during decoding/playback.

Multi-channel (ie. more than stereo) OGG, WAV and AIFF files are supported.

Use BASS_ChannelGetInfo to retrieve information on the file format and sample format of the stream. The playback length of the stream can be retrieved using BASS_ChannelGetLength.

If length = 0 (use all data up to the end of the file), and the file length increases after creating the stream (ie. the file is still being written), then BASS will play the extra data too, but the length returned by BASS_ChannelGetLength will not be updated until the end is reached. The BASS_StreamGetFilePosition return values will be updated during playback of the extra data though.

When streaming from memory (mem = TRUE), the memory must not be freed before the stream is freed. There may be exceptions to that with some add-ons (see the documentation).

When a plugin is used by a stream, there may be additional flags that are supported by it. Any such flags can be set after stream creation via BASS_ChannelFlags. BASS_ChannelGetInfo can be used to check which, if any, plugin is being used.

To stream a file from the internet, use BASS_StreamCreateURL. To stream from other locations, see BASS_StreamCreateFileUser.

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. The BASS_CONFIG_MF_DISABLE config option can used to check whether Media Foundation is available. On iOS and macOS, CoreAudio codecs are supported, including support for AAC and ALAC. Android's media codecs are also supported, including support for AAC, on Android 5 and above. 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.

On Android, file may be a String, ByteBuffer, ParcelFileDescriptor (Android 3.1 and above), or asset (via the Asset class) when using Java. See the BASS.JAVA file for available overloads. When a ParcelFileDescriptor is provided, BASS assumes ownership of the file descriptor and closes it when done with it, including when this function fails.

Example

Create a stream from an MP3 file.

HSTREAM stream = BASS_StreamCreateFile(FALSE, "afile.mp3", 0, 0, 0);