LISPBUILDER-SDL-MIXER - Use SDL_Mixer from Common Lisp

Abstract

LISPBUILDER-SDL-MIXER provides a Common Lisp binding to the SDL_mixer library. The library mixes multiple samples into one or more audio output channels. Lisp callbacks provide the capability to implement custom mixing algorithms and custom audio effects over and above the distance attenuation, panning and reverse stereo effects provided by the SDL_mixer library. WAVE, MOD, MIDI, OGG, AIFF, RIFF and VOC formats are supported.

LISPBUILDER-SDL-MIXER has a dependency on LISPBUILDER-SDL.

The code comes with a MIT-style license so you can basically do with it whatever you want.

Download shortcut: http://www.balooga.com/lispbuilder/lispbuilder-sdl-mixer.tgz.

Example of Usage

;; Load an mp3 music file and play the file continuously.
(sdl:with-init (sdl:sdl-init-video sdl:sdl-init-audio)
  (sdl:window 50 10)

  (sdl-mixer:OPEN-AUDIO)
  (let ((music (sdl-mixer:load-music "sample.mp3")))
    (sdl-mixer:play-music music :loop t)

    (sdl:with-events ()
      (:quit-event ()
		   (sdl-mixer:Halt-Music)
		   (sdl-mixer:free music)
		   t)
      (:idle () (sdl:update-display)))))

Download
Support
License
Installation
Usage
Examples
The LISPBUILDER-SDL-MIXER dictionary

+channel-post+
+channels+
+default-channels+
+default-format+
+default-frequency+
+default-sample-buffer+
+max-volume+
allocate-channels
audio-channels-p
audio-format-p
audio-frequency-p
audio-opened-p
channel-volume
close-audio
free
gc-p
halt-music
halt-sample
linked-version
load-music
load-sample
music-fading-p
music-paused-p
music-playing-p
music-position
music-type-of
music-type-p
music-volume
open-audio
pause-music
play-music
play-sample
register-music-finished
register-music-mixer
register-sample-finished
rewind-music
sample-fading-p
sample-from-channel
sample-paused-p
sample-playing-p
sample-volume
sdl-mixer-version
simple-free
this-fp
unregister-music-finished
unregister-music-mixer
unregister-sample-finished

Acknowledgements

Current Version: The latest stable version of LISPBUILDER-SDL-MIXER, together with this documentation can be downloaded from http://www.balooga.com/lispbiulder/lispbuilder-sdl-mixer.tgz. The current version is 0.2.0.

Development: The latest developement version is available via anonymous SVN:

svn co https://lispbuilder.svn.sourceforge.net/svnroot/lispbuilder lispbuilder-sdl-mixer

Documentation, Support & Mailing Lists

Questions answered and help given on the lispbuilder discussion list. Documentation for LISPBUILDER-SDL and related packages is available on the LISPBUILDER project page on Sourceforge. For additional information, look at the Lisp Gardeners page, and Application Builder page on the ALU's (Association of Lisp Users) wiki.

License

LISPBUILDER-SDL-MIXER is distributed under the MIT-style license.

Installation

See the LISPBUILDER documentation for general installation instructions.

Using LISPBUILDER-SDL-MIXER

Enter the following at the REPL to compile and load the LISPBUILDER-SDL-MIXER package:

