public class

SoftMixingSourceDataLine

extends SoftMixingDataLine
implements SourceDataLine
java.lang.Object
   ↳ com.sun.media.sound.SoftMixingDataLine
     ↳ com.sun.media.sound.SoftMixingSourceDataLine

Class Overview

SourceDataLine implemention for the SoftMixingMixer.

Summary

[Expand]
Inherited Fields
From class com.sun.media.sound.SoftMixingDataLine
Protected Constructors
SoftMixingSourceDataLine(SoftMixingMixer mixer, DataLine.Info info)
Public Methods
int available()
Obtains the number of bytes of data currently available to the application for processing in the data line's internal buffer.
void close()
Closes the line, indicating that any system resources in use by the line can be released.
void drain()
Drains queued data from the line by continuing data I/O until the data line's internal buffer has been emptied.
void flush()
Flushes queued data from the line.
int getBufferSize()
Obtains the maximum number of bytes of data that will fit in the data line's internal buffer.
AudioFormat getFormat()
Obtains the current format (encoding, sample rate, number of channels, etc.) of the data line's audio data.
int getFramePosition()
Obtains the current position in the audio data, in sample frames.
float getLevel()
Obtains the current volume level for the line.
long getLongFramePosition()
Obtains the current position in the audio data, in sample frames.
long getMicrosecondPosition()
Obtains the current position in the audio data, in microseconds.
boolean isActive()
Indicates whether the line is engaging in active I/O (such as playback or capture).
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.
boolean isRunning()
Indicates whether the line is running.
void open()
Opens the line, indicating that it should acquire any required system resources and become operational.
void open(AudioFormat format)
Opens the line with the specified format, causing the line to acquire any required system resources and become operational.
void open(AudioFormat format, int bufferSize)
Opens the line with the specified format and suggested buffer size, causing the line to acquire any required system resources and become operational.
void start()
Allows a line to engage in data I/O.
void stop()
Stops the line.
int write(byte[] b, int off, int len)
Writes audio data to the mixer via this source data line.
Protected Methods
void processAudioLogic(SoftAudioBuffer[] buffers)
void processControlLogic()
[Expand]
Inherited Methods
From class com.sun.media.sound.SoftMixingDataLine
From class java.lang.Object
From interface javax.sound.sampled.DataLine
From interface javax.sound.sampled.Line
From interface javax.sound.sampled.SourceDataLine

Protected Constructors

protected SoftMixingSourceDataLine (SoftMixingMixer mixer, DataLine.Info info)

Public 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. 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

public void 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.

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.

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.)

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
  • the size of the buffer in bytes

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. open(AudioFormat)) will override the default format.

Returns
  • current audio data format

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
  • the number of frames already processed since the line was opened

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
  • the current amplitude of the signal in this line, or NOT_SPECIFIED

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
  • the number of frames already processed since the line was opened

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

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
  • true if the line is actively capturing or rendering sound, otherwise false

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
  • true if the line is open, otherwise false

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
  • true if the line is running, otherwise false

public void open ()

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.

public void open (AudioFormat format)

Opens the line with the specified format, causing the line to acquire any required system resources and become operational.

The implementation chooses a buffer size, which is measured in bytes but which encompasses an integral number of sample frames. The buffer size that the system has chosen may be queried by subsequently calling getBufferSize().

If this operation succeeds, the line is marked as open, and an OPEN event is dispatched to the line's listeners.

Invoking this method on a line which is already open is illegal and may result in an IllegalStateException.

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

Parameters
format the desired audio format

public void open (AudioFormat format, int bufferSize)

Opens the line with the specified format and suggested buffer size, causing the line to acquire any required system resources and become operational.

The buffer size is specified in bytes, but must represent an integral number of sample frames. Invoking this method with a requested buffer size that does not meet this requirement may result in an IllegalArgumentException. The actual buffer size for the open line may differ from the requested buffer size. The value actually set may be queried by subsequently calling getBufferSize().

If this operation succeeds, the line is marked as open, and an OPEN event is dispatched to the line's listeners.

Invoking this method on a line which is already open is illegal and may result in an IllegalStateException.

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

Parameters
format the desired audio format
bufferSize the desired buffer size

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.

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.

public int write (byte[] b, int off, int len)

Writes audio data to the mixer via this source data line. The requested number of bytes of data are read from the specified array, starting at the given offset into the array, and written to the data line's buffer. If the caller attempts to write more data than can currently be written (see available), this method blocks until the requested amount of data has been written. This applies even if the requested amount of data to write is greater than the data line's buffer size. However, if the data line is closed, stopped, or flushed before the requested amount has been written, the method no longer blocks, but returns the number of bytes written thus far.

The number of bytes that can be written without blocking can be ascertained using the available method of the DataLine interface. (While it is guaranteed that this number of bytes can be written without blocking, there is no guarantee that attempts to write additional data will block.)

The number of bytes to write must represent an integral number of sample frames, such that:

[ bytes written ] % [frame size in bytes ] == 0

The return value will always meet this requirement. A request to write a number of bytes representing a non-integral number of sample frames cannot be fulfilled and may result in an IllegalArgumentException.

Parameters
b a byte array containing data to be written to the data line
off the offset from the beginning of the array, in bytes
len the length, in bytes, of the valid data in the array (in other words, the requested amount of data to write, in bytes)
Returns
  • the number of bytes actually written

Protected Methods

protected void processAudioLogic (SoftAudioBuffer[] buffers)

protected void processControlLogic ()