View Javadoc
1   /*
2    * Copyright (c) 1999, 2013, 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.util.Arrays;
29  
30  /**
31   * <code>DataLine</code> adds media-related functionality to its
32   * superinterface, <code>{@link Line}</code>.  This functionality includes
33   * transport-control methods that start, stop, drain, and flush
34   * the audio data that passes through the line.  A data line can also
35   * report the current position, volume, and audio format of the media.
36   * Data lines are used for output of audio by means of the
37   * subinterfaces <code>{@link SourceDataLine}</code> or
38   * <code>{@link Clip}</code>, which allow an application program to write data.  Similarly,
39   * audio input is handled by the subinterface <code>{@link TargetDataLine}</code>,
40   * which allows data to be read.
41   * <p>
42   * A data line has an internal buffer in which
43   * the incoming or outgoing audio data is queued.  The
44   * <code>{@link #drain()}</code> method blocks until this internal buffer
45   * becomes empty, usually because all queued data has been processed.  The
46   * <code>{@link #flush()}</code> method discards any available queued data
47   * from the internal buffer.
48   * <p>
49   * A data line produces <code>{@link LineEvent.Type#START START}</code> and
50   * <code>{@link LineEvent.Type#STOP STOP}</code> events whenever
51   * it begins or ceases active presentation or capture of data.  These events
52   * can be generated in response to specific requests, or as a result of
53   * less direct state changes.  For example, if <code>{@link #start()}</code> is called
54   * on an inactive data line, and data is available for capture or playback, a
55   * <code>START</code> event will be generated shortly, when data playback
56   * or capture actually begins.  Or, if the flow of data to an active data
57   * line is constricted so that a gap occurs in the presentation of data,
58   * a <code>STOP</code> event is generated.
59   * <p>
60   * Mixers often support synchronized control of multiple data lines.
61   * Synchronization can be established through the Mixer interface's
62   * <code>{@link Mixer#synchronize synchronize}</code> method.
63   * See the description of the <code>{@link Mixer Mixer}</code> interface
64   * for a more complete description.
65   *
66   * @author Kara Kytle
67   * @see LineEvent
68   * @since 1.3
69   */
70  public interface DataLine extends Line {
71  
72  
73      /**
74       * Drains queued data from the line by continuing data I/O until the
75       * data line's internal buffer has been emptied.
76       * This method blocks until the draining is complete.  Because this is a
77       * blocking method, it should be used with care.  If <code>drain()</code>
78       * is invoked on a stopped line that has data in its queue, the method will
79       * block until the line is running and the data queue becomes empty.  If
80       * <code>drain()</code> is invoked by one thread, and another continues to
81       * fill the data queue, the operation will not complete.
82       * This method always returns when the data line is closed.
83       *
84       * @see #flush()
85       */
86      public void drain();
87  
88      /**
89       * Flushes queued data from the line.  The flushed data is discarded.
90       * In some cases, not all queued data can be discarded.  For example, a
91       * mixer can flush data from the buffer for a specific input line, but any
92       * unplayed data already in the output buffer (the result of the mix) will
93       * still be played.  You can invoke this method after pausing a line (the
94       * normal case) if you want to skip the "stale" data when you restart
95       * playback or capture. (It is legal to flush a line that is not stopped,
96       * but doing so on an active line is likely to cause a discontinuity in the
97       * data, resulting in a perceptible click.)
98       *
99       * @see #stop()
100      * @see #drain()
101      */
102     public void flush();
103 
104     /**
105      * Allows a line to engage in data I/O.  If invoked on a line
106      * that is already running, this method does nothing.  Unless the data in
107      * the buffer has been flushed, the line resumes I/O starting
108      * with the first frame that was unprocessed at the time the line was
109      * stopped. When audio capture or playback starts, a
110      * <code>{@link LineEvent.Type#START START}</code> event is generated.
111      *
112      * @see #stop()
113      * @see #isRunning()
114      * @see LineEvent
115      */
116     public void start();
117 
118     /**
119      * Stops the line.  A stopped line should cease I/O activity.
120      * If the line is open and running, however, it should retain the resources required
121      * to resume activity.  A stopped line should retain any audio data in its buffer
122      * instead of discarding it, so that upon resumption the I/O can continue where it left off,
123      * if possible.  (This doesn't guarantee that there will never be discontinuities beyond the
124      * current buffer, of course; if the stopped condition continues
125      * for too long, input or output samples might be dropped.)  If desired, the retained data can be
126      * discarded by invoking the <code>flush</code> method.
127      * When audio capture or playback stops, a <code>{@link LineEvent.Type#STOP STOP}</code> event is generated.
128      *
129      * @see #start()
130      * @see #isRunning()
131      * @see #flush()
132      * @see LineEvent
133      */
134     public void stop();
135 
136     /**
137      * Indicates whether the line is running.  The default is <code>false</code>.
138      * An open line begins running when the first data is presented in response to an
139      * invocation of the <code>start</code> method, and continues
140      * until presentation ceases in response to a call to <code>stop</code> or
141      * because playback completes.
142      * @return <code>true</code> if the line is running, otherwise <code>false</code>
143      * @see #start()
144      * @see #stop()
145      */
146     public boolean isRunning();
147 
148     /**
149      * Indicates whether the line is engaging in active I/O (such as playback
150      * or capture).  When an inactive line becomes active, it sends a
151      * <code>{@link LineEvent.Type#START START}</code> event to its listeners.  Similarly, when
152      * an active line becomes inactive, it sends a
153      * <code>{@link LineEvent.Type#STOP STOP}</code> event.
154      * @return <code>true</code> if the line is actively capturing or rendering
155      * sound, otherwise <code>false</code>
156      * @see #isOpen
157      * @see #addLineListener
158      * @see #removeLineListener
159      * @see LineEvent
160      * @see LineListener
161      */
162     public boolean isActive();
163 
164     /**
165      * Obtains the current format (encoding, sample rate, number of channels,
166      * etc.) of the data line's audio data.
167      *
168      * <p>If the line is not open and has never been opened, it returns
169      * the default format. The default format is an implementation
170      * specific audio format, or, if the <code>DataLine.Info</code>
171      * object, which was used to retrieve this <code>DataLine</code>,
172      * specifies at least one fully qualified audio format, the
173      * last one will be used as the default format. Opening the
174      * line with a specific audio format (e.g.
175      * {@link SourceDataLine#open(AudioFormat)}) will override the
176      * default format.
177      *
178      * @return current audio data format
179      * @see AudioFormat
180      */
181     public AudioFormat getFormat();
182 
183     /**
184      * Obtains the maximum number of bytes of data that will fit in the data line's
185      * internal buffer.  For a source data line, this is the size of the buffer to
186      * which data can be written.  For a target data line, it is the size of
187      * the buffer from which data can be read.  Note that
188      * the units used are bytes, but will always correspond to an integral
189      * number of sample frames of audio data.
190      *
191      * @return the size of the buffer in bytes
192      */
193     public int getBufferSize();
194 
195     /**
196      * Obtains the number of bytes of data currently available to the
197      * application for processing in the data line's internal buffer.  For a
198      * source data line, this is the amount of data that can be written to the
199      * buffer without blocking.  For a target data line, this is the amount of data
200      * available to be read by the application.  For a clip, this value is always
201      * 0 because the audio data is loaded into the buffer when the clip is opened,
202      * and persists without modification until the clip is closed.
203      * <p>
204      * Note that the units used are bytes, but will always
205      * correspond to an integral number of sample frames of audio data.
206      * <p>
207      * An application is guaranteed that a read or
208      * write operation of up to the number of bytes returned from
209      * <code>available()</code> will not block; however, there is no guarantee
210      * that attempts to read or write more data will block.
211      *
212      * @return the amount of data available, in bytes
213      */
214     public int available();
215 
216     /**
217      * Obtains the current position in the audio data, in sample frames.
218      * The frame position measures the number of sample
219      * frames captured by, or rendered from, the line since it was opened.
220      * This return value will wrap around after 2^31 frames. It is recommended
221      * to use <code>getLongFramePosition</code> instead.
222      *
223      * @return the number of frames already processed since the line was opened
224      * @see #getLongFramePosition()
225      */
226     public int getFramePosition();
227 
228 
229     /**
230      * Obtains the current position in the audio data, in sample frames.
231      * The frame position measures the number of sample
232      * frames captured by, or rendered from, the line since it was opened.
233      *
234      * @return the number of frames already processed since the line was opened
235      * @since 1.5
236      */
237     public long getLongFramePosition();
238 
239 
240     /**
241      * Obtains the current position in the audio data, in microseconds.
242      * The microsecond position measures the time corresponding to the number
243      * of sample frames captured by, or rendered from, the line since it was opened.
244      * The level of precision is not guaranteed.  For example, an implementation
245      * might calculate the microsecond position from the current frame position
246      * and the audio sample frame rate.  The precision in microseconds would
247      * then be limited to the number of microseconds per sample frame.
248      *
249      * @return the number of microseconds of data processed since the line was opened
250      */
251     public long getMicrosecondPosition();
252 
253     /**
254      * Obtains the current volume level for the line.  This level is a measure
255      * of the signal's current amplitude, and should not be confused with the
256      * current setting of a gain control. The range is from 0.0 (silence) to
257      * 1.0 (maximum possible amplitude for the sound waveform).  The units
258      * measure linear amplitude, not decibels.
259      *
260      * @return the current amplitude of the signal in this line, or
261      * <code>{@link AudioSystem#NOT_SPECIFIED}</code>
262      */
263     public float getLevel();
264 
265     /**
266      * Besides the class information inherited from its superclass,
267      * <code>DataLine.Info</code> provides additional information specific to data lines.
268      * This information includes:
269      * <ul>
270      * <li> the audio formats supported by the data line
271      * <li> the minimum and maximum sizes of its internal buffer
272      * </ul>
273      * Because a <code>Line.Info</code> knows the class of the line its describes, a
274      * <code>DataLine.Info</code> object can describe <code>DataLine</code>
275      * subinterfaces such as <code>{@link SourceDataLine}</code>,
276      * <code>{@link TargetDataLine}</code>, and <code>{@link Clip}</code>.
277      * You can query a mixer for lines of any of these types, passing an appropriate
278      * instance of <code>DataLine.Info</code> as the argument to a method such as
279      * <code>{@link Mixer#getLine Mixer.getLine(Line.Info)}</code>.
280      *
281      * @see Line.Info
282      * @author Kara Kytle
283      * @since 1.3
284      */
285     public static class Info extends Line.Info {
286 
287         private final AudioFormat[] formats;
288         private final int minBufferSize;
289         private final int maxBufferSize;
290 
291         /**
292          * Constructs a data line's info object from the specified information,
293          * which includes a set of supported audio formats and a range for the buffer size.
294          * This constructor is typically used by mixer implementations
295          * when returning information about a supported line.
296          *
297          * @param lineClass the class of the data line described by the info object
298          * @param formats set of formats supported
299          * @param minBufferSize minimum buffer size supported by the data line, in bytes
300          * @param maxBufferSize maximum buffer size supported by the data line, in bytes
301          */
302         public Info(Class<?> lineClass, AudioFormat[] formats, int minBufferSize, int maxBufferSize) {
303 
304             super(lineClass);
305 
306             if (formats == null) {
307                 this.formats = new AudioFormat[0];
308             } else {
309                 this.formats = Arrays.copyOf(formats, formats.length);
310             }
311 
312             this.minBufferSize = minBufferSize;
313             this.maxBufferSize = maxBufferSize;
314         }
315 
316 
317         /**
318          * Constructs a data line's info object from the specified information,
319          * which includes a single audio format and a desired buffer size.
320          * This constructor is typically used by an application to
321          * describe a desired line.
322          *
323          * @param lineClass the class of the data line described by the info object
324          * @param format desired format
325          * @param bufferSize desired buffer size in bytes
326          */
327         public Info(Class<?> lineClass, AudioFormat format, int bufferSize) {
328 
329             super(lineClass);
330 
331             if (format == null) {
332                 this.formats = new AudioFormat[0];
333             } else {
334                 this.formats = new AudioFormat[]{format};
335             }
336 
337             this.minBufferSize = bufferSize;
338             this.maxBufferSize = bufferSize;
339         }
340 
341 
342         /**
343          * Constructs a data line's info object from the specified information,
344          * which includes a single audio format.
345          * This constructor is typically used by an application to
346          * describe a desired line.
347          *
348          * @param lineClass the class of the data line described by the info object
349          * @param format desired format
350          */
351         public Info(Class<?> lineClass, AudioFormat format) {
352             this(lineClass, format, AudioSystem.NOT_SPECIFIED);
353         }
354 
355 
356         /**
357          * Obtains a set of audio formats supported by the data line.
358          * Note that <code>isFormatSupported(AudioFormat)</code> might return
359          * <code>true</code> for certain additional formats that are missing from
360          * the set returned by <code>getFormats()</code>.  The reverse is not
361          * the case: <code>isFormatSupported(AudioFormat)</code> is guaranteed to return
362          * <code>true</code> for all formats returned by <code>getFormats()</code>.
363          *
364          * Some fields in the AudioFormat instances can be set to
365          * {@link javax.sound.sampled.AudioSystem#NOT_SPECIFIED NOT_SPECIFIED}
366          * if that field does not apply to the format,
367          * or if the format supports a wide range of values for that field.
368          * For example, a multi-channel device supporting up to
369          * 64 channels, could set the channel field in the
370          * <code>AudioFormat</code> instances returned by this
371          * method to <code>NOT_SPECIFIED</code>.
372          *
373          * @return a set of supported audio formats.
374          * @see #isFormatSupported(AudioFormat)
375          */
376         public AudioFormat[] getFormats() {
377             return Arrays.copyOf(formats, formats.length);
378         }
379 
380         /**
381          * Indicates whether this data line supports a particular audio format.
382          * The default implementation of this method simply returns <code>true</code> if
383          * the specified format matches any of the supported formats.
384          *
385          * @param format the audio format for which support is queried.
386          * @return <code>true</code> if the format is supported, otherwise <code>false</code>
387          * @see #getFormats
388          * @see AudioFormat#matches
389          */
390         public boolean isFormatSupported(AudioFormat format) {
391 
392             for (int i = 0; i < formats.length; i++) {
393                 if (format.matches(formats[i])) {
394                     return true;
395                 }
396             }
397 
398             return false;
399         }
400 
401         /**
402          * Obtains the minimum buffer size supported by the data line.
403          * @return minimum buffer size in bytes, or <code>AudioSystem.NOT_SPECIFIED</code>
404          */
405         public int getMinBufferSize() {
406             return minBufferSize;
407         }
408 
409 
410         /**
411          * Obtains the maximum buffer size supported by the data line.
412          * @return maximum buffer size in bytes, or <code>AudioSystem.NOT_SPECIFIED</code>
413          */
414         public int getMaxBufferSize() {
415             return maxBufferSize;
416         }
417 
418 
419         /**
420          * Determines whether the specified info object matches this one.
421          * To match, the superclass match requirements must be met.  In
422          * addition, this object's minimum buffer size must be at least as
423          * large as that of the object specified, its maximum buffer size must
424          * be at most as large as that of the object specified, and all of its
425          * formats must match formats supported by the object specified.
426          * @return <code>true</code> if this object matches the one specified,
427          * otherwise <code>false</code>.
428          */
429         public boolean matches(Line.Info info) {
430 
431             if (! (super.matches(info)) ) {
432                 return false;
433             }
434 
435             Info dataLineInfo = (Info)info;
436 
437             // treat anything < 0 as NOT_SPECIFIED
438             // demo code in old Java Sound Demo used a wrong buffer calculation
439             // that would lead to arbitrary negative values
440             if ((getMaxBufferSize() >= 0) && (dataLineInfo.getMaxBufferSize() >= 0)) {
441                 if (getMaxBufferSize() > dataLineInfo.getMaxBufferSize()) {
442                     return false;
443                 }
444             }
445 
446             if ((getMinBufferSize() >= 0) && (dataLineInfo.getMinBufferSize() >= 0)) {
447                 if (getMinBufferSize() < dataLineInfo.getMinBufferSize()) {
448                     return false;
449                 }
450             }
451 
452             AudioFormat[] localFormats = getFormats();
453 
454             if (localFormats != null) {
455 
456                 for (int i = 0; i < localFormats.length; i++) {
457                     if (! (localFormats[i] == null) ) {
458                         if (! (dataLineInfo.isFormatSupported(localFormats[i])) ) {
459                             return false;
460                         }
461                     }
462                 }
463             }
464 
465             return true;
466         }
467 
468         /**
469          * Obtains a textual description of the data line info.
470          * @return a string description
471          */
472         public String toString() {
473 
474             StringBuffer buf = new StringBuffer();
475 
476             if ( (formats.length == 1) && (formats[0] != null) ) {
477                 buf.append(" supporting format " + formats[0]);
478             } else if (getFormats().length > 1) {
479                 buf.append(" supporting " + getFormats().length + " audio formats");
480             }
481 
482             if ( (minBufferSize != AudioSystem.NOT_SPECIFIED) && (maxBufferSize != AudioSystem.NOT_SPECIFIED) ) {
483                 buf.append(", and buffers of " + minBufferSize + " to " + maxBufferSize + " bytes");
484             } else if ( (minBufferSize != AudioSystem.NOT_SPECIFIED) && (minBufferSize > 0) ) {
485                 buf.append(", and buffers of at least " + minBufferSize + " bytes");
486             } else if (maxBufferSize != AudioSystem.NOT_SPECIFIED) {
487                 buf.append(", and buffers of up to " + minBufferSize + " bytes");
488             }
489 
490             return new String(super.toString() + buf);
491         }
492     } // class Info
493 
494 } // interface DataLine