Top Description Fields Constructors Methods
com.sun.media.jfxmedia

public abstract Class AudioClip

extends Object
Class Inheritance
Known Direct Subclasses
com.sun.media.jfxmediaimpl.NativeAudioClip, com.sun.media.jfxmediaimpl.NativeMediaAudioClip
Imports
com.sun.media.jfxmediaimpl.AudioClipProvider, java.io.IOException, .FileNotFoundException, java.net.URI, .URISyntaxException
AudioClips are short segments of audio that can be played quickly and on-demand. Though loading of compressed audio formats may be supported, all AudioClip data is stored uncompressed internally to avoid decoding latency. The system is currently capable of playing up to 16 AudioClips simultaneously.

Core AudioClip features:

  • Near-zero latency playback, playback begins as soon as it's called, decoding is done at load time
  • Play clips up to ten seconds, though clips of any length may be loaded
  • Quick and simple "one shot" playback interface, just load the effect and play, cleanup is automatic
  • Play/pause/stop playback of effect, each playback instance is unique and can be controlled individually
  • Each effect can be played multiple times simultaneously
  • Loop playback (to some maximum amount?)
  • Vary rate/pitch
  • Playback volume
  • Effect balance
  • Pan left/right
  • Mix N audio effects for simultaneous playback (N TBD, start with 32)
  • Audio effect priority, lower priority effects get dropped first when playback threshold is reached


    • Loading sound effects 
    
SoundEffectBank soundBank = /* TBD */ ;
AudioClip ding = soundBank.effectNamed("ding");
AudioClip dong = soundBank.effectNamed("dong");
    OR
    
import javafx.scene.media.Media;
import javafx.scene.media.AudioClip;

AudioClip ding = new AudioClip("http://somehost.com/sounds/ding.aiff");
AudioClip dong = new AudioClip("jar:http://host/path/some.jar!/resources/sounds/dong.aiff");

     // Or you can use the ClassLoader to get a resource URI for resources bundled inside your application jar file
AudioClip bonk = new AudioClip(this.getClass().getClassLoader().getResource("sounds/bonk.wav"));

     // You can also load from a Media object
Media whizMedia = new Media("http://somehost.com/sounds/whiz.aiff");
AudioClip whiz = new AudioClip(whizMedia);

    Playing sound effects

    Single play (fire and forget method): 

    ding.play();
dong.play(); // the two sounds play simultaneously, there is no further control over playback

    Chaining multiple effects: 
    ding.append(dong).play(); // ding and dong play sequentially, when finished the player is automatically disposed of
