3D Sound System

[Paul]

-- This slot is reserved for the most recent working releases --

Downloads:

Sound System  Version date:  August 24, 2010
The core SoundSystem library, independent from 3rd-party libraries.  It is stripped down to the bare essentials, and designed to be easily customizable with various sound library and codec plug-ins.  If memory is a concern (such as in an applet) this may be a good option, because it allows you to choose as many or as few plug-ins as you require for your project.  NOTE: The core SoundSystem library without any plug-ins is only capable of playing MIDI files.  Additional plug-ins should be added for more capabilities.  The source code and license are included in the .zip file.

Sound System jPCT  Version date:  August 24, 2010
The jPCT-friendly 3D sound library.  The SoundSystemJPCT class overrides the core SoundSystem libray, and provides a number of methods to make adding 3D sound to any jPCT project easy.  It includes methods for binding Listener to Camera and Sources to Object3Ds, as well as using SimpleVector parameters.  SoundSystemJPCT utilizes the LWJGL binding of OpenAL (with JavaSound as a backup option), and the J-Ogg library for .ogg support.  NOTE: The core SoundSystem library, source code, and all relevant licenses are included in the .zip file.

SoundSystem Utils  Version date:  August 9, 2009
Includes a SoundSystem loader, and an example XML file.


Plug-ins:

JavaSound library plug-in  Version date:  August 24, 2010
Interface to the Java Sound API.  More compatable than OpenAL, but not as high quality and fewer features.  This plug-in utilizes JavaSound's panning and volume control methods to simulate an reasonable-quality 3D sound system.  Known bug: quickPlaying sounds will begin playing them at full volume for a split second, before switching to the correct volume.  This is a bug with the Java Sound API itself, and therefore beyond my control to correct.  An easy workaround is to add 0.02 seconds of silence to the beginning of each sound effect (the free Audacity sound editor works well for this).

