TBASS_MusicLoad

<< Click to Display Table of Contents >>

Navigation:  ThinBASIC Modules > TBASS (Sound Module) > Music >

TBASS_MusicLoad

 

Description

 

Loads music from file or memory.

 

Syntax

 

music = TBASS_LoadMusic(mem, source, offset, length, flags, freq)

 

Returns

 

Number, music handle - non-zero in case of success.

 

Parameters

 

Name

Type

Optional

Meaning

mem

Numeric

No

flag indicating if you want to load the sample from memory

source

String / Pointer

No

file name (if mem is FALSE), otherwise memory location of sample

offset



file offset to load the sample from (only used if mem is FALSE).

length



Data length... 0 = use all data up to the end of file (if mem is FALSE). If length over-runs the end of the file, it will automatically be lowered to the end of the file.

flags



A combination of these flags

 

A combination of these flags.

%TBASS_SAMPLE_8BITS

Use 8-bit resolution. If neither this or the %TBASS_SAMPLE_FLOAT flags are specified, then the sample data will be 16-bit.

%TBASS_SAMPLE_FLOAT

Use 32-bit floating-point sample data. See Floating-point channels for info.

%TBASS_SAMPLE_MONO

Decode/play the MOD music in mono (uses less CPU than stereo). This flag is automatically applied if %TBASS_DEVICE_MONO was specified when calling TBASS_Init.

%TBASS_SAMPLE_SOFTWARE

Force the MOD music to not use hardware DirectSound mixing.

%TBASS_SAMPLE_3D

Enable 3D functionality. This requires that the %TBASS_DEVICE_3D flag was specified when calling TBASS_Init. 3D channels must also be mono, so %TBASS_SAMPLE_MONO is automatically applied. The SPEAKER flags cannot be used together with this flag.

%TBASS_SAMPLE_LOOP

Loop the music.

%TBASS_MUSIC_NONINTER

Use non-interpolated sample mixing. This generally reduces the sound quality, but can be good for chip-tunes.

%TBASS_MUSIC_SINCINTER

Use sinc interpolated sample mixing. This increases the sound quality, but also requires more CPU. If neither this or the %TBASS_MUSIC_NONINTER flag is specified, linear interpolation is used.

%TBASS_MUSIC_RAMP

Use "normal" ramping (as in FastTracker 2).

%TBASS_MUSIC_RAMPS

Use "sensitive" ramping.

%TBASS_MUSIC_SURROUND

Apply XMPlay's surround sound to the music. This is ignored if the %TBASS_SAMPLE_MONO flag is also specified.

%TBASS_MUSIC_SURROUND2

Apply XMPlay's surround sound mode 2 to the music. This is ignored if the %TBASS_SAMPLE_MONO flag is also specified.

%TBASS_MUSIC_FT2PAN

Apply FastTracker 2 panning to XM files.

%TBASS_MUSIC_FT2MOD

Play .MOD files as FastTracker 2 would, including applying FastTracker 2 panning.

%TBASS_MUSIC_PT1MOD

Play .MOD files as ProTracker 1 would.

%TBASS_MUSIC_POSRESET

Stop all notes when seeking (TBASS_ChannelSetPosition).

%TBASS_MUSIC_POSRESETEX

Stop all notes and reset bpm/etc when seeking.

%TBASS_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 %TBASS_SAMPLE_LOOP flag, then the music would not be stopped but any %TBASS_SYNC_END sync would be triggered.

%TBASS_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 TBASS_ChannelGetLength to retrieve the length.

%TBASS_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.

%TBASS_MUSIC_AUTOFREE

Automatically free the music when playback ends. Note that some musics have infinite loops, so never actually end on their own.

%TBASS_MUSIC_DECODE

Decode/render the sample data, without playing it. Use TBASS_ChannelGetData to retrieve decoded sample data. The %TBASS_SAMPLE_3D, %TBASS_STREAM_AUTOFREE and SPEAKER flags cannot be used together with this flag. The %TBASS_SAMPLE_SOFTWARE and %TBASS_SAMPLE_FX flags are also ignored.

%TBASS_SPEAKER_xxx

Speaker assignment flags. The %TBASS_SAMPLE_MONO flag is automatically applied when using a mono speaker assignment flag.

%TBASS_UNICODE

file is in UTF-16 form. Otherwise it is ANSI on Windows or Windows CE, and UTF-8 on other platforms.

 

 

freq



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

 

 

Remarks

 

Restrictions

 

See also

 

Examples