Jsaus Java Simple Audio System written by Nerius Anthony Landys

Overview

This Java software library consists of the ability to play, loop, stop, pause, and resume audio clips which are loaded from WAV or AU files. The entry point into this functionality is class com.nerius.audio.ModernAudioClip. By its intended design, this audio package is reminiscent of the ancient and deprecated java.applet.AudioClip, only with added methods pause() and resume().

There are several main objectives of this software:

• Use features from Java 1.3 and nothing newer.
• It is expected that the pause/resume operations will not necessarily be called from the same thread which calls play/loop/stop.
• All calls should be non-blocking and non-waiting, because they are expected to be made from application thread(s).
• Regardless of how frequently or in which order the five audio operations are called, the audio system should behave correctly all of the time.

You may ask, why not use class javax.sound.sampled.Clip directly by employing its methods start(), loop(LOOP_CONTINUOUSLY), and stop(), and maybe even setMicrosecondPosition(long) for implementation of pause/resume? The nature of these native Java sound APIs is very delicate and fragile; class com.nerius.audio.NaiveAudioClip exists to demonstrate the effects of calling the javax.sound.sampled.Clip methods in the most naive manner possible. The result is that the audio clips become completely unreliable as soon as the commands are made in rapid succession. To solve these issues more careful thread-planning and listener-waiting is needed, which is exactly what this library was created for. The purpose of this library is essentially to expose perfectly-working, non-blocking audio functionality which works around the quirks in the native Java sound layer.

For reference, the naive implementation of AudioClip which exhibits problems is as follows:

package com.nerius.audio;

public class NaiveAudioClip implements AudioClip
{

  javax.sound.sampled.Clip  m_clip; // Set by constructor, omitted for clarity.

  public void play() { m_clip.stop();
                       m_clip.setFramePosition(0);
                       m_clip.start(); }

  public void loop() { m_clip.stop();
                       m_clip.setFramePosition(0);
                       m_clip.loop(Clip.LOOP_CONTINUOUSLY); }

  public void stop() { m_clip.stop(); }

  public void pause()  { /* Not implemented. */ }
  public void resume() { /* Not implemented. */ }

}

The code above does not work reliably. If we play() this AudioClip and then play() it again when it's only halfway through, more often than not the clip simply stops playing. Therefore, more intricate polling/listening/waiting is needed, which is exactly what this library is intended to do.

Acknowledgments

The Jsaus project is hosted on sourceforge.net.

API

Complete Javadoc for Jsaus can be browsed here. Below is the API explained in a nutshell.

Interface com.nerius.audio.AudioClip

public void play()

Plays the audio clip once through. This always causes the playing to start from beginning of clip, even in cases where clip is already playing or looping.

public void loop()

Plays the audio clip once through, then jumps back to beginning, playing it through again and again, indefinitely. This always causes the playing to start from beginning of clip, even in cases where clip is already playing or looping.

public void stop()

Stops a playing or looping audio clip. The next time the clip is played or looped it will start from beginning of clip.

public void pause()

Puts the audio clip into paused state, if not already. When the clip is resumed it will continue exactly where it left off when it was paused. If play(), loop(), or stop() are called while the clip is paused, then upon resume() the clip will behave as if calling those operations in the same order immediately upon resume.

public void resume()

Resumes the clip after paused state, if clip was paused previously. For clarification on required behavior of pause/resume please see discussion on pause().

Download

All releases for Jsaus are available at https://sourceforge.net/projects/jsaus/files/. The current version of Jsaus is 1.0.

To obtain and browse [main trunk] project files from the SourceForge Subversion repository an operation such as this should be used:

  svn checkout svn://svn.code.sf.net/p/jsaus/code/ ./jsaus

or

  svn checkout https://svn.code.sf.net/p/jsaus/code/ ./jsaus