BASS_Init

Initializes an output device.

BOOL BASS_Init(
    int device,
    DWORD freq,
    DWORD flags,
    HWND win,
    void *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_16BITS	Limit the output to 16-bit.
BASS_DEVICE_MONO	Mono output.
BASS_DEVICE_STEREO	Limit the output to stereo, saving some CPU if the device has more speakers available.
BASS_DEVICE_SPEAKERS	Enable 8 speaker output (instead of stereo) when BASS is unable to detect the number of available speakers.
BASS_DEVICE_NOSPEAKER	Ignore speaker arrangement. This flag tells BASS to not make any special consideration for speaker arrangements when playing 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) devices.
BASS_DEVICE_FREQ	Set the device's output rate to freq, otherwise leave it as it is.
BASS_DEVICE_DSOUND	Initialize the device to use DirectSound output instead of WASAPI. If WASAPI is not available (pre-Vista Windows) then this will be applied automatically.
BASS_DEVICE_AUDIOTRACK	Initialize the device to use AudioTrack output instead of OpenSL ES or AAudio. If OpenSL ES and AAudio are not available (pre-2.3 Android) then this will be applied automatically.
BASS_DEVICE_DMIX	Initialize the device using the ALSA "dmix" plugin, else initialize the device for exclusive access. This will be applied automatically if the device cannot be initialized without it.
BASS_DEVICE_SOFTWARE	Disable hardware/fastpath output.
BASS_DEVICE_REINIT	Reinitialize the device while retaining the device's existing BASS channels and 3D settings. This flag cannot be used with device -1.

win

The application's main window... 0 = the desktop window (use this for console applications). This is only needed when using DirectSound output.

clsid

Unused. Set to NULL.

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_DEVICE	device is invalid.
BASS_ERROR_NOTAVAIL	The BASS_DEVICE_REINIT flag cannot be used when device is -1. Use the real device number instead.
BASS_ERROR_ALREADY	The device has already been initialized. The BASS_DEVICE_REINIT flag can be used to request reinitialization.
BASS_ERROR_ILLPARAM	win is not a valid window handle.
BASS_ERROR_DRIVER	There is no available device driver.
BASS_ERROR_BUSY	Something else has exclusive use of the device.
BASS_ERROR_FORMAT	The specified format is not supported by the device. Try changing the freq parameter.
BASS_ERROR_MEM	There is insufficient memory.
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.

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.

The default device (device = -1) maps to one of the real devices (not the no sound device). It will always be the "Default" device unless that has been disabled via the BASS_CONFIG_DEV_DEFAULT config option. BASS_GetDevice can be used afterwards to confirm which device is being used.

The BASS_CONFIG_DEV_BUFFER and BASS_CONFIG_DEV_PERIOD config options determine how much data is buffered for the device and how often it is updated.

When the BASS_DEVICE_REINIT flag is specified to request reinitialization, any BASS channels that were playing prior will continue to do so, if successful. But there is likely to be a small interruption to the sound, so it is best to reinitialize while nothing is playing. If reinitialization fails then playback will be paused and the device will be left in a partially-freed state. Reinitialization could be tried again with different parameters or BASS_Free used to fully free the device. Until BASS_Free is used, the device's BASS channels will still exist and can be moved to another device via BASS_ChannelSetDevice.

Platform-specific

The sample format specified in the freq and flags parameters has no effect on the output on macOS or iOS, or Windows Vista and above - the device's native sample format is automatically used. 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 macOS or iOS 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 Android, when the BASS_DEVICE_AUDIOTRACK flag is not specified, AAudio or OpenSL ES output may be used depending on the BASS_CONFIG_ANDROID_AAUDIO config option setting. AAudio has a low latency mode, which will be enabled when BASS_CONFIG_DEV_BUFFER is set below 50.

The win parameter is only used with DirectSound output on Windows and is ignored in all other cases. The BASS_DEVICE_STEREO flag is ignored on macOS and Windows, except when using DirectSound output.

The BASS_DEVICE_SOFTWARE flag is only used on Windows to disable DirectSound hardware mixing and on Android to disable AAudio fastpath output.

The BASS_DEVICE_SPEAKERS flag only has effect on Linux, typically when using PulseAudio or PipeWire output.

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.

Example

Initialize BASS to use the default output device with a nominal rate of 44100 Hz.

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