The Line interface represents a mono or multi-channel audio feed. A line is an element of the digital audio "pipeline," such as a mixer, an input or output port, or a data path into or out of a mixer.

A line can have controls, such as gain, pan, and reverb. The controls themselves are instances of classes that extend the base Control class. The Line interface provides two accessor methods for obtaining the line's controls: getControls returns the entire set, and getControl returns a single control of specified type.

Lines exist in various states at different times. When a line opens, it reserves system resources for itself, and when it closes, these resources are freed for other objects or applications. The isOpen() method lets you discover whether a line is open or closed. An open line need not be processing data, however. Such processing is typically initiated by subinterface methods such as SourceDataLine.write and TargetDataLine.read.

You can register an object to receive notifications whenever the line's state changes. The object must implement the LineListener interface, which consists of the single method update. This method will be invoked when a line opens and closes (and, if it's a DataLine , when it starts and stops).

An object can be registered to listen to multiple lines. The event it receives in its update method will specify which line created the event, what type of event it was (OPEN, CLOSE, START, or STOP), and how many sample frames the line had processed at the time the event occurred.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	Line.Info A `Line.Info` object contains information about a line.

Method Summary

Modifier and Type	Method and Description
public void	addLineListener(LineListener the object to add as a listener to this line listener) Adds a listener to this line.
public void	close() Redeclares java.lang.AutoCloseable.close. Closes the line, indicating that any system resources in use by the line can be released.
public Control	Returns: a control of the specified type getControl(Control.Type the type of the requested control control) Obtains a control of the specified type, if there is any.
public Control[]	Returns: the array of controls getControls() Obtains the set of controls associated with this line.
public Line.Info	Returns: description of the line getLineInfo() Obtains the `Line.Info` object describing this line.
public boolean	Returns: `true` if at least one control of the specified type is supported, otherwise `false` isControlSupported(Control.Type the type of the control for which support is queried control) Indicates whether the line supports a control of the specified type.
public boolean	Returns: `true` if the line is open, otherwise `false` isOpen() Indicates whether the line is open, meaning that it has reserved system resources and is operational, although it might not currently be playing or capturing sound.
public void	open() Opens the line, indicating that it should acquire any required system resources and become operational.
public void	removeLineListener(LineListener listener to remove listener) Removes the specified listener from this line's list of listeners.

Method Detail

addLineListener back to summary

addLineListener	back to summary
public void addLineListener(LineListener listener) Adds a listener to this line. Whenever the line's status changes, the listener's `update()` method is called with a `LineEvent` object that describes the change. Parameters listener:LineListener the object to add as a listener to this line See Also `removeLineListener`, `LineListener#update`, `LineEvent`

public void addLineListener(LineListener listener)

Adds a listener to this line. Whenever the line's status changes, the listener's update() method is called with a LineEvent object that describes the change.

Parameters

listener:LineListener: the object to add as a listener to this line

close back to summary

close	back to summary
public void close() Redeclares java.lang.AutoCloseable.close. Closes the line, indicating that any system resources in use by the line can be released. If this operation succeeds, the line is marked closed and a `CLOSE` event is dispatched to the line's listeners. Annotations @Override See Also `open`, `isOpen`, `LineEvent`

public void close()

Redeclares java.lang.AutoCloseable.close.

Closes the line, indicating that any system resources in use by the line can be released. If this operation succeeds, the line is marked closed and a CLOSE event is dispatched to the line's listeners.

Annotations

@Override

See Also

open, isOpen, LineEvent

getControl back to summary

getControl	back to summary
public Control getControl(Control.Type control) Obtains a control of the specified type, if there is any. Some controls may only be available when the line is open. Parameters control:Control.Type the type of the requested control Returns:Control a control of the specified type Exceptions IllegalArgumentException: if a control of the specified type is not supported See Also `getControls`, `isControlSupported(Control.Type control)`

public Control getControl(Control.Type control)

Obtains a control of the specified type, if there is any. Some controls may only be available when the line is open.

Parameters

control:Control.Type: the type of the requested control

Returns:Control

a control of the specified type

Exceptions

IllegalArgumentException:: if a control of the specified type is not supported

getControls back to summary

getControls	back to summary
public Control[] getControls() Obtains the set of controls associated with this line. Some controls may only be available when the line is open. If there are no controls, this method returns an array of length 0. Returns:Control[] the array of controls See Also `getControl`

