public abstract class AudioClip extends Object
AudioClip
s 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 AudioClip
s simultaneously.
Core AudioClip features:
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
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
Modifier and Type | Field and Description |
---|---|
protected double |
clipBalance |
protected double |
clipPan |
protected int |
clipPriority |
protected double |
clipRate |
protected double |
clipVolume |
protected int |
loopCount |
static int |
SAMPLE_FORMAT_S16BE
Unsigned 8 bit LPCM
|
static int |
SAMPLE_FORMAT_S16LE
Unsigned 16 bit LPCM, big endian byte order
|
static int |
SAMPLE_FORMAT_S24BE
Unsigned 16 bit LPCM, little endian byte order
|
static int |
SAMPLE_FORMAT_S24LE
Unsigned 24 bit LPCM, big endian byte order
|
static int |
SAMPLE_FORMAT_S8 |
static int |
SAMPLE_FORMAT_U16BE
Signed 16 bit LPCM, big endian byte order
|
static int |
SAMPLE_FORMAT_U16LE
Signed 16 bit LPCM, little endian byte order
|
static int |
SAMPLE_FORMAT_U24BE
Signed 24 bit LPCM, big endian byte order
|
static int |
SAMPLE_FORMAT_U24LE
Signed 24 bit LPCM, little endian byte order
|
static int |
SAMPLE_FORMAT_U8
Signed 8 bit LPCM
|
Constructor and Description |
---|
AudioClip() |
Modifier and Type | Method and Description |
---|---|
abstract AudioClip |
append(AudioClip clip)
Create a new AudioClip by appending the given clip to the current clip.
|
double |
balance()
Returns the left/right channel balance.
|
static AudioClip |
create(byte[] data,
int dataOffset,
int sampleCount,
int sampleFormat,
int channels,
int sampleRate)
Generate a AudioClip from raw LPCM audio data.
|
abstract AudioClip |
createSegment(double startTime,
double stopTime)
Create a new AudioClip from a segment of an existing AudioClip.
|
abstract AudioClip |
createSegment(int startSample,
int endSample)
Create a new AudioClip from a segment of an existing AudioClip.
|
abstract AudioClip |
flatten()
Creates a completely independent AudioClip.
|
abstract boolean |
isPlaying()
Test if any AudioClipPlayer has this AudioClip in its effect chain.
|
static AudioClip |
load(URI source)
Load an audio clip from the specified source URI.
|
int |
loopCount()
Get the number of times the associated AudioClip will repeat when
played.
|
double |
pan()
Pan (left/right spread) setting.
|
abstract void |
play()
Play this AudioClip with the default parameters.
|
abstract void |
play(double volume)
Play this AudioClip at the given volume level.
|
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.
|
double |
playbackRate()
Gets the audio sample rate multiplier that this player will use while
playing the associated AudioClip.
|
int |
priority() |
abstract AudioClip |
resample(int startSample,
int endSample,
int newSampleRate)
Create a new AudioClip from an existing clip by resampling a segment of
the source clip to the specified sample playbackRate.
|
void |
setBalance(double bal)
Set left/right balance or relative channel volumes for stereo effects.
|
void |
setLoopCount(int loopCount)
Specify the number of times a AudioClip should be repeated when this
player is played.
|
void |
setPan(double pan)
Sets the audio pan (or left/right channel spread) value.
|
void |
setPlaybackRate(double rate)
Set the audio sample rate multiplier.
|
void |
setPriority(int prio) |
void |
setVolume(double vol)
Set the volume level for playback.
|
abstract void |
stop()
Stops all playback of this AudioClip.
|
static void |
stopAllClips()
Stop all AudioClips that are currently playing.
|
double |
volume()
Returns playback volume.
|
protected int clipPriority
protected int loopCount
protected double clipVolume
protected double clipBalance
protected double clipRate
protected double clipPan
public static final int SAMPLE_FORMAT_S8
public static final int SAMPLE_FORMAT_U8
public static final int SAMPLE_FORMAT_S16BE
public static final int SAMPLE_FORMAT_U16BE
public static final int SAMPLE_FORMAT_S16LE
public static final int SAMPLE_FORMAT_U16LE
public static final int SAMPLE_FORMAT_S24BE
public static final int SAMPLE_FORMAT_U24BE
public static final int SAMPLE_FORMAT_S24LE
public static final int SAMPLE_FORMAT_U24LE
public static AudioClip load(URI source) throws URISyntaxException, FileNotFoundException, IOException
source
- URI to the desired clip.IOException
- If an error occurred while loading the clip.IllegalArgumentException
- If an invalid URI is provided.URISyntaxException
FileNotFoundException
public static AudioClip create(byte[] data, int dataOffset, int sampleCount, int sampleFormat, int channels, int sampleRate) throws IllegalArgumentException
data
- Raw PCM samples stored in a byte array.dataOffset
- Byte offset into data that the sample data starts.sampleCount
- Number of LPCM samples stored in data.sampleFormat
- Raw format that the LPCM data is being provided in.
This may not be the actual format stored internally.channels
- The number of channels. Currently only two channel
audio is supported, channels beyond two are simply dropped.sampleRate
- Audio sample playbackRate of the raw LPCM data.IllegalArgumentException
- If an AudioClip cannot be created with
the given arguments.public static void stopAllClips()
public abstract AudioClip createSegment(double startTime, double stopTime) throws IllegalArgumentException
startTime
- The start time for the segmentstopTime
- The end time of the segment or -1.0 for the remainder of
the source clip.IllegalArgumentException
- If startTime or stopTime are not valid
for this AudioClip.public abstract AudioClip createSegment(int startSample, int endSample) throws IllegalArgumentException
startSample
- The starting audio sample for the segmentendSample
- The ending audio sample of the segment, or -1 for the
remainder of the source clip.IllegalArgumentException
- If the given sample range is invalid for
this AudioClip.public abstract AudioClip resample(int startSample, int endSample, int newSampleRate) throws IllegalArgumentException, IOException
startSample
- starting sample to begin resampling at. The first
sample is always zero, negative values are not allowed.endSample
- The last sample to resample or -1 for the remainder of
the source clip.newSampleRate
- The sample playbackRate to create the new AudioClip at.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.public abstract AudioClip append(AudioClip clip) throws IOException
clip
- The clip to be appended to the current clip.IOException
- If an error occurred during the concatenation,
generally during rate conversion if it's necessary.public abstract AudioClip flatten()
public int priority()
public void setPriority(int prio)
public int loopCount()
public void setLoopCount(int loopCount)
loopCount
- 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.public double volume()
public void setVolume(double vol)
volume
- public double balance()
public void setBalance(double bal)
balance
- Balance value.public double playbackRate()
setPlaybackRate(double)
public void setPlaybackRate(double rate)
rate
- The new audio rate multiplier. Only positive values above
zero are allowed. Note that implementations may cap this value at some
undefined amount.playbackRate()
public double pan()
public void setPan(double pan)
pan
- Audio pan settingpublic abstract boolean isPlaying()
public abstract void play()
public abstract void play(double volume)
volume
- 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.public abstract void play(double volume, double balance, double rate, double pan, int loopCount, int priority)
volume
- 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
- Left/right balance or relative channel volumes for stereo
effects.rate
- Playback rate multiplier. 1.0 will play back 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.loopCount
- The number of times to play this clip, specify -1 to
loop indefinitelypriority
- Audio effect priority. Lower priority effects will be
dropped first if too many effects are trying to play simultaneously.public abstract void stop()
Copyright © 2020. All rights reserved.