Clip.java revision 11099:678faa7d1a6a
133965Sjdp/* 289857Sobrien * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. 3218822Sdim * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 433965Sjdp * 533965Sjdp * This code is free software; you can redistribute it and/or modify it 6130561Sobrien * under the terms of the GNU General Public License version 2 only, as 733965Sjdp * published by the Free Software Foundation. Oracle designates this 8130561Sobrien * particular file as subject to the "Classpath" exception as provided 9130561Sobrien * by Oracle in the LICENSE file that accompanied this code. 10130561Sobrien * 11130561Sobrien * This code is distributed in the hope that it will be useful, but WITHOUT 1233965Sjdp * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13130561Sobrien * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14130561Sobrien * version 2 for more details (a copy is included in the LICENSE file that 15130561Sobrien * accompanied this code). 16130561Sobrien * 1733965Sjdp * You should have received a copy of the GNU General Public License version 18130561Sobrien * 2 along with this work; if not, write to the Free Software Foundation, 19130561Sobrien * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20218822Sdim * 2133965Sjdp * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2233965Sjdp * or visit www.oracle.com if you need additional information or have any 2333965Sjdp * questions. 2433965Sjdp */ 2533965Sjdp 2633965Sjdppackage javax.sound.sampled; 2733965Sjdp 2833965Sjdpimport java.io.IOException; 2933965Sjdp 3078828Sobrien/** 3189857Sobrien * The {@code Clip} interface represents a special kind of data line whose audio 3278828Sobrien * data can be loaded prior to playback, instead of being streamed in real time. 3378828Sobrien * <p> 3478828Sobrien * Because the data is pre-loaded and has a known length, you can set a clip to 3533965Sjdp * start playing at any position in its audio data. You can also create a loop, 3633965Sjdp * so that when the clip is played it will cycle repeatedly. Loops are specified 37130561Sobrien * with a starting and ending sample frame, along with the number of times that 38130561Sobrien * the loop should be played. 3933965Sjdp * <p> 40130561Sobrien * Clips may be obtained from a {@link Mixer} that supports lines of this type. 41130561Sobrien * Data is loaded into a clip when it is opened. 4233965Sjdp * <p> 4333965Sjdp * Playback of an audio clip may be started and stopped using the 4433965Sjdp * {@link #start start} and {@link #stop stop} methods. These methods do not 4533965Sjdp * reset the media position; {@code start} causes playback to continue from the 46130561Sobrien * position where playback was last stopped. To restart playback from the 4733965Sjdp * beginning of the clip's audio data, simply follow the invocation of 4833965Sjdp * {@code stop} with {@code setFramePosition(0)}, which rewinds the media to the 4933965Sjdp * beginning of the clip. 5033965Sjdp * 5133965Sjdp * @author Kara Kytle 5233965Sjdp * @since 1.3 5333965Sjdp */ 5433965Sjdppublic interface Clip extends DataLine { 5533965Sjdp 5633965Sjdp /** 5733965Sjdp * A value indicating that looping should continue indefinitely rather than 5833965Sjdp * complete after a specific number of loops. 5933965Sjdp * 6033965Sjdp * @see #loop 6133965Sjdp */ 6233965Sjdp int LOOP_CONTINUOUSLY = -1; 6333965Sjdp 6433965Sjdp /** 6533965Sjdp * Opens the clip, meaning that it should acquire any required system 6633965Sjdp * resources and become operational. The clip is opened with the format and 67130561Sobrien * audio data indicated. If this operation succeeds, the line is marked as 68130561Sobrien * open and an {@link LineEvent.Type#OPEN OPEN} event is dispatched to the 6933965Sjdp * line's listeners. 7033965Sjdp * <p> 7133965Sjdp * Invoking this method on a line which is already open is illegal and may 7233965Sjdp * result in an {@code IllegalStateException}. 7333965Sjdp * <p> 7433965Sjdp * Note that some lines, once closed, cannot be reopened. Attempts to reopen 7533965Sjdp * such a line will always result in a {@code LineUnavailableException}. 7633965Sjdp * 7733965Sjdp * @param format the format of the supplied audio data 7833965Sjdp * @param data a byte array containing audio data to load into the clip 7989857Sobrien * @param offset the point at which to start copying, expressed in 80130561Sobrien * <em>bytes</em> from the beginning of the array 81130561Sobrien * @param bufferSize the number of <em>bytes</em> of data to load into the 8289857Sobrien * clip from the array 8333965Sjdp * @throws LineUnavailableException if the line cannot be opened due to 8433965Sjdp * resource restrictions 8533965Sjdp * @throws IllegalArgumentException if the buffer size does not represent an 8633965Sjdp * integral number of sample frames, or if {@code format} is not 8733965Sjdp * fully specified or invalid 8833965Sjdp * @throws IllegalStateException if the line is already open 8933965Sjdp * @throws SecurityException if the line cannot be opened due to security 9033965Sjdp * restrictions 9133965Sjdp * @see #close 9233965Sjdp * @see #isOpen 9333965Sjdp * @see LineListener 9433965Sjdp */ 9560484Sobrien void open(AudioFormat format, byte[] data, int offset, int bufferSize) 9660484Sobrien throws LineUnavailableException; 9760484Sobrien 9860484Sobrien /** 9960484Sobrien * Opens the clip with the format and audio data present in the provided 10060484Sobrien * audio input stream. Opening a clip means that it should acquire any 10160484Sobrien * required system resources and become operational. If this operation input 10260484Sobrien * stream. If this operation succeeds, the line is marked open and an 10360484Sobrien * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the line's 10460484Sobrien * listeners. 10533965Sjdp * <p> 10633965Sjdp * Invoking this method on a line which is already open is illegal and may 10789857Sobrien * result in an {@code IllegalStateException}. 10889857Sobrien * <p> 109130561Sobrien * Note that some lines, once closed, cannot be reopened. Attempts to reopen 110130561Sobrien * such a line will always result in a {@code LineUnavailableException}. 111130561Sobrien * 112130561Sobrien * @param stream an audio input stream from which audio data will be read 113130561Sobrien * into the clip 114130561Sobrien * @throws LineUnavailableException if the line cannot be opened due to 115130561Sobrien * resource restrictions 116130561Sobrien * @throws IOException if an I/O exception occurs during reading of the 11789857Sobrien * stream 11889857Sobrien * @throws IllegalArgumentException if the stream's audio format is not 11989857Sobrien * fully specified or invalid 120130561Sobrien * @throws IllegalStateException if the line is already open 121130561Sobrien * @throws SecurityException if the line cannot be opened due to security 12289857Sobrien * restrictions 12389857Sobrien * @see #close 12489857Sobrien * @see #isOpen 125130561Sobrien * @see LineListener 12689857Sobrien */ 12789857Sobrien void open(AudioInputStream stream) 12889857Sobrien throws LineUnavailableException, IOException; 12989857Sobrien 13033965Sjdp /** 131218822Sdim * Obtains the media length in sample frames. 13233965Sjdp * 13360484Sobrien * @return the media length, expressed in sample frames, or 134218822Sdim * {@code AudioSystem.NOT_SPECIFIED} if the line is not open 13533965Sjdp * @see AudioSystem#NOT_SPECIFIED 13633965Sjdp */ 137218822Sdim int getFrameLength(); 13833965Sjdp 139218822Sdim /** 14033965Sjdp * Obtains the media duration in microseconds. 141218822Sdim * 14233965Sjdp * @return the media duration, expressed in microseconds, or 143218822Sdim * {@code AudioSystem.NOT_SPECIFIED} if the line is not open 14460484Sobrien * @see AudioSystem#NOT_SPECIFIED 145218822Sdim */ 14633965Sjdp long getMicrosecondLength(); 147218822Sdim 14833965Sjdp /** 149218822Sdim * Sets the media position in sample frames. The position is zero-based; the 15033965Sjdp * first frame is frame number zero. When the clip begins playing the next 151218822Sdim * time, it will start by playing the frame at this position. 15233965Sjdp * <p> 153218822Sdim * To obtain the current position in sample frames, use the 15433965Sjdp * {@link DataLine#getFramePosition getFramePosition} method of 155218822Sdim * {@code DataLine}. 15633965Sjdp * 157218822Sdim * @param frames the desired new media position, expressed in sample frames 158218822Sdim */ 159218822Sdim void setFramePosition(int frames); 16060484Sobrien 161218822Sdim /** 16260484Sobrien * Sets the media position in microseconds. When the clip begins playing the 16360484Sobrien * next time, it will start at this position. The level of precision is not 164218822Sdim * guaranteed. For example, an implementation might calculate the 165218822Sdim * microsecond position from the current frame position and the audio sample 166218822Sdim * frame rate. The precision in microseconds would then be limited to the 167218822Sdim * number of microseconds per sample frame. 168218822Sdim * <p> 169130561Sobrien * To obtain the current position in microseconds, use the 170218822Sdim * {@link DataLine#getMicrosecondPosition getMicrosecondPosition} method of 171130561Sobrien * {@code DataLine}. 172130561Sobrien * 173218822Sdim * @param microseconds the desired new media position, expressed in 174218822Sdim * microseconds 175218822Sdim */ 176218822Sdim void setMicrosecondPosition(long microseconds); 177218822Sdim 178218822Sdim /** 179218822Sdim * Sets the first and last sample frames that will be played in the loop. 180218822Sdim * The ending point must be greater than or equal to the starting point, and 181218822Sdim * both must fall within the size of the loaded media. A value of 0 for 182218822Sdim * the starting point means the beginning of the loaded media. Similarly, a 183218822Sdim * value of -1 for the ending point indicates the last frame of the media. 184218822Sdim * 185218822Sdim * @param start the loop's starting position, in sample frames (zero-based) 186218822Sdim * @param end the loop's ending position, in sample frames (zero-based), 187218822Sdim * or -1 to indicate the final frame 188218822Sdim * @throws IllegalArgumentException if the requested loop points cannot be 189218822Sdim * set, usually because one or both falls outside the media's 190218822Sdim * duration or because the ending point is before the starting point 191218822Sdim */ 192218822Sdim void setLoopPoints(int start, int end); 193218822Sdim 194218822Sdim /** 195218822Sdim * Starts looping playback from the current position. Playback will continue 196218822Sdim * to the loop's end point, then loop back to the loop start point 197218822Sdim * {@code count} times, and finally continue playback to the end of the 198218822Sdim * clip. 199218822Sdim * <p> 200218822Sdim * If the current position when this method is invoked is greater than the 201218822Sdim * loop end point, playback simply continues to the end of the clip without 202218822Sdim * looping. 203218822Sdim * <p> 204218822Sdim * A {@code count} value of 0 indicates that any current looping should 205218822Sdim * cease and playback should continue to the end of the clip. The behavior 206218822Sdim * is undefined when this method is invoked with any other value during a 207218822Sdim * loop operation. 208218822Sdim * <p> 209218822Sdim * If playback is stopped during looping, the current loop status is 210218822Sdim * cleared; the behavior of subsequent loop and start requests is not 211218822Sdim * affected by an interrupted loop operation. 212218822Sdim * 213218822Sdim * @param count the number of times playback should loop back from the 214218822Sdim * loop's end position to the loop's start position, or 215218822Sdim * {@link #LOOP_CONTINUOUSLY} to indicate that looping should 21633965Sjdp * continue until interrupted 21733965Sjdp */ 218130561Sobrien void loop(int count); 219130561Sobrien} 220130561Sobrien