|
InitSoundSystemEx method |
  
|
|
InitSoundSystemEx method |
|
Remarks
Initializes the control: the call to this method is always mandatory when the control is instanced inside the container form and must be performed before calling any other method that will use any player related functionality, possibly from the initialization routine of the container form or dialog: calling this method inside the constructor function of the container form will not work and could cause unpredictable results.
In case the component should be instanced in conjunction with the recorder component and/or the editor component, this method should be called before calling the initialization methods of the other components (InitRecordingSystem for the recorder component and InitEditor for the editor component).
The purpose of this initialization method is to allocate the desired number of players (*), to synchronize the control with the container form, to set the output device (sound card) for the first 4 allocated players (players exceeding the fourth one will automatically output their sound flow into the system default sound card) and, eventually, setting the DirectX buffer length in order to reduce the latency time.
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 StreamOutputDeviceSet 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.
Syntax
[Visual Basic] Public Function InitSoundSystemEx ( nTotalPlayers as Int16, nOutput0 as Int16, nOutput1 as Int16, nOutput2 as Int16, nOutput3 as Int16, nBufferLength as Int16 ) As Int16 |
[C#] public Int16 InitSoundSystemEx ( Int16 nTotalPlayers, Int16 nOutput0, Int16 nOutput1, Int16 nOutput2, Int16 nOutput3, Int16 nBufferLength ); |
[C++] public: Int16 InitSoundSystemEx ( Int16 nTotalPlayers, Int16 nOutput0, Int16 nOutput1, Int16 nOutput2, Int16 nOutput3, Int16 nBufferLength ); |
Parameter |
Description |
|
|
nTotalPlayers |
Number of players (*) that must be allocated by the control. |
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. |
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. |
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. |
nBufferLength |
Number representing the length in milliseconds of the DirectX buffer. By default the buffer size contains 500 milliseconds: see the How to deal with latency section for further details about this parameter. |
Examples of use of the nOutputX parameters
As mentioned inside the tutorials, you can obtain the number of sound cards installed inside the system by invoking the GetOutputDevicesCount method and storing its return value into a numeric variable named, 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 (*)
nOutput0 = 0
nOutput1 = 0
nOutput2 = 2
nOutput3 = 1
Return value
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. In order to know if all of the instanced players have been set to operate with a valid output device, you should check the value of the LastError property: if it should have value 2 (WARNING_INVALID_DEVICE), this would mean that one or more of the nOutputX parameters where set to an invalid output device: in this case a reset of the multimedia engine (ResetEngine method) and of the control (ResetControl method) would be needed in order to set correct output devices. |
(*) 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.
