SoundClip (Java SE 26 & JDK 26)
Description: declaration: module: java.desktop, package: javax.sound, class: SoundClip
Keywords: javax.sound.SoundClip class

# Class SoundClip

java.lang.Object
javax.sound.SoundClip

public final class SoundClip extends Object
The `SoundClip` class is a simple abstraction for playing a sound clip. It will play any format that is recognized by the `javax.sound` API, and for which it has support. This includes midi data.

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.

Applications needing more precise control or advanced features should look into other parts of the `javax.sound` API. Playing sound requires that the environment grants access to audio devices. Typically this means running the application in a desktop environment.

Multiple `SoundClip` items can be playing at the same time, and the resulting sound is mixed together to produce a composite.

Since:
  25

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `canPlay()`
  Returns whether this is a playable sound clip.
  `static SoundClip`
  `createSoundClip(File file)`
  Creates a `SoundClip` instance which will play a clip from the supplied file.
  `boolean`
  `isPlaying()`
  Returns whether sound is currently playing.
  `void`
  `loop()`
  Starts playing this sound clip in a loop.
  `void`
  `play()`
  Starts playing this sound clip.
  `void`
  `stop()`
  Stops playing this sound clip.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Method Details

  - ### createSoundClip

    public static SoundClip createSoundClip(File file) throws IOException
    Creates a `SoundClip` instance which will play a clip from the supplied file.

    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.

    Parameters:
      `file` - the file from which to obtain the sound data
    Returns:
      a `SoundClip`
    Throws:
      `NullPointerException` - if `file` is `null`
      `IOException` - if there is an error reading from `file`

  - ### canPlay

    public boolean canPlay()
    Returns whether this is a playable sound clip.

    A value of `false` means that calling any of the other methods of this class is a no-op.

    Returns:
      whether this is a playable sound clip

  - ### isPlaying

    public boolean isPlaying()
    Returns whether sound is currently playing.
    Returns:
      whether sound is currently playing

  - ### play

    public void play()
    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.

    Threading notes : Most applications will not need to do anything except call `play()`. The following is therefore something most applications need not be concerned about. Play back is managed in a background thread, which is usually 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 `stop()` method.

  - ### loop

    public void loop()
    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.

    Threading notes : Most applications will not need to do anything except call `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 `stop()` method.

  - ### stop

    public void stop()
    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 `loop()`.