You are looking at historical revision 26798 of this page. It may differ significantly from its current revision.

sdl-mixer

Introduction

This egg provides a schemely wrapper around the libsdl-mixer library. The original library documentation can be found at the libsdl website.

Author

Christian Kellermann

Requirements

sdl and its dependencies.

API

Overview

Opening and closing the audio device

[procedure] (open-audio #!key sampling-rate sample-format channels chunk-size)

Opens the audio device and initialises libsdl-mixer. Needs to be called at least once. It will close and reopen the device if it has been opened before.

The defaults for the keyword arguments are:

sampling-rate
44100
sample-format
AUDIO_S16SYS
channels
2
chunk-size
1024

Note: The sdl-init and mix-init procedures will be called only once.

[procedure] (close-audio)

Closes the audio device and shuts down the mixer library. No procedure should access libsdl-mixer or sdl audio procedures after calling close-audio.

Playing samples in channels

[procedure] (load-sample filename) => sample

Loads the sample from filename. Raises an exception if the sample cannot be loaded or the sample format is not supported by sdl-mixer. Returns a pointer representing the sample which can be used by play-sample.

[procedure] (play-sample sample #!key channel repeat fadein duration)

Takes a sample pointer, which has been loaded with load-sample and plays it on channel. By default this is the next available channel. The sample will be repeated repeat times, which by default is #f, the sample will be played once only.

fadein and duration control how long the sample is played and the time that is used to fade in the sample to the channel. Both values represent milliseconds.

[procedure] (pause-channel #!optional channel)
[procedure] (resume-channel #!optional channel)

Will pause or resume all channels or the given channel.

[procedure] (halt-channel #!optional channel #!key fadeout)

Halts channel channel or all channels by default. If the fadeout parameter is set, this will be used to fade out the channel(s). fadeout is given in milliseconds.

[procedure] (channel-finished proc)

Sets a handler to be called when a channel has finished playing. The proc is expected to take an argument for the channel number that has finished.

[procedure] (channel-playing? channel)
[procedure] (channel-paused? channel)

Predicates indicating whether channel is in playing or paused state.

Playing music

[procedure] (load-music filename) => music

Loads a file filename and returns a music object. A condition is raised if the format of the file is not supported by libsdl-mixer. It returns a pointer representing the music which can be used by play-music.

[procedure] (play-music music #!key repeat fadein volume)

Plays music, optionally repeating it repeat times (by default it is played once), using a fade in of fadein milliseconds with a volume value set to ''volume'.

[procedure] (halt-music #!key fadeout)

Halts the currently played music, optionally with a fade out set to fadeout milliseconds.

[procedure] (pause-music)
[procedure] (resume-music)
[procedure] (rewind-music)

Pauses, resumes or rewinds the currently played music.

[procedure] (music-finished thunk)

Calls thunk whenever the currently played music is finished.

[procedure] (music-type music)

Returns the type of music. The return value is a symbol, and can be: wav, mp3, mod, midi, ogg or user-specific.

[procedure] (music-volume #!optional new)

Returns or sets the current volume level for music.

[procedure] (music-playing?)

Returns #t if music is playing.

Note: A paused state is considered playing for libsdl-mixer...

Errors

The procedures in this extension raise a composite condition with the properties:

((exn message msg)
 (sdl)
 (mixer))

Example

(use sdl-mixer)

(open-audio)

(channel-finished (lambda (c) (printf "Channel ~a finished~%" c)))

(play-music (load-music "background.mp3"))
(let ((s (load-sample "noise.wav")))
     (play-sample s))
(close-audio)

License

The wrapper is licensed as LGPL as is the original libsdl-mixer.

Version history

0.1
dev release
0.2
bugfix to appease salmonella
0.3
callbacks added