LWJGL OpenAL library plug-in  Version date:  August 24, 2010
Interface to the LWJGL binding of OpenAL.  The LWJGL library (http://www.lwjgl.org) is required for this plug-in to work.  This library sounds much better than Java Sound, but is not as compatable.  I recommend using the JavaSound library plug-in as a backup option.  NOTE: Please read the included LWJGL license.

JOAL library plug-in  Version date:  August 24, 2010
Interface to the JOAL binding of OpenAL.  The JOAL library (https://joal.dev.java.net/) is required for this plug-in to work.  As mentioned previously, this library sounds much better than Java Sound, but is not as compatable.  I recommend using the JavaSound library plug-in as a backup option.  NOTE: Please read the included JOAL license.

WAV codec plug-in  Version date:  August 24, 2010
Adds support for .wav files.

JOgg codec plug-in  Version date:  August 24, 2010
Adds support for .ogg files using the J-Ogg library.  This codec is less compatible than the JOrbis codec, but the license is less restrictive.  Sometimes running incompatable .ogg files through a converter will make them compatable.  NOTE: Please read the included JOgg license.

JOrbis codec plug-in  Version date:  August 24, 2010
Adds support for .ogg files using the JOrbis library.  More compatible than the JOgg codec, but reads data more slowly (it may not be possible to stream more than one file simultaneously when using this codec).  This plug-in is licensed by the LGPL.  NOTE: Please read the included LGPL document.

IBXM codec plug-in  Version date:  August 24, 2010
Adds support for Protracker, Fast Tracker 2, and Scream Tracker 3 (.s2m, .mod, and .xm) files using the IBXM library.  File sizes for these formats tend to be quite small, so this may be a good option for background music.  This plug-in is based on or using the IBXM library, which is bound by the BSD License.  NOTE: Please read the included license document.

JSpeex codec plug-in  Version date:  August 24, 2010
Adds support for .ogg or .wav files encoded with Speex (a compression optimized for human voice).  See http://www.speex.org/ for more information.


Documentation:

JavaDoc  Version date:  August 24, 2010
Also includes the JavaDocs for SoundSystemJPCT and all library and codec plug-ins, and the utils library.

3D Sound with SoundSystem  PDF (download the example programs)
A tutorial-style guide to using the core SoundSystem library (last updated: April 14, 2009).

Guide to SoundSystemJPCT  PDF (download the example programs)
Another tutorial-style guide to using SoundSystemJPCT. (last updated: April 14, 2009).


Demos:


Sound Effects Player  (download the Source Code)
Demonstrates library switching on the fly, streaming background music, playing MIDI, and playing multiple sources simultaneously.  Last updated August 21, 2010

Bullet / Target Collision  (download the Source Code)
Demonstrates the LibraryJavaSound plug-in.  Last updated March 30, 2009

Holy Bouncing Helicopter Balls!  (download the Source Code)
Demonstrates moving through a world with multiple sources.  Last updated August 21, 2010


What's new?

- Fixed incompatibility introduced by LWJGL 2.3 not supporting indirect buffers
- Fixed reverse-byte-order bug in CodecIBXM
- Fixed bug where switching libraries caused pre-loaded sounds not to re-load
- Fixed various bugs in 64-bit Java plug-in for Firefox on Linux
- Added error message when attempting to load missing file from the JAR
- Added Doppler algorithm to LibraryJavaSound using sample-rate control
- Implemented standard interface methods for Doppler effect
- Added Doppler interface methods to SoundSystemJPCT with SimpleVector parameters
- Implemented new listner interface for End Of Stream events
- Added workaround for InterruptedException bug when accessing MIDI sequencer
- Added auto-search for common MIDI synthesizers when the default is missing
- Added variable to SoundSystemConfig for specifying MIDI synthesizer to try
- Added method for creating normal sources from raw PCM audio data
- Added method for checking millisecond position of playing sources
- Added Mixer ranking system and auto-selection of the most compatible Mixer
- Fixed message-flooding bug when Mixer controls are unavailable
- Added work-around for Java Sound "webcam chosen as default Mixer" bug
- Added work-around for non-Sun Java (eg. OpenJDK) missing "Java Sound" Mixer
- Fixed multiple potential thread-synchronization bugs

[Paul]

Project Overview:

This project began as a problem posted on the jPCT forum about OpenAL being extremely complicated, and that there needs to be a 3D sound library that is easy to understand and use.  I decided to create a class that does all the tedious stuff and simplifies OpenAL.

This project has evolved a lot since then.  I have since added in a plug-in infrastructure for interfacing with multiple 3rd-party sound and codec libraries, the ability to switch between OpenAL and JavaSound on the fly, automatic compatibility checking, and much more.  And of course, I extended the base library to make a version that is easily compatible with jPCT.

If you are interested in reading about the early development of the library, check out the original thread here.

If anyone has any ideas for improving the library, let me know!


The SoundSystem License:

You are free to use this library for any purpose, commercial or otherwise.
You may modify this library or source code, and distribute it any way you
like, provided the following conditions are met:

1) You may not falsely claim to be the author of this library or any
   unmodified portion of it.
2) You may not copyright this library or a modified version of it and then
   sue me for copyright infringement.
3) If you modify the source code, you must clearly document the changes
   made before redistributing the modified source code, so other users know
   it is not the original code.
4) You are not required to give me credit for this library in any derived
   work, but if you do, you must also mention my website:
   http://www.paulscode.com
5) I the author will not be responsible for any damages (physical,
   financial, or otherwise) caused by the use if this library or any part
   of it.
6) I the author do not guarantee, warrant, or make any representations,
   either expressed or implied, regarding the use of this library or any
   part of it.

Author: Paul Lamb
http://www.paulscode.com

[Paul]

Today I discovered some delay problems when trying to put together some demos.  This problem didn't exist in earlier versions of SoundSystem, so it must be a problem with something I've added recently.  It appears to be a thread synchronization issue at first glance.  I will post an update after I've solved the problem.

[Paul]

I haven't been able to solve this problem yet, but I have discovered a couple of interesting things.  Firstly, the problem only appears when running jPCT via the LWJGL Applet Loader, and only for the LibraryLWJGLOpenAL plug-in (LibraryJavaSound works fine, even when loaded via the Applet Loader).  In other words, I can only replicate the problem when mixing the LibraryLWJGLOpenAL plug-in with jPCT in an applet.  Since jPCT relies on the LWJGL, as does the LibraryLWJGLOpenAL plug-in, I suspect there is a thread synchronization problem in my code related to the LWJGL that is conflicting with jPCT.  The confusing thing is that the problem only appears in applets and not applications (due to limited resources, perhaps?)

