DataLine JDK 1.6)

Description

public interface DataLine

DataLine adds media-related functionality to its superinterface, Line.

DataLine adds media-related functionality to its superinterface, 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 SourceDataLine or Clip, which allow an application program to write data. Similarly, audio input is handled by the subinterface TargetDataLine, which allows data to be read.

A data line has an internal buffer in which the incoming or outgoing audio data is queued. The DataLine.drain() method blocks until this internal buffer becomes empty, usually because all queued data has been processed. The DataLine.flush() method discards any available queued data from the internal buffer.

A data line produces START and 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 DataLine.start() is called on an inactive data line, and data is available for capture or playback, a 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 STOP event is generated.

Mixers often support synchronized control of multiple data lines. Synchronization can be established through the Mixer interface's synchronize method. See the description of the Mixer interface for a more complete description.

See also: LineEvent

Methods

Hide/Show inherited methods

public int available ()

Obtains the number of bytes of data currently available to the application for processing in the data line's internal buffer.

public void drain ()

Drains queued data from the line by continuing data I/O until the data line's internal buffer has been emptied.

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 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
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 Also: DataLine.flush(),

public void flush ()

Flushes queued data from the line.

public int getBufferSize ()

Obtains the maximum number of bytes of data that will fit in the data line's internal buffer.

public AudioFormat getFormat ()

Obtains the current format (encoding, sample rate, number of channels, etc.) of the data line's audio data.

public int getFramePosition ()

Obtains the current position in the audio data, in sample frames.

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 getLongFramePosition instead.
Returns: the number of frames already processed since the line was opened
See Also: DataLine.getLongFramePosition(),

public float getLevel ()

Obtains the current volume level for the line.

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.
Returns: the current amplitude of the signal in this line, or {@link AudioSystem#NOT_SPECIFIED}

public long getLongFramePosition ()

Obtains the current position in the audio data, in sample frames.

public long getMicrosecondPosition ()

Obtains the current position in the audio data, in microseconds.

public boolean isActive ()

Indicates whether the line is engaging in active I/O (such as playback or capture).

Indicates whether the line is engaging in active I/O (such as playback
or capture). When an inactive line becomes active, it sends a
START event to its listeners. Similarly, when
an active line becomes inactive, it sends a
STOP event.
Returns: true if the line is actively capturing or rendering sound, otherwise false
See Also: Line.isOpen(), Line.addLineListener(javax.sound.sampled.LineListener), Line.removeLineListener(javax.sound.sampled.LineListener), LineEvent, LineListener,

public boolean isRunning ()

Indicates whether the line is running.

Indicates whether the line is running. The default is false.
An open line begins running when the first data is presented in response to an
invocation of the start method, and continues
until presentation ceases in response to a call to stop or
because playback completes.
Returns: true if the line is running, otherwise false
See Also: DataLine.start(), DataLine.stop(),

public void start ()

Allows a line to engage in data I/O.

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
START event is generated.
See Also: DataLine.stop(), DataLine.isRunning(), LineEvent,

public void stop ()

Stops the line.

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 flush method.
When audio capture or playback stops, a STOP event is generated.
See Also: DataLine.start(), DataLine.isRunning(), DataLine.flush(), LineEvent,