Java tutorial
/* * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.sound.sampled; import java.io.IOException; /** * The {@code 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. * <p> * 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. * <p> * Clips may be obtained from a {@link Mixer} that supports lines of this type. * Data is loaded into a clip when it is opened. * <p> * Playback of an audio clip may be started and stopped using the * {@link #start start} and {@link #stop stop} methods. These methods do not * reset the media position; {@code 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 * {@code stop} with {@code setFramePosition(0)}, which rewinds the media to the * beginning of the clip. * * @author Kara Kytle * @since 1.3 */ public interface Clip extends DataLine { /** * A value indicating that looping should continue indefinitely rather than * complete after a specific number of loops. * * @see #loop */ int LOOP_CONTINUOUSLY = -1; /** * 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 {@link LineEvent.Type#OPEN OPEN} event is dispatched to the * line's listeners. * <p> * Invoking this method on a line which is already open is illegal and may * result in an {@code IllegalStateException}. * <p> * Note that some lines, once closed, cannot be reopened. Attempts to reopen * such a line will always result in a {@code LineUnavailableException}. * * @param format the format of the supplied audio data * @param data a byte array containing audio data to load into the clip * @param offset the point at which to start copying, expressed in * <em>bytes</em> from the beginning of the array * @param bufferSize the number of <em>bytes</em> of data to load into the * clip from the array * @throws LineUnavailableException if the line cannot be opened due to * resource restrictions * @throws IllegalArgumentException if the buffer size does not represent an * integral number of sample frames, or if {@code format} is not * fully specified or invalid * @throws IllegalStateException if the line is already open * @throws SecurityException if the line cannot be opened due to security * restrictions * @see #close * @see #isOpen * @see LineListener */ void open(AudioFormat format, byte[] data, int offset, int bufferSize) throws LineUnavailableException; /** * 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 * {@link LineEvent.Type#OPEN OPEN} event is dispatched to the line's * listeners. * <p> * Invoking this method on a line which is already open is illegal and may * result in an {@code IllegalStateException}. * <p> * Note that some lines, once closed, cannot be reopened. Attempts to reopen * such a line will always result in a {@code LineUnavailableException}. * * @param stream an audio input stream from which audio data will be read * into the clip * @throws LineUnavailableException if the line cannot be opened due to * resource restrictions * @throws IOException if an I/O exception occurs during reading of the * stream * @throws IllegalArgumentException if the stream's audio format is not * fully specified or invalid * @throws IllegalStateException if the line is already open * @throws SecurityException if the line cannot be opened due to security * restrictions * @see #close * @see #isOpen * @see LineListener */ void open(AudioInputStream stream) throws LineUnavailableException, IOException; /** * Obtains the media length in sample frames. * * @return the media length, expressed in sample frames, or * {@code AudioSystem.NOT_SPECIFIED} if the line is not open * @see AudioSystem#NOT_SPECIFIED */ int getFrameLength(); /** * Obtains the media duration in microseconds. * * @return the media duration, expressed in microseconds, or * {@code AudioSystem.NOT_SPECIFIED} if the line is not open * @see AudioSystem#NOT_SPECIFIED */ long getMicrosecondLength(); /** * 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. * <p> * To obtain the current position in sample frames, use the * {@link DataLine#getFramePosition getFramePosition} method of * {@code DataLine}. * * @param frames the desired new media position, expressed in sample frames */ void setFramePosition(int frames); /** * 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. * <p> * To obtain the current position in microseconds, use the * {@link DataLine#getMicrosecondPosition getMicrosecondPosition} method of * {@code DataLine}. * * @param microseconds the desired new media position, expressed in * microseconds */ void setMicrosecondPosition(long microseconds); /** * 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 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. * * @param start the loop's starting position, in sample frames (zero-based) * @param end the loop's ending position, in sample frames (zero-based), or * -1 to indicate the final frame * @throws IllegalArgumentException if the requested loop points cannot be * set, usually because one or both falls outside the media's * duration or because the ending point is before the starting point */ void setLoopPoints(int start, int end); /** * Starts looping playback from the current position. Playback will continue * to the loop's end point, then loop back to the loop start point * {@code count} times, and finally continue playback to the end of the * clip. * <p> * 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. * <p> * A {@code 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. * <p> * 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. * * @param count the number of times playback should loop back from the * loop's end position to the loop's start position, or * {@link #LOOP_CONTINUOUSLY} to indicate that looping should * continue until interrupted */ void loop(int count); }