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