chickadee » sdl-mixer

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-mixer headers and libraries must be present. Versions prior to 0.6 also needed the SDL egg.

API

Overview

Opening and closing the audio device

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

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.

(close-audio) procedure

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

(load-sample filename) => sample procedure

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.

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

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.

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

Will pause or resume all channels or the given channel.

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

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.

(channel-finished proc) procedure

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.

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

Predicates indicating whether channel is in playing or paused state.

Playing music

(load-music filename) => music procedure

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.

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

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'.

(halt-music #!key fadeout) procedure

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

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

Pauses, resumes or rewinds the currently played music.

(music-finished thunk) procedure

Calls thunk whenever the currently played music is finished.

(music-type music) procedure

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

(music-volume #!optional new) procedure

Returns or sets the current volume level for music.

(music-playing?) procedure

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
0.4
defaults of open-audio, pause-channel, halt-channel,
 rewind-channel changed
0.5
basically broken
0.6
bugfix release with working callbacks and without the need to install the SDL egg

Contents »