net.java.sip.communicator.impl.neomedia.conference
Class AudioMixer

java.lang.Object
  net.java.sip.communicator.impl.neomedia.conference.AudioMixer

public class AudioMixer
extends Object

Represents an audio mixer which manages the mixing of multiple audio streams i.e. it is able to output a single audio stream which contains the audio of multiple input audio streams.

The input audio streams are provided to the AudioMixer through addInputDataSource(DataSource) in the form of input DataSources giving access to one or more input SourceStreams.

The output audio stream representing the mix of the multiple input audio streams is provided by the AudioMixer in the form of a AudioMixingPushBufferDataSource giving access to a AudioMixingPushBufferStream. Such an output is obtained through createOutputDataSource(). The AudioMixer is able to provide multiple output audio streams at one and the same time, though, each of them containing the mix of a subset of the input audio streams.

Author:

Lubomir Marinov

Field Summary

protected javax.media.protocol.CaptureDevice

captureDevice The CaptureDevice capabilities provided by the AudioMixingPushBufferDataSources created by this AudioMixer.

Constructor Summary

AudioMixer(javax.media.protocol.CaptureDevice captureDevice)
Initializes a new AudioMixer instance.

Method Summary

void	addInputDataSource(javax.media.protocol.DataSource inputDataSource) Adds a new input DataSource to the collection of input DataSources from which this instance reads audio.
(package private) void	addInputDataSource(javax.media.protocol.DataSource inputDataSource, AudioMixingPushBufferDataSource outputDataSource) Adds a new input DataSource to the collection of input DataSources from which this instance reads audio.
(package private) void	connect() Notifies this AudioMixer that an output AudioMixingPushBufferDataSource reading from it has been connected.
protected void	connect(javax.media.protocol.DataSource dataSource, javax.media.protocol.DataSource inputDataSource) Connects to a specific DataSource which this AudioMixer will read audio from.
(package private) void	connected(InputDataSourceDesc inputDataSource) Notifies this AudioMixer that a specific input DataSource has finished its connecting procedure.
AudioMixingPushBufferDataSource	createOutputDataSource() Creates a new AudioMixingPushBufferDataSource which gives access to a single audio stream representing the mix of the audio streams input into this AudioMixer through its input DataSources.
(package private) void	disconnect() Notifies this AudioMixer that an output AudioMixingPushBufferDataSource reading from it has been disconnected.
(package private) javax.media.control.BufferControl	getBufferControl() Gets the BufferControl of this instance and, respectively, its AudioMixingPushBufferDataSources.
(package private) javax.media.CaptureDeviceInfo	getCaptureDeviceInfo() Gets the CaptureDeviceInfo of the CaptureDevice this AudioMixer provides through its output AudioMixingPushBufferDataSources.
(package private) String	getContentType() Gets the content type of the data output by this AudioMixer.
(package private) javax.media.Time	getDuration() Gets the duration of each one of the output streams produced by this AudioMixer.
(package private) javax.media.control.FormatControl[]	getFormatControls() Gets an array of FormatControls for the CaptureDevice this AudioMixer provides through its output AudioMixingPushBufferDataSources.
AudioMixingPushBufferDataSource	getLocalOutputDataSource() Gets the AudioMixingPushBufferDataSource containing the mix of all input DataSources excluding the CaptureDevice of this AudioMixer and is thus meant for playback on the local peer in a call.
(package private) AudioMixerPushBufferStream	getOutputStream() Gets the AudioMixerPushBufferStream, first creating it if it does not exist already, which reads data from the input DataSources of this AudioMixer and pushes it to output AudioMixingPushBufferStreams for audio mixing.
protected void	read(javax.media.protocol.PushBufferStream stream, javax.media.Buffer buffer, javax.media.protocol.DataSource dataSource) Reads media from a specific PushBufferStream which belongs to a specific DataSource into a specific output Buffer.
void	removeInputDataSources(DataSourceFilter dataSourceFilter) Removes DataSources accepted by a specific DataSourceFilter from the list of input DataSources of this AudioMixer from which it reads audio to be mixed.
(package private) void	start(AudioMixerPushBufferStream outputStream) Starts the input DataSources of this AudioMixer.
(package private) void	stop(AudioMixerPushBufferStream outputStream) Stops the input DataSources of this AudioMixer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

