BASS_Mixer_StreamCreate

Creates a mixer stream. 

HSTREAM BASS_Mixer_StreamCreate(
    DWORD freq,
    DWORD chans,
    DWORD flags
);

Parameters

freqThe sample rate of the mixer output.
chansThe number of channels... 1 = mono, 2 = stereo, 4 = quadraphonic, 6 = 5.1, 8 = 7.1.
flagsAny combination of these flags.
BASS_SAMPLE_8BITSProduce 8-bit output. If neither this or the BASS_SAMPLE_FLOAT flags are specified, then the stream is 16-bit.
BASS_SAMPLE_FLOATProduce 32-bit floating-point output. See Floating-point channels for more info.
BASS_SAMPLE_3DEnable 3D functionality. The stream must be mono (chans=1). The SPEAKER flags cannot be used together with this flag.
BASS_STREAM_AUTOFREEAutomatically free the stream when playback ends.
BASS_STREAM_DECODEMix the sample data, without playing it. Use BASS_ChannelGetData to retrieve the mixed sample data. The BASS_SAMPLE_3D, BASS_STREAM_AUTOFREE and SPEAKER flags cannot be used together with this flag.
BASS_MIXER_ENDEnd the stream when there are no active (including stalled) source channels, else it is never-ending.
BASS_MIXER_NONSTOPDo not stop producing output when there are no active source channels, else it will be stalled until there are active sources.
BASS_MIXER_NOSPEAKERIgnore speaker arrangement. This flag tells BASSmix to not make any special consideration for speaker arrangements when mixing multi-channel content or using the SPEAKER flags, eg. swapping the CENLFE and REAR speaker channels in 5/7.1 speaker output. This flag should be used with plain multi-channel (rather than 5/7.1) output.
BASS_MIXER_POSEXKeep a record of the source positions, making it possible to account for output latency when retrieving a source position. How far back the position record goes is determined by the BASS_CONFIG_MIXER_POSEX config option. If this flag is not used and neither is the BASS_STREAM_DECODE flag then the mixer will automatically have a position record of equal length to the BASS_CONFIG_BUFFER setting.
BASS_MIXER_QUEUEPlay the sources one at a time, in the order that they were added.
BASS_MIXER_RESUMEWhen stalled, resume the mixer immediately upon a source being added or unpaused, else it will be resumed at the next update cycle.
BASS_SPEAKER_xxxSpeaker assignment flags. These flags have no effect when the stream is more than stereo.

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_INITBASS_Init has not been successfully called.
BASS_ERROR_NOTAVAILThe BASS_STREAM_AUTOFREE flag cannot be combined with the BASS_STREAM_DECODE flag.
BASS_ERROR_FORMATThe sample format is not supported.
BASS_ERROR_SPEAKERThe specified SPEAKER flags are invalid.
BASS_ERROR_MEMThere is insufficient memory.
BASS_ERROR_NO3DCould not initialize 3D support.
BASS_ERROR_UNKNOWNSome other mystery problem!

Remarks

Source channels are added to a mixer using the BASS_Mixer_StreamAddChannel or BASS_Mixer_StreamAddChannelEx functions, and removed using the BASS_Mixer_ChannelRemove function. Sources can be added and removed at any time. So a mixer does not have a definite length, but one will be calculated by BASS_ChannelGetLength from the current sources if their lengths are all known and none of them are looping without a limit, and the mixer is not nonstopping (BASS_MIXER_NONSTOP).

If the mixer output is being played, there will be some delay in the effect of adding/removing source channels or changing their attributes being heard, due to buffering. This latency can be reduced via the BASS_ATTRIB_BUFFER attribute. The playback buffer can be flushed by calling BASS_ChannelPlay (restart = TRUE) or BASS_ChannelSetPosition (pos = 0). That can also be done to restart a mixer that has ended.

Seeking in a mix via BASS_ChannelSetPosition directly is not possible, but seeking can be implemented by setting the position of each source to where it would be at the seek position, and then flushing the mixer's playback buffer (see above) if required.

Unless the BASS_MIXER_END flag is specified, a mixer stream will never end. When there are no sources (or the sources have ended/stalled), it will produce no output until there is an active source. That is unless the BASS_MIXER_NONSTOP flag is used, in which case it will produce silent output while there are no active sources. The BASS_MIXER_END and BASS_MIXER_NONSTOP flags can be toggled at any time, using BASS_ChannelFlags.

A queued mixer, with the BASS_MIXER_QUEUE flag set, will play its sources one after another in the order that they were added, without a gap unless a delay is specified with BASS_Mixer_StreamAddChannelEx. After a source has been played, it will be removed from the mixer. Queueing can be enabled or disabled at any time using BASS_ChannelFlags. If it is disabled that way then all currently queued sources will start immediately, and if it is enabled then any current sources will continue to play normally and newly queued sources will start when the current ones have all ended. A BASS_SYNC_MIXER_QUEUE sync can be set to be notified whenever a source is dequeued.

Besides mixing channels, a mixer stream can be used for sample rate conversion. In that case the freq parameter would be set to the new sample rate, and the source channel's attributes would be left at their defaults. A mixer stream can also be used to downmix, upmix and generally rearrange channels, using the matrix mixing features.

By default, a mixer is single-threaded, meaning it will process its sources one at a time. When there are multiple sources and multiple CPU cores available, it may be advantageous to enable multiple threads via the BASS_ATTRIB_MIXER_THREADS setting.

See also

BASS_Mixer_StreamAddChannel, BASS_Mixer_StreamAddChannelEx, BASS_ATTRIB_MIXER_THREADS, BASS_ATTRIB_MIXER_VOL

BASS_ChannelPlay, BASS_StreamFree