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 drain() method blocks until this internal buffer becomes empty, usually because all queued data has been processed. The 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 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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	DataLine.Info Besides the class information inherited from its superclass, `DataLine.Info` provides additional information specific to data lines.

Method Summary

Modifier and Type	Method and Description
public int	Returns: the amount of data available, in bytes 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.
public void	flush() Flushes queued data from the line.
public int	Returns: the size of the buffer, in bytes getBufferSize() Obtains the maximum number of bytes of data that will fit in the data line's internal buffer.
public AudioFormat	Returns: current audio data format getFormat() Obtains the current format (encoding, sample rate, number of channels, etc.) of the data line's audio data.
public int	Returns: the number of frames already processed since the line was opened getFramePosition() Obtains the current position in the audio data, in sample frames.
public float	Returns: the current amplitude of the signal in this line, or `AudioSystem#NOT_SPECIFIED` getLevel() Obtains the current volume level for the line.
public long	Returns: the number of frames already processed since the line was opened getLongFramePosition() Obtains the current position in the audio data, in sample frames.
public long	Returns: the number of microseconds of data processed since the line was opened getMicrosecondPosition() Obtains the current position in the audio data, in microseconds.
public boolean	Returns: `true` if the line is actively capturing or rendering sound, otherwise `false` isActive() Indicates whether the line is engaging in active I/O (such as playback or capture).
public boolean	Returns: `true` if the line is running, otherwise `false` isRunning() Indicates whether the line is running.
public void	start() Allows a line to engage in data I/O.
public void	stop() Stops the line.

Inherited from javax.sound.sampled.Line:: addLineListener close getControl getControls getLineInfo isControlSupported isOpen open removeLineListener

Method Detail

available back to summary

available	back to summary
public 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:int the amount of data available, in bytes

public 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:int: the amount of data available, in bytes

drain back to summary

drain	back to summary
public 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()`

public 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()

flush back to summary

flush	back to summary
public 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()`, `drain()`

public 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(), drain()

getBufferSize	back to summary
public 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:int the size of the buffer, in bytes

getBufferSize

back to summary

public 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:int: the size of the buffer, in bytes

getFormat back to summary

getFormat	back to summary
public 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)`) will override the default format. Returns:AudioFormat current audio data format See Also `AudioFormat`

public 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)) will override the default format.

Returns:AudioFormat: current audio data format
See Also: AudioFormat

getFramePosition back to summary

getFramePosition	back to summary
public 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:int the number of frames already processed since the line was opened See Also `getLongFramePosition()`

public 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:int: the number of frames already processed since the line was opened
See Also: getLongFramePosition()

getLevel back to summary

getLevel	back to summary
public 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:float the current amplitude of the signal in this line, or `AudioSystem#NOT_SPECIFIED`

public 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:float: the current amplitude of the signal in this line, or AudioSystem#NOT_SPECIFIED

getLongFramePosition	back to summary
public 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:long the number of frames already processed since the line was opened Since 1.5

getLongFramePosition

back to summary

public 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:long: the number of frames already processed since the line was opened
Since: 1.5

getMicrosecondPosition	back to summary
public 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:long the number of microseconds of data processed since the line was opened

getMicrosecondPosition

back to summary

public 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:long: the number of microseconds of data processed since the line was opened

isActive back to summary

isActive	back to summary
public 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` event to its listeners. Similarly, when an active line becomes inactive, it sends a `STOP` event. Returns:boolean `true` if the line is actively capturing or rendering sound, otherwise `false` See Also `isOpen`, `addLineListener`, `removeLineListener`, `LineEvent`, `LineListener`

public 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 event to its listeners. Similarly, when an active line becomes inactive, it sends a STOP event.

Returns:boolean: true if the line is actively capturing or rendering sound, otherwise false
See Also: isOpen, addLineListener, removeLineListener, LineEvent, LineListener

isRunning back to summary

isRunning	back to summary
public 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:boolean `true` if the line is running, otherwise `false` See Also `start()`, `stop()`

public 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:boolean: true if the line is running, otherwise false
See Also: start(), stop()

start back to summary

start	back to summary
public 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` event is generated. See Also `stop()`, `isRunning()`, `LineEvent`

public 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 event is generated.

See Also: stop(), isRunning(), LineEvent

stop back to summary

