Java tutorial
/* * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.sound.sampled; import java.util.Arrays; /** * {@code DataLine} adds media-related functionality to its superinterface, * {@code Line}. This functionality includes transport-control methods that * start, stop, drain, and flush the audio data that passes through the line. A * data line can also report the current position, volume, and audio format of * the media. Data lines are used for output of audio by means of the * subinterfaces {@link SourceDataLine} or {@link Clip}, which allow an * application program to write data. Similarly, audio input is handled by the * subinterface {@link TargetDataLine}, which allows data to be read. * <p> * A data line has an internal buffer in which the incoming or outgoing audio * data is queued. The {@link #drain()} method blocks until this internal buffer * becomes empty, usually because all queued data has been processed. The * {@link #flush()} method discards any available queued data from the internal * buffer. * <p> * A data line produces {@link LineEvent.Type#START START} and * {@link LineEvent.Type#STOP STOP} events whenever it begins or ceases active * presentation or capture of data. These events can be generated in response to * specific requests, or as a result of less direct state changes. For example, * if {@link #start()} is called on an inactive data line, and data is available * for capture or playback, a {@code START} event will be generated shortly, * when data playback or capture actually begins. Or, if the flow of data to an * active data line is constricted so that a gap occurs in the presentation of * data, a {@code STOP} event is generated. * <p> * Mixers often support synchronized control of multiple data lines. * Synchronization can be established through the {@code Mixer} interface's * {@link Mixer#synchronize synchronize} method. See the description of the * {@link Mixer Mixer} interface for a more complete description. * * @author Kara Kytle * @see LineEvent * @since 1.3 */ public interface DataLine extends Line { /** * Drains queued data from the line by continuing data I/O until the data * line's internal buffer has been emptied. This method blocks until the * draining is complete. Because this is a blocking method, it should be * used with care. If {@code drain()} is invoked on a stopped line that has * data in its queue, the method will block until the line is running and * the data queue becomes empty. If {@code drain()} is invoked by one * thread, and another continues to fill the data queue, the operation will * not complete. This method always returns when the data line is closed. * * @see #flush() */ void drain(); /** * Flushes queued data from the line. The flushed data is discarded. In some * cases, not all queued data can be discarded. For example, a mixer can * flush data from the buffer for a specific input line, but any unplayed * data already in the output buffer (the result of the mix) will still be * played. You can invoke this method after pausing a line (the normal case) * if you want to skip the "stale" data when you restart playback or * capture. (It is legal to flush a line that is not stopped, but doing so * on an active line is likely to cause a discontinuity in the data, * resulting in a perceptible click.) * * @see #stop() * @see #drain() */ void flush(); /** * Allows a line to engage in data I/O. If invoked on a line that is already * running, this method does nothing. Unless the data in the buffer has been * flushed, the line resumes I/O starting with the first frame that was * unprocessed at the time the line was stopped. When audio capture or * playback starts, a {@link LineEvent.Type#START START} event is generated. * * @see #stop() * @see #isRunning() * @see LineEvent */ void start(); /** * Stops the line. A stopped line should cease I/O activity. If the line is * open and running, however, it should retain the resources required to * resume activity. A stopped line should retain any audio data in its * buffer instead of discarding it, so that upon resumption the I/O can * continue where it left off, if possible. (This doesn't guarantee that * there will never be discontinuities beyond the current buffer, of course; * if the stopped condition continues for too long, input or output samples * might be dropped.) If desired, the retained data can be discarded by * invoking the {@code flush} method. When audio capture or playback stops, * a {@link LineEvent.Type#STOP STOP} event is generated. * * @see #start() * @see #isRunning() * @see #flush() * @see LineEvent */ void stop(); /** * Indicates whether the line is running. The default is {@code false}. An * open line begins running when the first data is presented in response to * an invocation of the {@code start} method, and continues until * presentation ceases in response to a call to {@code stop} or because * playback completes. * * @return {@code true} if the line is running, otherwise {@code false} * @see #start() * @see #stop() */ boolean isRunning(); /** * Indicates whether the line is engaging in active I/O (such as playback or * capture). When an inactive line becomes active, it sends a * {@link LineEvent.Type#START START} event to its listeners. Similarly, * when an active line becomes inactive, it sends a * {@link LineEvent.Type#STOP STOP} event. * * @return {@code true} if the line is actively capturing or rendering * sound, otherwise {@code false} * @see #isOpen * @see #addLineListener * @see #removeLineListener * @see LineEvent * @see LineListener */ boolean isActive(); /** * Obtains the current format (encoding, sample rate, number of channels, * etc.) of the data line's audio data. * <p> * If the line is not open and has never been opened, it returns the default * format. The default format is an implementation specific audio format, * or, if the {@code DataLine.Info} object, which was used to retrieve this * {@code DataLine}, specifies at least one fully qualified audio format, * the last one will be used as the default format. Opening the line with a * specific audio format (e.g. {@link SourceDataLine#open(AudioFormat)}) * will override the default format. * * @return current audio data format * @see AudioFormat */ AudioFormat getFormat(); /** * Obtains the maximum number of bytes of data that will fit in the data * line's internal buffer. For a source data line, this is the size of the * buffer to which data can be written. For a target data line, it is the * size of the buffer from which data can be read. Note that the units used * are bytes, but will always correspond to an integral number of sample * frames of audio data. * * @return the size of the buffer, in bytes */ int getBufferSize(); /** * Obtains the number of bytes of data currently available to the * application for processing in the data line's internal buffer. For a * source data line, this is the amount of data that can be written to the * buffer without blocking. For a target data line, this is the amount of * data available to be read by the application. For a clip, this value is * always 0 because the audio data is loaded into the buffer when the clip * is opened, and persists without modification until the clip is closed. * <p> * Note that the units used are bytes, but will always correspond to an * integral number of sample frames of audio data. * <p> * An application is guaranteed that a read or write operation of up to the * number of bytes returned from {@code available()} will not block; * however, there is no guarantee that attempts to read or write more data * will block. * * @return the amount of data available, in bytes */ int available(); /** * Obtains the current position in the audio data, in sample frames. The * frame position measures the number of sample frames captured by, or * rendered from, the line since it was opened. This return value will wrap * around after 2^31 frames. It is recommended to use * {@code getLongFramePosition} instead. * * @return the number of frames already processed since the line was opened * @see #getLongFramePosition() */ int getFramePosition(); /** * Obtains the current position in the audio data, in sample frames. The * frame position measures the number of sample frames captured by, or * rendered from, the line since it was opened. * * @return the number of frames already processed since the line was opened * @since 1.5 */ long getLongFramePosition(); /** * Obtains the current position in the audio data, in microseconds. The * microsecond position measures the time corresponding to the number of * sample frames captured by, or rendered from, the line since it was * opened. The level of precision is not guaranteed. For example, an * implementation might calculate the microsecond position from the current * frame position and the audio sample frame rate. The precision in * microseconds would then be limited to the number of microseconds per * sample frame. * * @return the number of microseconds of data processed since the line was * opened */ long getMicrosecondPosition(); /** * Obtains the current volume level for the line. This level is a measure of * the signal's current amplitude, and should not be confused with the * current setting of a gain control. The range is from 0.0 (silence) to 1.0 * (maximum possible amplitude for the sound waveform). The units measure * linear amplitude, not decibels. * * @return the current amplitude of the signal in this line, or * {@link AudioSystem#NOT_SPECIFIED} */ float getLevel(); /** * Besides the class information inherited from its superclass, * {@code DataLine.Info} provides additional information specific to data * lines. This information includes: * <ul> * <li>the audio formats supported by the data line * <li>the minimum and maximum sizes of its internal buffer * </ul> * Because a {@code Line.Info} knows the class of the line its describes, a * {@code DataLine.Info} object can describe {@code DataLine} subinterfaces * such as {@link SourceDataLine}, {@link TargetDataLine}, and {@link Clip}. * You can query a mixer for lines of any of these types, passing an * appropriate instance of {@code DataLine.Info} as the argument to a method * such as {@link Mixer#getLine(Line.Info)}. * * @author Kara Kytle * @see Line.Info * @since 1.3 */ class Info extends Line.Info { /** * The set of supported formats. */ private final AudioFormat[] formats; /** * Minimum buffer size supported by the data line, in bytes. */ private final int minBufferSize; /** * Maximum buffer size supported by the data line, in bytes. */ private final int maxBufferSize; /** * Constructs a data line's info object from the specified information, * which includes a set of supported audio formats and a range for the * buffer size. This constructor is typically used by mixer * implementations when returning information about a supported line. * * @param lineClass the class of the data line described by the info * object * @param formats set of formats supported * @param minBufferSize minimum buffer size supported by the data line, * in bytes * @param maxBufferSize maximum buffer size supported by the data line, * in bytes */ public Info(Class<?> lineClass, AudioFormat[] formats, int minBufferSize, int maxBufferSize) { super(lineClass); if (formats == null) { this.formats = new AudioFormat[0]; } else { this.formats = Arrays.copyOf(formats, formats.length); } this.minBufferSize = minBufferSize; this.maxBufferSize = maxBufferSize; } /** * Constructs a data line's info object from the specified information, * which includes a single audio format and a desired buffer size. This * constructor is typically used by an application to describe a desired * line. * * @param lineClass the class of the data line described by the info * object * @param format desired format * @param bufferSize desired buffer size, in bytes */ public Info(Class<?> lineClass, AudioFormat format, int bufferSize) { super(lineClass); if (format == null) { this.formats = new AudioFormat[0]; } else { this.formats = new AudioFormat[] { format }; } this.minBufferSize = bufferSize; this.maxBufferSize = bufferSize; } /** * Constructs a data line's info object from the specified information, * which includes a single audio format. This constructor is typically * used by an application to describe a desired line. * * @param lineClass the class of the data line described by the info * object * @param format desired format */ public Info(Class<?> lineClass, AudioFormat format) { this(lineClass, format, AudioSystem.NOT_SPECIFIED); } /** * Obtains a set of audio formats supported by the data line. Note that * {@code isFormatSupported(AudioFormat)} might return {@code true} for * certain additional formats that are missing from the set returned by * {@code getFormats()}. The reverse is not the case: * {@code isFormatSupported(AudioFormat)} is guaranteed to return * {@code true} for all formats returned by {@code getFormats()}. * <p> * Some fields in the {@code AudioFormat} instances can be set to * {@link AudioSystem#NOT_SPECIFIED NOT_SPECIFIED} if that field does * not apply to the format, or if the format supports a wide range of * values for that field. For example, a multi-channel device supporting * up to 64 channels, could set the channel field in the * {@code AudioFormat} instances returned by this method to * {@code NOT_SPECIFIED}. * * @return a set of supported audio formats * @see #isFormatSupported(AudioFormat) */ public AudioFormat[] getFormats() { return Arrays.copyOf(formats, formats.length); } /** * Indicates whether this data line supports a particular audio format. * The default implementation of this method simply returns {@code true} * if the specified format matches any of the supported formats. * * @param format the audio format for which support is queried * @return {@code true} if the format is supported, otherwise * {@code false} * @see #getFormats * @see AudioFormat#matches */ public boolean isFormatSupported(AudioFormat format) { for (int i = 0; i < formats.length; i++) { if (format.matches(formats[i])) { return true; } } return false; } /** * Obtains the minimum buffer size supported by the data line. * * @return minimum buffer size in bytes, or * {@code AudioSystem.NOT_SPECIFIED} */ public int getMinBufferSize() { return minBufferSize; } /** * Obtains the maximum buffer size supported by the data line. * * @return maximum buffer size in bytes, or * {@code AudioSystem.NOT_SPECIFIED} */ public int getMaxBufferSize() { return maxBufferSize; } /** * Determines whether the specified info object matches this one. To * match, the superclass match requirements must be met. In addition, * this object's minimum buffer size must be at least as large as that * of the object specified, its maximum buffer size must be at most as * large as that of the object specified, and all of its formats must * match formats supported by the object specified. * * @param info the info object which is being compared to this one * @return {@code true} if this object matches the one specified, * otherwise {@code false} */ @Override public boolean matches(Line.Info info) { if (!(super.matches(info))) { return false; } Info dataLineInfo = (Info) info; // treat anything < 0 as NOT_SPECIFIED // demo code in old Java Sound Demo used a wrong buffer calculation // that would lead to arbitrary negative values if ((getMaxBufferSize() >= 0) && (dataLineInfo.getMaxBufferSize() >= 0)) { if (getMaxBufferSize() > dataLineInfo.getMaxBufferSize()) { return false; } } if ((getMinBufferSize() >= 0) && (dataLineInfo.getMinBufferSize() >= 0)) { if (getMinBufferSize() < dataLineInfo.getMinBufferSize()) { return false; } } AudioFormat[] localFormats = getFormats(); if (localFormats != null) { for (int i = 0; i < localFormats.length; i++) { if (!(localFormats[i] == null)) { if (!(dataLineInfo.isFormatSupported(localFormats[i]))) { return false; } } } } return true; } /** * Obtains a textual description of the data line info. * * @return a string description */ @Override public String toString() { StringBuilder sb = new StringBuilder(); if ((formats.length == 1) && (formats[0] != null)) { sb.append(" supporting format " + formats[0]); } else if (getFormats().length > 1) { sb.append(" supporting " + getFormats().length + " audio formats"); } if ((minBufferSize != AudioSystem.NOT_SPECIFIED) && (maxBufferSize != AudioSystem.NOT_SPECIFIED)) { sb.append(", and buffers of " + minBufferSize + " to " + maxBufferSize + " bytes"); } else if ((minBufferSize != AudioSystem.NOT_SPECIFIED) && (minBufferSize > 0)) { sb.append(", and buffers of at least " + minBufferSize + " bytes"); } else if (maxBufferSize != AudioSystem.NOT_SPECIFIED) { sb.append(", and buffers of up to " + minBufferSize + " bytes"); } return new String(super.toString() + sb); } } }