JavaFX 24 · javafx.scene.media.AudioClip · APIdia, the JavaDoc alternative

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. AudioClips 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();

Field Summary

Modifier and Type	Field and Description
private AudioClip	audioClip
private DoubleProperty	balance The relative left and right volume levels of the clip.
private IntegerProperty	cycleCount The number of times the clip will be played when `play()` is called.
public static final int	INDEFINITE When `cycleCount` is set to this value, the `AudioClip` will loop continuously until stopped.
private DoubleProperty	pan The relative "center" of the clip.
private IntegerProperty	priority The relative priority of the clip with respect to other clips.
private DoubleProperty	rate The relative rate at which the clip is played.
private String	sourceURL
private DoubleProperty	volume The relative volume level at which the clip is played.

Constructor Summary

Access	Constructor and Description
public	AudioClip(String URL string from which to load the audio clip. This can be an HTTP, HTTPS, FILE or JAR source. source) Create an `AudioClip` loaded from the supplied source URL.

Method Summary

Modifier and Type	Method and Description
public DoubleProperty	balanceProperty()
public IntegerProperty	cycleCountProperty()
public double	Returns: the default balance for this clip getBalance() Get the default balance level for this clip.
public int	Returns: the default cycleCount for this audio clip getCycleCount() Get the default cycle count.
public double	Returns: the default pan value for this clip getPan() Get the default pan value.
public int	Returns: the default playback priority of this clip getPriority() Get the default playback priority.
public double	Returns: default playback rate for this clip getRate() Get the default playback rate.
public String	Returns: source URL as provided to the constructor getSource() Get the source URL used to create this `AudioClip`.
public final double	Returns: the default volume level for this clip getVolume() Get the default volume level.
public boolean	Returns: true if any mixer channel has this clip queued, false otherwise isPlaying() Indicate whether this `AudioClip` is playing.
public DoubleProperty	panProperty()
public void	play() Play the `AudioClip` using all the default parameters.
public void	play(double the volume level at which to play the clip volume) Play the `AudioClip` using all the default parameters except volume.
public void	play(double 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. volume, double Left/right balance or relative channel volumes for stereo effects. balance, double Playback rate multiplier. 1.0 will play at the normal rate while 2.0 will double the rate. rate, double 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. pan, int Audio effect priority. Lower priority effects will be dropped first if too many effects are trying to play simultaneously. priority) Play the `AudioClip` using the given parameters.
public IntegerProperty	priorityProperty()
public DoubleProperty	rateProperty()
public void	setBalance(double new default balance balance) Set the default balance level.
public void	setCycleCount(int the new default cycle count for this clip count) Set the default cycle count.
public void	setPan(double the new default pan value pan) Set the default pan value.
public void	setPriority(int the new default playback priority priority) Set the default playback priority.
public void	setRate(double the new default playback rate rate) Set the default playback rate.
public final void	setVolume(double new default volume level for this clip value) Set the default volume level.
public void	stop() Immediately stop all playback of this `AudioClip`.
public DoubleProperty	volumeProperty()

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

audioClip	back to summary
private AudioClip audioClip

balance	back to summary
private DoubleProperty balance 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.

cycleCount	back to summary
private IntegerProperty cycleCount 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.

INDEFINITE	back to summary
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 `javafx.animation.Animation#INDEFINITE`, these values may be used interchangeably.

pan	back to summary
private DoubleProperty pan 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.

pan

back to summary

private DoubleProperty pan

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.

priority	back to summary
private IntegerProperty priority 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.

priority

back to summary

private IntegerProperty priority

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.

rate	back to summary
private DoubleProperty rate 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.

sourceURL	back to summary
private String sourceURL

volume	back to summary
private DoubleProperty volume 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.

Constructor Detail

AudioClip back to summary

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

public AudioClip(String source)

Create an AudioClip loaded from the supplied source URL.

Parameters

source:String: URL string from which to load the audio clip. This can be an HTTP, HTTPS, FILE or JAR source.

Exceptions

NullPointerException:: if the parameter is null.
IllegalArgumentException:: if the parameter violates RFC 2396.
MediaException:: if there is some other problem loading the media.

Method Detail

balanceProperty	back to summary
public DoubleProperty balanceProperty()

cycleCountProperty	back to summary
public IntegerProperty cycleCountProperty()

getBalance back to summary

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

public double getBalance()

Get the default balance level for this clip.

Returns:double: the default balance for this clip
See Also: balanceProperty()

getCycleCount back to summary

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

public int getCycleCount()

Get the default cycle count.

Returns:int: the default cycleCount for this audio clip
See Also: cycleCountProperty()

getPan back to summary

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

public double getPan()

Get the default pan value.

Returns:double: the default pan value for this clip
See Also: panProperty()

getPriority back to summary

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

public int getPriority()

Get the default playback priority.

Returns:int: the default playback priority of this clip
See Also: priorityProperty()

getRate back to summary

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

public double getRate()

Get the default playback rate.

Returns:double: default playback rate for this clip
See Also: rateProperty()

getSource back to summary

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

public String getSource()

Get the source URL used to create this AudioClip.

Returns:String: source URL as provided to the constructor

getVolume back to summary

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

public final double getVolume()

Get the default volume level.

Returns:double: the default volume level for this clip
See Also: volumeProperty()

isPlaying back to summary

isPlaying	back to summary
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:boolean true if any mixer channel has this clip queued, false otherwise

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:boolean: true if any mixer channel has this clip queued, false otherwise

panProperty	back to summary
public DoubleProperty panProperty()

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

play back to summary

play	back to summary
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:double the volume level at which to play the clip

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:double: the volume level at which to play the clip

play back to summary

play	back to summary
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:double 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:double Left/right balance or relative channel volumes for stereo effects. rate:double Playback rate multiplier. 1.0 will play at the normal rate while 2.0 will double the rate. pan:double 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:int Audio effect priority. Lower priority effects will be dropped first if too many effects are trying to play simultaneously.

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:double: 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:double: Left/right balance or relative channel volumes for stereo effects.
rate:double: Playback rate multiplier. 1.0 will play at the normal rate while 2.0 will double the rate.
pan:double: 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:int: Audio effect priority. Lower priority effects will be dropped first if too many effects are trying to play simultaneously.

priorityProperty	back to summary
public IntegerProperty priorityProperty()

rateProperty	back to summary
public DoubleProperty rateProperty()

setBalance back to summary

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

public void setBalance(double balance)

Set the default balance level. The new value will only affect subsequent plays.

Parameters

balance:double: new default balance

See Also

balanceProperty()

setCycleCount back to summary

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

public void setCycleCount(int count)

Set the default cycle count. The new value will only affect subsequent plays.

Parameters

count:int: the new default cycle count for this clip

See Also

cycleCountProperty()

setPan back to summary

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

public void setPan(double pan)

Set the default pan value. The new value will only affect subsequent plays.

Parameters

pan:double: the new default pan value

See Also

panProperty()

setPriority back to summary

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

public void setPriority(int priority)

Set the default playback priority. The new value will only affect subsequent plays.

Parameters

priority:int: the new default playback priority

See Also

priorityProperty()

setRate back to summary

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

public void setRate(double rate)

Set the default playback rate. The new value will only affect subsequent plays.

Parameters

rate:double: the new default playback rate

See Also

rateProperty()

setVolume back to summary

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

public final void setVolume(double value)

Set the default volume level. The new setting will only take effect on subsequent plays.

Parameters

value:double: new default volume level for this clip

See Also

volumeProperty()

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

volumeProperty	back to summary
public DoubleProperty volumeProperty()

public final Class AudioClip

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail