19 Audio

9.0.0.11

Racket

19 Audio🔗ℹ

This section covers audio playback using SDL3’s stream-based audio model.

SDL3 uses a stream-based audio model:

Open an audio device (or use the default)
Create audio streams with source/destination formats
Bind streams to devices
Push audio data into streams
SDL automatically mixes and plays

19.1 Audio Specs🔗ℹ

Audio specs describe the format of audio data.

procedure
(make-audio-spec format channels freq) → SDL_AudioSpec?
  format : exact-nonnegative-integer?
  channels : exact-positive-integer?
  freq : exact-positive-integer?

Creates an audio spec.

format is one of:

SDL_AUDIO_U8 — Unsigned 8-bit
SDL_AUDIO_S8 — Signed 8-bit
SDL_AUDIO_S16 — Signed 16-bit
SDL_AUDIO_S32 — Signed 32-bit
SDL_AUDIO_F32 — 32-bit float

channels is 1 for mono, 2 for stereo.

freq is the sample rate in Hz (e.g., 44100, 48000).

(define spec (make-audio-spec SDL_AUDIO_S16 2 44100))

procedure
(audio-spec-format spec) → exact-nonnegative-integer?
spec : SDL_AudioSpec?

Returns the audio format.

procedure
(audio-spec-channels spec) → exact-nonnegative-integer?
spec : SDL_AudioSpec?

Returns the channel count.

procedure
(audio-spec-freq spec) → exact-nonnegative-integer?
spec : SDL_AudioSpec?

Returns the sample rate.

19.2 Device Enumeration🔗ℹ

procedure
(audio-playback-devices)
→ (listof (cons/c exact-nonnegative-integer? string?))

Returns a list of available playback devices.

Each element is (cons device-id device-name).

(for ([dev (audio-playback-devices)])
(printf "Device ~a: ~a~n" (car dev) (cdr dev)))

procedure
(audio-recording-devices)
→ (listof (cons/c exact-nonnegative-integer? string?))

Returns a list of available recording devices.

