1 /*
2 * Copyright 1999-2003 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.sound.sampled;
27
28 import java.io.InputStream;
29 import java.io.IOException;
30
31 /**
32 * The <code>Clip</code> interface represents a special kind of data line whose
33 * audio data can be loaded prior to playback, instead of being streamed in
34 * real time.
35 * <p>
36 * Because the data is pre-loaded and has a known length, you can set a clip
37 * to start playing at any position in its audio data. You can also create a
38 * loop, so that when the clip is played it will cycle repeatedly. Loops are
39 * specified with a starting and ending sample frame, along with the number of
40 * times that the loop should be played.
41 * <p>
42 * Clips may be obtained from a <code>{@link Mixer}</code> that supports lines
43 * of this type. Data is loaded into a clip when it is opened.
44 * <p>
45 * Playback of an audio clip may be started and stopped using the <code>start</code>
46 * and <code>stop</code> methods. These methods do not reset the media position;
47 * <code>start</code> causes playback to continue from the position where playback
48 * was last stopped. To restart playback from the beginning of the clip's audio
49 * data, simply follow the invocation of <code>{@link DataLine#stop stop}</code>
50 * with setFramePosition(0), which rewinds the media to the beginning
51 * of the clip.
52 *
53 * @author Kara Kytle
54 * @since 1.3
55 */
56 public interface Clip extends DataLine {
57
58
59 /**
60 * A value indicating that looping should continue indefinitely rather than
61 * complete after a specific number of loops.
62 * @see #loop
63 */
64 public static final int LOOP_CONTINUOUSLY = -1;
65
66 /**
67 * Opens the clip, meaning that it should acquire any required
68 * system resources and become operational. The clip is opened
69 * with the format and audio data indicated.
70 * If this operation succeeds, the line is marked as open and an
71 * <code>{@link LineEvent.Type#OPEN OPEN}</code> event is dispatched
72 * to the line's listeners.
73 * <p>
74 * Invoking this method on a line which is already open is illegal
75 * and may result in an IllegalStateException.
76 * <p>
77 * Note that some lines, once closed, cannot be reopened. Attempts
78 * to reopen such a line will always result in a
79 * <code>{@link LineUnavailableException}</code>.
80 *
81 * @param format the format of the supplied audio data
82 * @param data a byte array containing audio data to load into the clip
83 * @param offset the point at which to start copying, expressed in
84 * <em>bytes</em> from the beginning of the array
85 * @param bufferSize the number of <em>bytes</em>
86 * of data to load into the clip from the array.
87 * @throws LineUnavailableException if the line cannot be
88 * opened due to resource restrictions
89 * @throws IllegalArgumentException if the buffer size does not represent
90 * an integral number of sample frames,
91 * or if <code>format</code> is not fully specified or invalid
92 * @throws IllegalStateException if the line is already open
93 * @throws SecurityException if the line cannot be
94 * opened due to security restrictions
95 *
96 * @see #close
97 * @see #isOpen
98 * @see LineListener
99 */
100 public void open(AudioFormat format, byte[] data, int offset, int bufferSize) throws LineUnavailableException;
101
102 /**
103 * Opens the clip with the format and audio data present in the provided audio
104 * input stream. Opening a clip means that it should acquire any required
105 * system resources and become operational. If this operation
106 * input stream. If this operation
107 * succeeds, the line is marked open and an
108 * <code>{@link LineEvent.Type#OPEN OPEN}</code> event is dispatched
109 * to the line's listeners.
110 * <p>
111 * Invoking this method on a line which is already open is illegal
112 * and may result in an IllegalStateException.
113 * <p>
114 * Note that some lines, once closed, cannot be reopened. Attempts
115 * to reopen such a line will always result in a
116 * <code>{@link LineUnavailableException}</code>.
117 *
118 * @param stream an audio input stream from which audio data will be read into
119 * the clip
120 * @throws LineUnavailableException if the line cannot be
121 * opened due to resource restrictions
122 * @throws IOException if an I/O exception occurs during reading of
123 * the stream
124 * @throws IllegalArgumentException if the stream's audio format
125 * is not fully specified or invalid
126 * @throws IllegalStateException if the line is already open
127 * @throws SecurityException if the line cannot be
128 * opened due to security restrictions
129 *
130 * @see #close
131 * @see #isOpen
132 * @see LineListener
133 */
134 public void open(AudioInputStream stream) throws LineUnavailableException, IOException;
135
136 /**
137 * Obtains the media length in sample frames.
138 * @return the media length, expressed in sample frames,
139 * or <code>AudioSystem.NOT_SPECIFIED</code> if the line is not open.
140 * @see AudioSystem#NOT_SPECIFIED
141 */
142 public int getFrameLength();
143
144 /**
145 * Obtains the media duration in microseconds
146 * @return the media duration, expressed in microseconds,
147 * or <code>AudioSystem.NOT_SPECIFIED</code> if the line is not open.
148 * @see AudioSystem#NOT_SPECIFIED
149 */
150 public long getMicrosecondLength();
151
152 /**
153 * Sets the media position in sample frames. The position is zero-based;
154 * the first frame is frame number zero. When the clip begins playing the
155 * next time, it will start by playing the frame at this position.
156 * <p>
157 * To obtain the current position in sample frames, use the
158 * <code>{@link DataLine#getFramePosition getFramePosition}</code>
159 * method of <code>DataLine</code>.
160 *
161 * @param frames the desired new media position, expressed in sample frames
162 */
163 public void setFramePosition(int frames);
164
165 /**
166 * Sets the media position in microseconds. When the clip begins playing the
167 * next time, it will start at this position.
168 * The level of precision is not guaranteed. For example, an implementation
169 * might calculate the microsecond position from the current frame position
170 * and the audio sample frame rate. The precision in microseconds would
171 * then be limited to the number of microseconds per sample frame.
172 * <p>
173 * To obtain the current position in microseconds, use the
174 * <code>{@link DataLine#getMicrosecondPosition getMicrosecondPosition}</code>
175 * method of <code>DataLine</code>.
176 *
177 * @param microseconds the desired new media position, expressed in microseconds
178 */
179 public void setMicrosecondPosition(long microseconds);
180
181 /**
182 * Sets the first and last sample frames that will be played in
183 * the loop. The ending point must be greater than
184 * or equal to the starting point, and both must fall within the
185 * the size of the loaded media. A value of 0 for the starting
186 * point means the beginning of the loaded media. Similarly, a value of -1
187 * for the ending point indicates the last frame of the media.
188 * @param start the loop's starting position, in sample frames (zero-based)
189 * @param end the loop's ending position, in sample frames (zero-based), or
190 * -1 to indicate the final frame
191 * @throws IllegalArgumentException if the requested
192 * loop points cannot be set, usually because one or both falls outside
193 * the media's duration or because the ending point is
194 * before the starting point
195 */
196 public void setLoopPoints(int start, int end);
197
198 /**
199 * Starts looping playback from the current position. Playback will
200 * continue to the loop's end point, then loop back to the loop start point
201 * <code>count</code> times, and finally continue playback to the end of
202 * the clip.
203 * <p>
204 * If the current position when this method is invoked is greater than the
205 * loop end point, playback simply continues to the
206 * end of the clip without looping.
207 * <p>
208 * A <code>count</code> value of 0 indicates that any current looping should
209 * cease and playback should continue to the end of the clip. The behavior
210 * is undefined when this method is invoked with any other value during a
211 * loop operation.
212 * <p>
213 * If playback is stopped during looping, the current loop status is
214 * cleared; the behavior of subsequent loop and start requests is not
215 * affected by an interrupted loop operation.
216 *
217 * @param count the number of times playback should loop back from the
218 * loop's end position to the loop's start position, or
219 * <code>{@link #LOOP_CONTINUOUSLY}</code> to indicate that looping should
220 * continue until interrupted
221 */
222 public void loop(int count);
223 }
Save This Page