stop	back to summary
public 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` event is generated. See Also `start()`, `isRunning()`, `flush()`, `LineEvent`

public 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 event is generated.

See Also: start(), isRunning(), flush(), LineEvent

javax.sound.sampled back to summary

public Class DataLine.Info

Class Inheritance

extends Info

java.lang.Object
javax.sound.sampled.Line.Info
javax.sound.sampled.DataLine.Info

Known Direct Subclasses

com.sun.media.sound.DirectAudioDevice.DirectDLI

Besides the class information inherited from its superclass, DataLine.Info provides additional information specific to data lines. This information includes:

the audio formats supported by the data line
the minimum and maximum sizes of its internal buffer

Because a Line.Info knows the class of the line its describes, a DataLine.Info object can describe DataLine subinterfaces such as SourceDataLine, TargetDataLine, and Clip. You can query a mixer for lines of any of these types, passing an appropriate instance of DataLine.Info as the argument to a method such as Mixer#getLine(Line.Info).

Author: Kara Kytle
Since: 1.3
See Also: Line.Info

Field Summary

Modifier and Type	Field and Description
private final AudioFormat[]	formats The set of supported formats.
private final int	maxBufferSize Maximum buffer size supported by the data line, in bytes.
private final int	minBufferSize Minimum buffer size supported by the data line, in bytes.

Constructor Summary

Access	Constructor and Description
public	Info(Class<?> the class of the data line described by the info object lineClass, AudioFormat[] set of formats supported formats, int minimum buffer size supported by the data line, in bytes minBufferSize, int maximum buffer size supported by the data line, in bytes 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.
public	Info(Class<?> the class of the data line described by the info object lineClass, AudioFormat desired format format, int desired buffer size, in bytes bufferSize) Constructs a data line's info object from the specified information, which includes a single audio format and a desired buffer size.
public	Info(Class<?> the class of the data line described by the info object lineClass, AudioFormat desired format format) Constructs a data line's info object from the specified information, which includes a single audio format.

Method Summary

Modifier and Type	Method and Description
public AudioFormat[]	Returns: a set of supported audio formats getFormats() Obtains a set of audio formats supported by the data line.
public int	Returns: maximum buffer size in bytes, or `AudioSystem.NOT_SPECIFIED` getMaxBufferSize() Obtains the maximum buffer size supported by the data line.
public int	Returns: minimum buffer size in bytes, or `AudioSystem.NOT_SPECIFIED` getMinBufferSize() Obtains the minimum buffer size supported by the data line.
public boolean	Returns: `true` if the format is supported, otherwise `false` isFormatSupported(AudioFormat the audio format for which support is queried format) Indicates whether this data line supports a particular audio format.
public boolean	Returns: `true` if this object matches the one specified, otherwise `false` matches(Line.Info the info object which is being compared to this one info) Overrides javax.sound.sampled.Line.Info.matches. Determines whether the specified info object matches this one.
public String	Returns: a string representation of the info object toString() Overrides javax.sound.sampled.Line.Info.toString. Returns a string representation of the info object.

Inherited from javax.sound.sampled.Line.Info:: getLineClass

Field Detail

formats	back to summary
private final AudioFormat[] formats The set of supported formats.

maxBufferSize	back to summary
private final int maxBufferSize Maximum buffer size supported by the data line, in bytes.

minBufferSize	back to summary
private final int minBufferSize Minimum buffer size supported by the data line, in bytes.

Constructor Detail

Info	back to summary
public Info(Class<?> lineClass, AudioFormat[] formats, int minBufferSize, 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. Parameters lineClass:Class<?> the class of the data line described by the info object formats:AudioFormat[] set of formats supported minBufferSize:int minimum buffer size supported by the data line, in bytes maxBufferSize:int maximum buffer size supported by the data line, in bytes

Info

back to summary

public Info(Class<?> lineClass, AudioFormat[] formats, int minBufferSize, 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.

Parameters

lineClass:Class<?>: the class of the data line described by the info object
formats:AudioFormat[]: set of formats supported
minBufferSize:int: minimum buffer size supported by the data line, in bytes
maxBufferSize:int: maximum buffer size supported by the data line, in bytes

Info	back to summary
public Info(Class<?> lineClass, AudioFormat format, int bufferSize) 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. Parameters lineClass:Class<?> the class of the data line described by the info object format:AudioFormat desired format bufferSize:int desired buffer size, in bytes

Info

back to summary

public Info(Class<?> lineClass, AudioFormat format, int bufferSize)

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.

Parameters

lineClass:Class<?>: the class of the data line described by the info object
format:AudioFormat: desired format
bufferSize:int: desired buffer size, in bytes

Info	back to summary
public Info(Class<?> lineClass, AudioFormat format) 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. Parameters lineClass:Class<?> the class of the data line described by the info object format:AudioFormat desired format

Info

back to summary

public Info(Class<?> lineClass, AudioFormat format)

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.

Parameters

lineClass:Class<?>: the class of the data line described by the info object
format:AudioFormat: desired format

Method Detail

getFormats back to summary

getFormats	back to summary
public AudioFormat[] getFormats() Obtains a set of audio formats supported by the data line. Note that `isFormatSupported(AudioFormat)` might return `true` for certain additional formats that are missing from the set returned by `getFormats()`. The reverse is not the case: `isFormatSupported(AudioFormat)` is guaranteed to return `true` for all formats returned by `getFormats()`. Some fields in the `AudioFormat` instances can be set to `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 `AudioFormat` instances returned by this method to `NOT_SPECIFIED`. Returns:AudioFormat[] a set of supported audio formats See Also `isFormatSupported(AudioFormat)`

