BassMixBASS_Split_StreamCreate Method

[DllImportAttribute("bassmix")]
public static int BASS_Split_StreamCreate(
	int channel,
	BASSFlag flags,
	int[] mapping
)

<DllImportAttribute("bassmix">]
Public Shared Function BASS_Split_StreamCreate ( 
	channel As Integer,
	flags As BASSFlag,
	mapping As Integer()
) As Integer

Parameters

channel

Type: SystemInt32
The handle of the decoding source channel to split... a HMUSIC, HSTREAM or HRECORD (e.g. created with BASS_StreamCreateFile(String, Int64, Int64, BASSFlag)).

flags

Type: Un4seen.BassBASSFlag
The channel falgs to be used to create the reader channel, any combination of these flags (see BASSFlag):

BASS_SAMPLE_3D	Use 3D functionality. This is ignored if BASS_DEVICE_3D wasn't specified when calling BASS_Init(Int32, Int32, BASSInit, IntPtr, IntPtr). 3D streams must be mono. The SPEAKER flags can not be used together with this flag.
BASS_STREAM_AUTOFREE	Automatically free the stream when it ends. This allows you to stream a file and forget about it, as BASS will automatically free the stream's resources when it has reached the end or when BASS_ChannelStop(Int32) (or BASS_Stop) is called.
BASS_STREAM_DECODE	Split the sample data, without playing it. Use BASS_ChannelGetData(Int32, IntPtr, Int32) to retrieve decoded sample data. The BASS_SAMPLE_SOFTWARE, BASS_SAMPLE_3D, BASS_SAMPLE_FX, BASS_STREAM_AUTOFREE and SPEAKER flags can not be used together with this flag.
BASS_SPLIT_POS	The splitter's length and position is based on the splitter's (rather than the source's) channel count.
BASS_SPLIT_SLAVE	Only get data from the splitter buffer, not directly from the source.
BASS_SPEAKER_xxx	Speaker assignment flags. These flags have no effect when the stream is more than stereo.

mapping

Type: SystemInt32
The target (readers) channel mapping definition, which is an array of source channel index values (0=1st channel, 1=2nd channel, 2=3rd channel, 3=4th channel etc.) ending with a final -1 element (use to create a 1:1 reader).

Return Value

The splitter stream will have the same sample rate and resolution as its source, but it can have a different number of channels, as dictated by the mapping parameter. Even when the number of channels is different (and so the amount of data produced is different), BASS_ChannelGetLength(Int32, BASSMode) will give the source length, and BASS_ChannelGetPosition(Int32, BASSMode) will give the source position that is currently being output by the splitter stream, unless the BASS_SPLIT_POS flag is used. The BASS_SPLIT_POS flag can be toggled at any time via BASS_ChannelFlags(Int32, BASSFlag, BASSFlag).

All splitter streams with the same source share a buffer to access its sample data. The length of the buffer is determined by the BASS_CONFIG_SPLIT_BUFFER config option; the splitter streams should not be allowed to drift apart beyond that, otherwise those left behind will suffer buffer overflows. A splitter stream's buffer state can be reset via BASS_Split_StreamReset(Int32); that can also be used to reset a splitter stream that has ended, so that it can be played again.

If the BASS_SPLIT_SLAVE flag is used, the splitter stream will only receive data from the buffer and will not request more data from the source, so it can only receive data that has already been received by another splitter stream with the same source. The BASS_SPLIT_SLAVE flag can be toggled at any time via BASS_ChannelFlags(Int32, BASSFlag, BASSFlag).

When BASS_ChannelSetPosition(Int32, Int64, BASSMode) is used on a splitter stream, its source will be set to the requested position and the splitter stream's buffer state will be reset so that it immediately receives data from the new position. The position change will affect all of the source's splitter streams, but the others will not have their buffer state reset; they will continue to receive any buffered data before reaching the data from the new position. BASS_Split_StreamReset(Int32) can be used to reset the buffer state.

The source can be a "dummy" stream (STREAMPROC_DUMMY). In that case, the BASS_SPLIT_SLAVE flag is set automatically because the splitters can only receive data as it is processed rather than request it.

Use BASS_StreamFree(Int32) with a splitter channel to remove it from the source. When a source is freed, all of its splitter streams are automatically freed.

The mapping array defines the channel number to be created for the reader as well as which source channels should be used for each. This enables you to create a reader stream which extract certain source channels (e.g. create a mono reader based on a stereo source), remaps the channel order (e.g. swap left and right in the reader) or even contains more channels than the source (e.g. create a 5.1 reader based on a stereo source).

Platform-specific

Away from Windows, all mixing is done in software (by BASS), so the BASS_SAMPLE_SOFTWARE flag is unnecessary. The BASS_SAMPLE_FX flag is also ignored.

int source = Bass.BASS_StreamCreateFile("test.mp3", 0L, 0L, BASSFlag.BASS_SAMPLE_FLOAT | BASSFlag.BASS_STREAM_DECODE);
int reader1 = BassMix.BASS_Split_StreamCreate(source, BASSFlag.BASS_SAMPLE_FLOAT, null);
int reader2 = BassMix.BASS_Split_StreamCreate(source, BASSFlag.BASS_SAMPLE_FLOAT, null);
...

Dim source As Integer = Bass.BASS_StreamCreateFile("test.mp3", 0L, 0L, BASSFlag.BASS_SAMPLE_FLOAT | BASSFlag.BASS_STREAM_DECODE)
Dim reader1 As Integer = BassMix.BASS_Split_StreamCreate(source, BASSFlag.BASS_SAMPLE_FLOAT, Nothing)
Dim reader2 As Integer = BassMix.BASS_Split_StreamCreate(source, BASSFlag.BASS_SAMPLE_FLOAT, Nothing)
...

// create a mono reader containing only the right channel based on a stereo source
int[] mapping = {1,-1};

// create a stereo reader which swaps the left and right channel of the stereo source
int[] mapping = {1,0,-1};

// create a quad-channel reader based on a stereo source
int[] mapping = {0,1,0,1,-1};

// create a sterao reader based on a mono source
int[] mapping = {0,0,-1};

Reference