I am currently working on porting the helicopter demo applet to the JMonkey Engine so I can mix OpenAL and OpenGL in an applet without the LWJGL Applet Loader.  This should either strengthen or refute my theory that the problem is a thread synchronization issue related to the LWJGL.  If the problem exists there as well, then I will start looking at other possible causes, such as memory leaks and the like.  I will post further information as I progress.

[Paul]

I thought I would share a recent conversation I had with a developer, in case anyone else was having a similar issue.

hey Paul,

I extended your Sound System and added this class/function. My goal is to load all sounds on startup and associate them with a string identifier for play/pause/stop later. I'm not really sure what ManageSources really does but it only works with the QUICK_PLAY option. The question is, is the below correct for what I'm trying to do?

Also, I noticed a minor problem. Sometimes when a sound starts to play, a split second into that sound, the sound starts again. This happens randomly but every so often. It's very slight so you really have to listen for it. After running a bunch of tests I can only assume the CommandThread is going to sleep right after the sound just starts to play and then when the thread is awaken, it finishes off what it started. I don't know. Your thoughts please.

Any help would be greatly appreciated.

howie

Code:

public class NinjaSound extends SoundSystem
{

    public void loadSound( String sourcename, String filename,
                           boolean toStream, boolean toLoop )
    {
        if( toStream )
        {
            newStreamingSource( true, sourcename, filename, toLoop, 0, 0, 0,
                                SoundSystemConfig.ATTENUATION_NONE, 0 );
        }

        ManageSources( new CommandObject( CommandObject.QUICK_PLAY, true,
                           true, toLoop, sourcename, filename, 0, 0, 0,
                           SoundSystemConfig.ATTENUATION_NONE, 0, false ) );

        if( !toStream )
        {
            loadSound( filename );
        }
    }
}

never mind. I figured it out. I was basing my code on your backgroundMusic function. The newStreamingSource and ManageSources basicly do that same thing so you end up with two calls in the sourceMap.

Code:

    public void backgroundMusic( String sourcename, String filename,
                                 boolean toLoop )
    {
        newStreamingSource( true, sourcename, filename, toLoop, 0, 0, 0,
                            SoundSystemConfig.ATTENUATION_NONE, 0 );
        // Queue a command to quick stream this new source:
        ManageSources( new CommandObject( CommandObject.QUICK_PLAY, true,
                           true, toLoop, sourcename, filename, 0, 0, 0,
                           SoundSystemConfig.ATTENUATION_NONE, 0, false ) );
        CommandQueue( new CommandObject( CommandObject.PLAY, sourcename) );
       
        commandThread.interrupt();
    }

here's my new function for loading sound.

Code:

public class NinjaSound extends SoundSystem
{

    public void loadSound( String sourcename, String filename,
                           boolean toStream, boolean toLoop )
    {
        CommandNewSource( false, toStream, toLoop, sourcename,
                          filename, 0, 0, 0,
                          SoundSystemConfig.ATTENUATION_NONE, 0 );

        commandThread.interrupt();
    }
}

Howard,
 
Yes, I can see how this part of the code might be confusing.  I originally made it so quickPlay and backgroundMusic both created a temporary source and then immediately played it (seems logical).  All commands, including these two, were processed in order from the "CommandQueue" method via the Command Thread.
 
However, I later wanted the ability to "cull" and "activate" sources.  This feature is so that developers can extend the SoundSystem and manage which sources should play and which shouldn't based on their own rules.  For example, one might create a game where there are hundreds of simultaneously playing sources, and they only want the closest ones to play on whatever channels are available.
 
This seemingly simple update ended up requiring a significant change to the CommandQueue infrastructure.  All source creation, deletion, cull, and activate commands now needed to be processed first before play commands could be processed (this is the only way to ensure that only the active sources would play and not the culled ones).  So I created a new method called ManageSources, which is basically the same as CommandQueue, except it is called before CommandQueue is called.  This method processes the creation, deletion, cull, and activate commands that needed to be processed first.  The Command Thread processes all commands in the ManageSources queue first, then those in the CommandQueue.  Additionally, the ManageSources method is used in extended classes to sort the sources (by distance, for example), and to cull and activate the proper ones.  After all of those commands in the ManageSources queue are done, the commands in the CommandQueue are processed.
 
