SDL Audio Streaming: Practical Resampling with SDL_AudioStream for Cross-Platform Audio

The Problem: Mismatched Audio Formats Break Playback

When your audio source runs at 48kHz stereo but your output device expects 44.1kHz stereo, you can't just copy the samples. The channel count and sample rate mismatch causes distortion, silence, or outright failure. SDL_AudioStream solves this by providing a portable buffer that handles format conversion on the fly.

The Solution: SDL_AudioStream for Format Conversion

SDL_AudioStream is a stateful converter that accumulates input audio and flushes properly formatted output. It handles sample rate conversion, channel remapping, and format transcoding without requiring you to implement the math yourself.

Creating the Stream

Use SDL_NewAudioStream() with your source and destination specifications:

SDL_AudioSpec src = {0};
src.freq = 48000;
src.format = AUDIO_F32;
src.channels = 2;

src.channels = 2;

SDL_AudioSpec dst = {0};
dst.freq = 44100;
dst.format = AUDIO_S16;
dst.channels = 2;

SDL_AudioStream *stream = SDL_NewAudioStream(&src, &dst);
if (!stream) {
    fprintf(stderr, "Failed to create stream: %s\n", SDL_GetError());
    return -1;
}

Feeding and Flushing Data

Accumulate source data with SDL_AudioStreamPut() then retrieve converted output with SDL_AudioStreamGet():

// In your audio callback or processing loop
void process_audio(SDL_AudioStream *stream, const void *input, int len) {
    SDL_AudioStreamPut(stream, input, len);
    
    uint8_t output_buffer[4096];
    int out_len = sizeof(output_buffer);
    
    while (SDL_AudioStreamGet(stream, output_buffer, &out_len) > 0) {
        // Write output_buffer to audio device
        play_audio(output_buffer, out_len);
        out_len = sizeof(output_buffer);
    }
}

// When shutting down
SDL_FreeAudioStream(stream);

Worked Example: Converting 48kHz to 44.1kHz

Here's a minimal program that loads a 48kHz audio file and plays it through a 44.1kHz device:

#include <SDL.h>
#include <stdio.h>

int main(int argc, char *argv[]) {
    if (SDL_Init(SDL_INIT_AUDIO) < 0) {
        fprintf(stderr, "SDL_Init failed: %s\n", SDL_GetError());
        return 1;
    }

    // Source: 48kHz float stereo
    SDL_AudioSpec src = {0};
    src.freq = 48000;
    src.format = AUDIO_F32;
    src.channels = 2;

    // Destination: 44.1kHz int16 stereo
    SDL_AudioSpec dst = {0};
    dst.freq = 44100;
    dst.format = AUDIO_S16;
    dst.channels = 2;
    dst.callback = NULL;

    SDL_AudioStream *stream = SDL_NewAudioStream(&src, &dst);
    if (!stream) {
        fprintf(stderr, "Stream creation failed: %s\n", SDL_GetError());
        SDL_Quit();
        return 1;
    }

    // Your audio data would go here
    // SDL_AudioStreamPut(stream, your_data, data_len);
    // SDL_AudioStreamGet(stream, output_buffer, &out_len);

    SDL_FreeAudioStream(stream);
    SDL_Quit();
    return 0;
}

Trade-Offs and Limitations

Thread Safety: SDL_AudioStream is not thread-safe. If you're using it in an audio callback, protect it with a mutex or ring buffer to avoid race conditions.

Latency: Small buffer sizes reduce latency but increase CPU usage due to more frequent conversions. Balance based on your application's real-time requirements.

Quality: SDL's conversion quality depends on the underlying audio driver implementation. On some platforms, you may get better results using platform-specific resampling libraries.

Memory: The stream allocates internal buffers. Monitor memory usage in long-running applications to ensure proper cleanup with SDL_FreeAudioStream().

Actionable Verification

To verify SDL_AudioStream works correctly:

1. Compile with SDL 2.28+ and test with mismatched sample rates
2. Monitor memory during stream creation and destruction
3. Compare output quality across Windows, macOS, and Linux
4. Measure latency with different buffer sizes to find your sweet spot

The key takeaway: SDL_AudioStream provides a portable, battle-tested solution for audio format conversion, but it requires careful buffer management and thread safety considerations in production code.