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()
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 *
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 AudioSystem#NOT_SPECIFIED NOT_SPECIFIED} if that field does
359 * not apply to the format, or if the format supports a wide range of
360 * values for that field. For example, a multi-channel device supporting
361 * up to 64 channels, could set the channel field in the
362 * {@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
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 }
|
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 {@code 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()
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 *
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 * @author Kara Kytle
274 * @see Line.Info
275 * @since 1.3
276 */
277 class Info extends Line.Info {
278
279 /**
280 * The set of supported formats.
281 */
282 private final AudioFormat[] formats;
283
284 /**
285 * Minimum buffer size supported by the data line, in bytes.
286 */
287 private final int minBufferSize;
288
289 /**
290 * Maximum buffer size supported by the data line, in bytes.
291 */
292 private final int maxBufferSize;
293
294 /**
295 * Constructs a data line's info object from the specified information,
296 * which includes a set of supported audio formats and a range for the
297 * buffer size. This constructor is typically used by mixer
298 * implementations when returning information about a supported line.
299 *
300 * @param lineClass the class of the data line described by the info
301 * object
302 * @param formats set of formats supported
303 * @param minBufferSize minimum buffer size supported by the data line,
304 * in bytes
305 * @param maxBufferSize maximum buffer size supported by the data line,
306 * in bytes
307 */
308 public Info(Class<?> lineClass, AudioFormat[] formats, int minBufferSize, int maxBufferSize) {
309
310 super(lineClass);
311
312 if (formats == null) {
313 this.formats = new AudioFormat[0];
314 } else {
315 this.formats = Arrays.copyOf(formats, formats.length);
316 }
317
318 this.minBufferSize = minBufferSize;
319 this.maxBufferSize = maxBufferSize;
320 }
321
322 /**
323 * Constructs a data line's info object from the specified information,
324 * which includes a single audio format and a desired buffer size. This
325 * constructor is typically used by an application to describe a desired
326 * line.
327 *
328 * @param lineClass the class of the data line described by the info
329 * object
330 * @param format desired format
331 * @param bufferSize desired buffer size, in bytes
332 */
333 public Info(Class<?> lineClass, AudioFormat format, int bufferSize) {
334
335 super(lineClass);
336
337 if (format == null) {
338 this.formats = new AudioFormat[0];
339 } else {
340 this.formats = new AudioFormat[]{format};
341 }
342
343 this.minBufferSize = bufferSize;
344 this.maxBufferSize = bufferSize;
345 }
346
347 /**
348 * Constructs a data line's info object from the specified information,
349 * which includes a single audio format. This constructor is typically
350 * used by an application to describe a desired line.
351 *
352 * @param lineClass the class of the data line described by the info
353 * object
354 * @param format desired format
355 */
356 public Info(Class<?> lineClass, AudioFormat format) {
357 this(lineClass, format, AudioSystem.NOT_SPECIFIED);
358 }
359
360 /**
361 * Obtains a set of audio formats supported by the data line. Note that
362 * {@code isFormatSupported(AudioFormat)} might return {@code true} for
363 * certain additional formats that are missing from the set returned by
364 * {@code getFormats()}. The reverse is not the case:
365 * {@code isFormatSupported(AudioFormat)} is guaranteed to return
366 * {@code true} for all formats returned by {@code getFormats()}.
367 * <p>
368 * Some fields in the {@code AudioFormat} instances can be set to
369 * {@link AudioSystem#NOT_SPECIFIED NOT_SPECIFIED} if that field does
370 * not apply to the format, or if the format supports a wide range of
371 * values for that field. For example, a multi-channel device supporting
372 * up to 64 channels, could set the channel field in the
373 * {@code AudioFormat} instances returned by this method to
374 * {@code NOT_SPECIFIED}.
375 *
376 * @return a set of supported audio formats
377 * @see #isFormatSupported(AudioFormat)
378 */
379 public AudioFormat[] getFormats() {
380 return Arrays.copyOf(formats, formats.length);
381 }
382
383 /**
384 * Indicates whether this data line supports a particular audio format.
385 * The default implementation of this method simply returns {@code true}
386 * if the specified format matches any of the supported formats.
387 *
388 * @param format the audio format for which support is queried
413 }
414
415 /**
416 * Obtains the maximum buffer size supported by the data line.
417 *
418 * @return maximum buffer size in bytes, or
419 * {@code AudioSystem.NOT_SPECIFIED}
420 */
421 public int getMaxBufferSize() {
422 return maxBufferSize;
423 }
424
425 /**
426 * Determines whether the specified info object matches this one. To
427 * match, the superclass match requirements must be met. In addition,
428 * this object's minimum buffer size must be at least as large as that
429 * of the object specified, its maximum buffer size must be at most as
430 * large as that of the object specified, and all of its formats must
431 * match formats supported by the object specified.
432 *
433 * @param info the info object which is being compared to this one
434 * @return {@code true} if this object matches the one specified,
435 * otherwise {@code false}
436 */
437 @Override
438 public boolean matches(Line.Info info) {
439
440 if (! (super.matches(info)) ) {
441 return false;
442 }
443
444 Info dataLineInfo = (Info)info;
445
446 // treat anything < 0 as NOT_SPECIFIED
447 // demo code in old Java Sound Demo used a wrong buffer calculation
448 // that would lead to arbitrary negative values
449 if ((getMaxBufferSize() >= 0) && (dataLineInfo.getMaxBufferSize() >= 0)) {
450 if (getMaxBufferSize() > dataLineInfo.getMaxBufferSize()) {
451 return false;
452 }
453 }
|