This change also required me to change the quickPlay and backgroundMusic methods, because I could no longer have these methods automatically play the new source (cull and activate stuff had to be figured out first via ManageSources).  So I changed it so quickPlay and backgroundMusic queues one command to create the source (via ManageSources), and a second command to play the source (via CommandQueue).
 
Now, I have tested this new infrastructure quite a bit since I wrote it, but I will go back and take another look to make sure two calls to "play" are not happening from the quickPlay and backgroundMusic methods.  I should also add in more comments to that section of the code to explain what is going on and why there are two methods that look virtually the same.
 
Thanks for the insight!
 
-Paul

Howard,

After reviewing the source, you are correct - there is a bug in the backgroundMusic method (not in the quickPlay method, though) -- I am creating two sources with the exact same information.  Nice catch!  I will have this corrected in the next release.

-Paul

[Paul]

Sound System, Cumulative Updates/Bug-Fixes

Sound System jPCT
Sound System
Sound System Utils

JavaSound library pluggin
LWJGL OpenAL library pluggin
JOAL library pluggin

JOrbis codec pluggin

-Made it so initializing OpenAL plug-ins will notify when AL_PITCH is not supported
-Fixed vorbis-header compatability issue with OGG files generated by Audacity
-Improved error-handling in multiple classes
-Updated and added multiple classes to allow user to specify either String filenames or URL instances
-Added new class to associate filename/identifier with URL
-Improved MIDIChannel class - searches for alternate sequencer/synthesizer if defaults don't work
-Added a new method for feeding raw audio data directly to a channel through streaming sources
-Added a new source-creation method to produce streams that can be fed directly with raw audio data
-Added a new SoundSystemUtils library which includes an XML loader
-Corrected problem in LibraryJavaSound plug-in where sources would only play once
-Corrected channel-source association bug which caused rare odd behaviors

[Paul]

Something I added seems to have broken Command synchronization.  I am currently looking into the problem, so please stand by.

[Paul]

Ok, I solved the problem.  This logic error has actually been in the code for a very long time, but it never manafested itself until now.  I had to change the CommanQueue/ManageSources infrastructure to correct it, so any legacy code that extends the SoundSystem class for customized source management models will most likely now be broken.  If this causes problems for anyone, please refer to the JavaDoc for the proper new way to do custom source management, or post questions here for help.  Sorry any inconvenience this causes.

Updated packages:
Sound System
Sound System jPCT
Sound System Utils

[Paul]

I fixed one more minor bug - a looping MIDI source without any sequences its play queue wasn't looping.  I went ahead and uploaded the fixed JAR and sourcecode (only the SoundSystem core was affected by the change).

Also, I finished my new and improved Helicopter Balls applet (taking the silliness to a whole new level):

Helicopter Balls Applet

And if you want the source code (not sure why anyone would):

Helicopter Balls Source

[Paul]

Minor bug fixes Update

I haven't updated the JavaDoc yet - there seems to be a bug in NetBeans that is preventing me from producing any JavaDocs, and I haven't had time to search for a fix.

Updated packages:
Sound System
Sound System jPCT


- Corrected a problem in the SoundSystemJPCT extension where source creation methods requiring a String filename parameter stopped working after a previous core library update.
- Added additional methods that take URL file references.
- Simplified thread synchronization in the core library, making it easy for users to manually manipulate sources by synchronizing on SoundSystemConfig.THREAD_SYNC object.
- Fixed a potential deadlock caused by overly-complicated thread synchronization infrastructure in core library.

[Paul]

Sound System, Major Update, Beta Release

Sound System
Sound System jPCT

JavaSound library pluggin
LWJGL OpenAL library pluggin
JOAL library pluggin

WAV codec pluggin
JOgg codec pluggin
JOrbis codec pluggin
IBXM codec pluggin

JavaDoc

I am calling this a beta release, because this has been one of the biggest overhauls of the library yet, and I fully expect there to be bugs.  I'll post additional updates in the coming days and problems are discovered.  I'm working on updating the tutorials as well.

There have been extensive changes since the last release.  I'll try and explain all of them quickly.

