| javax.sound.sampled.Clip
| Clip | | public interface Clip extends DataLine(Code) | | The Clip interface represents a special kind of data line whose
audio data can be loaded prior to playback, instead of being streamed in
real time.
Because the data is pre-loaded and has a known length, you can set a clip
to start playing at any position in its audio data. You can also create a
loop, so that when the clip is played it will cycle repeatedly. Loops are
specified with a starting and ending sample frame, along with the number of
times that the loop should be played.
Clips may be obtained from a
Mixer that supports lines
of this type. Data is loaded into a clip when it is opened.
Playback of an audio clip may be started and stopped using the start
and stop methods. These methods do not reset the media position;
start causes playback to continue from the position where playback
was last stopped. To restart playback from the beginning of the clip's audio
data, simply follow the invocation of
DataLine.stop stop
with setFramePosition(0), which rewinds the media to the beginning
of the clip.
author:
Kara Kytle
version:
1.45, 07/05/05
since:
1.3 |
| Field Summary | |
| final public static int | LOOP_CONTINUOUSLY
A value indicating that looping should continue indefinitely rather than
complete after a specific number of loops. |
| Method Summary | |
| public int | getFrameLength()
Obtains the media length in sample frames. | | public long | getMicrosecondLength()
| | public void | loop(int count)
Starts looping playback from the current position. | | public void | open(AudioFormat format, byte[] data, int offset, int bufferSize)
Opens the clip, meaning that it should acquire any required
system resources and become operational. | | public void | open(AudioInputStream stream)
Opens the clip with the format and audio data present in the provided audio
input stream. | | public void | setFramePosition(int frames)
Sets the media position in sample frames. | | public void | setLoopPoints(int start, int end)
Sets the first and last sample frames that will be played in
the loop. | | public void | setMicrosecondPosition(long microseconds)
Sets the media position in microseconds. |
| LOOP_CONTINUOUSLY | | final public static int LOOP_CONTINUOUSLY(Code) | | A value indicating that looping should continue indefinitely rather than
complete after a specific number of loops.
See Also: Clip.loop |
| getFrameLength | | public int getFrameLength()(Code) | | Obtains the media length in sample frames.
the media length, expressed in sample frames,or AudioSystem.NOT_SPECIFIED if the line is not open.
See Also: AudioSystem.NOT_SPECIFIED |
| getMicrosecondLength | | public long getMicrosecondLength()(Code) | | Obtains the media duration in microseconds
the media duration, expressed in microseconds,or AudioSystem.NOT_SPECIFIED if the line is not open.
See Also: AudioSystem.NOT_SPECIFIED |
| loop | | public void loop(int count)(Code) | | Starts looping playback from the current position. Playback will
continue to the loop's end point, then loop back to the loop start point
count times, and finally continue playback to the end of
the clip.
If the current position when this method is invoked is greater than the
loop end point, playback simply continues to the
end of the clip without looping.
A count value of 0 indicates that any current looping should
cease and playback should continue to the end of the clip. The behavior
is undefined when this method is invoked with any other value during a
loop operation.
If playback is stopped during looping, the current loop status is
cleared; the behavior of subsequent loop and start requests is not
affected by an interrupted loop operation.
Parameters:
count - the number of times playback should loop back from theloop's end position to the loop's start position, orClip.LOOP_CONTINUOUSLY to indicate that looping shouldcontinue until interrupted |
| open | | public void open(AudioFormat format, byte[] data, int offset, int bufferSize) throws LineUnavailableException(Code) | | Opens the clip, meaning that it should acquire any required
system resources and become operational. The clip is opened
with the format and audio data indicated.
If this operation succeeds, the line is marked as open and an
LineEvent.Type.OPEN OPEN event is dispatched
to the line's listeners.
Invoking this method on a line which is already open is illegal
and may result in an IllegalStateException.
Note that some lines, once closed, cannot be reopened. Attempts
to reopen such a line will always result in a
LineUnavailableException .
Parameters:
format - the format of the supplied audio data
Parameters:
data - a byte array containing audio data to load into the clip
Parameters:
offset - the point at which to start copying, expressed inbytes from the beginning of the array
Parameters:
bufferSize - the number of bytesof data to load into the clip from the array.
throws:
LineUnavailableException - if the line cannot beopened due to resource restrictions
throws:
IllegalArgumentException - if the buffer size does not representan integral number of sample frames,or if format is not fully specified or invalid
throws:
IllegalStateException - if the line is already open
throws:
SecurityException - if the line cannot beopened due to security restrictions
See Also: Clip.close
See Also: Clip.isOpen
See Also: LineListener |
| open | | public void open(AudioInputStream stream) throws LineUnavailableException, IOException(Code) | | Opens the clip with the format and audio data present in the provided audio
input stream. Opening a clip means that it should acquire any required
system resources and become operational. If this operation
input stream. If this operation
succeeds, the line is marked open and an
LineEvent.Type.OPEN OPEN event is dispatched
to the line's listeners.
Invoking this method on a line which is already open is illegal
and may result in an IllegalStateException.
Note that some lines, once closed, cannot be reopened. Attempts
to reopen such a line will always result in a
LineUnavailableException .
Parameters:
stream - an audio input stream from which audio data will be read intothe clip
throws:
LineUnavailableException - if the line cannot beopened due to resource restrictions
throws:
IOException - if an I/O exception occurs during reading ofthe stream
throws:
IllegalArgumentException - if the stream's audio formatis not fully specified or invalid
throws:
IllegalStateException - if the line is already open
throws:
SecurityException - if the line cannot beopened due to security restrictions
See Also: Clip.close
See Also: Clip.isOpen
See Also: LineListener |
| setFramePosition | | public void setFramePosition(int frames)(Code) | | Sets the media position in sample frames. The position is zero-based;
the first frame is frame number zero. When the clip begins playing the
next time, it will start by playing the frame at this position.
To obtain the current position in sample frames, use the
DataLine.getFramePosition getFramePosition
method of DataLine.
Parameters:
frames - the desired new media position, expressed in sample frames |
| setLoopPoints | | public void setLoopPoints(int start, int end)(Code) | | Sets the first and last sample frames that will be played in
the loop. The ending point must be greater than
or equal to the starting point, and both must fall within the
the size of the loaded media. A value of 0 for the starting
point means the beginning of the loaded media. Similarly, a value of -1
for the ending point indicates the last frame of the media.
Parameters:
start - the loop's starting position, in sample frames (zero-based)
Parameters:
end - the loop's ending position, in sample frames (zero-based), or-1 to indicate the final frame
throws:
IllegalArgumentException - if the requestedloop points cannot be set, usually because one or both falls outsidethe media's duration or because the ending point isbefore the starting point |
| setMicrosecondPosition | | public void setMicrosecondPosition(long microseconds)(Code) | | Sets the media position in microseconds. When the clip begins playing the
next time, it will start at this position.
The level of precision is not guaranteed. For example, an implementation
might calculate the microsecond position from the current frame position
and the audio sample frame rate. The precision in microseconds would
then be limited to the number of microseconds per sample frame.
To obtain the current position in microseconds, use the
DataLine.getMicrosecondPosition getMicrosecondPosition
method of DataLine.
Parameters:
microseconds - the desired new media position, expressed in microseconds |
|
|