procedure
(audio-device-name device-id) → (or/c string? #f)
device-id : exact-nonnegative-integer?

Returns the name of an audio device.

19.3 Device Management🔗ℹ

procedure
(open-audio-device [device-id spec]) → exact-nonnegative-integer?
device-id : (or/c exact-nonnegative-integer? #f) = #f
spec : (or/c SDL_AudioSpec? #f) = #f

Opens an audio device.

If device-id is #f, opens the default playback device. If spec is #f, uses the system default format.

Returns the device ID.

;; Open default device with default format
(define dev (open-audio-device))

;; Open default device with specific format
(define spec (make-audio-spec SDL_AUDIO_S16 2 44100))
(define dev2 (open-audio-device #f spec))

procedure
(close-audio-device! device) → void?
device : exact-nonnegative-integer?

Closes an audio device.

procedure
(pause-audio-device! device) → void?
device : exact-nonnegative-integer?

Pauses audio playback on a device.

procedure
(resume-audio-device! device) → void?
device : exact-nonnegative-integer?

Resumes audio playback on a device.

procedure
(audio-device-paused? device) → boolean?
device : exact-nonnegative-integer?

Returns #t if the device is paused.

procedure
(audio-device-format [device-id])
→
SDL_AudioSpec? exact-nonnegative-integer?
device-id : exact-nonnegative-integer?
= SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK

Returns the audio format and buffer size for a device.

procedure
(audio-device-gain device-id) → real?
device-id : exact-nonnegative-integer?

Returns the current device gain (volume multiplier).

procedure
(set-audio-device-gain! device-id gain) → void?
device-id : exact-nonnegative-integer?
gain : real?

Sets the device gain. 1.0 is normal volume.

19.4 Audio Streams🔗ℹ

Audio streams handle format conversion and buffering.

procedure
(make-audio-stream src-spec [dst-spec]) → cpointer?
src-spec : SDL_AudioSpec?
dst-spec : (or/c SDL_AudioSpec? #f) = #f

Creates an audio stream.

If dst-spec is #f, uses the same format as the source.

(define src-spec (make-audio-spec SDL_AUDIO_S16 2 44100))
(define stream (make-audio-stream src-spec))

procedure
(open-audio-device-stream [ device-id
spec
#:callback callback
#:userdata userdata]) → cpointer?
   device-id : exact-nonnegative-integer?
= SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK
  spec : (or/c SDL_AudioSpec? #f) = #f
  callback : (or/c procedure? #f) = #f
  userdata : any/c = #f

Opens a device and creates a bound stream in one call.

The device starts paused. Call resume-audio-stream-device! to start.

If callback is provided, it will be called when the stream needs data. The callback can accept 2, 3, or 4 arguments:

4 args: (userdata stream additional-bytes total-bytes)
3 args: (stream additional-bytes total-bytes)
2 args: (additional-bytes total-bytes)

;; Simple device+stream setup
(define stream (open-audio-device-stream))
(resume-audio-stream-device! stream)

procedure
(destroy-audio-stream! stream) → void?
stream : cpointer?

Destroys an audio stream.

procedure
(audio-stream-device stream) → exact-nonnegative-integer?
stream : cpointer?

Returns the device ID associated with a stream.

procedure
(bind-audio-stream! device stream) → void?
device : exact-nonnegative-integer?
stream : cpointer?

Binds a stream to a device.

procedure
(unbind-audio-stream! stream) → void?
stream : cpointer?

Unbinds a stream from its device.

procedure
(pause-audio-stream-device! stream) → void?
stream : cpointer?

Pauses the device associated with a stream.

procedure
(resume-audio-stream-device! stream) → void?
stream : cpointer?

Resumes the device associated with a stream.

procedure
(audio-stream-device-paused? stream) → boolean?
stream : cpointer?

Returns #t if the stream’s device is paused.

19.5 Stream Operations🔗ℹ

procedure
(audio-stream-put! stream data length) → void?
  stream : cpointer?
  data : cpointer?
  length : exact-nonnegative-integer?

Adds audio data to a stream.

data is a pointer to the audio data. length is the number of bytes.

procedure
(audio-stream-available stream) → exact-nonnegative-integer?
stream : cpointer?

Returns the number of bytes available in the stream.

procedure
(audio-stream-clear! stream) → void?
stream : cpointer?

Clears all buffered data from the stream.

procedure
(audio-stream-flush! stream) → void?
stream : cpointer?

Flushes pending data through format conversion.

procedure
(play-audio! stream data length) → void?
  stream : cpointer?
  data : cpointer?
  length : exact-nonnegative-integer?

Convenience function that puts data into a stream.

Same as audio-stream-put!.

19.6 WAV Loading🔗ℹ

procedure
(load-wav source) →
SDL_AudioSpec?
cpointer?
exact-nonnegative-integer?
source : (or/c string? path? bytes? input-port?)

Loads a WAV file.

Returns (values audio-spec audio-data length).

The audio-data pointer must be freed with free-audio-data!.

(define-values (spec data len) (load-wav "sound.wav"))

;; Play the sound
(audio-stream-put! stream data len)

;; Free when done
(free-audio-data! data)

procedure
(free-audio-data! data) → void?
data : cpointer?

Frees audio data returned by load-wav.

19.7 Audio Mixing and Conversion🔗ℹ

procedure
(mix-audio! dst src format length [volume]) → void?
  dst : cpointer?
  src : cpointer?
  format : exact-nonnegative-integer?
  length : exact-nonnegative-integer?
  volume : real? = 1.0

Mixes audio data from src into dst.

volume is a multiplier (1.0 = full volume).

procedure
(convert-audio-samples src-spec
src-data
src-length
dst-spec)
→
cpointer? exact-nonnegative-integer?
  src-spec : SDL_AudioSpec?
  src-data : cpointer?
  src-length : exact-nonnegative-integer?
  dst-spec : SDL_AudioSpec?

Converts audio samples between formats.

Returns (values dst-data dst-length).

The returned data must be freed with free-audio-data!.

procedure
(audio-format-name format) → string?
format : exact-nonnegative-integer?

Returns a human-readable name for an audio format.

19.8 Audio Format Constants🔗ℹ

value
SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK : exact-nonnegative-integer?

The default playback device ID.

value
SDL_AUDIO_DEVICE_DEFAULT_RECORDING : exact-nonnegative-integer?

The default recording device ID.

value
SDL_AUDIO_U8 : exact-nonnegative-integer?

Unsigned 8-bit audio format.

value
SDL_AUDIO_S8 : exact-nonnegative-integer?

Signed 8-bit audio format.

value
SDL_AUDIO_S16 : exact-nonnegative-integer?

Signed 16-bit audio format (most common for CD-quality audio).

value
SDL_AUDIO_S32 : exact-nonnegative-integer?

Signed 32-bit audio format.

value
SDL_AUDIO_F32 : exact-nonnegative-integer?

32-bit floating point audio format.

19.9 Example: Playing a Sound🔗ℹ

Here’s a complete example of loading and playing a WAV file:

#lang racket/base
(require sdl3)

(with-sdl
  ;; Initialize audio
  (sdl-init! 'audio)

  ;; Open default audio device and stream
  (define stream (open-audio-device-stream))

  ;; Load a WAV file
  (define-values (spec data len) (load-wav "sound.wav"))

  ;; Start audio playback
  (resume-audio-stream-device! stream)

  ;; Play the sound
  (audio-stream-put! stream data len)

  ;; Wait for sound to finish
  (let loop ()
    (when (> (audio-stream-available stream) 0)
      (delay! 100)
      (loop)))

  ;; Cleanup
  (free-audio-data! data)
  (destroy-audio-stream! stream))

1	Overview
2	Quick Start
3	Resource Management
4	Initialization
5	Windows and Renderers
6	Timer Functions
7	Configuration Hints
8	Properties
9	Drawing
10	Textures
11	Images and Surfaces
12	True Type Fonts
13	Rectangle Collision Detection
14	Events
15	Keyboard Functions
16	Mouse Functions
17	Gamepads
18	Joysticks
19	Audio
20	Camera
21	Display Information
22	Clipboard
23	Dialogs
24	System Tray
25	Open GL
26	Vulkan
27	GPU API

19.1	Audio Specs
19.2	Device Enumeration
19.3	Device Management
19.4	Audio Streams
19.5	Stream Operations
19.6	WAV Loading
19.7	Audio Mixing and Conversion
19.8	Audio Format Constants
19.9	Example: Playing a Sound