bb.gui
Class SoundUtil

java.lang.Object
  extended by bb.gui.SoundUtil

public class SoundUtil
extends Object

Provides static methods relating to sound.

Warning: there is apparently a bug in all JDKs at least thru 1.4.x, in which the JVM will not naturally terminate if the JavaSound API is used; System.exit must be used to force shutdown. This bug has been fixed in JDK 1.5.0, and this class assumes that this or a later version of Java is being used.

This class is multithread safe: it is stateless.

Author:
Brent Boyer

Nested Class Summary
private static class SoundUtil.Player
          Generates a Clip from a URL and can play it, but most importantly it robustly ensures that the clip is eventually closed and that this close event gets propagated.
static class SoundUtil.UnitTest
          See the Overview page of the project's javadocs for a general description of this unit test class.
 
Constructor Summary
private SoundUtil()
          This sole private constructor suppresses the default (public) constructor, ensuring non-instantiability outside of this class.
 
Method Summary
static void main(String[] args)
           
static void play(URL url, int numberLoops, boolean synchronous)
          Plays the sound located at url in a loop that will execute numberLoops times.
static void playAsynch(File file)
          Simply calls playAsynch(file, 1).
static void playAsynch(File file, int numberLoops)
          Creates a URL for file and supplies this to playAsynch.
static void playAsynch(URL url)
          Simply calls playAsynch(url, 1).
static void playAsynch(URL url, int numberLoops)
          Simply calls play(url, numberLoops, false).
static void playSynch(File file)
          Simply calls playSynch(file, 1).
static void playSynch(File file, int numberLoops)
          Creates a URL for file and supplies this to playSynch.
static void playSynch(URL url)
          Simply calls playSynch(url, 1).
static void playSynch(URL url, int numberLoops)
          Simply calls play(url, numberLoops, true).
private static void printAudioFileFormatsCanWrite()
           
private static void printFileDescriptions(File directory)
           
private static void printUrlDescription(URL url)
           
static long timeToPlay(Clip clip)
          Returns timeToPlay(clip, 1).
static long timeToPlay(Clip clip, int numberLoops)
          Returns the number of milliseconds that it should take to play clip in a loop that will execute numberLoops times.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SoundUtil

private SoundUtil()
This sole private constructor suppresses the default (public) constructor, ensuring non-instantiability outside of this class.

Method Detail

main

public static void main(String[] args)
                 throws Exception
Throws:
Exception

printAudioFileFormatsCanWrite

private static void printAudioFileFormatsCanWrite()

printFileDescriptions

private static void printFileDescriptions(File directory)
                                   throws Exception
Throws:
Exception

printUrlDescription

private static void printUrlDescription(URL url)
                                 throws Exception
Throws:
Exception

playSynch

public static void playSynch(File file)
                      throws IllegalArgumentException,
                             RuntimeException
Simply calls playSynch(file, 1).

Throws:
IllegalArgumentException - if file is not valid
RuntimeException - (or some subclass) if any other error occurs; this may merely wrap some other underlying Throwable

playSynch

public static void playSynch(File file,
                             int numberLoops)
                      throws IllegalArgumentException,
                             RuntimeException
Creates a URL for file and supplies this to playSynch.

Throws:
IllegalArgumentException - if file is not valid; numberLoops < 1
RuntimeException - (or some subclass) if any other error occurs; this may merely wrap some other underlying Throwable

playSynch

public static void playSynch(URL url)
                      throws IllegalArgumentException,
                             RuntimeException
Simply calls playSynch(url, 1).

Throws:
IllegalArgumentException - if url == null
RuntimeException - (or some subclass) if any other error occurs; this may merely wrap some other underlying Throwable

playSynch

public static void playSynch(URL url,
                             int numberLoops)
                      throws IllegalArgumentException,
                             RuntimeException
Simply calls play(url, numberLoops, true).

Because the synchronous parameter supplied to play is true, the playing is done "synchronously", that is, this method does not return until the sound has finished playing.

Throws:
IllegalArgumentException - if url == null; numberLoops < 1
RuntimeException - (or some subclass) if any other error occurs; this may merely wrap some other underlying Throwable

playAsynch

public static void playAsynch(File file)
                       throws IllegalArgumentException,
                              RuntimeException
Simply calls playAsynch(file, 1).

Throws:
IllegalArgumentException - if file is not valid
RuntimeException - (or some subclass) if any other error occurs; this may merely wrap some other underlying Throwable

playAsynch

public static void playAsynch(File file,
                              int numberLoops)
                       throws IllegalArgumentException,
                              RuntimeException
Creates a URL for file and supplies this to playAsynch.

Throws:
IllegalArgumentException - if file is not valid; numberLoops < 1
RuntimeException - (or some subclass) if any other error occurs; this may merely wrap some other underlying Throwable

playAsynch

public static void playAsynch(URL url)
                       throws IllegalArgumentException,
                              RuntimeException
Simply calls playAsynch(url, 1).

Throws:
IllegalArgumentException - if url == null
RuntimeException - (or some subclass) if any other error occurs; this may merely wrap some other underlying Throwable

playAsynch

public static void playAsynch(URL url,
                              int numberLoops)
                       throws IllegalArgumentException,
                              RuntimeException
Simply calls play(url, numberLoops, false).

Because the synchronous parameter supplied to play is false, the playing is done "asynchronously", that is, this method immediately returns while another thread carries out the playing of the sound.

Throws:
IllegalArgumentException - if url == null; numberLoops < 1
RuntimeException - (or some subclass) if any other error occurs; this may merely wrap some other underlying Throwable

play

public static void play(URL url,
                        int numberLoops,
                        boolean synchronous)
                 throws IllegalArgumentException,
                        RuntimeException
Plays the sound located at url in a loop that will execute numberLoops times.

The actual playing of the sound is always done by some internal thread in the sound system. If the synchronous parameter is true, however, then this method behaves "synchronously", that is, it does not return until that other thread has finished playing the sound. Otherwise, this method behaves "asynchronously", that is, it immediately returns while that other thread concurrently plays the sound.

Warning: this method does nothing to prevent another thread from simultaneously using the sound output system (e.g. by calling some method of this class), in which case multiple sounds may be playing simultaneously.

Throws:
IllegalArgumentException - if url == null; numberLoops < 1
RuntimeException - (or some subclass) if any other error occurs; this may merely wrap some other underlying Throwable

timeToPlay

public static long timeToPlay(Clip clip)
                       throws IllegalArgumentException,
                              IllegalStateException
Returns timeToPlay(clip, 1).

Throws:
IllegalArgumentException - if clip == null
IllegalStateException - if the line for clip is not open

timeToPlay

public static long timeToPlay(Clip clip,
                              int numberLoops)
                       throws IllegalArgumentException,
                              IllegalStateException
Returns the number of milliseconds that it should take to play clip in a loop that will execute numberLoops times. The result is always an upper bound because it comes from rounding up a microsecond time.

Throws:
IllegalArgumentException - if clip == null; numberLoops < 1
IllegalStateException - if the line for clip is not open