public Control[] getControls()

Obtains the set of controls associated with this line. Some controls may only be available when the line is open. If there are no controls, this method returns an array of length 0.

Returns:Control[]: the array of controls
See Also: getControl

getLineInfo back to summary

getLineInfo	back to summary
public Line.Info getLineInfo() Obtains the `Line.Info` object describing this line. Returns:Line.Info description of the line

public Line.Info getLineInfo()

Obtains the Line.Info object describing this line.

Returns:Line.Info: description of the line

isControlSupported back to summary

isControlSupported	back to summary
public boolean isControlSupported(Control.Type control) Indicates whether the line supports a control of the specified type. Some controls may only be available when the line is open. Parameters control:Control.Type the type of the control for which support is queried Returns:boolean `true` if at least one control of the specified type is supported, otherwise `false`

public boolean isControlSupported(Control.Type control)

Indicates whether the line supports a control of the specified type. Some controls may only be available when the line is open.

Parameters

control:Control.Type: the type of the control for which support is queried

Returns:boolean

true if at least one control of the specified type is supported, otherwise false

isOpen back to summary

isOpen	back to summary
public boolean isOpen() Indicates whether the line is open, meaning that it has reserved system resources and is operational, although it might not currently be playing or capturing sound. Returns:boolean `true` if the line is open, otherwise `false` See Also `open()`, `close()`

public boolean isOpen()

Indicates whether the line is open, meaning that it has reserved system resources and is operational, although it might not currently be playing or capturing sound.

Returns:boolean: true if the line is open, otherwise false
See Also: open(), close()

open back to summary

open	back to summary
public void open() throws LineUnavailableException Opens the line, indicating that it should acquire any required system resources and become operational. If this operation succeeds, the line is marked as open, and an `OPEN` event is dispatched to the line's listeners. Note that some lines, once closed, cannot be reopened. Attempts to reopen such a line will always result in an `LineUnavailableException`. Some types of lines have configurable properties that may affect resource allocation. For example, a `DataLine` must be opened with a particular format and buffer size. Such lines should provide a mechanism for configuring these properties, such as an additional `open` method or methods which allow an application to specify the desired settings. This method takes no arguments, and opens the line with the current settings. For `SourceDataLine` and `TargetDataLine` objects, this means that the line is opened with default settings. For a `Clip`, however, the buffer size is determined when data is loaded. Since this method does not allow the application to specify any data to load, an `IllegalArgumentException` is thrown. Therefore, you should instead use one of the `open` methods provided in the `Clip` interface to load data into the `Clip`. For `DataLine`'s, if the `DataLine.Info` object which was used to retrieve the line, specifies at least one fully qualified audio format, the last one will be used as the default format. Exceptions LineUnavailableException: if the line cannot be opened due to resource restrictions IllegalArgumentException: if this method is called on a Clip instance See Also `close`, `isOpen`, `LineEvent`, `DataLine`, `Clip#open(AudioFormat, byte[], int, int)`, `Clip#open(AudioInputStream)`

public void open() throws LineUnavailableException

Opens the line, indicating that it should acquire any required system resources and become operational. If this operation succeeds, the line is marked as open, and an OPEN event is dispatched to the line's listeners.

Note that some lines, once closed, cannot be reopened. Attempts to reopen such a line will always result in an LineUnavailableException.

Some types of lines have configurable properties that may affect resource allocation. For example, a DataLine must be opened with a particular format and buffer size. Such lines should provide a mechanism for configuring these properties, such as an additional open method or methods which allow an application to specify the desired settings.

This method takes no arguments, and opens the line with the current settings. For SourceDataLine and TargetDataLine objects, this means that the line is opened with default settings. For a Clip, however, the buffer size is determined when data is loaded. Since this method does not allow the application to specify any data to load, an IllegalArgumentException is thrown. Therefore, you should instead use one of the open methods provided in the Clip interface to load data into the Clip.

For DataLine's, if the DataLine.Info object which was used to retrieve the line, specifies at least one fully qualified audio format, the last one will be used as the default format.

Exceptions

LineUnavailableException:: if the line cannot be opened due to resource restrictions
IllegalArgumentException:: if this method is called on a Clip instance

removeLineListener back to summary

removeLineListener	back to summary
public void removeLineListener(LineListener listener) Removes the specified listener from this line's list of listeners. Parameters listener:LineListener listener to remove See Also `addLineListener`