ding.append(dong).append(ding).append(dong).append(ding).append(dong).play(); // really impatient person at the door :)
AudioClip dingDong = ding.append(dong).flatten(); // dingDong is completely independent of ding and dong

    Field Summary

    Modifier and TypeField and Description
    protected double
    clipBalance

    protected double
    clipPan

    protected int
    clipPriority

    protected double
    clipRate

    protected double
    clipVolume

    protected int
    loopCount

    public static final int
    SAMPLE_FORMAT_S16BE

    Unsigned 8 bit LPCM

    public static final int
    SAMPLE_FORMAT_S16LE

    Unsigned 16 bit LPCM, big endian byte order

    public static final int
    SAMPLE_FORMAT_S24BE

    Unsigned 16 bit LPCM, little endian byte order

    public static final int
    SAMPLE_FORMAT_S24LE

    Unsigned 24 bit LPCM, big endian byte order

    public static final int
    SAMPLE_FORMAT_S8

    public static final int
    SAMPLE_FORMAT_U16BE

    Signed 16 bit LPCM, big endian byte order

    public static final int
    SAMPLE_FORMAT_U16LE

    Signed 16 bit LPCM, little endian byte order

    public static final int
    SAMPLE_FORMAT_U24BE

    Signed 24 bit LPCM, big endian byte order

    public static final int
    SAMPLE_FORMAT_U24LE

    Signed 24 bit LPCM, little endian byte order

    public static final int
    SAMPLE_FORMAT_U8

    Signed 8 bit LPCM

    Constructor Summary

    AccessConstructor and Description
    public
    AudioClip()

    Method Summary

    Modifier and TypeMethod and Description
    public abstract AudioClip

    Returns:

    A new AudioClip that contains the concatenation of the two source clips.
    append    (AudioClip
    The clip to be appended to the current clip.
    clip    )

    Create a new AudioClip by appending the given clip to the current clip.

    public double
    balance()

    Returns the left/right channel balance.

    public static AudioClip

    Returns:

    A new AudioClip that can play the given raw LPCM audio data.
    create    (byte[]
    Raw PCM samples stored in a byte array.
    data    ,     int
    Byte offset into data that the sample data starts.
    dataOffset    ,     int
    Number of LPCM samples stored in data.
    sampleCount    ,     int
    Raw format that the LPCM data is being provided in. This may not be the actual format stored internally.
    sampleFormat    ,     int
    The number of channels. Currently only two channel audio is supported, channels beyond two are simply dropped.
    channels    ,     int
    Audio sample playbackRate of the raw LPCM data.
    sampleRate    )

    Generate a AudioClip from raw LPCM audio data.

    public abstract AudioClip

    Returns:

    A new AudioClip instance containing only the specified segment of the source clip
    createSegment    (double
    The start time for the segment
    startTime    ,     double
    The end time of the segment or -1.0 for the remainder of the source clip.
    stopTime    )

    Create a new AudioClip from a segment of an existing AudioClip.

    public abstract AudioClip

    Returns:

    A new AudioClip instance containing only the specified segment of the source clip
    createSegment    (int
    The starting audio sample for the segment
    startSample    ,     int
    The ending audio sample of the segment, or -1 for the remainder of the source clip.
    endSample    )

    Create a new AudioClip from a segment of an existing AudioClip.

    public abstract AudioClip

    Returns:

    A new AudioClip that is independent of all other clips.
    flatten    ()

    Creates a completely independent AudioClip.

    public abstract boolean

    Returns:

    true if at least one AudioClipPlayer is playing or has this AudioClip enqueued.
    isPlaying    ()

    Test if any AudioClipPlayer has this AudioClip in its effect chain.

    public static AudioClip

    Returns:

    AudioClip ready to play.
    load    (URI
    URI to the desired clip.
    source    )

    Load an audio clip from the specified source URI.

    public int

    Returns:

    The number of times a AudioClip will be repeated when played.
    loopCount    ()

    Get the number of times the associated AudioClip will repeat when played.

    public double

    Returns:

    Current pan value.
    pan    ()

    Pan (left/right spread) setting.

    public abstract void
    play()

    Play this AudioClip with the default parameters.

    public abstract void
    play(double
    Volume level to play this effect at. Valid volume range is 0.0 to 1.0, where 0.0 is effectively muted and 1.0 is full volume.
    volume    )

    Play this AudioClip at the given volume level.

    public abstract void
    play(double
    Volume level to play this effect at. 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 back 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
    The number of times to play this clip, specify -1 to loop indefinitely
    loopCount    ,     int
    Audio effect priority. Lower priority effects will be dropped first if too many effects are trying to play simultaneously.
    priority    )

    Play this AudioClip at the given volume level and relative pitch.

    public double

    Returns:

    Audio playback sample rate multiplier.
    playbackRate    ()

    Gets the audio sample rate multiplier that this player will use while playing the associated AudioClip.

    public int
    priority()

    public abstract AudioClip

    Returns:

    A new AudioClip that contains a copy of the source AudioClip resampled to the new sample playbackRate.
    resample    (int
    starting sample to begin resampling at. The first sample is always zero, negative values are not allowed.
    startSample    ,     int
    The last sample to resample or -1 for the remainder of the source clip.
    endSample    ,     int
    The sample playbackRate to create the new AudioClip at.
    newSampleRate    )

    Create a new AudioClip from an existing clip by resampling a segment of the source clip to the specified sample playbackRate.

    public void
    setBalance(double bal)

    Set left/right balance or relative channel volumes for stereo effects.

    public void
    setLoopCount(int
    How many times to repeat the AudioClip during normal playback. If this is zero, then the AudioClip will play exactly once and stop. Set this to -1 to repeat indefinitely, other negative values are undefined.
    loopCount    )

    Specify the number of times a AudioClip should be repeated when this player is played.

    public void
    setPan(double
    Audio pan setting
    pan    )

    Sets the audio pan (or left/right channel spread) value.

    public void
    setPlaybackRate(double
    The new audio rate multiplier. Only positive values above zero are allowed. Note that implementations may cap this value at some undefined amount.
    rate    )

    Set the audio sample rate multiplier.

    public void
    setPriority(int prio)

    public void
    setVolume(double vol)

    Set the volume level for playback.

    public abstract void
    stop()

    Stops all playback of this AudioClip.

    public static void
    stopAllClips()

    Stop all AudioClips that are currently playing.

    public double

    Returns:

    Volume level.
    volume    ()

    Returns playback volume.

    Inherited from java.lang.Object:
    cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

    Field Detail

    clipBalanceback to summary
    protected double clipBalance
    clipPanback to summary
    protected double clipPan
    clipPriorityback to summary
    protected int clipPriority
    clipRateback to summary
    protected double clipRate
    clipVolumeback to summary
    protected double clipVolume
    loopCountback to summary
    protected int loopCount
    SAMPLE_FORMAT_S16BEback to summary
    public static final int SAMPLE_FORMAT_S16BE

    Unsigned 8 bit LPCM

    SAMPLE_FORMAT_S16LEback to summary
    public static final int SAMPLE_FORMAT_S16LE

    Unsigned 16 bit LPCM, big endian byte order

    SAMPLE_FORMAT_S24BEback to summary
    public static final int SAMPLE_FORMAT_S24BE

    Unsigned 16 bit LPCM, little endian byte order

    SAMPLE_FORMAT_S24LEback to summary
    public static final int SAMPLE_FORMAT_S24LE

    Unsigned 24 bit LPCM, big endian byte order

    SAMPLE_FORMAT_S8back to summary
    public static final int SAMPLE_FORMAT_S8
    SAMPLE_FORMAT_U16BEback to summary
    public static final int SAMPLE_FORMAT_U16BE

    Signed 16 bit LPCM, big endian byte order

    SAMPLE_FORMAT_U16LEback to summary
    public static final int SAMPLE_FORMAT_U16LE

    Signed 16 bit LPCM, little endian byte order

    SAMPLE_FORMAT_U24BEback to summary
    public static final int SAMPLE_FORMAT_U24BE

    Signed 24 bit LPCM, big endian byte order

    SAMPLE_FORMAT_U24LEback to summary
    public static final int SAMPLE_FORMAT_U24LE

    Signed 24 bit LPCM, little endian byte order

    SAMPLE_FORMAT_U8back to summary
    public static final int SAMPLE_FORMAT_U8

    Signed 8 bit LPCM

    Constructor Detail

    AudioClipback to summary
    public AudioClip()

    Method Detail

    appendback to summary
    public abstract AudioClip append(AudioClip clip) throws IOException

    Create a new AudioClip by appending the given clip to the current clip. The new clip is independent of the two source clips. If the sample rates are mismatched, the new clip will contain at least one resampled copy of a source clip. Which clip is resampled is implementation dependent.

    Parameters
    clip:AudioClip

    The clip to be appended to the current clip.

    Returns:AudioClip

    A new AudioClip that contains the concatenation of the two source clips.

    Exceptions
    IOException:
    If an error occurred during the concatenation, generally during rate conversion if it's necessary.
    balanceback to summary
    public double balance()

    Returns the left/right channel balance.

    createback to summary
    public static AudioClip create(byte[] data, int dataOffset, int sampleCount, int sampleFormat, int channels, int sampleRate) throws IllegalArgumentException

    Generate a AudioClip from raw LPCM audio data. This can be used to programmatically create sound effects, either generated mathematically or loaded from some arbitrary source. Multiple channels must be interleaved properly, for stereo audio left channel is always first.

    Parameters
    data:byte[]

    Raw PCM samples stored in a byte array.

    dataOffset:int

    Byte offset into data that the sample data starts.

    sampleCount:int

    Number of LPCM samples stored in data.

    sampleFormat:int

    Raw format that the LPCM data is being provided in. This may not be the actual format stored internally.

    channels:int

    The number of channels. Currently only two channel audio is supported, channels beyond two are simply dropped.

    sampleRate:int

    Audio sample playbackRate of the raw LPCM data.

    Returns:AudioClip

    A new AudioClip that can play the given raw LPCM audio data.

    Exceptions
    IllegalArgumentException:
    If an AudioClip cannot be created with the given arguments.
    createSegmentback to summary
    public abstract AudioClip createSegment(double startTime, double stopTime) throws IllegalArgumentException

    Create a new AudioClip from a segment of an existing AudioClip. The new clip may copy or simply reference this existing clip, so be aware that this operation may have a severe memory usage impact for long segments. The default parameters are copied to the new clip. This variant specifies the start and end times of the segment. Specifying an end time beyond the duration of the clip will crop the new AudioClip to the end of the source clip. Specifying a start time less than zero or greater than end time is undefined and will return null.

    Parameters
    startTime:double

    The start time for the segment

    stopTime:double

    The end time of the segment or -1.0 for the remainder of the source clip.

    Returns:AudioClip

    A new AudioClip instance containing only the specified segment of the source clip

    Exceptions
    IllegalArgumentException:
    If startTime or stopTime are not valid for this AudioClip.
    createSegmentback to summary
    public abstract AudioClip createSegment(int startSample, int endSample) throws IllegalArgumentException

    Create a new AudioClip from a segment of an existing AudioClip. The new clip may copy or simply reference this existing clip, so be aware that this operation may have a severe memory usage impact for long segments. The default parameters are copied to the new clip. This variant specifies the exact sample offsets of the segment, starting at sample zero. If endSample is greater than the number of samples in the source clip, it will be cropped to the last sample. Specifying a start sample less than zero or higher than endSample is undefined and will return null.

    Parameters
    startSample:int

    The starting audio sample for the segment

    endSample:int

    The ending audio sample of the segment, or -1 for the remainder of the source clip.

    Returns:AudioClip

    A new AudioClip instance containing only the specified segment of the source clip

    Exceptions
    IllegalArgumentException:
    If the given sample range is invalid for this AudioClip.
    flattenback to summary
    public abstract AudioClip flatten()

    Creates a completely independent AudioClip. Any references contained will be copied and the references removed. The result will be a single AudioEffect containing all the audio data required to produce the effect. If the effect is already independent, then this will simply return the same AudioClip.

    Returns:AudioClip

    A new AudioClip that is independent of all other clips.

    isPlayingback to summary
    public abstract boolean isPlaying()

    Test if any AudioClipPlayer has this AudioClip in its effect chain.

    Returns:boolean

    true if at least one AudioClipPlayer is playing or has this AudioClip enqueued.

    loadback to summary
    public static AudioClip load(URI source) throws URISyntaxException, FileNotFoundException, IOException

    Load an audio clip from the specified source URI. Currently supported formats are AIFF and WAV files. Audio data in the file must be raw PCM, loading compressed files is not supported at this time.

    Parameters
    source:URI

    URI to the desired clip.

    Returns:AudioClip

    AudioClip ready to play.

    Exceptions
    IOException:
    If an error occurred while loading the clip.
    IllegalArgumentException:
    If an invalid URI is provided.
    loopCountback to summary
    public int loopCount()

    Get the number of times the associated AudioClip will repeat when played. Note that if you start a clip looping indefinitely the only way to stop is to call AudioClip.stop() to stop all playback of a clip.

    Returns:int

    The number of times a AudioClip will be repeated when played.

    panback to summary
    public double pan()

    Pan (left/right spread) setting.

    Returns:double

    Current pan value.

    playback to summary
    public abstract void play()

    Play this AudioClip with the default parameters. This is a fire and forget method, the clip will play exactly once using the default parameters.

    playback to summary
    public abstract void play(double volume)

    Play this AudioClip at the given volume level. This is a fire and forget method, the clip will play exactly once using the given volume and default pitch and pan.

    Parameters
    volume:double

    Volume level to play this effect at. Valid volume range is 0.0 to 1.0, where 0.0 is effectively muted and 1.0 is full volume.

    playback to summary
    public abstract void play(double volume, double balance, double rate, double pan, int loopCount, int priority)

    Play this AudioClip at the given volume level and relative pitch. This is a fire and forget method, the clip will play exactly once using the given parameters.

    Parameters
    volume:double

    Volume level to play this effect at. 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 back 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.

    loopCount:int

    The number of times to play this clip, specify -1 to loop indefinitely

    priority:int

    Audio effect priority. Lower priority effects will be dropped first if too many effects are trying to play simultaneously.

    playbackRateback to summary
    public double playbackRate()

    Gets the audio sample rate multiplier that this player will use while playing the associated AudioClip.

    Returns:double

    Audio playback sample rate multiplier.

    See Also
    setPlaybackRate(double)
    priorityback to summary
    public int priority()
    resampleback to summary
    public abstract AudioClip resample(int startSample, int endSample, int newSampleRate) throws IllegalArgumentException, IOException

    Create a new AudioClip from an existing clip by resampling a segment of the source clip to the specified sample playbackRate.

    Parameters
    startSample:int

    starting sample to begin resampling at. The first sample is always zero, negative values are not allowed.

    endSample:int

    The last sample to resample or -1 for the remainder of the source clip.

    newSampleRate:int

    The sample playbackRate to create the new AudioClip at.

    Returns:AudioClip

    A new AudioClip that contains a copy of the source AudioClip resampled to the new sample playbackRate.

    Exceptions
    IllegalArgumentException:
    If the sample range is invalid for this AudioClip, or the new sample rate is not supported.
    IOException:
    If an error occurred during rate conversion.
    setBalanceback to summary
    public void setBalance(double bal)

    Set left/right balance or relative channel volumes for stereo effects. A value of 0.0 is equal levels (both channels at full volume), -1.0 is full left channel with muted right, 1.0 is full right channel with muted left.

    setLoopCountback to summary
    public void setLoopCount(int loopCount)

    Specify the number of times a AudioClip should be repeated when this player is played. Note that if you start a clip looping indefinitely the only way to stop is to call AudioClip.stop() to stop all playback of a clip.

    Parameters
    loopCount:int

    How many times to repeat the AudioClip during normal playback. If this is zero, then the AudioClip will play exactly once and stop. Set this to -1 to repeat indefinitely, other negative values are undefined.

    setPanback to summary
    public void setPan(double pan)

    Sets the audio pan (or left/right channel spread) value. Valid range is -1.0 to 1.0 inclusively. A zero setting means normal playback, left and right channels will be sent to their respective output channels. A -1.0 value shifts the AudioClip so that all sound is output only on the left output channel, likewise a 1.0 value shifts completely to the right output channel.

    Parameters
    pan:double

    Audio pan setting

    setPlaybackRateback to summary
    public void setPlaybackRate(double rate)

    Set the audio sample rate multiplier. The player will use this multiplier when mixing audio to effectively modify the playback rate. A value of 1.0 plays the AudioClip at it's normal sample rate. For example, setting the playback rate of a AudioClip that normally plays at 48 KHz to 0.5 will cause the player to effectively play the AudioClip at 24 KHz.

    Parameters
    rate:double

    The new audio rate multiplier. Only positive values above zero are allowed. Note that implementations may cap this value at some undefined amount.

    See Also
    playbackRate()
    setPriorityback to summary
    public void setPriority(int prio)
    setVolumeback to summary
    public void setVolume(double vol)

    Set the volume level for playback. Volume control is by attenuation, a volume of 1.0 is full volume where 0.0 is effectively muted.

    stopback to summary
    public abstract void stop()

    Stops all playback of this AudioClip.

    stopAllClipsback to summary
    public static void stopAllClips()

    Stop all AudioClips that are currently playing.

    volumeback to summary
    public double volume()

    Returns playback volume.

    Returns:double

    Volume level.