BASS_SampleLoad

Loads a WAV, AIFF, MP3, MP2, MP1, OGG or plugin supported sample.

HSAMPLE BASS_SampleLoad(
    BOOL mem,
    void *file,
    QWORD offset,
    DWORD length,
    DWORD max,
    DWORD flags
);

Parameters

memTRUE = load the sample from memory.
fileFilename (mem = FALSE) or a memory location (mem = TRUE).
offsetFile offset to load the sample from (only used if mem = FALSE).
lengthData length... 0 = use all data up to the end of file (if mem = FALSE). If length over-runs the end of the file, it will automatically be lowered to the end of the file.
maxMaximum number of simultaneous playbacks... 1 (min) - 65535 (max). Use one of the BASS_SAMPLE_OVER flags to choose the override decider, in the case of there being no free channel available for playback (ie. the sample is already playing max times).
flagsA combination of these flags.
BASS_SAMPLE_FLOATUse 32-bit floating-point sample data. Not really recommended for samples as it (at least) doubles the memory usage.
BASS_SAMPLE_LOOPLoop the sample.
BASS_SAMPLE_MONOConvert the sample to mono, if it is not already mono. This flag is automatically applied if BASS_DEVICE_MONO was specified when calling BASS_Init.
BASS_SAMPLE_3DEnable 3D functionality. The sample must be mono.
BASS_SAMPLE_MUTEMAXMute the sample when it is at (or beyond) its max distance (3D samples only).
BASS_SAMPLE_OVER_VOLOverride: the channel with the lowest volume is overridden.
BASS_SAMPLE_OVER_POSOverride: the longest playing channel is overridden.
BASS_SAMPLE_OVER_DISTOverride: the channel furthest away (from the listener) is overridden (3D samples only).
BASS_UNICODEfile is in UTF-16 form. Otherwise it is ANSI on Windows and UTF-8 on other platforms.

Return value

If successful, the loaded sample's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INITBASS_Init has not been successfully called.
BASS_ERROR_ILLPARAMmax and/or length is invalid. The length must be specified when loading from memory.
BASS_ERROR_FILEOPENThe file could not be opened.
BASS_ERROR_FILEFORMThe file's format is not recognised/supported.
BASS_ERROR_NOTAUDIOThe file does not contain audio, or it also contains video and videos are disabled.
BASS_ERROR_CODECThe file uses a codec that is not available/supported. This can apply to WAV and AIFF files.
BASS_ERROR_FORMATThe sample format is not supported.
BASS_ERROR_EMPTYThe file does not contain any sample data.
BASS_ERROR_MEMThere is insufficient memory.
BASS_ERROR_NO3DCould not initialize 3D support.
BASS_ERROR_UNKNOWNSome other mystery problem!

Remarks

This function supports the same file formats as BASS_StreamCreateFile does, including those supported via the plugin system.

To play a sample, first a channel must be obtained using BASS_SampleGetChannel, which can then be played using BASS_ChannelStart or BASS_ChannelPlay.

After loading a sample from memory (mem = TRUE), the memory can safely be discarded, as a copy is made.

If you want to play a large or one-off sample, then it would probably be better to stream it instead with BASS_StreamCreateFile.

Platform-specific

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.

See also

BASS_SampleCreate, BASS_SampleFree, BASS_SampleGetChannel, BASS_SampleGetInfo, BASS_StreamCreateFile