public void removeLineListener(LineListener listener)

Removes the specified listener from this line's list of listeners.

Parameters

listener:LineListener: listener to remove

See Also

addLineListener

javax.sound.sampled back to summary

public Class Line.Info

Class Inheritance

extends Object

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

Known Direct Subclasses

javax.sound.sampled.Port.Info, javax.sound.sampled.DataLine.Info

A Line.Info object contains information about a line. The only information provided by Line.Info itself is the Java class of the line. A subclass of Line.Info adds other kinds of information about the line. This additional information depends on which Line subinterface is implemented by the kind of line that the Line.Info subclass describes.

A Line.Info can be retrieved using various methods of the Line, Mixer, and AudioSystem interfaces. Other such methods let you pass a Line.Info as an argument, to learn whether lines matching the specified configuration are available and to obtain them.

Author: Kara Kytle
Since: 1.3
See Also: Line#getLineInfo(), Mixer#getSourceLineInfo(), Mixer#getTargetLineInfo(), Mixer#getLine(Line.Info), Mixer#getSourceLineInfo(Line.Info), Mixer#getTargetLineInfo(Line.Info), Mixer#isLineSupported(Line.Info), AudioSystem#getLine(Line.Info), AudioSystem#getSourceLineInfo(Line.Info), AudioSystem#getTargetLineInfo(Line.Info), AudioSystem#isLineSupported(Line.Info)

Field Summary

Modifier and Type	Field and Description
private final Class<?>	lineClass The class of the line described by the info object.

Constructor Summary

Access	Constructor and Description
public	Info(Class<?> the class of the line that the new `Line.Info` object describes lineClass) Constructs an info object that describes a line of the specified class.

Method Summary

Modifier and Type	Method and Description
public Class<?>	Returns: the described line's class getLineClass() Obtains the class of the line that this `Line.Info` object describes.
public boolean	Returns: `true` if the specified object matches this one, `false` otherwise matches(Line.Info the info object which is being compared to this one info) Indicates whether the specified info object matches this one.
public String	Returns: a string representation of the info object toString() Overrides java.lang.Object.toString. Returns a string representation of the info object.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

lineClass	back to summary
private final Class<?> lineClass The class of the line described by the info object.

Constructor Detail

Info back to summary

Info	back to summary
public Info(Class<?> lineClass) Constructs an info object that describes a line of the specified class. This constructor is typically used by an application to describe a desired line. Parameters lineClass:Class<?> the class of the line that the new `Line.Info` object describes

public Info(Class<?> lineClass)

Constructs an info object that describes a line of the specified class. This constructor is typically used by an application to describe a desired line.

Parameters

lineClass:Class<?>: the class of the line that the new Line.Info object describes

Method Detail

getLineClass back to summary

getLineClass	back to summary
public Class<?> getLineClass() Obtains the class of the line that this `Line.Info` object describes. Returns:Class<?> the described line's class

public Class<?> getLineClass()

Obtains the class of the line that this Line.Info object describes.

Returns:Class<?>: the described line's class

matches back to summary

matches	back to summary
public boolean matches(Line.Info info) Indicates whether the specified info object matches this one. To match, the specified object must be identical to or a special case of this one. The specified info object must be either an instance of the same class as this one, or an instance of a sub-type of this one. In addition, the attributes of the specified object must be compatible with the capabilities of this one. Specifically, the routing configuration for the specified info object must be compatible with that of this one. Subclasses may add other criteria to determine whether the two objects match. Parameters info:Line.Info the info object which is being compared to this one Returns:boolean `true` if the specified object matches this one, `false` otherwise

public boolean matches(Line.Info info)

Indicates whether the specified info object matches this one. To match, the specified object must be identical to or a special case of this one. The specified info object must be either an instance of the same class as this one, or an instance of a sub-type of this one. In addition, the attributes of the specified object must be compatible with the capabilities of this one. Specifically, the routing configuration for the specified info object must be compatible with that of this one. Subclasses may add other criteria to determine whether the two objects match.

Parameters

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

Returns:boolean

true if the specified object matches this one, false otherwise

toString	back to summary
public String toString() Overrides java.lang.Object.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 java.lang.Object.toString.

Returns a string representation of the info object.

Returns:String

a string representation of the info object

Annotations