ThinBASIC Modules > TBASS (Sound Module) > Channels > TBASS

Description

Retrieves the immediate sample data (or an FFT representation of it) of a stream or MOD music channel.

Syntax

n = TBASS_ChannelGetData(hChannel, BufferDataPTR, DataLen)

Returns

Number

If an error occurs, -1 is returned. Use TBASS_ErrorGetCode to get the error code.

When requesting FFT data, the number of bytes read from the channel (to perform the FFT) is returned. When requesting sample data, the number of bytes written to buffer will be returned (not necessarily the same as the number of bytes read when using the %TBASS_DATA_FLOAT flag). When using the %TBASS_DATA_AVAILABLE flag, the number of bytes in the channel's buffer is returned.

Parameters

Name	Type	Optional	Meaning
hChannel	Numeric	No	The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD.
BufferDataPTR	Numeric	No	Location to write the data... can be NULL when handle is a recording channel, to discard the requested amount of data from the recording buffer. Use VARPTR or STRPTR or any function returning a pointer to any memory location area where to store data.
DataLen	Numeric	No	Number of bytes wanted, and/or the following flags: %TBASS_DATA_FLOAT Return floating-point sample data. %TBASS_DATA_FFT256 256 sample FFT (returns 128 floating-point values) %TBASS_DATA_FFT512 512 sample FFT (returns 256 floating-point values) %TBASS_DATA_FFT1024 1024 sample FFT (returns 512 floating-point values) %TBASS_DATA_FFT2048 2048 sample FFT (returns 1024 floating-point values) %TBASS_DATA_FFT4096 4096 sample FFT (returns 2048 floating-point values) %TBASS_DATA_FFT8192 8192 sample FFT (returns 4096 floating-point values) %TBASS_DATA_FFT_INDIVIDUAL Use this flag to request separate FFT data for each channel. The size of the data returned (as listed above) is multiplied by the number channels. %TBASS_DATA_FFT_NOWINDOW This flag can be used to prevent a Hann window being applied to the sample data when performing an FFT. %TBASS_DATA_AVAILABLE Query the amount of data the channel has buffered for playback, or from recording. This flag can't be used with decoding channels as they do not have playback buffers. buffer is ignored when using this flag.

Remarks

This function can only return as much data as has been written to the channel's buffer, so it may not always be possible to get the amount of data requested, especially if you request large amounts. If you really do need large amounts, then increase the buffer lengths (BASS_CONFIG_BUFFER). The %TBASS_DATA_AVAILABLE flag can be used to check how much data a channel's buffer contains at any time, including when stopped or stalled.

When retrieving sample data, 8-bit samples are unsigned (0 to 255) , 16-bit samples are signed (-32768 to 32767), 32-bit floating-point samples range from -1 to +1 (not clipped, so can actually be outside this range). That's unless the %TBASS_DATA_FLOAT flag is used, in which case, the sample data will be converted to 32-bit floating-point (if it isn't already).

When requesting FFT data, floating-point values ranging from 0 to 1 are returned. Only the first half of the FFT is useful, so that's what BASS returns. For example, with a 2048 sample FFT, it will return 1024 values; the 1st value being the DC component, the 2nd being the amplitude at 1/2048 of the channel's sample rate, then the amplitude at 2/2048, 3/2048, etc... A Hann window is applied to the sample data to reduce leakage, unless the %TBASS_DATA_FFT_NOWINDOW flag is used.

Channels that have 2 or more sample channels (ie. stereo or above) may have FFT performed on each individual channel, using the %TBASS_DATA_FFT_INDIVIDUAL flag. Without this flag, all the channels are combined, and a single mono FFT is performed. Performing the extra individual FFTs of course increases the amount of processing required. The return values are interleaved in the same order as the channel's sample data, eg. stereo = left,right,left,etc...

This function is most useful if you wish to visualize (eg. spectrum analyze) the sound.

Restrictions