public AudioFormat[] getFormats()

Obtains a set of audio formats supported by the data line. Note that isFormatSupported(AudioFormat) might return true for certain additional formats that are missing from the set returned by getFormats(). The reverse is not the case: isFormatSupported(AudioFormat) is guaranteed to return true for all formats returned by getFormats().

Some fields in the AudioFormat instances can be set to 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 AudioFormat instances returned by this method to NOT_SPECIFIED.

Returns:AudioFormat[]: a set of supported audio formats
See Also: isFormatSupported(AudioFormat)

getMaxBufferSize back to summary

getMaxBufferSize	back to summary
public int getMaxBufferSize() Obtains the maximum buffer size supported by the data line. Returns:int maximum buffer size in bytes, or `AudioSystem.NOT_SPECIFIED`

public int getMaxBufferSize()

Obtains the maximum buffer size supported by the data line.

Returns:int: maximum buffer size in bytes, or AudioSystem.NOT_SPECIFIED

getMinBufferSize back to summary

getMinBufferSize	back to summary
public int getMinBufferSize() Obtains the minimum buffer size supported by the data line. Returns:int minimum buffer size in bytes, or `AudioSystem.NOT_SPECIFIED`

public int getMinBufferSize()

Obtains the minimum buffer size supported by the data line.

Returns:int: minimum buffer size in bytes, or AudioSystem.NOT_SPECIFIED

isFormatSupported back to summary

isFormatSupported	back to summary
public boolean isFormatSupported(AudioFormat format) Indicates whether this data line supports a particular audio format. The default implementation of this method simply returns `true` if the specified format matches any of the supported formats. Parameters format:AudioFormat the audio format for which support is queried Returns:boolean `true` if the format is supported, otherwise `false` See Also `getFormats`, `AudioFormat#matches`

public boolean isFormatSupported(AudioFormat format)

Indicates whether this data line supports a particular audio format. The default implementation of this method simply returns true if the specified format matches any of the supported formats.

Parameters

format:AudioFormat: the audio format for which support is queried

Returns:boolean

true if the format is supported, otherwise false

See Also

getFormats, AudioFormat#matches

matches back to summary

matches	back to summary
public boolean matches(Line.Info info) Overrides javax.sound.sampled.Line.Info.matches. 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. Parameters info:Line.Info the info object which is being compared to this one Returns:boolean `true` if this object matches the one specified, otherwise `false` Annotations @Override

public boolean matches(Line.Info info)

Overrides javax.sound.sampled.Line.Info.matches.

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.

Parameters

info:Line.Info: the info object which is being compared to this one

Returns:boolean

true if this object matches the one specified, otherwise false

Annotations

@Override

toString	back to summary
public String toString() Overrides javax.sound.sampled.Line.Info.toString. Returns a string representation of the info object. Returns:String a string representation of the info object Annotations @Override

toString

back to summary

public String toString()

Overrides javax.sound.sampled.Line.Info.toString.

Returns a string representation of the info object.

Returns:String

a string representation of the info object

Annotations