Summary

Add a new class javax.sound.SoundClip which provides simple API to play back a supported audio stream from a file.

Problem

Applications have used java.applet.AudioClip.getAudioClip as a simple means to play back an audio clip. However the java.applet package is deprecated for removal.

Solution

Since the applet AudioClip class is just a wrapper around java.sound APIs, define a new class in the javax.sound package in the java.desktop module which provides similar easy to use functionality.

A new package javax.sound is also introduced since existing javax.sound APIs are in the packages javax.sound.midi and javax.sound.sampled.

Specification

new package javax.sound:

    +/**
    + * Provides interfaces and classes for the Java Sound API.
    + * The API is divided into sub-packages.
    + * <ul>
    + * <li>Capture, processing and playback of sampled audio data is under {@link javax.sound.sampled}.
    + * <li>Sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data is under {@link javax.sound.midi}.
    + * </ul>
    + *
    + * <h2>Related Documentation</h2>
    + * For more information on using Java Sound see:
    + *   <a href="https://docs.oracle.com/javase/tutorial/sound/">
    + *   The Java Sound Tutorial</a>
    + *
    + * @since 25
    + */
    +package javax.sound;

============================

new class javax.sound.SoundClip:

+/**
+ * The {@code SoundClip} class is a simple abstraction for playing a sound clip.
+ * It will play any format that is recognized by the {@code javax.sound} API,
+ * and for which it has support. This includes midi data.
+ * <p>
+ * This class is intended for easy playback of short clips or snippets of sound.
+ * Examples of when this might be used is to play an audible alert or effect in a UI app,
+ * or to make a short announcement or to provide audible feedback such announcing as the
+ * function of a button or control.
+ * The application will typically let such clips play once to completion.
+ * <p>
+ * Applications needing more precise control or advanced
+ * features should look into other parts of the {@code javax.sound} API.
+ * Playing sound requires that the environment grants access to audio devices.
+ * Typically this means running the application in a desktop environment.
+ * <p>
+ * Multiple {@code SoundClip} items can be playing at the same time, and
+ * the resulting sound is mixed together to produce a composite.
+ *
+ * @since 25
+ */
+ 
+    /**
+     * Creates a {@code SoundClip} instance which will play a clip from the supplied file.
+     * <p>
+     * The file contents will be fully read before this method returns.
+     * If the file does not contain recognizable and supported sound data, or
+     * if the implementation does not find a suitable output device for the data,
+     * playing the clip will be a no-op.
+     *
+     * @param file the file from which to obtain the sound data
+     * @return a {@code SoundClip}
+     * @throws NullPointerException if {@code file} is {@code null}
+     * @throws IOException if there is an error reading from {@code file}
+     */
+    public static SoundClip createSoundClip(File file) throws IOException;
+
+    /**
+     * {@return whether this is a playable sound clip}
+     * <p>
+     * A value of {@code false} means that calling any of the other methods
+     * of this class is a no-op.
+     */
+    public boolean canPlay();
+
+    /**
+     * {@return whether sound is currently playing}
+     */
+    public boolean isPlaying();
+
+    /**
+     * Starts playing this sound clip.
+     * Each time this method is called, the clip is restarted from the beginning.
+     * This method will return immediately whether or not sound is played,
+     * and possibly before the sound has started playing.
+     * <p>
+     * Threading notes : Most applications will not need to do anything except call {@code play()}.
+     * The following is therefore something most applications need not be concerned about.
+     * Play back is managed in a background thread, which is ususally a daemon thread.
+     * Running daemon threads do not prevent the VM from exiting.
+     * So at least one thread must be alive to prevent the VM from terminating.
+     * A UI application with any window displayed automatically satisfies this requirement.
+     * Conversely, if the application wants to guarantee VM exit before the play() has completed, 
+     * it should call the {@code stop()} method.
+     */
+    public void play();
+
+    /**
+     * Starts playing this sound clip in a loop.
+     * Each time this method is called, the clip is restarted from the beginning.
+     * This method will return immediately whether or not sound is played,
+     * and possibly before the sound has started playing.
+     * <p>
+     * Threading notes : Most applications will not need to do anything except call {@code loop()}.
+     * The following is therefore something most applications need not be concerned about.
+     * Play back is managed in a background thread, which is ususally a daemon thread.
+     * Running daemon threads do not prevent the VM from exiting.
+     * So at least one thread must be alive to prevent the VM from terminating.
+     * A UI application with any window displayed automatically satisfies this requirement.
+     * Conversely, if the application wants to guarantee VM exit before the play() has completed,
+     * it should call the {@code stop()} method.
+     */
+
+    public void loop();
+
+    /**
+     * Stops playing this sound clip.
+     * Call this if the clip is playing and the application needs to stop
+     * it early, for example so that the application can ensure the clip
+     * playing does not block exit. It is also required to stop a {@code loop()}.
+     */
+    public void stop();