javax.sound.sampled
Interface DataLine

All Superinterfaces:
Line sample code for javax.sound.sampled.Line definition code for javax.sound.sampled.Line
All Known Subinterfaces:
Clip sample code for javax.sound.sampled.Clip definition code for javax.sound.sampled.Clip , SourceDataLine sample code for javax.sound.sampled.SourceDataLine definition code for javax.sound.sampled.SourceDataLine , TargetDataLine sample code for javax.sound.sampled.TargetDataLine definition code for javax.sound.sampled.TargetDataLine

public interface DataLine
extends Line sample code for javax.sound.sampled.Line definition code for javax.sound.sampled.Line

DataLine adds media-related functionality to its superinterface, Line sample code for javax.sound.sampled.Line definition code for javax.sound.sampled.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 sample code for javax.sound.sampled.SourceDataLine definition code for javax.sound.sampled.SourceDataLine or Clip sample code for javax.sound.sampled.Clip definition code for javax.sound.sampled.Clip , which allow an application program to write data. Similarly, audio input is handled by the subinterface TargetDataLine sample code for javax.sound.sampled.TargetDataLine definition code for javax.sound.sampled.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 drain() sample code for javax.sound.sampled.DataLine.drain() definition code for javax.sound.sampled.DataLine.drain() method blocks until this internal buffer becomes empty, usually because all queued data has been processed. The flush() sample code for javax.sound.sampled.DataLine.flush() definition code for javax.sound.sampled.DataLine.flush() method discards any available queued data from the internal buffer.

A data line produces START sample code for javax.sound.sampled.LineEvent.Type.START definition code for javax.sound.sampled.LineEvent.Type.START and STOP sample code for javax.sound.sampled.LineEvent.Type.STOP definition code for javax.sound.sampled.LineEvent.Type.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 start() sample code for javax.sound.sampled.DataLine.start() definition code for javax.sound.sampled.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 sample code for javax.sound.sampled.Mixer.synchronize(javax.sound.sampled.Line[], boolean) definition code for javax.sound.sampled.Mixer.synchronize(javax.sound.sampled.Line[], boolean) method. See the description of the Mixer sample code for javax.sound.sampled.Mixer definition code for javax.sound.sampled.Mixer interface for a more complete description.

Since:
1.3
See Also:
LineEvent sample code for javax.sound.sampled.LineEvent definition code for javax.sound.sampled.LineEvent

Nested Class Summary
static class DataLine.Info sample code for javax.sound.sampled.DataLine.Info definition code for javax.sound.sampled.DataLine.Info
          Besides the class information inherited from its superclass, DataLine.Info provides additional information specific to data lines.
 
Method Summary
 int available sample code for javax.sound.sampled.DataLine.available() definition code for javax.sound.sampled.DataLine.available() ()
          Obtains the number of bytes of data currently available to the application for processing in the data line's internal buffer.
 void drain sample code for javax.sound.sampled.DataLine.drain() definition code for javax.sound.sampled.DataLine.drain() ()
          Drains queued data from the line by continuing data I/O until the data line's internal buffer has been emptied.
 void flush sample code for javax.sound.sampled.DataLine.flush() definition code for javax.sound.sampled.DataLine.flush() ()
          Flushes queued data from the line.
 int getBufferSize sample code for javax.sound.sampled.DataLine.getBufferSize() definition code for javax.sound.sampled.DataLine.getBufferSize() ()
          Obtains the maximum number of bytes of data that will fit in the data line's internal buffer.
 AudioFormat sample code for javax.sound.sampled.AudioFormat definition code for javax.sound.sampled.AudioFormat getFormat sample code for javax.sound.sampled.DataLine.getFormat() definition code for javax.sound.sampled.DataLine.getFormat() ()
          Obtains the current format (encoding, sample rate, number of channels, etc.) of the data line's audio data.
 int getFramePosition sample code for javax.sound.sampled.DataLine.getFramePosition() definition code for javax.sound.sampled.DataLine.getFramePosition() ()
          Obtains the current position in the audio data, in sample frames.
 float getLevel sample code for javax.sound.sampled.DataLine.getLevel() definition code for javax.sound.sampled.DataLine.getLevel() ()
          Obtains the current volume level for the line.
 long getLongFramePosition sample code for javax.sound.sampled.DataLine.getLongFramePosition() definition code for javax.sound.sampled.DataLine.getLongFramePosition() ()
          Obtains the current position in the audio data, in sample frames.
 long getMicrosecondPosition sample code for javax.sound.sampled.DataLine.getMicrosecondPosition() definition code for javax.sound.sampled.DataLine.getMicrosecondPosition() ()
          Obtains the current position in the audio data, in microseconds.
 boolean isActive sample code for javax.sound.sampled.DataLine.isActive() definition code for javax.sound.sampled.DataLine.isActive() ()
          Indicates whether the line is engaging in active I/O (such as playback or capture).
 boolean isRunning sample code for javax.sound.sampled.DataLine.isRunning() definition code for javax.sound.sampled.DataLine.isRunning() ()
          Indicates whether the line is running.
 void start sample code for javax.sound.sampled.DataLine.start() definition code for javax.sound.sampled.DataLine.start() ()
          Allows a line to engage in data I/O.
 void stop sample code for javax.sound.sampled.DataLine.stop() definition code for javax.sound.sampled.DataLine.stop() ()
          Stops the line.
 
