Sfxlib Backends
Output and capture backends used by FreeBASIC's built-in sound library.
sfxlib has a shared command layer and mixer, but it still needs a platform backend to talk to the actual operating system or hardware. The backend is the part that sends mixed audio to speakers, receives captured input, or talks to a platform MIDI system.
Most programs do not need to select a backend manually. sfxlib tries the compiled backend list for the target and uses a working output path. The DEVICE command family exists for diagnostics and programs that want to show or choose the available audio paths.
The null driver is special. It accepts sound output but does not play it through speakers. This is useful for automated tests, package smoke tests, servers, and systems where audio hardware is not available.
Set SFXLIB_DRIVER=null before program startup to request the null driver when it is available. That lets a program exercise parsing, linking, mixing, and shutdown without requiring a real audio device.
For native Linux example checks, build_scripts/test-sfx-examples.py runs both compiler backends with the genuine null driver. It limits diagnostic dumps to 8192 frames, checks finite submitted samples, independently reads the MIDI/stress WAV captures, and opens the composer on its own authenticated X display. These checks cover software execution and file output; they do not establish speaker, microphone or external MIDI-device operation.
Use --driver pulse --private-pulse with that runner to check the genuine PulseAudio backend against a separate clocked null sink. The helper creates its own authenticated Unix socket and D-Bus session, then stops the service when the run ends. It does not change an existing desktop sound service. --driver alsa checks the ALSA backend using the caller's selected ALSA configuration; a process-local ALSA null PCM can be used on a headless test host.
ALSA and PulseAudio diagnostic dumps contain only samples accepted by the native API. ALSA short writes advance the buffer offset, and zero-frame writes use the same bounded retry budget as interrupted or temporarily unavailable writes. Diagnostic dumps remain optional and capped; successful software-sink checks do not establish physical speaker operation.
Description
sfxlib has a shared command layer and mixer, but it still needs a platform backend to talk to the actual operating system or hardware. The backend is the part that sends mixed audio to speakers, receives captured input, or talks to a platform MIDI system.
Most programs do not need to select a backend manually. sfxlib tries the compiled backend list for the target and uses a working output path. The DEVICE command family exists for diagnostics and programs that want to show or choose the available audio paths.
The null driver is special. It accepts sound output but does not play it through speakers. This is useful for automated tests, package smoke tests, servers, and systems where audio hardware is not available.
Common backends
- Windows: WASAPI, WinMM, and the null driver.
- Linux: PulseAudio, ALSA, and the null driver.
- macOS: CoreAudio and the null driver.
- Android: AAudio, OpenSL ES, and the null driver.
- JavaScript: WebAudio and the null driver.
- Haiku: native Haiku audio and the null driver.
- DOS: Sound Blaster, PC speaker, and target-specific MIDI support where available.
- BSD targets: OSS-style backends; OpenBSD uses sndio.
- Solaris-like targets: the platform audio device backend.
- Wii: ASND.
- Xbox: XAudio.
Testing
Set SFXLIB_DRIVER=null before program startup to request the null driver when it is available. That lets a program exercise parsing, linking, mixing, and shutdown without requiring a real audio device.
For native Linux example checks, build_scripts/test-sfx-examples.py runs both compiler backends with the genuine null driver. It limits diagnostic dumps to 8192 frames, checks finite submitted samples, independently reads the MIDI/stress WAV captures, and opens the composer on its own authenticated X display. These checks cover software execution and file output; they do not establish speaker, microphone or external MIDI-device operation.
Use --driver pulse --private-pulse with that runner to check the genuine PulseAudio backend against a separate clocked null sink. The helper creates its own authenticated Unix socket and D-Bus session, then stops the service when the run ends. It does not change an existing desktop sound service. --driver alsa checks the ALSA backend using the caller's selected ALSA configuration; a process-local ALSA null PCM can be used on a headless test host.
ALSA and PulseAudio diagnostic dumps contain only samples accepted by the native API. ALSA short writes advance the buffer offset, and zero-frame writes use the same bounded retry budget as interrupted or temporarily unavailable writes. Diagnostic dumps remain optional and capped; successful software-sink checks do not establish physical speaker operation.
See also