BASS_Split_StreamCreate

Creates a splitter stream.

HSTREAM BASS_Split_StreamCreate(
    DWORD channel,
    DWORD flags,
    int *chanmap
);

Parameters

channel

The handle of the channel to split... a HMUSIC, HSTREAM or HRECORD.

flags

Any combination of these flags.

BASS_SAMPLE_3D	Enable 3D functionality. The stream must be mono. The SPEAKER flags cannot be used together with this flag.
BASS_STREAM_AUTOFREE	Automatically free the stream when playback ends.
BASS_STREAM_DECODE	Render the sample data, without playing it. Use BASS_ChannelGetData to retrieve the sample data. The BASS_SAMPLE_3D, BASS_STREAM_AUTOFREE and SPEAKER flags cannot be used together with this flag.
BASS_SPLIT_AUTORESET	Automatically reset the splitter when BASS_ChannelSetPosition is called on another splitter with the same source, or when the source's playback buffer is flushed (if it has one). This flag can be toggled with BASS_ChannelFlags.
BASS_SPLIT_DSP	Use a DSP function on the source to feed the splitter, instead of requesting data from the source. This flag must be set on all or none of a source's splitters; there cannot be a mix. It is set automatically when the source is not a decoding channel or it is a "dummy" stream (STREAMPROC_DUMMY or STREAMPROC_DEVICE).
BASS_SPLIT_POS	The splitter's length and position is based on the splitter's (rather than the source's) channel count. This flag can be toggled with BASS_ChannelFlags.
BASS_SPLIT_SLAVE	Only get data from the splitter buffer, not directly from the source. This flag is set automatically when BASS_SPLIT_DSP is set. It can otherwise be toggled with BASS_ChannelFlags.
BASS_SPEAKER_xxx	Speaker assignment flags. These flags have no effect when the stream is more than stereo.

chanmap

Channel map... pointer to an array of channel indexes (0=first, -1=end of array), NULL = a 1:1 mapping of the source.

Return value

If successful, the new stream'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_HANDLE	channel is not valid.
BASS_ERROR_DECODE	channel is not a decoding channel (or recording channel) and the BASS version is older than 2.4.18.
BASS_ERROR_ALREADY	channel already has splitter(s) with a different BASS_SPLIT_DSP flag setting.
BASS_ERROR_ILLPARAM	chanmap contains an invalid channel index.
BASS_ERROR_NOTAVAIL	The BASS_STREAM_AUTOFREE flag cannot be combined with the BASS_STREAM_DECODE flag.
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

A "splitter" basically does the opposite of a mixer: it splits a single source into multiple streams rather then mixing multiple sources into a single stream. If the BASS version is older than 2.4.18 then splitter sources must be a decoding channel or recording channel, otherwise they can also be a normal playback channel.

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 chanmap parameter. Even when the number of channels is different (and so the amount of data produced is different), BASS_ChannelGetLength will give the source length and BASS_ChannelGetPosition will give the source position that is currently being output by the splitter stream, unless the BASS_SPLIT_POS flag is used.

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 (dropped data). When the BASS_SPLIT_DSP flag is not set, data will usually be requested from the source as it is needed, but it can also be gotten ahead of time asynchronously via the BASS_ATTRIB_SPLIT_ASYNCBUFFER attribute. When the BASS_SPLIT_DSP flag is set, data is received via a DSP function on the source, with the DSP chain position determined by the BASS_CONFIG_SPLIT_PRIORITY config option when the first splitter is created.

BASS_ChannelSetPosition cannot be used on a slave splitter stream. When BASS_ChannelSetPosition is used on a non-slave 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 the source's other splitter streams too but they will not be reset by default, so they will continue to receive any buffered old data before reaching data from the new position. The other splitter streams can be reset with BASS_Split_StreamReset, or the BASS_SPLIT_AUTORESET flag can be set on them to do it automatically.

Splitter streams can be linked via BASS_ChannelSetLink to have them start and stop playing together. If the source is a playback channel then the splitters should generally be linked to it rather than each other. To keep them in sync when changing position, it is best to pause them with BASS_ChannelPause before changing the source's position with BASS_ChannelSetPosition and resetting the splitters with BASS_Split_StreamReset and then resuming with BASS_ChannelStart.

Looping cannot be enabled (via the BASS_SAMPLE_LOOP flag) on a splitter stream but it can be on the source, if the source supports looping.

When a source is freed, all of its splitter streams are automatically freed.

Example

Create a splitter stream from a stereo source with the channels reversed.