BASS

BASS_Init

Initializes an output device.

BOOL BASS_Init(
    int device,
    DWORD freq,
    DWORD flags,
    HWND win,
    GUID *clsid
);

Parameters

device

The device to use... -1 = default device, 0 = no sound, 1 = first real output device. BASS_GetDeviceInfo can be used to enumerate the available devices.

freq

Output sample rate.

flags

A combination of these flags.

BASS_DEVICE_8BITS	Use 8-bit resolution, else 16-bit.
BASS_DEVICE_MONO	Use mono, else stereo.
BASS_DEVICE_3D	Enable 3D functionality.
BASS_DEVICE_LATENCY	Calculates the latency of the device, that is the delay between requesting a sound to play and it actually being heard. A recommended minimum buffer length is also calculated. Both values are retrievable in the BASS_INFO structure (latency & minbuf members). These calculations can increase the time taken by this function by 1-3 seconds.
BASS_DEVICE_CPSPEAKERS	Use the Windows control panel setting to detect the number of speakers. Soundcards generally have their own control panel to set the speaker config, so the Windows control panel setting may not be accurate unless it matches that. This flag has no effect on Vista, as the speakers are already accurately detected.
BASS_DEVICE_SPEAKERS	Force the enabling of speaker assignment. With some devices/drivers, the number of speakers BASS detects may be 2, when the device in fact supports more than 2 speakers. This flag forces the enabling of assignment to 8 possible speakers. This flag has no effect with non-WDM drivers.
BASS_DEVICE_NOSPEAKER	Ignore speaker arrangement. This flag tells BASS not to make any special consideration for speaker arrangements when 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) devices.
BASS_DEVICE_FREQ	Set the device's output rate to freq, otherwise leave it as it is.
BASS_DEVICE_DMIX	Initialize the device using the ALSA "dmix" plugin, else initialize the device for exclusive access.

win

The application's main window... 0 = the desktop window (use this for console applications).

clsid

Class identifier of the object to create, that will be used to initialize DirectSound... NULL = use default.

Return value

If the device was successfully initialized, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_DX	DirectX (or ALSA on Linux or OpenSL ES on Android) is not installed.
BASS_ERROR_DEVICE	device is invalid.
BASS_ERROR_ALREADY	The device has already been initialized. BASS_Free must be called before it can be initialized again.
BASS_ERROR_DRIVER	There is no available device driver. The device may already be in use.
BASS_ERROR_FORMAT	The specified format is not supported by the device. Try changing the freq and flags parameters.
BASS_ERROR_MEM	There is insufficient memory.
BASS_ERROR_NO3D	Could not initialize 3D support.
BASS_ERROR_UNKNOWN	Some other mystery problem!

Remarks

This function must be successfully called before using any sample, stream or MOD music functions. The recording functions may be used without having called this function.

Playback is not possible with the "no sound" device, but it does allow the use of "decoding channels", eg. to decode files.

Simultaneously using multiple devices is supported in the BASS API via a context switching system; instead of there being an extra "device" parameter in the function calls, the device to be used is set prior to calling the functions. BASS_SetDevice is used to switch the current device. When successful, BASS_Init automatically sets the current thread's device to the one that was just initialized.

When using the default device (device = -1), BASS_GetDevice can be used to find out which device it was mapped to.

Platform-specific

On Linux, a "Default" device is hardcoded to device number 1, which uses the default output set in the ALSA config; that could map directly to one of the other devices or it could use ALSA plugins. If the BASS_CONFIG_DEV_DEFAULT config option has been enabled, a "Default" device is also available on Windows, who's output will follow default device changes on Windows 7. In both cases, the "Default" device will also be the default device (device = -1)

The sample format specified in the freq and flags parameters has no effect on the device output on iOS or OSX, and not on Windows unless VxD drivers are used (on Windows 98/95); with WDM drivers (on Windows XP/2000/Me/98SE), the output format is automatically set depending on the format of what is played and what the device supports, while on Vista and newer, the output format is determined by the user's choice in the Sound control panel. On Linux, the output device will use the specified format if possible, but will otherwise use a format as close to it as possible. On Android, the device's native sample rate (as reported by the AudioTrack getNativeOutputSampleRate method) will be used unless the BASS_DEVICE_FREQ flag is specified, in which case the freq parameter will be used (this only affects BASS's output format, not the device's output format). If the BASS_DEVICE_FREQ flag is specified on iOS or OSX, then the device's output rate will be set to the freq parameter if possible. The BASS_DEVICE_FREQ flag has no effect on other platforms. BASS_GetInfo can be used to check what the output format actually is.

On Windows, when specifying a class identifier (clsid), BASS_GetDSoundObject can be used to retrieve the DirectSound object after successful initialization, and through that access any special interfaces that the object may provide.

The win and clsid parameters are only used on Windows and are ignored on other platforms. That applies to the BASS_DEVICE_CPSPEAKERS and BASS_DEVICE_SPEAKERS flags too, as the number of available speakers is always accurately detected on the other platforms. The BASS_DEVICE_LATENCY flag is also ignored on those other platforms, as latency information is available without it.

The BASS_DEVICE_DMIX flag is only available on Linux, and allows multiple applications to share the device (if they all use "dmix"). It may also be possible for multiple applications to use exclusive access if the device is capable of hardware mixing. If exclusive access initialization fails, the BASS_DEVICE_DMIX flag will automatically be tried; if that happens, it can be detected via BASS_GetInfo and the initflags.

On Linux, Android, and Windows CE, the length of the device's buffer can be set via the BASS_CONFIG_DEV_BUFFER config option.

Example

Initialize BASS to use the default output device, and a nominal format of 44100 Hz stereo 16-bit.

BASS_Init(-1, 44100, 0, hwnd, NULL);