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)
		   (sdl-mixer:close-audio)
		   t)
      (:idle () (sdl:update-display)))))

 

Contents

  1. Abstract
  2. Dependencies
  3. Download
  4. Installation
  5. Usage
  6. Examples
  7. Support
  8. License
  9. The LISPBUILDER-SDL-MIXER dictionary
  10. Acknowledgements

 

Dependencies


 

Download

Current Version: The latest stable version of LISPBUILDER-SDL-MIXER, together with this documentation can be downloaded from http://www.balooga.com/lispbuilder/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


 

Installation

See the LISPBUILDER documentation for installation instructions for Windows, Mac OS-X and Linux.
 

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)

 

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.
 

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 SDL:AUDIO-S16LSB, big-endian is SDL:AUDIO-S16MSB. Audio formats are defined in SDL_audio.h;


[Constant]
+default-frequency+


Default sampling frequency of 22,050hz


[Constant]
+default-sample-buffer+


Default size of the sample output buffer is 4096 bytes


[Constant]
+max-volume+


Default volume of 128 for CHUNK, 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.


[Standard class]
chunk



[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 a CHUNK once freed. Do not attempt to free a CHUNK that is still being played.


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


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

Parameters
Returns


[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
Returns


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


[Standard class]
music



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


[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
Returns


[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
Returns


[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
Returns


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


Sets the callback that is executed when MUSIC finishes playback or is halted. FUNC is of the format #(lambda ())

Example 
(REGISTER-MUSIC-FINISHED 
    (lambda ()
      (FORMAT T "MUSIC FINISHED")))


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


Sets the callback that is executed to fill the music audio output buffer. FUNC is of the format #(lambda (user-data stream len))

Example 
(REGISTER-MUSIC-MIXER 
    (lambda (user stream len)
      'FILL-THE-AUDIO-OUTPUT-BUFFER))


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


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

Example 
(REGISTER-SAMPLE-FINISHED 
    (lambda (channel)
      (FORMAT T "SAMPLE FINISHED ON CHANNEL: ~A" 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]
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

BACK