BASS_MusicLoad

Loads a MOD music file.

HMUSIC BASS_MusicLoad(
    BOOL mem,
    void *file,
    QWORD offset,
    DWORD length,
    DWORD flags,
    DWORD freq
);

Parameters

mem

TRUE = load the MOD music from memory.

file

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

offset

File offset to load the MOD music from (only used if mem = FALSE).

length

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

flags

A combination of these flags.

BASS_SAMPLE_8BITS	Use 8-bit resolution. If neither this or the BASS_SAMPLE_FLOAT flags are specified, then the sample data is 16-bit.
BASS_SAMPLE_FLOAT	Use 32-bit floating-point sample data. See Floating-point channels for info.
BASS_SAMPLE_MONO	Decode/play the MOD music in mono (uses less CPU than stereo). This flag is automatically applied if BASS_DEVICE_MONO was specified when calling BASS_Init.
BASS_SAMPLE_3D	Enable 3D functionality. 3D channels must be mono, so BASS_SAMPLE_MONO is automatically applied. The SPEAKER flags cannot be used together with this flag.
BASS_SAMPLE_LOOP	Loop the music.
BASS_MUSIC_NONINTER	Use non-interpolated sample mixing. This generally reduces the sound quality, but can be good for chip-tunes.
BASS_MUSIC_SINCINTER	Use sinc interpolated sample mixing. This increases the sound quality, but also requires more CPU. If neither this or the BASS_MUSIC_NONINTER flag is specified, linear interpolation is used.
BASS_MUSIC_RAMP	Use "normal" ramping (as in FastTracker 2).
BASS_MUSIC_RAMPS	Use "sensitive" ramping.
BASS_MUSIC_SURROUND	Apply XMPlay's surround sound to the music. This is ignored if the BASS_SAMPLE_MONO flag is also specified.
BASS_MUSIC_SURROUND2	Apply XMPlay's surround sound mode 2 to the music. This is ignored if the BASS_SAMPLE_MONO flag is also specified.
BASS_MUSIC_FT2PAN	Apply FastTracker 2 panning to XM files.
BASS_MUSIC_FT2MOD	Play .MOD files as FastTracker 2 would, including applying FastTracker 2 panning.
BASS_MUSIC_PT1MOD	Play .MOD files as ProTracker 1 would.
BASS_MUSIC_POSRESET	Stop all notes when seeking (BASS_ChannelSetPosition).
BASS_MUSIC_POSRESETEX	Stop all notes and reset bpm/etc to defaults when seeking.
BASS_MUSIC_STOPBACK	Stop the music when a backward jump effect is played. This stops musics that never reach the end from going into endless loops. Some MOD musics are designed to jump all over the place, so this flag would cause those to be stopped prematurely. If this flag is used together with the BASS_SAMPLE_LOOP flag, then the music would not be stopped but any BASS_SYNC_END sync would be triggered.
BASS_MUSIC_PRESCAN	Calculate the playback length of the music, and enable seeking in bytes. This slightly increases the time taken to load the music, depending on how long it is. In the case of musics that loop, the length until the loop occurs is calculated. Use BASS_ChannelGetLength to retrieve the length.
BASS_MUSIC_NOSAMPLE	Do not load the samples. This reduces the time (and memory) taken to load the music, notably with MO3 files, which is useful if you just want to get the text and/or length of the music without playing it.
BASS_MUSIC_AUTOFREE	Automatically free the music when playback ends. Note that some musics have infinite loops, so never actually end on their own.
BASS_MUSIC_DECODE	Decode/render 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. The BASS_SAMPLE_MONO flag is automatically applied when using a mono speaker assignment flag.
BASS_UNICODE	file is in UTF-16 form. Otherwise it is ANSI on Windows and UTF-8 on other platforms.

freq

Sample rate to render/play the MOD music at... 0 = the rate specified in the BASS_Init call, 1 = the device's current output rate (or the BASS_Init rate if that is not available).

Return value

If successful, the loaded MOD music'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_MUSIC_AUTOFREE flag is unavailable to decoding channels.
BASS_ERROR_FILEOPEN	The file could not be opened.
BASS_ERROR_FILEFORM	The file's format is not recognised/supported.
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 uses the same code as XMPlay for its MOD music support, giving an accurate reproduction of the MO3 / IT / XM / S3M / MTM / MOD / UMX formats.

MO3s are treated and used in exactly the same way as normal MOD musics. The advantage of MO3s is that they can be a lot smaller with virtually identical quality. Playing a MO3 does not use any more CPU power than playing the original MOD version does. The only difference is a slightly longer load time as the samples are being decoded. MO3 files are created using the MO3 encoder available at the BASS website.

DMO effects (the same as available with BASS_ChannelSetFX) can be used in IT and XM files (and MO3 versions of them) created with Modplug Tracker. This allows effects to be added to a track without having to resort to an MP3 or OGG version, so it can remain small and still sound fancy. Of course, the effects require some CPU, so should not be used carelessly if performance is key.

"Ramping" does not take a lot of extra processing and improves the sound quality by removing clicks, by ramping/smoothing volume and pan changes. The start of a sample may also be ramped-in. That is always the case with XM files (or MOD files in FT2 mode) when using normal ramping, and possibly with all formats when using sensitive ramping; senstitive ramping will only ramp-in when necessary to avoid a click. Generally, normal ramping is recommended for XM files, and sensitive ramping for the other formats, but some XM files may also sound better using sensitive ramping.

After loading a MOD music from memory (mem = TRUE), the memory can safely be discarded.

Platform-specific

DMO effects require DirectX 8 (or above) on Windows. They are always available on other platforms, except for the following: Compressor, Gargle, and I3DL2Reverb. When a DMO effect is unavailable, the MOD music can still be played, but the effect will be disabled.