Applets !
Open projects
About JavaZOOM

Make a Donation

Any Question ?
Try our Forums !



Last Update : 01/22/2007
Overview Run jlGUI JNLP configurator Developer guide  API FAQ Links

jlGui is designed in two layers. BasicPlayer layer provides an high level API - based on JavaSound API- to play, stop, pause, resume and seek audio file or stream. jlGui Player layer is a front-end, WinAmp 2.0 skins compliant, with playlist and equalizer.

jlGui design

jlGui Player layer :
This layer is the front-end of jlGui (jlgui3.0.jar). These classes are not designed to be a Player API that you could use in any application. Here is a short description below of these classes.

  • Player class: Player is the main UI class. It extends java.awt.Window and implements BasicPlayerListener and many AWT listeners (Drag and Drop, Actions ...).
  • GUI and Skins classes : skin package provides custom AWT classes that implement two state skined buttons and WinAmp skins 2.x loader and parser.
  • Playlist classes : Playlist is the interface for playlist implementation. PlaylistFactory generates playlist instances for any implementation. BasePlaylist is a basic playlist implementation (Vector). Any developer can write a playlist implementation (e.g. SQLPlaylist) and plug it to jlGui. PlaylistItem is a class for song name, path ... MP3Files is the playlist UI class. It also extends java.awt.Window.
  • Tag viewer classes : tag package provides classes to read Ogg Vorbis comments and ID3 tags info. tag.ui package provides classes to display Ogg vorbis comments and ID3 tags info.
  • Configuration and utils classes : util and util.ini packages provide all classes to manage persistent configuration, debug, BMP loading and file filtering.

jlGui BasicPlayer layer :
This layer is player API of jlGui (basicplayer2.3.jar). These classes are designed to be used in any application that needs simple features (play, stop, pause, resume, seek) to play audio file or stream. Here is a short description below of these classes.

  • BasicPlayerListener : This interface defines callbacks methods that will be notified for all registered BasicPlayerListener of BasicPlayer.
  • BasicPlayerEvent : This class implements BasicPlayer events such as stream opened, seeking, playing, ...
  • BasicController : This interface defines controls (such as stop, play, pause, ...) available for BasicPlayer.
  • BasicPlayer : BasicPlayer is a threaded simple player class based on JavaSound API. It implements BasicController interface and notify BasicPlayerEvent to all registered BasicPlayerListeners.
  • BasicPlayerException : This class implements custom exception for BasicPlayer.

Audio format support :
You might wonder about audio format (MP3, OGG Vorbis, WAV ...) support classes. You won't see any in source code because jlGui relies on JavaSound SPI (Service Provider Interface) architecture. It's a plugin architecture that loads audio codecs (SPI) automatically on JVM startup. Matching JAR files must be included in CLASSPATH. That's way, adding a new audio format is really easy and has no impact of BasicPlayer source code. Note that SPI (MP3SPI and VorbisSPI) also provide audio comments (ID3v1, ID3v2, Ogg comments) support.

You're now ready to use BasicPlayer and our SPIs in your own application ;-)

  Required libraries :
  • OGG Vorbis support : jogg-0.0.7.jar, jorbis-0.0.15.jar, vorbisspi1.0.2.jar.
  • MP3 support : jl1.0.jar, mp3sp.1.9.4.jar.
  • SPEEX support : jspeex0.9.7.jar
  • FLAC support : jflac-1.2.jar
  • Monkey's Audio support : jmactritonusspi1.74.jar
  • BasicPlayer classes : basicplayer3.0.jar
  • Others classes needed : tritonus_share.jar, commons-logging-api.jar, kj_dsp1.1.jar.
    All these JAR files are available under lib/ folder of jlGui package.
  Sample code : Using BasicPlayer to play a song from file
This source code sample is available in srctest/ folder.
import java.io.File;
import java.io.PrintStream;
import java.util.Map;

/** * This class implements a simple player based on BasicPlayer. * BasicPlayer is a threaded class providing most features * of a music player. BasicPlayer works with underlying JavaSound * SPIs to support multiple audio formats. Basically JavaSound supports * WAV, AU, AIFF audio formats. Add MP3 SPI and Vorbis * SPI in your CLASSPATH to play MP3 and Ogg Vorbis file. */
public class BasicPlayerTest implements BasicPlayerListener { private PrintStream out = null;
* Entry point.
* @param args filename to play.

public static void main(String[] args)
BasicPlayerTest test = new BasicPlayerTest();
/** * Contructor. */
public BasicPlayerTest() { out = System.out; }

public void play(String filename)
// Instantiate BasicPlayer.
BasicPlayer player = new BasicPlayer();
// BasicPlayer is a BasicController.
BasicController control = (BasicController) player;
// Register BasicPlayerTest to BasicPlayerListener events.
// It means that this object will be notified on BasicPlayer
// events such as : opened(...), progress(...), stateUpdated(...)


try { // Open file, or URL or Stream (shoutcast, icecast) to play.
control.open(new File(filename));

// control.open(new URL("http://yourshoutcastserver.com:8000"));

// Start playback in a thread. control.play();
// If you want to pause/resume/pause the played file then
// write a Swing player and just call control.pause(),
// control.resume() or control.stop().
// Use control.seek(bytesToSkip) to seek file
// (i.e. fast forward and rewind). seek feature will
// work only if underlying JavaSound SPI implements
// skip(...). True for MP3SPI and SUN SPI's
// (WAVE, AU, AIFF).
// Set Volume (0 to 1.0). control.setGain(0.85);
// Set Pan (-1.0 to 1.0).
} catch (BasicPlayerException e) { e.printStackTrace(); } }
* Open callback, stream is ready to play.
* properties map includes audio format dependant features such as
* bitrate, duration, frequency, channels, number of frames, vbr flag, ...
* @param stream could be File, URL or InputStream
* @param properties audio stream properties.

public void opened(Object stream, Map properties)
// Pay attention to properties. It's useful to get duration,
// bitrate, channels, even tag such as ID3v2.

display("opened : "+properties.toString());
/** * Progress callback while playing.
* This method is called severals time per seconds while playing.
* properties map includes audio format features such as
* instant bitrate, microseconds position, current frame number, ...
* @param bytesread from encoded stream.
* @param microseconds elapsed (<b>reseted after a seek !</b>).
* @param pcmdata PCM samples.
* @param properties audio stream parameters.

public void progress(int bytesread, long microseconds, byte[] pcmdata, Map properties)
// Pay attention to properties. It depends on underlying JavaSound SPI
// MP3SPI provides mp3.equalizer.

display("progress : "+properties.toString());
* Notification callback for basicplayer events such as opened, eom ...
* @param event

public void stateUpdated(BasicPlayerEvent event)
// Notification of BasicPlayer states (opened, playing, end of media, ...)
display("stateUpdated : "+event.toString());

* A handle to the BasicPlayer, plugins may control the player through
* the controller (play, stop, ...)
* @param controller : a handle to the player

public void setController(BasicController controller)
display("setController : "+controller);

public void display(String msg)
if (out != null) out.println(msg);
  Notes :

- Before running the sample, close any resources that could use your soundcard.
For instance, under JBuilder IDE : Disable Audio feedback from Tools -> IDE options.

- If you get UnsupportedAudioException when trying to play MP3 or Ogg Vorbis song then double check your CLASSPATH.

[News] [Applets] [Servlets] [Services] [Projects] [Links] [About]


Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U. S. and other countries.
All other company and/or product names are the property of their respective owners.