Methods inherited from interface javax.sound.sampled.Line sample code for javax.sound.sampled.Line definition code for javax.sound.sampled.Line
addLineListener sample code for javax.sound.sampled.Line.addLineListener(javax.sound.sampled.LineListener) definition code for javax.sound.sampled.Line.addLineListener(javax.sound.sampled.LineListener) , close sample code for javax.sound.sampled.Line.close() definition code for javax.sound.sampled.Line.close() , getControl sample code for javax.sound.sampled.Line.getControl(javax.sound.sampled.Control.Type) definition code for javax.sound.sampled.Line.getControl(javax.sound.sampled.Control.Type) , getControls sample code for javax.sound.sampled.Line.getControls() definition code for javax.sound.sampled.Line.getControls() , getLineInfo sample code for javax.sound.sampled.Line.getLineInfo() definition code for javax.sound.sampled.Line.getLineInfo() , isControlSupported sample code for javax.sound.sampled.Line.isControlSupported(javax.sound.sampled.Control.Type) definition code for javax.sound.sampled.Line.isControlSupported(javax.sound.sampled.Control.Type) , isOpen sample code for javax.sound.sampled.Line.isOpen() definition code for javax.sound.sampled.Line.isOpen() , open sample code for javax.sound.sampled.Line.open() definition code for javax.sound.sampled.Line.open() , removeLineListener sample code for javax.sound.sampled.Line.removeLineListener(javax.sound.sampled.LineListener) definition code for javax.sound.sampled.Line.removeLineListener(javax.sound.sampled.LineListener)
 

Method Detail

drain sample code for javax.sound.sampled.DataLine.drain() definition code for javax.sound.sampled.DataLine.drain()

void drain()
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:
flush() sample code for javax.sound.sampled.DataLine.flush() definition code for javax.sound.sampled.DataLine.flush()

flush sample code for javax.sound.sampled.DataLine.flush() definition code for javax.sound.sampled.DataLine.flush()

void flush()
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 Also:
stop() sample code for javax.sound.sampled.DataLine.stop() definition code for javax.sound.sampled.DataLine.stop() , drain() sample code for javax.sound.sampled.DataLine.drain() definition code for javax.sound.sampled.DataLine.drain()

start sample code for javax.sound.sampled.DataLine.start() definition code for javax.sound.sampled.DataLine.start()

void start()
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 sample code for javax.sound.sampled.LineEvent.Type.START definition code for javax.sound.sampled.LineEvent.Type.START event is generated.

See Also:
stop() sample code for javax.sound.sampled.DataLine.stop() definition code for javax.sound.sampled.DataLine.stop() , isRunning() sample code for javax.sound.sampled.DataLine.isRunning() definition code for javax.sound.sampled.DataLine.isRunning() , LineEvent sample code for javax.sound.sampled.LineEvent definition code for javax.sound.sampled.LineEvent

stop sample code for javax.sound.sampled.DataLine.stop() definition code for javax.sound.sampled.DataLine.stop()

void stop()
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 sample code for javax.sound.sampled.LineEvent.Type.STOP definition code for javax.sound.sampled.LineEvent.Type.STOP event is generated.

See Also:
start() sample code for javax.sound.sampled.DataLine.start() definition code for javax.sound.sampled.DataLine.start() , isRunning() sample code for javax.sound.sampled.DataLine.isRunning() definition code for javax.sound.sampled.DataLine.isRunning() , flush() sample code for javax.sound.sampled.DataLine.flush() definition code for javax.sound.sampled.DataLine.flush() , LineEvent sample code for javax.sound.sampled.LineEvent definition code for javax.sound.sampled.LineEvent

