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