BASS.NET API for the Un4seen BASS Audio LibraryBassMixBASS_Split_StreamCreate Method BASS.NET API for the Un4seen BASS Audio Library
Creates a splitter stream (adds a reader channel to a decoding source channel).

Namespace: Un4seen.Bass.AddOn.Mix
Assembly: Bass.Net (in Bass.Net.dll) Version: 2.4.12.0
Syntax

[DllImportAttribute("bassmix.dll", CharSet = CharSet.Unicode)]
public static int BASS_Split_StreamCreate(
	int channel,
	BASSFlag flags,
	int[] mapping
)

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_SOFTWAREForce the stream to not use hardware mixing.
BASS_SAMPLE_3DUse 3D functionality. This is ignored if BASS_DEVICE_3D wasn't specified when calling BASS_Init(Int32, Int32, BASSInit, IntPtr). 3D streams must be mono. The SPEAKER flags can not be used together with this flag.
BASS_SAMPLE_FXRequires DirectX 8 or above: Enable the old implementation of DirectX 8 effects. See the DX8 effect implementations section for details. Use BASS_ChannelSetFX(Int32, BASSFXType, Int32) to add effects to the stream.
BASS_STREAM_AUTOFREEAutomatically 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_DECODESplit 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_SLAVEOnly get data from the splitter buffer, not directly from the source.
BASS_SPEAKER_xxxSpeaker 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

Type: Int32
If successful, the new reader stream's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.
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. Like mixer sources, splitter sources must be decoding channels.

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.

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.

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).

ERROR CODEDescription
BASS_ERROR_INITBASS_Init(Int32, Int32, BASSInit, IntPtr) has not been successfully called.
BASS_ERROR_HANDLEThe channel is not valid.
BASS_ERROR_DECODEThe channel is not a decoding channel.
BASS_ERROR_ILLPARAMThe mapping contains an invalid channel index.
BASS_ERROR_NOTAVAILOnly decoding streams (BASS_STREAM_DECODE) are allowed when using the "no sound" device. The BASS_STREAM_AUTOFREE flag is also unavailable to decoding channels.
BASS_ERROR_FORMATThe sample format is not supported by the device/drivers. If the stream is more than stereo or the BASS_SAMPLE_FLOAT flag is used, it could be that they are not supported (ie. no WDM drivers).
BASS_ERROR_SPEAKERThe device/drivers do not support the requested speaker(s), or you're attempting to assign a stereo stream to a mono speaker.
BASS_ERROR_MEMThere is insufficent memory.
BASS_ERROR_NO3DCouldn't initialize 3D support for the stream.
BASS_ERROR_UNKNOWNSome other mystery problem!

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.

Examples

Create two 1:1 clones:
VB
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)
...
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);
...
Here are some more channel mapping examples...
// 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};
See Also

Reference