isRunning sample code for javax.sound.sampled.DataLine.isRunning() definition code for javax.sound.sampled.DataLine.isRunning()

boolean isRunning()
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:
start() sample code for javax.sound.sampled.DataLine.start() definition code for javax.sound.sampled.DataLine.start() , stop() sample code for javax.sound.sampled.DataLine.stop() definition code for javax.sound.sampled.DataLine.stop()

isActive sample code for javax.sound.sampled.DataLine.isActive() definition code for javax.sound.sampled.DataLine.isActive()

boolean isActive()
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 sample code for javax.sound.sampled.LineEvent.Type.START definition code for javax.sound.sampled.LineEvent.Type.START event to its listeners. Similarly, when an active line becomes inactive, it sends a STOP sample code for javax.sound.sampled.LineEvent.Type.STOP definition code for javax.sound.sampled.LineEvent.Type.STOP event.

Returns:
true if the line is actively capturing or rendering sound, otherwise false
See Also:
Line.isOpen() sample code for javax.sound.sampled.Line.isOpen() definition code for javax.sound.sampled.Line.isOpen() , Line.addLineListener(javax.sound.sampled.LineListener) sample code for javax.sound.sampled.Line.addLineListener(javax.sound.sampled.LineListener) definition code for javax.sound.sampled.Line.addLineListener(javax.sound.sampled.LineListener) , Line.removeLineListener(javax.sound.sampled.LineListener) sample code for javax.sound.sampled.Line.removeLineListener(javax.sound.sampled.LineListener) definition code for javax.sound.sampled.Line.removeLineListener(javax.sound.sampled.LineListener) , LineEvent sample code for javax.sound.sampled.LineEvent definition code for javax.sound.sampled.LineEvent , LineListener sample code for javax.sound.sampled.LineListener definition code for javax.sound.sampled.LineListener

getFormat sample code for javax.sound.sampled.DataLine.getFormat() definition code for javax.sound.sampled.DataLine.getFormat()

AudioFormat sample code for javax.sound.sampled.AudioFormat definition code for javax.sound.sampled.AudioFormat  getFormat()
Obtains the current format (encoding, sample rate, number of channels, etc.) of the data line's audio data.

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 DataLine.Info object, which was used to retrieve this 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. SourceDataLine.open(AudioFormat) sample code for javax.sound.sampled.SourceDataLine.open(javax.sound.sampled.AudioFormat) definition code for javax.sound.sampled.SourceDataLine.open(javax.sound.sampled.AudioFormat) ) will override the default format.

Returns:
current audio data format
See Also:
AudioFormat sample code for javax.sound.sampled.AudioFormat definition code for javax.sound.sampled.AudioFormat

getBufferSize sample code for javax.sound.sampled.DataLine.getBufferSize() definition code for javax.sound.sampled.DataLine.getBufferSize()

int getBufferSize()
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.

Returns:
the size of the buffer in bytes

available sample code for javax.sound.sampled.DataLine.available() definition code for javax.sound.sampled.DataLine.available()

int available()
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.

Note that the units used are bytes, but will always correspond to an integral number of sample frames of audio data.

An application is guaranteed that a read or write operation of up to the number of bytes returned from available() will not block; however, there is no guarantee that attempts to read or write more data will block.

Returns:
the amount of data available, in bytes

getFramePosition sample code for javax.sound.sampled.DataLine.getFramePosition() definition code for javax.sound.sampled.DataLine.getFramePosition()

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. 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:
getLongFramePosition() sample code for javax.sound.sampled.DataLine.getLongFramePosition() definition code for javax.sound.sampled.DataLine.getLongFramePosition()

getLongFramePosition sample code for javax.sound.sampled.DataLine.getLongFramePosition() definition code for javax.sound.sampled.DataLine.getLongFramePosition()

long getLongFramePosition()
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.

Returns:
the number of frames already processed since the line was opened
Since:
1.5

getMicrosecondPosition sample code for javax.sound.sampled.DataLine.getMicrosecondPosition() definition code for javax.sound.sampled.DataLine.getMicrosecondPosition()

long getMicrosecondPosition()
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.

Returns:
the number of microseconds of data processed since the line was opened

getLevel sample code for javax.sound.sampled.DataLine.getLevel() definition code for javax.sound.sampled.DataLine.getLevel()

float getLevel()
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 AudioSystem.NOT_SPECIFIED sample code for javax.sound.sampled.AudioSystem.NOT_SPECIFIED definition code for javax.sound.sampled.AudioSystem.NOT_SPECIFIED