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