How to use custom Stream Mixers
Custom Stream Mixers allows mixing the output of a number of players into one single audio stream before outputting the audio stream itself to a chosen output. The graph below summarizes the available features of a custom Stream Mixer:
As you may know, a player can generate a PCM stream from a sound file or, through the interaction with Active Sound Recorder, from an input channel; as seen on the graph above, the mixing result, on which it's still possible applying further effects (for example changing the volume of the mixed stream or changing the output device), can be redirected to one or more of the following destinations:
|•||Directly to DirectSound and to the selected sound card.|
|•||Through the use of an external encoder (Lame.exe for MP3, Fdkaac.exe for AAC+, OggEnc.exe for Ogg Vorbis), to a streaming server (SHOUTcast, Icecast and Windows Media Services are currently supported): in this case the control behaves as a "streaming server source".|
|•||In combination with our Active Sound Recorder control, directly to an output file whose format can be predisposed inside Active Sound Recorder itself.|
It's very important to note that the three destinations described above can be applied all at the same time: this means that you can hear what is being played and mixed on your local speakers, at the same time you can send what you are hearing to a streaming server and, again at the same time, save what you are hearing into a file on your hard disk.
The first thing to do is to create an instance of the Stream Mixer: for this purpose you can use the StreamMixerCreate method: through this call you can pass the index of the output device that will be used in order to render the audio stream; the number and descriptions of available output devices can be obtained with a prior call to the GetOutputDevicesCount and GetOutputDeviceDesc methods; if no output device should be chosen (by passing -1 to the nOutput parameter), you could in any case output the audio stream to the Active Sound Recorder control or to a streaming server.
A successful call to the StreamMixerCreate method will return a unique identifier that will be used with other mixer-related methods calls. Once we have created an instance of the Stream Mixer and we have obtained back a unique identifier, we can start adding players to the instance of the Stream Mixer: for this purpose we need to call the StreamMixerPlayerAdd method; after this call the added player will no more send its audio stream to the output device chosen inside the InitDJSystem method but will redirect its audio stream into the Stream Mixer as seen in the graph above. A player can be removed from the Stream Mixer through the StreamMixerPlayerRemove method.
The unique identifier allows applying further effects to mixed streams, for example applying a custom DSP or modifying the Preamplifier volume: for this purpose the unique identifier can be used in place of the nPlayer parameter for all of the methods that will modify the output stream, like volume-related methods and all methods described inside the How to apply special effects to a playing sound tutorial. In the same way you have the possibility to redirect the mixed stream to a different output device through the StreamOutputDeviceSet method or to perform speakers management through the StreamOutputSpeakerSet method.
Another important feature is the possibility to create visual feedbacks that display sound levels of the stream mixer output: also in this case you simply have to use the unique identifier of the stream mixer as a replacement for the nPlayer parameter used with VUMeter, Spectrum, Oscilloscope and Waveform objects; this feature affects the VuMeterValueChange and SpectrumValueChange events as well: their nPlayer parameter will report the unique identifier of the stream mixer generating the event.
The mixed stream can be sent to a Shoutcast or Icecast server through the CastingCreateFromStreamMixer method followed by a call to the CastingStart method; casting can be stopped at any time through a call to the CastingStop method. For further details about audio stream casting take a look to the tutorial How to use the control as a source for Shoutcast/Icecast servers.
In order to save the mixed audio stream into an output file, we need to use our Active DJ Studio control in combination with our Active Sound Recorder control: the StartFromDjStudioMixer method of the recorder component will record the audio stream generated by the Stream Mixer and will encode it by using settings predisposed inside the EncodeFormats object of the recorder component itself.
Stream mixers created through the StreamMixerCreate method can be in Mono or Stereo only: in case you should need to create a multi-channel surround stream mixer you could use the StreamMixerCreateWithSurround method which allows to output mixed streams up to 8 channels: when using surround mode, the output of the stream mixer cannot be used as a source for casting sessions. When dealing with multi-channel surround stream mixers, you can add players to the instance of the Stream Mixer through the StreamMixerPlayerAddToSpeaker method which allows setting the specific speaker (channel) of the stream mixer used for outputting the player's audio stream.
IMPORTANT NOTICE ABOUT EFFECTS APPLIED TO THE OUTPUT OF THE STREAM MIXER BEING SENT TO A CASTING SERVER OR TO THE RECORDER
As mentioned before, you can apply a custom DSP or a VST effect to the output of the custom stream mixer by using the unique identifier of the custom stream mixer itself for the nPlayer parameter of the effect to apply; if you want that these effects are reflected to the stream going to the casting server or to the recorder control also, you need to set the nPriority parameter of the custom DSP or of the VST to a value higher than 0.
Samples of use of custom Stream Mixers in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:
- StreamMixer (requires the installation of Active Sound Suite)