The big/important changes:

1) I fixed the incompatibility introduced back in LWJGL 2.3 when they stopped supporting indirect buffers.
2) I added a Doppler effect algorithm to LibraryJavaSound using sample-rate controls.  Note: normal sample-rate ranges in JavaSound are 4KHz - 48Khz, so this can effect how well certain sound effects do with the Doppler effect.
3) I implemented a standard interface for Doppler effect, which can now be used with all library plug-ins.  There are also new Doppler-effect interface methods in SoundSystemJPCT with SimpleVector parameters in jPCT's coordinate system.
4) I implemented a new stream-listener interface, which enables listening for End of Stream events (most useful for playing a sequence of music clips)
5) I added in an intelligent auto-search for common MIDI synthesizers when the default is missing.  This makes MIDI possible on non-Sun Java versions (such as OpenJDK)
6) I added the ability to create normal sources from raw PCM data.  Most useful for playing procedurally-generated sound effects.
7) I added the ability to check the millisecond position of any playing source
8) I added a Mixer ranking system, and an intelligent Mixer-picking based on the functions compatible with each Mixer.  This allowed an intelligent work-around for the Java Sound "webcam chosen as default Mixer" bug, as well as the fact that non-Sun Java (such as OpenJDK) may not have the "Java Sound Audio Engine" mixer available.

Additional changes:

1) I fixed a reverse-byte-order bug in CodecIBXM which caused some sounds to be loud and scratchy.
2) I fixed a bug where switching libraries caused pre-loaded sounds not to re-load.
3) I fixed various bugs when running 64-bit Java plug-in for Firefox on Linux.  There are still more (see below).
4) I added an error message when attempting to load a missing file from the JAR.  Before it acted as if there were no problem if a file was not present.
5) I added in a workaround for the Java Sound bug where a random InterruptedException is sometimes thrown when trying to access the default MIDI sequencer.
6) I added a varriable to SoundSystemCongfig for specifying which MIDI synthesizer to try first
7) I fixed the message-flooding bug that would happen when Mixer controls are not available.
8) I fixed various potential thread-synchronization bugs.

There are still several know issues with 64-bit Java on Linux which I am currently working on, including:

1) No MIDI
2) Random blocking for a half-second every few seconds
3) No sound from Java Sound when switching from OpenAL to Java Sound on the fly
4) JFrame 'paint' method causes system graphics to go wacky when playing JavaSound, and can even result in a complete OS lock-up requiring reset.

Please let me know if you run into any problems, and I will work on correcting them right away.

[Paul]

Sound System, Bug Fixes, New Plug-in

Sound System
Sound System jPCT

JavaSound library pluggin
LWJGL OpenAL library pluggin
JOAL library pluggin

WAV codec pluggin
JOgg codec pluggin
JOrbis codec pluggin
IBXM codec pluggin
JSpeex codec pluggin

JavaDoc

I fixed the new bug I introduced by trying to fix the IBXM reverse-byte-order bug.  While this is a relatively minor fix, I ended up having to make small changes to nearly every package, so be sure to download all the new versions (in other words, mix-and-match at your own peril).

Additionally, I finished the JSpeex codec plug-in.  Speex-encoded files are generally wrapped into a .ogg container file.  (This is what is produced by the binaries you can download from http://www.speex.org/downloads/).  While I was digging around, I noticed that there is an "experimental" capability for JSpeex to wrap the data into .wav files as well.  Since the .wav format is quite simple to read from (much easier to understand than .ogg), I went ahead and made this codec plug-in useable with either format.  By default, it assumes a .ogg container, but I added a method you can call to use speex-encoded .wav files if you prefer instead.  Just a reminder - these aren't normal .ogg or .wav files (just the header information is), so obviously they will not work with the other codec plug-ins.  I would recommend using a different file extension (like .spx) so you don't get them mixed up with any other non-speex files.

One more note: Speex can also save into "raw" format (i.e., no header information).  I didn't make the codec plug-in support this format because it requires the user to define the header information manually, which doesn't mesh well with SoundSystem.  However, if using the raw format is a requirement for you, let me know and I can look into it more closely to see if there is a way to support it in my codec plug-in.

As always, let me know if you run into any problems, and I will work on correcting them as soon as possible.