Clip


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