BASS_Mixer_StreamAddChannel

Plugs a channel into a mixer.

BOOL BASS_Mixer_StreamAddChannel(
    HSTREAM handle,
    DWORD channel,
    DWORD flags
);

Parameters

handle

The mixer handle.

channel

The handle of the channel to plug into the mixer... a HMUSIC, HSTREAM or HRECORD.

flags

Any combination of these flags.

BASS_MIXER_CHAN_BUFFER	Buffer the sample data, for use by BASS_Mixer_ChannelGetData and BASS_Mixer_ChannelGetLevel and BASS_Mixer_ChannelGetLevelEx. This increases memory requirements, so should not be enabled needlessly. The size of the buffer can be controlled via the BASS_CONFIG_MIXER_BUFFER config option.
BASS_MIXER_CHAN_DOWNMIX	If the source uses channels/speakers that the mixer output does not have, then a matrix is created and initialized with a suitable downmixing matrix (for up to 8 channels). Note the source sample data is assumed to follow the standard channel ordering, as described in the STREAMPROC documentation.
BASS_MIXER_CHAN_LIMIT	Limit the mixer processing to the amount of data available from this source, while the source is active (not ended). If the source stalls, then the mixer will too, rather than continuing to mix other sources, as it would normally do. This flag can only be applied to one source per mixer, so it will automatically be removed from any other source of the same mixer.
BASS_MIXER_CHAN_MATRIX	Creates a matrix, allowing the source's channels to be sent to any of the mixer output channels, at any levels. The matrix can be retrieved and modified via the BASS_Mixer_ChannelGetMatrix and BASS_Mixer_ChannelSetMatrix functions. The matrix will initially contain a mapping of the source's channels to the mixer's corresponding channels, or a one-to-one mapping (1st out = 1st in, 2nd out = 2nd in, etc) if the BASS_MIXER_NOSPEAKER flag is set on the mixer.
BASS_MIXER_CHAN_NORAMPIN	Do not ramp-in the start, including after seeking (BASS_Mixer_ChannelSetPosition). This is useful for gapless playback, where a source channel is intended to seamlessly follow another. Even without this flag, ramping-in is skipped when the sample data begins at a low level (below -42dB). This does not affect volume and pan changes, which are always ramped.
BASS_MIXER_CHAN_PAUSE	Pause processing of the source. Use BASS_Mixer_ChannelFlags to resume processing.
BASS_STREAM_AUTOFREE	Automatically free the source channel when it ends. This allows you to add a channel to a mixer and forget about it, as it will automatically be freed when it has reached the end, or when the source is removed from the mixer or when the mixer is freed. When the mixer reaches the end of it, the source will be freed asynchronously (in another thread) to avoid delaying the mixer's other processing.
BASS_SPEAKER_xxx	Speaker assignment flags. If matrix mixing is enabled then the matrix will be initialized to place the source on the requested speaker(s), with downmixing also applied if the BASS_MIXER_CHAN_DOWNMIX flag is specified.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE	At least one of handle and channel is not valid.
BASS_ERROR_DECODE	channel is not a decoding channel.
BASS_ERROR_ALREADY	channel is already plugged into a mixer. It must be unplugged first.
BASS_ERROR_SPEAKER	The mixer does not support the requested speaker(s), or you are attempting to assign a stereo stream to a mono speaker.

Remarks

Internally, a mixer will use the BASS_ChannelGetData function to get data from its source channels. That means that the source channels must be decoding channels (not using a RECORDPROC in the case of a recording channel). Plugging a channel into more than one mixer at a time is not possible because the mixers would be taking data away from each other. An advantage of this is that there is no need for a mixer's handle to be provided with the channel functions. It is actually possible to plug a channel into multiple mixers by using splitter streams.

Channels can be removed with BASS_Mixer_ChannelRemove. They are also removed automatically when they are freed, or when they end in a queued mixer.

When mixing a channel, the mixer makes use of the channel's freq/volume/pan attributes, as set with BASS_ChannelSetAttribute. The BASS_CONFIG_CURVE_VOL and BASS_CONFIG_CURVE_PAN config option settings are also used. The channel's pan attribute has no effect when matrix mixing is enabled; panning can be applied in the matrix instead then.

If a multi-channel source has more channels than the mixer output then the extra channels will be discarded by default. For example, if a 5.1 source is plugged into a stereo mixer then only the front-left/right channels will be retained. If the mixer is multi-channel too, but not the same as the source, then the source may also end up on the wrong speakers due to differing channel layouts. Matrix mixing can be used to fix both issues. The default matrix will remap channels to the correct speakers (unless the BASS_MIXER_NOSPEAKER flag is set on the mixer) but will not include unavailable channels. The BASS_MIXER_CHAN_DOWNMIX flag can be used to enable downmixing and have the unavailable channels mixed into the available ones. When multiple channels are combined by that, their levels are lowered to reduce the chances of clipping, but they are not normalized, so some clipping is still possible. If wanted, the matrix can be normalized afterwards, or indeed a different downmixing matrix used, via BASS_Mixer_ChannelSetMatrix.

The mixer processing is performed in floating-point, so it makes sense (for both quality and efficiency reasons) for the source channels to be floating-point too, though they do not have to be. It is also more efficient if the source channels have the same sample rate as the mixer output because no sample rate conversion is required then. When sample rate conversion is required, windowed sinc interpolation is used and the source's BASS_ATTRIB_SRC attribute determines how many points/samples are used in that, as follows: 0 (or below) = 4 points, 1 = 8 points, 2 = 16 points, 3 = 32 points, 4 = 64 points, 5 = 128 points, 6 (or above) = 256 points. 8 points are used if the BASS_ATTRIB_SRC attribute is unavailable (old BASS version). A higher number of points results in better sound quality (less aliasing and narrower transition band in the low-pass filter), but also higher CPU usage.

Platform-specific