captureDevice

protected final javax.media.protocol.CaptureDevice captureDevice

The CaptureDevice capabilities provided by the AudioMixingPushBufferDataSources created by this AudioMixer. JMF's Manager.createMergingDataSource(DataSource[]) requires the interface implementation for audio if it is implemented for video and it is indeed the case for our use case of AudioMixingPushBufferDataSource.

Constructor Detail

AudioMixer

public AudioMixer(javax.media.protocol.CaptureDevice captureDevice)

Initializes a new AudioMixer instance. Because JMF's Manager.createMergingDataSource(DataSource[]) requires the implementation of CaptureDevice for audio if it is implemented for video and it is indeed the cause for our use case of AudioMixingPushBufferDataSource, the new AudioMixer instance provides specified CaptureDevice capabilities to the AudioMixingPushBufferDataSources it creates. The specified CaptureDevice is also added as the first input DataSource of the new instance.

Parameters:

captureDevice - the CaptureDevice capabilities to be provided to the AudioMixingPushBufferDataSources created by the new instance and its first input DataSource

Method Detail

addInputDataSource

public void addInputDataSource(javax.media.protocol.DataSource inputDataSource)

Adds a new input DataSource to the collection of input DataSources from which this instance reads audio. If the specified DataSource indeed provides audio, the respective contributions to the mix are always included.

Parameters:

inputDataSource - a new DataSource to input audio to this instance

addInputDataSource

void addInputDataSource(javax.media.protocol.DataSource inputDataSource,
                        AudioMixingPushBufferDataSource outputDataSource)

Adds a new input DataSource to the collection of input DataSources from which this instance reads audio. If the specified DataSource indeed provides audio, the respective contributions to the mix will be excluded from the mix output provided through a specific AudioMixingPushBufferDataSource.

Parameters:

inputDataSource - a new DataSource to input audio to this instance

outputDataSource - the AudioMixingPushBufferDataSource to not include the audio contributions of inputDataSource in the mix it outputs

connect

void connect()
       throws IOException

Notifies this AudioMixer that an output AudioMixingPushBufferDataSource reading from it has been connected. The first of the many AudioMixingPushBufferDataSources reading from this AudioMixer which gets connected causes it to connect to the input DataSources it manages.

Throws:

IOException - if input/output error occurred

connect

protected void connect(javax.media.protocol.DataSource dataSource,
                       javax.media.protocol.DataSource inputDataSource)
                throws IOException

Connects to a specific DataSource which this AudioMixer will read audio from. The specified DataSource is known to exist because of a specific DataSource added as an input to this instance i.e. it may be an actual input DataSource added to this instance or a DataSource transcoding an input DataSource added to this instance.

Parameters:

dataSource - the DataSource to connect to

inputDataSource - the DataSource which is the cause for dataSource to exist in this AudioMixer

Throws:

IOException - if anything wrong happens while connecting to dataSource

connected

void connected(InputDataSourceDesc inputDataSource)
         throws IOException

Notifies this AudioMixer that a specific input DataSource has finished its connecting procedure. Primarily meant for input DataSource which have their connecting executed in a separate thread as are, for example, input DataSources which are being transcoded.

Parameters:

inputDataSource - the InputDataSourceDesc of the input DataSource which has finished its connecting procedure

Throws:

IOException - if anything wrong happens while including inputDataSource into the mix

createOutputDataSource

public AudioMixingPushBufferDataSource createOutputDataSource()

Creates a new AudioMixingPushBufferDataSource which gives access to a single audio stream representing the mix of the audio streams input into this AudioMixer through its input DataSources. The returned AudioMixingPushBufferDataSource can also be used to include new input DataSources in this AudioMixer but have their contributions not included in the mix available through the returned AudioMixingPushBufferDataSource.

Returns:

a new AudioMixingPushBufferDataSource which gives access to a single audio stream representing the mix of the audio streams input into this AudioMixer through its input DataSources

disconnect

void disconnect()

Notifies this AudioMixer that an output AudioMixingPushBufferDataSource reading from it has been disconnected. The last of the many AudioMixingPushBufferDataSources reading from this AudioMixer which gets disconnected causes it to disconnect from the input DataSources it manages.

