001 /*
002 * Copyright 1999-2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.sound.sampled;
027
028 import java.io.InputStream;
029 import java.io.IOException;
030
031 /**
032 * The <code>Clip</code> interface represents a special kind of data line whose
033 * audio data can be loaded prior to playback, instead of being streamed in
034 * real time.
035 * <p>
036 * Because the data is pre-loaded and has a known length, you can set a clip
037 * to start playing at any position in its audio data. You can also create a
038 * loop, so that when the clip is played it will cycle repeatedly. Loops are
039 * specified with a starting and ending sample frame, along with the number of
040 * times that the loop should be played.
041 * <p>
042 * Clips may be obtained from a <code>{@link Mixer}</code> that supports lines
043 * of this type. Data is loaded into a clip when it is opened.
044 * <p>
045 * Playback of an audio clip may be started and stopped using the <code>start</code>
046 * and <code>stop</code> methods. These methods do not reset the media position;
047 * <code>start</code> causes playback to continue from the position where playback
048 * was last stopped. To restart playback from the beginning of the clip's audio
049 * data, simply follow the invocation of <code>{@link DataLine#stop stop}</code>
050 * with setFramePosition(0), which rewinds the media to the beginning
051 * of the clip.
052 *
053 * @author Kara Kytle
054 * @version 1.45, 07/05/05
055 * @since 1.3
056 */
057 public interface Clip extends DataLine {
058
059 /**
060 * A value indicating that looping should continue indefinitely rather than
061 * complete after a specific number of loops.
062 * @see #loop
063 */
064 public static final int LOOP_CONTINUOUSLY = -1;
065
066 /**
067 * Opens the clip, meaning that it should acquire any required
068 * system resources and become operational. The clip is opened
069 * with the format and audio data indicated.
070 * If this operation succeeds, the line is marked as open and an
071 * <code>{@link LineEvent.Type#OPEN OPEN}</code> event is dispatched
072 * to the line's listeners.
073 * <p>
074 * Invoking this method on a line which is already open is illegal
075 * and may result in an IllegalStateException.
076 * <p>
077 * Note that some lines, once closed, cannot be reopened. Attempts
078 * to reopen such a line will always result in a
079 * <code>{@link LineUnavailableException}</code>.
080 *
081 * @param format the format of the supplied audio data
082 * @param data a byte array containing audio data to load into the clip
083 * @param offset the point at which to start copying, expressed in
084 * <em>bytes</em> from the beginning of the array
085 * @param bufferSize the number of <em>bytes</em>
086 * of data to load into the clip from the array.
087 * @throws LineUnavailableException if the line cannot be
088 * opened due to resource restrictions
089 * @throws IllegalArgumentException if the buffer size does not represent
090 * an integral number of sample frames,
091 * or if <code>format</code> is not fully specified or invalid
092 * @throws IllegalStateException if the line is already open
093 * @throws SecurityException if the line cannot be
094 * opened due to security restrictions
095 *
096 * @see #close
097 * @see #isOpen
098 * @see LineListener
099 */
100 public void open(AudioFormat format, byte[] data, int offset,
101 int bufferSize) throws LineUnavailableException;
102
103 /**
104 * Opens the clip with the format and audio data present in the provided audio
105 * input stream. Opening a clip means that it should acquire any required
106 * system resources and become operational. If this operation
107 * input stream. If this operation
108 * succeeds, the line is marked open and an
109 * <code>{@link LineEvent.Type#OPEN OPEN}</code> event is dispatched
110 * to the line's listeners.
111 * <p>
112 * Invoking this method on a line which is already open is illegal
113 * and may result in an IllegalStateException.
114 * <p>
115 * Note that some lines, once closed, cannot be reopened. Attempts
116 * to reopen such a line will always result in a
117 * <code>{@link LineUnavailableException}</code>.
118 *
119 * @param stream an audio input stream from which audio data will be read into
120 * the clip
121 * @throws LineUnavailableException if the line cannot be
122 * opened due to resource restrictions
123 * @throws IOException if an I/O exception occurs during reading of
124 * the stream
125 * @throws IllegalArgumentException if the stream's audio format
126 * is not fully specified or invalid
127 * @throws IllegalStateException if the line is already open
128 * @throws SecurityException if the line cannot be
129 * opened due to security restrictions
130 *
131 * @see #close
132 * @see #isOpen
133 * @see LineListener
134 */
135 public void open(AudioInputStream stream)
136 throws LineUnavailableException, IOException;
137
138 /**
139 * Obtains the media length in sample frames.
140 * @return the media length, expressed in sample frames,
141 * or <code>AudioSystem.NOT_SPECIFIED</code> if the line is not open.
142 * @see AudioSystem#NOT_SPECIFIED
143 */
144 public int getFrameLength();
145
146 /**
147 * Obtains the media duration in microseconds
148 * @return the media duration, expressed in microseconds,
149 * or <code>AudioSystem.NOT_SPECIFIED</code> if the line is not open.
150 * @see AudioSystem#NOT_SPECIFIED
151 */
152 public long getMicrosecondLength();
153
154 /**
155 * Sets the media position in sample frames. The position is zero-based;
156 * the first frame is frame number zero. When the clip begins playing the
157 * next time, it will start by playing the frame at this position.
158 * <p>
159 * To obtain the current position in sample frames, use the
160 * <code>{@link DataLine#getFramePosition getFramePosition}</code>
161 * method of <code>DataLine</code>.
162 *
163 * @param frames the desired new media position, expressed in sample frames
164 */
165 public void setFramePosition(int frames);
166
167 /**
168 * Sets the media position in microseconds. When the clip begins playing the
169 * next time, it will start at this position.
170 * The level of precision is not guaranteed. For example, an implementation
171 * might calculate the microsecond position from the current frame position
172 * and the audio sample frame rate. The precision in microseconds would
173 * then be limited to the number of microseconds per sample frame.
174 * <p>
175 * To obtain the current position in microseconds, use the
176 * <code>{@link DataLine#getMicrosecondPosition getMicrosecondPosition}</code>
177 * method of <code>DataLine</code>.
178 *
179 * @param microseconds the desired new media position, expressed in microseconds
180 */
181 public void setMicrosecondPosition(long microseconds);
182
183 /**
184 * Sets the first and last sample frames that will be played in
185 * the loop. The ending point must be greater than
186 * or equal to the starting point, and both must fall within the
187 * the size of the loaded media. A value of 0 for the starting
188 * point means the beginning of the loaded media. Similarly, a value of -1
189 * for the ending point indicates the last frame of the media.
190 * @param start the loop's starting position, in sample frames (zero-based)
191 * @param end the loop's ending position, in sample frames (zero-based), or
192 * -1 to indicate the final frame
193 * @throws IllegalArgumentException if the requested
194 * loop points cannot be set, usually because one or both falls outside
195 * the media's duration or because the ending point is
196 * before the starting point
197 */
198 public void setLoopPoints(int start, int end);
199
200 /**
201 * Starts looping playback from the current position. Playback will
202 * continue to the loop's end point, then loop back to the loop start point
203 * <code>count</code> times, and finally continue playback to the end of
204 * the clip.
205 * <p>
206 * If the current position when this method is invoked is greater than the
207 * loop end point, playback simply continues to the
208 * end of the clip without looping.
209 * <p>
210 * A <code>count</code> value of 0 indicates that any current looping should
211 * cease and playback should continue to the end of the clip. The behavior
212 * is undefined when this method is invoked with any other value during a
213 * loop operation.
214 * <p>
215 * If playback is stopped during looping, the current loop status is
216 * cleared; the behavior of subsequent loop and start requests is not
217 * affected by an interrupted loop operation.
218 *
219 * @param count the number of times playback should loop back from the
220 * loop's end position to the loop's start position, or
221 * <code>{@link #LOOP_CONTINUOUSLY}</code> to indicate that looping should
222 * continue until interrupted
223 */
224 public void loop(int count);
225 }
|