InitSoundSystem method (A)

InitSoundSystem method

Initialises the control keeping the default 500 milliseconds DirectSound buffer length. Its purpose is to allocate the desired number of players (*), to synchronise the control with the container form and to set the output device (sound card) for each of the allocated players: if using the Light edition of the control, the system default sound card is the unique available output device.

Use the value returned by the GetOutputDevicesCount method in order to know how many output devices are currently installed on the system and the GetOutputDeviceDesc method in order to retrieve the friendly name of every output device.

The output device for a certain player can be changed at a later time using the SetPlayerOutputDevice method.

For further details about multi-player management, take a look to the How to deal with multi-player features section.

For further details about output devices management, take a look to the How to work with multiple output devices and speakers section.

[Visual Basic]

Public Function InitSoundSystem (

nTotalPlayers as Int16,

nOutput0 as Int16,

nOutput1 as Int16,

nOutput2 as Int16,

nOutput3 as Int16,

) As Int16

[C#]

public Int16 InitSoundSystem (

Int16 nTotalPlayers,

Int16 nOutput0,

Int16 nOutput1,

Int16 nOutput2,

Int16 nOutput3,

);

[C++]

public: Int16 InitSoundSystem (

Int16 nTotalPlayers,

Int16 nOutput0,

Int16 nOutput1,

Int16 nOutput2,

Int16 nOutput3,

);

Parameter	Description

nTotalPlayers	Number of players that must be allocated by the control: if the requested number exceed the maximum allowed by the control you purchased (*) then the number will be cut to the number of available players
nOutput0	Number representing the zero-based index of the output device (sound card) that will be used for playback by player 0 (pass 0 for using the system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis. Check the How to use the control in your projects section for details about obtaining output devices. If the multimedia engine shouldn't find any enabled or valid output device, the container application would be notified through the WarnNoOutputDevice event.
nOutput1	Number representing the zero-based index of the output device (sound card) that will be used for playback by player 1 (use 0 for system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis.
nOutput2	Number representing the zero-based index of the output device (sound card) that will be used for playback by player 2 (use 0 for system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis. This parameter is ignored when using the Light edition of the control.
nOutput3	Number representing the zero-based index of the output device (sound card) that will be used for playback by player 3 (use 0 for system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis. This parameter is ignored when using the Light edition of the control.

Examples of use of the nOutputX parameters

We have already told that you can obtain the number of sound cards calling the GetOutputDevicesCount method and storing its return value into a numeric variable called, for example, nCount.

Example 1: nCount value is 1

Suppose that you must allocate two players (0 and 1); you have only one sound card that, for exclusion, will be the default one, so you can set the following values:

nTotalPlayers = 2 (*)

nOutput0 = 0 (use default sound card)

nOutput1 = 0 (use default sound card)

nOutput2 = 0 (value ignored)

nOutput3 = 0 (value ignored)

Example 2: nCount value is 3

Call the GetOutputDeviceDesc method nCount times (once for every sound card) using a zero-based index in order to obtain every sound card friendly name (suppose you obtain A, B and C).

Now suppose that you must allocate four players (0, 1, 2 and 3) that will redirect their output in the following way:

- player 0 and player 1 must output to the system default sound card A.

- player 2 must output to sound card C.

- player 3 must output to sound card B.

You will have to call the InitSoundSystem method with the following parameters:

nTotalPlayers = 4 (*)

Value	Meaning

0	An error occurred, check the LastError property value in order to get the error code
Value > 0	The method completed successfully and this value represents the number of allocated players; if this value is smaller than the value set through the nTotalPlayers parameter, check the maximum number of players supported by the control you purchased (*)

(*) A "player" can be compared to a physical "deck" on a DJ console, the place where you put the vinyl/CD to be played; the developer can create a console with many virtual decks that can play simultaneously many different songs on one or more sound cards, each deck having its own volume/tempo/pitch settings. The availability of a certain number of players (decks) will enable the container application to mix several songs on different output channels, giving for example the ability to play advertising spots while songs are being played/mixed on different output channels: this is very useful for multi-channel radio stations automation software.