Module javafx.media
Package javafx.scene.media

# Class AudioClip

java.lang.Object
javafx.scene.media.AudioClip

public final class AudioClip extends Object
An `AudioClip` represents a segment of audio that can be played with minimal latency. Clips are loaded similarly to `Media` objects but have different behavior, for example, a `Media` cannot play itself. `AudioClip`s are also usable immediately. Playback behavior is fire and forget: once one of the play methods is called the only operable control is `stop()`. An `AudioClip` may also be played multiple times simultaneously. To accomplish the same task using `Media` one would have to create a new `MediaPlayer` object for each sound played in parallel. `Media` objects are however better suited for long-playing sounds. This is primarily because `AudioClip` stores in memory the raw, uncompressed audio data for the entire sound, which can be quite large for long audio clips. A `MediaPlayer` will only have enough decompressed audio data pre-rolled in memory to play for a short amount of time so it is much more memory efficient for long clips, especially if they are compressed.

Example usage:

         AudioClip plonkSound = new AudioClip("http://somehost/path/plonk.aiff");
         plonkSound.play();

Since:
  JavaFX 2.0

- ## Property Summary

  Properties
  Type
  Property
  Description
  `DoubleProperty`
  `balance`
  The relative left and right volume levels of the clip.
  `IntegerProperty`
  `cycleCount`
  The number of times the clip will be played when `play()` is called.
  `DoubleProperty`
  `pan`
  The relative "center" of the clip.
  `IntegerProperty`
  `priority`
  The relative priority of the clip with respect to other clips.
  `DoubleProperty`
  `rate`
  The relative rate at which the clip is played.
  `DoubleProperty`
  `volume`
  The relative volume level at which the clip is played.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `INDEFINITE`
  When `cycleCount` is set to this value, the `AudioClip` will loop continuously until stopped.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AudioClip(String source)`
  Create an `AudioClip` loaded from the supplied source URL.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `DoubleProperty`
  `balanceProperty()`
  The relative left and right volume levels of the clip.
  `IntegerProperty`
  `cycleCountProperty()`
  The number of times the clip will be played when `play()` is called.
  `double`
  `getBalance()`
  Get the default balance level for this clip.
  `int`
  `getCycleCount()`
  Get the default cycle count.
  `double`
  `getPan()`
  Get the default pan value.
  `int`
  `getPriority()`
  Get the default playback priority.
  `double`
  `getRate()`
  Get the default playback rate.
  `String`
  `getSource()`
  Get the source URL used to create this `AudioClip`.
  `final double`
  `getVolume()`
  Get the default volume level.
  `boolean`
  `isPlaying()`
  Indicate whether this `AudioClip` is playing.
  `DoubleProperty`
  `panProperty()`
  The relative "center" of the clip.
  `void`
  `play()`
  Play the `AudioClip` using all the default parameters.
  `void`
  `play(double volume)`
  Play the `AudioClip` using all the default parameters except volume.
  `void`
  `play(double volume, double balance, double rate, double pan, int priority)`
  Play the `AudioClip` using the given parameters.
  `IntegerProperty`
  `priorityProperty()`
  The relative priority of the clip with respect to other clips.
  `DoubleProperty`
  `rateProperty()`
  The relative rate at which the clip is played.
  `void`
  `setBalance(double balance)`
  Set the default balance level.
  `void`
  `setCycleCount(int count)`
  Set the default cycle count.
  `void`
  `setPan(double pan)`
  Set the default pan value.
  `void`
  `setPriority(int priority)`
  Set the default playback priority.
  `void`
  `setRate(double rate)`
  Set the default playback rate.
  `final void`
  `setVolume(double value)`
  Set the default volume level.
  `void`
  `stop()`
  Immediately stop all playback of this `AudioClip`.
  `DoubleProperty`
  `volumeProperty()`
  The relative volume level at which the clip is played.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Property Details

  - ### volume

    public DoubleProperty volumeProperty
    The relative volume level at which the clip is played. Valid range is 0.0 (muted) to 1.0 (full volume). Values are clamped to this range internally so values outside this range will have no additional effect. Volume is controlled by attenuation, so values below 1.0 will reduce the sound level accordingly.
    See Also:
      - `getVolume()`
      - `setVolume(double)`
      - `volumeProperty()`

  - ### balance

    public DoubleProperty balanceProperty
    The relative left and right volume levels of the clip. Valid range is -1.0 to 1.0 where -1.0 gives full volume to the left channel while muting the right channel, 0.0 gives full volume to both channels and 1.0 gives full volume to right channel and mutes the left channel. Values outside this range are clamped internally.
    See Also:
      - `getBalance()`
      - `setBalance(double)`
      - `balanceProperty()`

  - ### rate

    public DoubleProperty rateProperty
    The relative rate at which the clip is played. Valid range is 0.125 (1/8 speed) to 8.0 (8x speed); values outside this range are clamped internally. Normal playback for a clip is 1.0; any other rate will affect pitch and duration accordingly.
    See Also:
      - `getRate()`
      - `setRate(double)`
      - `rateProperty()`

  - ### pan

    public DoubleProperty panProperty
    The relative "center" of the clip. A pan value of 0.0 plays the clip normally where a -1.0 pan shifts the clip entirely to the left channel and 1.0 shifts entirely to the right channel. Unlike balance this setting mixes both channels so neither channel loses data. Setting pan on a mono clip has the same effect as setting balance, but with a much higher cost in CPU overhead so this is not recommended for mono clips.
    See Also:
      - `getPan()`
      - `setPan(double)`
      - `panProperty()`

  - ### priority

    public IntegerProperty priorityProperty
    The relative priority of the clip with respect to other clips. This value is used to determine which clips to remove when the maximum allowed number of clips is exceeded. The lower the priority, the more likely the clip is to be stopped and removed from the mixer channel it is occupying. Valid range is any integer; there are no constraints. The default priority is zero for all clips until changed. The number of simultaneous sounds that can be played is implementation- and possibly system-dependent.
    See Also:
      - `getPriority()`
      - `setPriority(int)`
      - `priorityProperty()`

  - ### cycleCount

    public IntegerProperty cycleCountProperty
    The number of times the clip will be played when `play()` is called. A cycleCount of 1 plays exactly once, a cycleCount of 2 plays twice and so on. Valid range is 1 or more, but setting this to `INDEFINITE` will cause the clip to continue looping until `stop()` is called.
    See Also:
      - `getCycleCount()`
      - `setCycleCount(int)`
      - `cycleCountProperty()`

- ## Field Details

  - ### INDEFINITE

    public static final int INDEFINITE
    When `cycleCount` is set to this value, the `AudioClip` will loop continuously until stopped. This value is synonymous with `MediaPlayer.INDEFINITE` and `Animation.INDEFINITE`, these values may be used interchangeably.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### AudioClip

    public AudioClip(String source)
    Create an `AudioClip` loaded from the supplied source URL.
    Parameters:
      `source` - URL string from which to load the audio clip. This can be an HTTP, HTTPS, FILE or JAR source.
    Throws:
      `NullPointerException` - if the parameter is `null`.
      `IllegalArgumentException` - if the parameter violates RFC 2396.
      `MediaException` - if there is some other problem loading the media.

- ## Method Details

  - ### getSource

    public String getSource()
    Get the source URL used to create this `AudioClip`.
    Returns:
      source URL as provided to the constructor

  - ### setVolume

    public final void setVolume(double value)
    Set the default volume level. The new setting will only take effect on subsequent plays.
    Parameters:
      `value` - new default volume level for this clip
    See Also:
      - `volumeProperty()`

  - ### getVolume

    public final double getVolume()
    Get the default volume level.
    Returns:
      the default volume level for this clip
    See Also:
      - `volumeProperty()`

  - ### volumeProperty

    public DoubleProperty volumeProperty()
    The relative volume level at which the clip is played. Valid range is 0.0 (muted) to 1.0 (full volume). Values are clamped to this range internally so values outside this range will have no additional effect. Volume is controlled by attenuation, so values below 1.0 will reduce the sound level accordingly.
    Returns:
      the `volume` property
    See Also:
      - `getVolume()`
      - `setVolume(double)`

  - ### setBalance

    public void setBalance(double balance)
    Set the default balance level. The new value will only affect subsequent plays.
    Parameters:
      `balance` - new default balance
    See Also:
      - `balanceProperty()`

  - ### getBalance

    public double getBalance()
    Get the default balance level for this clip.
    Returns:
      the default balance for this clip
    See Also:
      - `balanceProperty()`

  - ### balanceProperty

    public DoubleProperty balanceProperty()
    The relative left and right volume levels of the clip. Valid range is -1.0 to 1.0 where -1.0 gives full volume to the left channel while muting the right channel, 0.0 gives full volume to both channels and 1.0 gives full volume to right channel and mutes the left channel. Values outside this range are clamped internally.
    Returns:
      the `balance` property
    See Also:
      - `getBalance()`
      - `setBalance(double)`

  - ### setRate

    public void setRate(double rate)
    Set the default playback rate. The new value will only affect subsequent plays.
    Parameters:
      `rate` - the new default playback rate
    See Also:
      - `rateProperty()`

  - ### getRate

    public double getRate()
    Get the default playback rate.
    Returns:
      default playback rate for this clip
    See Also:
      - `rateProperty()`

  - ### rateProperty

    public DoubleProperty rateProperty()
    The relative rate at which the clip is played. Valid range is 0.125 (1/8 speed) to 8.0 (8x speed); values outside this range are clamped internally. Normal playback for a clip is 1.0; any other rate will affect pitch and duration accordingly.
    Returns:
      the `rate` property
    See Also:
      - `getRate()`
      - `setRate(double)`

  - ### setPan

    public void setPan(double pan)
    Set the default pan value. The new value will only affect subsequent plays.
    Parameters:
      `pan` - the new default pan value
    See Also:
      - `panProperty()`

  - ### getPan

    public double getPan()
    Get the default pan value.
    Returns:
      the default pan value for this clip
    See Also:
      - `panProperty()`

  - ### panProperty

    public DoubleProperty panProperty()
    The relative "center" of the clip. A pan value of 0.0 plays the clip normally where a -1.0 pan shifts the clip entirely to the left channel and 1.0 shifts entirely to the right channel. Unlike balance this setting mixes both channels so neither channel loses data. Setting pan on a mono clip has the same effect as setting balance, but with a much higher cost in CPU overhead so this is not recommended for mono clips.
    Returns:
      the `pan` property
    See Also:
      - `getPan()`
      - `setPan(double)`

  - ### setPriority

    public void setPriority(int priority)
    Set the default playback priority. The new value will only affect subsequent plays.
    Parameters:
      `priority` - the new default playback priority
    See Also:
      - `priorityProperty()`

  - ### getPriority

    public int getPriority()
    Get the default playback priority.
    Returns:
      the default playback priority of this clip
    See Also:
      - `priorityProperty()`

  - ### priorityProperty

    public IntegerProperty priorityProperty()
    The relative priority of the clip with respect to other clips. This value is used to determine which clips to remove when the maximum allowed number of clips is exceeded. The lower the priority, the more likely the clip is to be stopped and removed from the mixer channel it is occupying. Valid range is any integer; there are no constraints. The default priority is zero for all clips until changed. The number of simultaneous sounds that can be played is implementation- and possibly system-dependent.
    Returns:
      the `priority` property
    See Also:
      - `getPriority()`
      - `setPriority(int)`

  - ### setCycleCount

    public void setCycleCount(int count)
    Set the default cycle count. The new value will only affect subsequent plays.
    Parameters:
      `count` - the new default cycle count for this clip
    See Also:
      - `cycleCountProperty()`

  - ### getCycleCount

    public int getCycleCount()
    Get the default cycle count.
    Returns:
      the default cycleCount for this audio clip
    See Also:
      - `cycleCountProperty()`

  - ### cycleCountProperty

    public IntegerProperty cycleCountProperty()
    The number of times the clip will be played when `play()` is called. A cycleCount of 1 plays exactly once, a cycleCount of 2 plays twice and so on. Valid range is 1 or more, but setting this to `INDEFINITE` will cause the clip to continue looping until `stop()` is called.
    Returns:
      the `cycleCount` property
    See Also:
      - `getCycleCount()`
      - `setCycleCount(int)`

  - ### play

    public void play()
    Play the `AudioClip` using all the default parameters.

  - ### play

    public void play(double volume)
    Play the `AudioClip` using all the default parameters except volume. This method does not modify the clip's default parameters.
    Parameters:
      `volume` - the volume level at which to play the clip

  - ### play

    public void play(double volume, double balance, double rate, double pan, int priority)
    Play the `AudioClip` using the given parameters. Values outside the ranges as specified by their associated properties are clamped. This method does not modify the clip's default parameters.
    Parameters:
      `volume` - Volume level at which to play this clip. Valid volume range is 0.0 to 1.0, where 0.0 is effectively muted and 1.0 is full volume.
      `balance` - Left/right balance or relative channel volumes for stereo effects.
      `rate` - Playback rate multiplier. 1.0 will play at the normal rate while 2.0 will double the rate.
      `pan` - Left/right shift to be applied to the clip. A pan value of -1.0 means full left channel, 1.0 means full right channel, 0.0 has no effect.
      `priority` - Audio effect priority. Lower priority effects will be dropped first if too many effects are trying to play simultaneously.

  - ### isPlaying

    public boolean isPlaying()
    Indicate whether this `AudioClip` is playing. If this returns true then `play()` has been called at least once and it is still playing.
    Returns:
      true if any mixer channel has this clip queued, false otherwise

  - ### stop

    public void stop()
    Immediately stop all playback of this `AudioClip`.