3D Sound System

[Paul]

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

Downloads:

Sound System  Version date:  January 7, 2012
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:  January, 2012
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:  January 7, 2012
Interface to the Java Sound API.  More compatible 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:  April 17, 2013
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 compatible.  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:  April 17, 2013
Interface to the JOAL binding of OpenAL.  The JOAL library (http://jogamp.org) is required for this plug-in to work.  As mentioned previously, this library sounds much better than Java Sound, but is not as compatible.  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:  October 23, 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:  November 23, 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:  November 8, 2011
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 raw data stream repeating bug in LibraryLWJGLOpenAL and LibraryJOAL
- Fixed raw data stream millisecond position bug in LibraryLWJGLOpenAL and LibraryJOAL

[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: [Select]

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: [Select]

    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: [Select]

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]

Sound System, Streaming Optimizations


Sound System
Sound System jPCT

- Improved transition time between loops of a streaming source
- Added hack to improve streaming performance if files are all the same audio format

[Dane]

Thank you so much for this, I'll make sure to mention your website in the credits of my project after I get it to work! =)

[Enerccio]

I came here to download the bugfix on LibraryJavaAudio (about the non looping sources), however, the download links seems to point to nothing. Where is the new download location?
Thanks in advance.

[Paul]

Just grab the one in the first post of this thread (it is the newest version, and will have that bugfix incorporated).  I'll have to see why those other links went dead (I don't recall changing anything on the server)

[Paul]

Sound System, Bug Fix

Sound System
Sound System jPCT

- Fixed looping stream stutter bug when StreamQueueFormatsMatch is set to true

[Enerccio]

Unfortunately, that is the version I have. And songs will still not loop at all with Java Sound.

[Paul]

Hmm, maybe I uploaded the wrong version..  Here try this one (I just tested it, and it works for me):

JavaSound Library Plug-in

If it still has the problem, could you upload one of the files you are having troubles with so I can see if there is anything with the file that might be causing this?  Also, is this happening with streaming sources or normal sources (or both?)

[Enerccio]

It still doesnt work. Here is the testing sound: http://www.sendspace.com/file/pat7cb [nofollow]

I also had to fix one bug in the de.jarnbjo.ogg, which was causing the infinite loop while loading small oggs: http://pastebin.com/L1XDpzPh [nofollow]

[Paul]

It works fine on my computer.  I'd be just about willing to bet your problem the JavaSound bug that only lets you create a limited number of lines (often either 1 or 32), after which no more can be created even if you close and destroy the other ones.  If this is what you are experiencing, then you would only be able to play 1 source (or possibly 32 in sequence), after which sound would stop working all together.  Is this what you are experiencing?  If not, I'll keep looking to see where your problem is located.

Unfortunately, the line problem is a limitation with JavaSound not the SoundSystem.  The only way around it is to write my own software mixer rather than using the ones available in JavaSound (so I can just open a single line and use it to play everything).  I've started developing one, but it may be some time before I get back to finishing it (my other project will be taking up most of my free time for a while).  I know other folks have been developing mixers for JavaSound, so you might do a little searching to see if you can find something you can use, otherwise I'd recommend switching to one of the other Library plug-ins for now.

--EDIT--
Also, the only change I could see in the CachedUrlStream.java code you posted was:

Code: [Select]

      while(!loaderThread.isBosDone() || pageOffsets.size()<5) {
         try {
            Thread.sleep(5);
         }
         catch (InterruptedException ex) {
         }
      }(specifically, changed the number in the while loop and the length of the thread sleep).  Are those really the only changes, or did I miss something?