getBufferControl

javax.media.control.BufferControl getBufferControl()

Gets the BufferControl of this instance and, respectively, its AudioMixingPushBufferDataSources.

Returns:

the BufferControl of this instance and, respectively, its AudioMixingPushBufferDataSources if such a control is available for the CaptureDevice of this instance; otherwise, null

getCaptureDeviceInfo

javax.media.CaptureDeviceInfo getCaptureDeviceInfo()

Gets the CaptureDeviceInfo of the CaptureDevice this AudioMixer provides through its output AudioMixingPushBufferDataSources.

Returns:

the CaptureDeviceInfo of the CaptureDevice this AudioMixer provides through its output AudioMixingPushBufferDataSources

getContentType

String getContentType()

Gets the content type of the data output by this AudioMixer.

Returns:

the content type of the data output by this AudioMixer

getDuration

javax.media.Time getDuration()

Gets the duration of each one of the output streams produced by this AudioMixer.

Returns:

the duration of each one of the output streams produced by this AudioMixer

getFormatControls

javax.media.control.FormatControl[] getFormatControls()

Gets an array of FormatControls for the CaptureDevice this AudioMixer provides through its output AudioMixingPushBufferDataSources.

Returns:

an array of FormatControls for the CaptureDevice this AudioMixer provides through its output AudioMixingPushBufferDataSources

getLocalOutputDataSource

public AudioMixingPushBufferDataSource getLocalOutputDataSource()

Gets the AudioMixingPushBufferDataSource containing the mix of all input DataSources excluding the CaptureDevice of this AudioMixer and is thus meant for playback on the local peer in a call.

Returns:

the AudioMixingPushBufferDataSource containing the mix of all input DataSources excluding the CaptureDevice of this AudioMixer and is thus meant for playback on the local peer in a call

getOutputStream

AudioMixerPushBufferStream getOutputStream()

Gets the AudioMixerPushBufferStream, first creating it if it does not exist already, which reads data from the input DataSources of this AudioMixer and pushes it to output AudioMixingPushBufferStreams for audio mixing.

Returns:

the AudioMixerPushBufferStream which reads data from the input DataSources of this AudioMixer and pushes it to output AudioMixingPushBufferStreams for audio mixing

read

protected void read(javax.media.protocol.PushBufferStream stream,
                    javax.media.Buffer buffer,
                    javax.media.protocol.DataSource dataSource)
             throws IOException

Reads media from a specific PushBufferStream which belongs to a specific DataSource into a specific output Buffer. Allows extenders to tap into the reading and monitor and customize it.

Parameters:

stream - the PushBufferStream to read media from and known to belong to the specified DataSOurce

buffer - the output Buffer in which the media read from the specified stream is to be written so that it gets returned to the caller

dataSource - the DataSource from which stream originated

Throws:

IOException - if anything wrong happens while reading from the specified stream

removeInputDataSources

public void removeInputDataSources(DataSourceFilter dataSourceFilter)

Removes DataSources accepted by a specific DataSourceFilter from the list of input DataSources of this AudioMixer from which it reads audio to be mixed.

Parameters:

dataSourceFilter - the DataSourceFilter which selects the DataSources to be removed from the list of input DataSources of this AudioMixer from which it reads audio to be mixed

start

void start(AudioMixerPushBufferStream outputStream)
     throws IOException

Starts the input DataSources of this AudioMixer.

Parameters:

outputStream - the AudioMixerPushBufferStream which requests this AudioMixer to start. If outputStream is the current one and only AudioMixerPushBufferStream of this AudioMixer, this AudioMixer starts if it hasn't started yet. Otherwise, the request is ignored.

Throws:

IOException - if any of the input DataSources of this AudioMixer throws such an exception while attempting to start it

stop

void stop(AudioMixerPushBufferStream outputStream)
    throws IOException

Stops the input DataSources of this AudioMixer.

Parameters:

outputStream - the AudioMixerPushBufferStream which requests this AudioMixer to stop. If outputStream is the current one and only AudioMixerPushBufferStream of this AudioMixer, this AudioMixer stops. Otherwise, the request is ignored.

Throws:

IOException - if any of the input DataSources of this AudioMixer throws such an exception while attempting to stop it