BASS_Mixer_StreamAddChannelEx


Plugs a channel into a mixer, optionally delaying the start and limiting the length.

BOOL BASS_Mixer_StreamAddChannelEx(
    HSTREAM handle,
    DWORD channel,
    DWORD flags,
    QWORD start,
    QWORD length
);

Parameters

handleThe mixer handle.
channelThe handle of the channel to plug into the mixer... a HMUSIC, HSTREAM or HRECORD.
flagsAny combination of these flags.
BASS_MIXER_MATRIXCreates a channel 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 one-to-one mapping, eg. left out = left in, right out = right in, etc...
BASS_MIXER_DOWNMIXIf the source has more channels than the mixer output (and the mixer is stereo or mono), then a channel matrix is created, initialized with the appropriate downmixing matrix. Note the source data is assumed to follow the standard channel ordering, as described in the STREAMPROC documentation.
BASS_MIXER_BUFFERBuffer the sample data, for use by BASS_Mixer_ChannelGetData and BASS_Mixer_ChannelGetLevel and 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_LIMITLimit 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_NORAMPINDo not ramp-in the start, including after seeking (BASS_Mixer_ChannelSetPosition). This is useful for gap-less playback, where a source channel is intended to seamlessly follow another. This does not affect volume and pan changes, which are always ramped.
BASS_MIXER_PAUSEPause processing of the source. Use BASS_Mixer_ChannelFlags to resume processing.
BASS_STREAM_AUTOFREEAutomatically 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.
BASS_SPEAKER_xxxSpeaker assignment flags. Ignored when using the BASS_MIXER_MATRIX or BASS_MIXER_DOWNMIX flag. The BASS_Init BASS_DEVICE_NOSPEAKER flag has effect here.
startDelay (in bytes) before the channel is mixed in.
lengthThe maximum amount of data (in bytes) to mix... 0 = no limit. Once this end point is reached, the channel will be removed from the mixer.

Return value

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

Error codes

BASS_ERROR_HANDLEAt least one of handle and channel is not valid.
BASS_ERROR_DECODEchannel is not a decoding channel.
BASS_ERROR_ALREADYchannel is already plugged into a mixer. It must be unplugged first.
BASS_ERROR_SPEAKERThe mixer does not support the requested speaker(s), or you are attempting to assign a stereo stream to a mono speaker.

Remarks

This function is identical to BASS_Mixer_StreamAddChannel, but with the additional ability to specify a delay and duration for the channel.

The start and length parameters relate to the mixer output. So when calculating these values, use the mixer stream's sample format rather than the source channel's. The start parameter is automatically rounded-down to the nearest sample boundary, while the length parameter is rounded-up to the nearest sample boundary.

Example

Add a channel to a mixer, delaying the start by 1 second and limiting the duration to 2 seconds.
QWORD start=BASS_ChannelSeconds2Bytes(mixer, 1); // delay
QWORD length=BASS_ChannelSeconds2Bytes(mixer, 2); // duration
BASS_Mixer_StreamAddChannelEx(mixer, channel, 0, start, length); // add the channel

See also

BASS_Mixer_ChannelFlags, BASS_Mixer_ChannelGetLevel, BASS_Mixer_ChannelGetMixer, BASS_Mixer_ChannelGetPosition, BASS_Mixer_ChannelRemove, BASS_Mixer_ChannelSetMatrix, BASS_Mixer_ChannelSetPosition, BASS_Mixer_StreamAddChannel, BASS_Mixer_StreamCreate