Back to the Antelmann.com Java Framework Tutorial

Sound Tutorial

The com.antelmann.sound package is designed to make it as easy as possible to play some sounds in your application through functionality provided by J2SE. The sound types that are supported are those supported by your J2SE (see also The Java Sound Home Page).

Playing a sound from within your application

The class SoundPlayer provides great convenience for playing sounds. Suppose you have a file called "mysound.wav" that you want to play in your application; all you would have to put into your application is the following line of code:

new SoundPlayer(new File("mysound.wav")).play();

or more complete along with the proper exception handling:

try { new SoundPlayer(new File("mysound.wav")).play(); } catch (SoundException e) { // if you care for the exception that caused the problem .. System.out.println("problem encountered: " + e.getCause()); }

The same will work for other sound files, such as *.aiff, *.au or *.midi files. Also, the different constructors for SoundPlayer allow the same functionality directly taken from a URL, a Midi Sequence or an InputStream.

A SoundPlayer can also be instantiated without specifying a sound in the constructor. You can then always load a sound into an existing SoundPlayer object by using one of its load(..) methods; every call to a load(..) method will close the previous sound if one was present, so it is always save to call load(..). Here is an example:

try {
    SoundPlayer player = new SoundPlayer();
    player.load(new File("c:\\mysounds\sound1.wav"));
    player.play();
    // do something else here
    player.load(new File("c:\\mysounds\sound2.wav"));
    player.play();
} catch (SoundException e) {}

The load(..) methods enable the reuse of a single SoundPlayer object for playing back various different sounds at different times. Multiple SoundPlayer objects could be used to play back sounds simultaneously.

Note that the call to the method play() is not blocking, i.e. regardless of how long your sound will play, this method call will return immediately. If you were to shut down your application immediately after the call to play(), the sound would potentially not play until its end.
To be notified when a sound finishes after you called play(), you can register a SoundPlayer.Listener object with SoundPlayer.addListener().

If you keep a reference to the SoundPlayer object, you can pause the playback by calling stop() and then resume by calling play() again. If a sound played through to its end, you may have to call stop() before another call to play() will repeat the sound.

Other methods available in SoundPlayer will also give you access to the length of the given sound as well as the current microsecond position during playback. It even supports seeking to a desired position.

Using a GUI to play sounds

If you want to play sounds through a simple GUI, you can use the class JPlayer. There are two ways to use it:

from within your application:
new JPlayer().setVisible(true);
directly from the command line (as JPlayer provides a main() method):
> java com.antelmann.sound.JPlayer

Additionally, you can also preset a certain sound file and the directory for the file chooser; you can even make the GUI playing before you even press 'play' manually. Here is an example:

try { JPlayer jplayer = new JPlayer(); File mySound = new File("mysound.midi"); jplayer.load(mySound); jplayer.setInitialDirectory(mySound.getParent()); jplayer.play(); jplayer.setVisible(true); } catch (SoundException e) {}

Playing sounds from the command line

Here is some sample code that demonstrates how to provide a simple command line based sound player that can be invoked by entering the following:

> java Play <URL_or_File>

Support for MP3 files

Unfortunately, J2SE (up until at least version 1.4) does not provide support for mp3 files. However, there is at least one class library freely available under GNU licensing that fills this hole. The class MP3Player provides a wrapper around one of these class libraries, so that you can use it the same way as the SoundPlayer class.

As MP3Player inherits from SoundPlayer, you can easily replace SoundPlayer with MP3Player in all examples above to obtain mp3 support.

In order to use the MP3Player class, you will have to download the class library it uses separately and ensure that it is in your classpath along with the com.antelmann.sound classes.
The class library required for MP3Player is JavaLayer (version 0.1.2 or later) from JavaZOOM and it is available for download at http://www.javazoom.net/javalayer/javalayer.html.

There is also a separate GUI available that uses the MP3Player class (which can otherwise be used just like JPlayer): it's JMP3Player.

The reason for keeping the MP3 support (MP3Player and its GUI wrapper JMP3Player) separate from the other classes of this package is to enable the user to take advantage of the sound capabilities without having to depend on the third-party class library from JavaZoom. As long as you don't use these two classes, you will be fine with just the com.antelmann.sound package - of course without mp3 support in that case.

Note that there are several restrictions for using MP3 sounds (in comparison to the standard SoundPlayer functionality), as the JavaLayer class library unfortunately doesn't support certain methods. These restrictions are documented in the comments for the class MP3Player.

Every class within this framework that has external dependencies on a 3rd party MP3 class library, implements the interface MP3.

Playing multiple songs from a play list

If you want to play many songs in a row (so you can focus on your other party duties while the music is supposed to play ;-), the class JukeBox may be of interest for you. It makes it quite easy to play several songs (either specified by a file list, directory list or individually) sequentially - it even provides random playback. JukeBox ensures that the next song is played after the last one finished; you can also skip directly to the next song by using the playNext() method.

JukeBox also provides a convenient command-line based application if you start it with the main() method.

JJukeBox

Finally, JJukeBox is a nice gui that supports most functionality that one would want from a complete player - including drop-support from the operating system to add files to the playlist.

Sample sound files shipped with antelmann.jar

The class SampleSounds provides easy access to some sound examples that are included in the antelmann.jar distribution - just for demo purpose. You can play such a sound as follows (as an example):

try { new SoundPlayer(SampleSounds.RING).play(); } catch (SoundException e) {};