(asdf:operate 'asdf:load-op :lispbuilder-sdl-mixer)

ASDF will automatically load and compile the CFFI and :LISPBUILDER-SDL dependencies.

Included Examples

Enter the following at the REPL to compile and load the examples included in the LISPBUILDER-SDL-MIXER-EXAMPLES package:

(asdf:operate 'asdf:load-op :lispbuilder-sdl-mixer-examples)

Run the examples by entering any of the following at the REPL:

(SDL-MIXER-EXAMPLES:MIXER)

The LISPBUILDER-SDL-MIXER dictionary

[Constant]
+channel-post+

Default channel of -2 used for post-processing.

[Constant]
+channels+

Default number of 8 mixer channels.

[Constant]
+default-channels+

Default number of 2 sound channels for Stereo output.

[Constant]
+default-format+

Default SDL audio format; little-endian is AUDIO-S16LSB, big-endian is AUDIO-S16MSB. Audio formats are defined in SDL_audio.h;
AUDIO_U8 : Unsigned 8-bit samples

AUDIO_S8 : Signed 8-bit samples

AUDIO_U16LSB : Unsigned 16-bit samples, in little-endian byte order

AUDIO_S16LSB : Signed 16-bit samples, in little-endian byte order

AUDIO_U16MSB : Unsigned 16-bit samples, in big-endian byte order

AUDIO_S16MSB : Signed 16-bit samples, in big-endian byte order

AUDIO_U16 : same as AUDIO_U16LSB (for backwards compatability probably)

AUDIO_S16 : same as AUDIO_S16LSB (for backwards compatability probably)

AUDIO_U16SYS : Unsigned 16-bit samples, in system byte order

AUDIO_S16SYS : Signed 16-bit samples, in system byte order

[Constant]
+default-frequency+

Default sampling frequency of 22,050hz

[Constant]
+default-sample-buffer+

Default size of the sample output buffer is 4906 bytes

[Constant]
+max-volume+

Default volume of 128 for samples, output channels and mix channels.

[Function]
allocate-channels num-channels => result

Allocates NUM-CHANNELS to be used for mixing samples. Frees all allocated channnels when NUM-CHANNELS is NIL or 0. A negative value for NUM-CHANNELS is ignored. Returns the number of channels currently allocated. Can be called multiple times even if samples are currently playing. If the current allocation of channels is greater than NUM-CHANNELS, then channels greater than NUM-CHANNELS will be stopped and these resources freed. The callback set by REGISTER-SAMPLE-FINISHED is called for each channel halted. NOTE: Samples will continue playing when NUM-CHANNELS is 0.

[Function]
audio-channels-p => result

Returns the number of output channels used by the audio device, e.g. 2 for stereo and 1 for mono. Does not return the number of mixing channels allocated.

[Function]
audio-format-p => result

Returns the current audio format of the audio device.

[Function]
audio-frequency-p => result

Returns the current audio frequency of the audio device.

[Function]
audio-opened-p => result

Returns the number of times the audio device has been opened by OPEN-AUDIO, or NIL if the audio device is closed.

[Accessor]
channel-volume channel => result
(setf (channel-volume channel) volume)

Returns the volume of CHANNEL, as an INTEGER. Volume can be from 0 to +MAX-VOLUME+. If CHANNEL is NIL then the average volume over all channels is returned.

[Function]
close-audio &optional all => result

Attempts to close the audio device. The audio device can be opened multiple times by OPEN-AUDIO and to properly close the audio device, CLOSE-AUDIO should be called the same number of times. Optionally ALL when T will forcibly close the audio device, no matter how many times the device was opened.

[Generic function]
free chunk => result

[Method]
free (chunk music) => result

Frees the music in MUSIC. Stops MUSIC if currently playing. Will block until any current fade effect completes. Do not reuse MUSIC once freed.

[Method]
free (chunk chunk) => result

Frees the sample in CHUNK. Do not reuse CHUNK once freed. Do not attempt to free CHUNK that is still being played.

[Generic accessor]
gc-p foreign-object => result
(setf (gc-p foreign-object) value)

[Specialized accessor]
gc-p (foreign-object foreign-object) => result
(setf (gc-p (foreign-object foreign-object)) value)

[Function]
halt-music &optional fade => result

Stops playing music. The callback set by REGISTER-MUSIC-FINISHED is called when the music stops.
Parameters

FADE is the number of milliseconds to perform the fade-out effect. Will block until any current fade effect completes. Has no effect on paused or halted music. When FADE is NIL the music is stopped and all fade effects are immediately cancelled. The default is NIL.

Returns

T on success and NIL on failure.

[Function]
halt-sample channel &key fade ticks => result

Stops playing the sample on CHANNEL. The callback set by REGISTER-SAMPLE-FINISHED is called when the channel stops.
Parameters

CHANNEL specifies the channel to stop playing. When T, will stop playback samples on all channels. Ignores channels not currently playing out samples.

FADE is the number of milliseconds to perform the fade-out effect. The sample is stopped when fade effect completes. When FADE is NIL or 0 the sample is stopped immediately. Default is NIL.

TICKS is the number of milliseconds until the sample is stopped. When NIL or 0, the sample is stopped immediately. Default is NIL.

Returns

Returns the number of samples fading out, when FADE is set.

Returns the number of samples halted, when TICKS is set.

Otherwise, returns T on success and NIL on failure.

[Function]
linked-version => result

Returns the version number of the SDL_mixer dynamic library in use as #(MAJORMINORPATCH).

[Function]
load-music filepath => result

Loads the music file at location FILEPATH. Must be a WAVE, MOD, MIDI, OGG or MP3 file. Returns music as a new MUSIC object, or NIL on error.

[Function]
load-sample filepath => result

Loads the sample file at location FILEPATH. Must be a WAVE, AIFF, RIFF, OGG, or VOC file. Returns the sample as a new CHUNK object, or NIL on error.

[Function]
music-fading-p => result

Returns the current fade effect on music regardless of the current play or pause state. Returns :FADING-OUT if a fade-out is in effect, :FADING-IN if a fade-in is in effect, or NIL if no fade is in effect.

[Function]
music-paused-p => result

Returns T if music is currently paused or was previously paused prior to a halt, or NIL otherwise.

[Function]
music-playing-p => result

Returns T if music is currently playing or is paused, or NIL if music is halted.

[Function]
music-position position => result

Sets the play POSITION of the currently playing music. Returns T on success and NIL on failure. Applicable only to MOD, OGG and MP3 music formats as described below.
MOD, jumps to the pattern number in the module identified by POSITION. 0 will rewind the module to the beginning.

OGG, jumps to POSITION seconds from the beginning of the song.

MP3, jumps forwards POSITION seconds from the current play position. Negative values are ignored. To rewind, use REWIND-MUSIC to jump to the start of the song, then jump forward POSITION seconds using MUSIC-POSITION.

[Function]
music-type-of music type => result

Returns T if MUSIC is of TYPE, returns NIL otherwise. TYPE may be one of WAV, MOD, MID, OGG, MP3, MP3-MAD, FLAC or CMD. If MUSIC is NIL returns the type of the currently playing music. Returns NIL is no music is playing.

[Function]
music-type-p music => result

Returns the format type of MUSIC as one of WAV, MOD, MID, OGG, MP3, MP3-MAD, FLAC or CMD. Returns the format type of the currently playing music when MUSIC is NIL. Returns NIL is no music is playing.

[Accessor]
music-volume => result
(setf (music-volume ) volume)

Returns current music volume as an INTEGER from 0 to +MAX-VOLUME+.

[Function]
open-audio &key frequency format channels chunksize => result

Initializes the mixer. SDL must be initialized with SDL-INIT-AUDIO prior to this call. OPEN-AUDIO can be called multiple times, however FORMAT is set on the first call and will not changed on subsequent calls. The audio device must be closed and re-opened for any change to FORMAT to take effect. CLOSE-AUDIO must be called the same number of time to close the audio device. Use ALLOCATE-CHANNELS to set the number of mixing channels. OPEN-AUDIO will allocate +MIX-CHANNELS+ by default.
Parameters

FREQUENCY is the output sampling frequency in samples per second (Hz). Default is +DEFAULT-FREQUENCY+. Most games use a FREQUENCY of +DEFAULT-FREQUENCY+. The higher the FREQUENCY the greater the CPU resource requirements. (A value of 44100 is the CD audio rate).

FORMAT is the output sample format. Default is +DEFAULT-FORMAT+.

CHANNELS sets the number of sound channels in the output. Default is +DEFAULT-CHANNELS+. This is not the same as ALLOCATE-CHANNELS which sets the number of mixing channels.

CHUNKSIZE is the size in bytes of each mixed sample buffer. Default is +DEFAULT-SAMPLE-BUFFER+ bytes. The smaller the CHUNKSIZE, the more frequenctly the mixer hooks are called. Increase CHUNKSIZE to decrease CPU resources, if sound skips or if playing music. Decrease CHUNKSIZE to decrease sound lag.

Returns

T on success and NIL on failure.

[Function]
pause-music => result

Pause music. Music can only be paused if it is actively playing. You may halt paused music.

[Function]
play-music music &key loop fade position => result

Starts playing MUSIC from POSITION. The music can be faded-in over the number of milliseconds in FADE. Automatically repeats the music when finished the number of time specified in LOOP. Any previous music will be halted. Will block until any current fade effect completes.
Parameters

MUSIC is the MUSIC to play.

LOOP is the number of times to play the music. T continuously loops the music. Plays once when NIL, or 0. Default is NIL.

FADE is the number of milliseconds to perform the fade-in effect. Default is NIL, no fade effect. Only applies to the first loop.

POSITION is the position in the music to begin playing from. Default is to start playout from the beginning.

Returns

T on success and NIL on failure.

[Function]
play-sample chunk &key channel loop fade ticks => result

Plays the sample in CHUNK for TICKS milliseconds, repeated LOOP times. The sample is repeated the number of times specified in LOOP, or until TICKS. The sample will fade-in over FADE milliseconds. The callback set by REGISTER-SAMPLE-FINISHED is called when the sample stops playing.
Parameters

CHUNK is the sample CHUNK.

CHANNEL specifies the channel to play the sample. When NIL, will play on the first free unreserved channel. Default is NIL.

LOOP is the number of times to loop the sample. Loops continuously when T. Plays once when NIL, or 0. Default in NIL.

FADE is the number of milliseconds to perform the fade-in effect. Default is NIL, no fade effect. Only applies to the first loop.

TICKS is the number of milliseconds to play the sample. When T will play the sample from start to finish. Default is T.

Returns

The channel the sample is playing on, or NIL on failure.

[Function]
register-music-finished func => result

Sets the function that is called when music finishes playback or is halted. FUNC is of the format #(lambda ()).

[Function]
register-music-mixer func => result

Takes a function of the format #(lambda (user-data stream len)) that is called to fill the music audio buffer.

[Function]
register-sample-finished func => result

Sets the function that is called when a sample finishes playback or is halted. FUNC is of the format #(lambda (channel)).

[Function]
rewind-music => result

Rewind to the start of music. Safe to use on halted, paused, and currently playing music. It is not necessary to rewind the music immediately after starting playback, as it starts at the beginning by default. Only the following streams support rewind: MOD, OGG, MP3, Native MIDI.

[Function]
sample-fading-p channel => result

Returns T if a fade is in effect for the sample on CHANNEL, regardless of the current play or pause state of the sample. Returns :FADING-OUT if a fade-out is in effect, :FADING-IN if a fade-in is in effect, or NIL if no fade is in effect.

[Function]
sample-from-channel channel => result

Returns currently playing or most recently played sample on CHANNEL as a new CHUNK object, or NIL if CHANNEL is not allocated or CHANNEL has not yet played out any samples. NOTE: The sample may already have been freed and therefore the pointer to the foreign object in CHUNK may not be valid.

[Function]
sample-paused-p channel => result

Returns T if the sample on CHANNEL is currently paused or was previously paused prior to a halt, or NIL otherwise. Returns the number of paused samples when CHANNEL is T or NIL.

[Function]
sample-playing-p channel => result

Returns T if a sample is currently playing or is paused on CHANNEL, or NIL if the sample is halted. Returns the number of samples playing or paused when CHANNEL is T or NIL.

[Accessor]
sample-volume chunk => result
(setf (sample-volume chunk) volume)

Returns the volume of the sample in CHUNK, as an INTEGER from 0 to +MAX-VOLUME+.

[Function]
sdl-mixer-version sdl-version => result

Sets the SDL-VERSION structure with the version of the library..

[Function]
simple-free func-fp type => result

[Generic function]
this-fp foreign-object => result

Returns the foreign pointer to FOREIGN-OBJECT

[Method]
this-fp (foreign-object foreign-object) => result

Returns the reference to the foreign object for this FOREIGN-OBJECT. The difference between FP and THIS-FP, is that FP can be overriden, for example to refer to the TARGET-NODE of a META-NODE.

[Function]
unregister-music-finished => result

Removes the callback function set by set by REGISTER-MUSIC-FINISHED.

[Function]
unregister-music-mixer => result

Removes any callback function set by REGISTER-MUSIC-MIXER.

[Function]
unregister-sample-finished => result

Removes the callback function set by REGISTER-SAMPLE-FINISHED.

Acknowledgements

Documentation prepared using:

Edi Weitz's DOCUMENTATION-TEMPLATE.
Gary King's CL-MARKDOWN.

BACK