c-snd

swgysnd is a small C audio library built on SDL2. It loads WAV files from disk and plays them through the system audio device, with per-sound stereo balance and mixing of several sounds at once. The repository ships the library (libswgysnd), a manual page, and a condition-generator tool that writes event scripts for listening-environment experiments.

Goals

The library exists to drive audio playback for psychoacoustic and listening-environment research, where stimuli need to be triggered on cue and positioned in the stereo field. It keeps the surface area small so that an experiment harness can load a set of cues up front and fire them by handle while the run is in progress. Format handling stays out of the caller's way, since incoming WAVs are converted to a single internal representation at load time.

Capabilities

• Loads WAV files and converts each one to signed 16-bit stereo at the file's native sample rate.
• Holds up to 128 loaded sounds at once, each referenced by an integer handle returned at load time.
• Mixes up to 8 sounds playing simultaneously inside an SDL audio callback.
• Applies a stereo balance per playback, from full left (-1.0) through center (0.0) to full right (+1.0). Values beyond that range are clamped.
• Opens the audio device lazily on the first successful load and releases every loaded sound, channel, and the device itself on shutdown.

API

• swgysnd_init(void) starts SDL audio and clears internal state. Call it before anything else.
• swgysnd_loadwav(const char *path, int *handle_out) loads and converts a WAV, writing its handle to handle_out.
• swgysnd_playwav(int handle, double balance) starts the sound on the next free channel at the given balance.
• swgysnd_freewav(int handle) releases one loaded sound.
• swgysnd_shutdown(void) stops playback, frees every loaded sound, and closes the audio device.
• swgysnd_version_str(void) returns the library version string.

Basic usage

The calling program defines the verbose symbol that the library reads for its diagnostic output. A minimal program loads a sound, plays it twice with different balance, waits for it to finish, and shuts down.

#include <SDL2/SDL.h>
#include "swgysnd.h"

int verbose = 0;

int
main(void)
{
        int beep;

        if (swgysnd_init() != 0)
                return 1;

        if (swgysnd_loadwav("beep.wav", &beep) != 0)
                return 1;

        swgysnd_playwav(beep, 0.0);   /* centered */
        swgysnd_playwav(beep, 0.5);   /* halfway right */

        SDL_Delay(2000);              /* let playback finish */

        swgysnd_shutdown();
        return 0;
}

Build the library with the supplied BSD Makefile, which compiles swgysnd.c and links against SDL2. See swgysnd.3 for the manual page and README.md for the package requirements.