net.java.sip.communicator.impl.neomedia.device
Class MediaDeviceSession

java.lang.Object
  net.java.sip.communicator.util.event.PropertyChangeNotifier
      net.java.sip.communicator.impl.neomedia.device.MediaDeviceSession

Direct Known Subclasses:

AudioMediaDeviceSession, VideoMediaDeviceSession

public class MediaDeviceSession
extends PropertyChangeNotifier

Represents the use of a specific MediaDevice by a MediaStream.

Author:

Lyubomir Marinov, Damian Minkov, Emil Ivov

Field Summary

static String	OUTPUT_DATA_SOURCE The name of the MediaDeviceSession instance property the value of which represents the output DataSource of the MediaDeviceSession instance which provides the captured (RTP) data to be sent by MediaStream to MediaStreamTarget.
protected boolean	outputsizeChanged Whether output size has changed after latest processor config.
static String	SSRC_LIST The name of the property that corresponds to the array of SSRC identifiers that we store in this MediaDeviceSession instance and that we update upon adding and removing ReceiveStream

Constructor Summary

protected

MediaDeviceSession(AbstractMediaDevice device) Initializes a new MediaDeviceSession instance which is to represent the use of a specific MediaDevice by a MediaStream.

Method Summary

void	addDTMF(DTMFInbandTone tone) Adds a new inband DTMF tone to send.
void	addPlaybackDataSource(javax.media.protocol.DataSource playbackDataSource) Adds a specific DataSource to the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance.
void	addReceiveStream(javax.media.rtp.ReceiveStream receiveStream) Adds a specific ReceiveStream to the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance.
protected void	addSSRC(long ssrc) Adds ssrc to the array of SSRC identifiers representing parties that this MediaDeviceSession is currently receiving streams from.
protected void	checkDevice(AbstractMediaDevice device) Asserts that a specific MediaDevice is acceptable to be set as the MediaDevice of this instance.
void	close() Releases the resources allocated by this instance in the course of its execution and prepares it to be garbage collected.
void	copyPlayback(MediaDeviceSession deviceSession) Copies the playback part of a specific MediaDeviceSession into this instance.
protected javax.media.protocol.DataSource	createCaptureDevice() Creates the DataSource that this instance is to read captured media from.
protected javax.media.Player	createPlayer(javax.media.protocol.DataSource dataSource) Creates a new Player for a specific DataSource so that it is played back on the MediaDevice represented by this instance.
protected javax.media.Processor	createProcessor() Initializes a new FMJ Processor which is to transcode captureDevice into the format of this instance.
protected javax.media.protocol.ContentDescriptor	createProcessorContentDescriptor(javax.media.Processor processor) Creates a ContentDescriptor to be set on a specific Processor of captured media to be sent to the remote peer.
protected void	disposePlayer(javax.media.Player player) Releases the resources allocated by a specific Player in the course of its execution and prepares it to be garbage collected.
javax.media.protocol.DataSource	getCaptureDevice() Gets the DataSource that this instance uses to read captured media from.
protected javax.media.protocol.DataSource	getConnectedCaptureDevice() Gets captureDevice in a connected state.
AbstractMediaDevice	getDevice() Gets the MediaDevice associated with this instance and the work of a MediaStream with which is represented by it.
MediaFormatImpl<? extends javax.media.Format>	getFormat() Gets the MediaFormat in which this instance captures media from its associated MediaDevice.
javax.media.protocol.DataSource	getOutputDataSource() Gets the output DataSource of this instance which provides the captured (RTP) data to be sent by MediaStream to MediaStreamTarget.
protected List<javax.media.Player>	getPlayers() Gets the Players rendering the ReceiveStreams of this instance on its associated MediaDevice.
javax.media.Format	getProcessorFormat() Gets the JMF Format in which this instance captures media.
List<javax.media.rtp.ReceiveStream>	getReceiveStreams() Gets a list of the ReceiveStreams being played back on the MediaDevice represented by this instance.
long[]	getRemoteSSRCList() Returns the list of SSRC identifiers that this device session is handling streams from.
MediaDirection	getStartedDirection() Gets the MediaDirection in which this instance has been started.
List<MediaFormat>	getSupportedFormats() Gets a list of the MediaFormats in which this instance is capable of capturing media from its associated MediaDevice.
boolean	isMute() Determines whether this MediaDeviceSession is set to output "silence" instead of the actual media fed from its CaptureDevice.
protected void	playbackDataSourceAdded(javax.media.protocol.DataSource playbackDataSource) Notifies this MediaDeviceSession that a DataSource has been added for playback on the represented MediaDevice.
protected void	playbackDataSourceRemoved(javax.media.protocol.DataSource playbackDataSource) Notifies this MediaDeviceSession that a DataSource has been removed from playback on the represented MediaDevice.
protected void	playerConfigureComplete(javax.media.Processor player) Notifies this instance that a specific Player of remote content has generated a ConfigureCompleteEvent.
protected void	playerControllerUpdate(javax.media.ControllerEvent event) Gets notified about ControllerEvents generated by a specific Player of remote content.
protected void	playerRealizeComplete(javax.media.Processor player) Notifies this instance that a specific Player of remote content has generated a RealizeCompleteEvent.
protected void	processorControllerUpdate(javax.media.ControllerEvent event) Gets notified about ControllerEvents generated by processor.
protected void	receiveStreamAdded(javax.media.rtp.ReceiveStream receiveStream) Notifies this instance that a specific ReceiveStream has been added to the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance.
protected void	receiveStreamRemoved(javax.media.rtp.ReceiveStream receiveStream) Notifies this instance that a specific ReceiveStream has been removed from the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance.
void	removePlaybackDataSource(javax.media.protocol.DataSource playbackDataSource) Removes a specific DataSource from the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance.
void	removeReceiveStream(javax.media.rtp.ReceiveStream receiveStream) Removes a specific ReceiveStream from the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance.
protected void	removeSSRC(long ssrc) Removes ssrc from the array of SSRC identifiers representing parties that this MediaDeviceSession is currently receiving streams from.
protected void	setCaptureDeviceFormat(javax.media.protocol.DataSource captureDevice, MediaFormatImpl<? extends javax.media.Format> mediaFormat)
void	setContentDescriptor(javax.media.protocol.ContentDescriptor contentDescriptor) Sets the ContentDescriptor which specifies the content type in which this MediaDeviceSession is to output the media captured by its MediaDevice.
void	setDisposePlayerOnClose(boolean disposePlayerOnClose) Sets the indicator which determines whether this instance is to dispose of its associated player upon closing.
void	setFormat(MediaFormat format) Sets the MediaFormat in which this MediaDeviceSession outputs the media captured by its MediaDevice.
void	setMute(boolean mute) Sets the indicator which determines whether this MediaDeviceSession is set to output "silence" instead of the actual media fed from its CaptureDevice.
protected void	setProcessorFormat(javax.media.Processor processor, MediaFormatImpl<? extends javax.media.Format> mediaFormat) Sets the MediaFormatImpl in which a specific Processor producing media to be streamed to the remote peer is to output.
protected javax.media.Format	setProcessorFormat(javax.media.control.TrackControl trackControl, MediaFormatImpl<? extends javax.media.Format> mediaFormat, javax.media.Format format) Sets the MediaFormatImpl of a specific TrackControl of the Processor which produces the media to be streamed by this MediaDeviceSession to the remote peer.
void	start(MediaDirection direction) Starts the processing of media in this instance in a specific direction.
protected void	startedDirectionChanged(MediaDirection oldValue, MediaDirection newValue) Notifies this instance that the value of its startedDirection property has changed from a specific oldValue to a specific newValue.
protected void	startProcessorInAccordWithDirection(javax.media.Processor processor) Starts a specific Processor if this MediaDeviceSession has been started and the specified Processor is not started.
void	stop(MediaDirection direction) Stops the processing of media in this instance in a specific direction.

Methods inherited from class net.java.sip.communicator.util.event.PropertyChangeNotifier

addPropertyChangeListener, firePropertyChange, getPropertyChangeSource, removePropertyChangeListener

Methods inherited from class java.lang.Object

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

Field Detail

OUTPUT_DATA_SOURCE

public static final String OUTPUT_DATA_SOURCE

The name of the MediaDeviceSession instance property the value of which represents the output DataSource of the MediaDeviceSession instance which provides the captured (RTP) data to be sent by MediaStream to MediaStreamTarget.

See Also:

Constant Field Values

SSRC_LIST

public static final String SSRC_LIST

The name of the property that corresponds to the array of SSRC identifiers that we store in this MediaDeviceSession instance and that we update upon adding and removing ReceiveStream

See Also:

Constant Field Values

outputsizeChanged

protected boolean outputsizeChanged

Whether output size has changed after latest processor config. Used for video streams.

Constructor Detail

MediaDeviceSession

protected MediaDeviceSession(AbstractMediaDevice device)

Initializes a new MediaDeviceSession instance which is to represent the use of a specific MediaDevice by a MediaStream.

Parameters:

device - the MediaDevice the use of which by a MediaStream is to be represented by the new instance

Method Detail

setDisposePlayerOnClose

public void setDisposePlayerOnClose(boolean disposePlayerOnClose)

Sets the indicator which determines whether this instance is to dispose of its associated player upon closing.

Parameters:

disposePlayerOnClose - true to have this instance dispose of its associated player upon closing; otherwise, false

addSSRC

protected void addSSRC(long ssrc)

Adds ssrc to the array of SSRC identifiers representing parties that this MediaDeviceSession is currently receiving streams from. We use this method mostly as a way of to caching SSRC identifiers during a conference call so that the streams that are sending CSRC lists could have them ready for use rather than have to construct them for every RTP packet.

Parameters:

ssrc - the new SSRC identifier that we'd like to add to the array of ssrc identifiers stored by this session.

checkDevice

protected void checkDevice(AbstractMediaDevice device)

Asserts that a specific MediaDevice is acceptable to be set as the MediaDevice of this instance. Allows extenders to override and customize the check.

Parameters:

device - the MediaDevice to be checked for suitability to become the MediaDevice of this instance

close

public void close()

Releases the resources allocated by this instance in the course of its execution and prepares it to be garbage collected.

createCaptureDevice

protected javax.media.protocol.DataSource createCaptureDevice()

Creates the DataSource that this instance is to read captured media from.

Returns:

the DataSource that this instance is to read captured media from

createPlayer

protected javax.media.Player createPlayer(javax.media.protocol.DataSource dataSource)

Creates a new Player for a specific DataSource so that it is played back on the MediaDevice represented by this instance.

Parameters:

dataSource - the DataSource to create a new Player for

Returns:

a new Player for the specified dataSource

createProcessor

protected javax.media.Processor createProcessor()

Initializes a new FMJ Processor which is to transcode captureDevice into the format of this instance.

Returns:

a new FMJ Processor which is to transcode captureDevice into the format of this instance

createProcessorContentDescriptor

protected javax.media.protocol.ContentDescriptor createProcessorContentDescriptor(javax.media.Processor processor)

Creates a ContentDescriptor to be set on a specific Processor of captured media to be sent to the remote peer. Allows extenders to override. The default implementation returns ContentDescriptor.RAW_RTP.

Parameters:

processor - the Processor of captured media to be sent to the remote peer which is to have its contentDescriptor set to the returned ContentDescriptor

Returns:

a ContentDescriptor to be set on the specified processor of captured media to be sent to the remote peer

disposePlayer

protected void disposePlayer(javax.media.Player player)

Releases the resources allocated by a specific Player in the course of its execution and prepares it to be garbage collected.

Parameters:

player - the Player to dispose of

getCaptureDevice

public javax.media.protocol.DataSource getCaptureDevice()

Gets the DataSource that this instance uses to read captured media from. If it does not exist yet, it is created.

Returns:

the DataSource that this instance uses to read captured media from

getConnectedCaptureDevice

protected javax.media.protocol.DataSource getConnectedCaptureDevice()

Gets captureDevice in a connected state. If this instance is not connected to captureDevice yet, first tries to connect to it. Returns null if this instance fails to create captureDevice or to connect to it.

Returns:

captureDevice in a connected state; null if this instance fails to create captureDevice or to connect to it

getDevice

public AbstractMediaDevice getDevice()

Gets the MediaDevice associated with this instance and the work of a MediaStream with which is represented by it.

Returns:

the MediaDevice associated with this instance and the work of a MediaStream with which is represented by it

getProcessorFormat

public javax.media.Format getProcessorFormat()

Gets the JMF Format in which this instance captures media.

Returns:

the JMF Format in which this instance captures media.

getFormat

public MediaFormatImpl<? extends javax.media.Format> getFormat()

Gets the MediaFormat in which this instance captures media from its associated MediaDevice.

Returns:

the MediaFormat in which this instance captures media from its associated MediaDevice

getOutputDataSource

public javax.media.protocol.DataSource getOutputDataSource()

Gets the output DataSource of this instance which provides the captured (RTP) data to be sent by MediaStream to MediaStreamTarget.

Returns:

the output DataSource of this instance which provides the captured (RTP) data to be sent by MediaStream to MediaStreamTarget

getPlayers

protected List<javax.media.Player> getPlayers()

Gets the Players rendering the ReceiveStreams of this instance on its associated MediaDevice.

Returns:

the Players rendering the ReceiveStreams of this instance on its associated MediaDevice

getReceiveStreams

public List<javax.media.rtp.ReceiveStream> getReceiveStreams()

Gets a list of the ReceiveStreams being played back on the MediaDevice represented by this instance.

Returns:

a list of ReceiveStreams being played back on the MediaDevice represented by this instance

getRemoteSSRCList

public long[] getRemoteSSRCList()

Returns the list of SSRC identifiers that this device session is handling streams from. In this case (i.e. the case of a device session handling a single remote party) we would rarely (if ever) have more than a single SSRC identifier returned. However, we would also be using the same method to query a device session operating over a mixer in which case we would have the SSRC IDs of all parties currently contributing to the mixing.

Returns:

a long[] array of SSRC identifiers that this device session is handling streams from.

getStartedDirection

public MediaDirection getStartedDirection()

Gets the MediaDirection in which this instance has been started. For example, a MediaDirection which returns true for allowsSending() signals that this instance is capturing media from its MediaDevice.

Returns:

the MediaDirection in which this instance has been started

getSupportedFormats

public List<MediaFormat> getSupportedFormats()

Gets a list of the MediaFormats in which this instance is capable of capturing media from its associated MediaDevice.

Returns:

a new list of MediaFormats in which this instance is capable of capturing media from its associated MediaDevice

isMute

public boolean isMute()

Determines whether this MediaDeviceSession is set to output "silence" instead of the actual media fed from its CaptureDevice.

Returns:

true if this MediaDeviceSession is set to output "silence" instead of the actual media fed from its CaptureDevice; otherwise, false

playbackDataSourceAdded

protected void playbackDataSourceAdded(javax.media.protocol.DataSource playbackDataSource)

Notifies this MediaDeviceSession that a DataSource has been added for playback on the represented MediaDevice.

Parameters:

playbackDataSource - the DataSource which has been added for playback on the represented MediaDevice

playbackDataSourceRemoved

protected void playbackDataSourceRemoved(javax.media.protocol.DataSource playbackDataSource)

Notifies this MediaDeviceSession that a DataSource has been removed from playback on the represented MediaDevice.

Parameters:

playbackDataSource - the DataSource which has been removed from playback on the represented MediaDevice

playerConfigureComplete

protected void playerConfigureComplete(javax.media.Processor player)

Notifies this instance that a specific Player of remote content has generated a ConfigureCompleteEvent. Allows extenders to carry out additional processing on the Player.

Parameters:

player - the Player which is the source of a ConfigureCompleteEvent

playerControllerUpdate

protected void playerControllerUpdate(javax.media.ControllerEvent event)

Gets notified about ControllerEvents generated by a specific Player of remote content.

Extenders who choose to override are advised to override more specialized methods such as playerConfigureComplete(Processor) and playerRealizeComplete(Processor). In any case, extenders overriding this method should call the super implementation.

Parameters:

event - the ControllerEvent specifying the Controller which is the source of the event and the very type of the event

playerRealizeComplete

protected void playerRealizeComplete(javax.media.Processor player)

Notifies this instance that a specific Player of remote content has generated a RealizeCompleteEvent. Allows extenders to carry out additional processing on the Player.

Parameters:

player - the Player which is the source of a RealizeCompleteEvent

processorControllerUpdate

protected void processorControllerUpdate(javax.media.ControllerEvent event)

Gets notified about ControllerEvents generated by processor.

Parameters:

event - the ControllerEvent specifying the Controller which is the source of the event and the very type of the event

removeSSRC

protected void removeSSRC(long ssrc)

Removes ssrc from the array of SSRC identifiers representing parties that this MediaDeviceSession is currently receiving streams from.

Parameters:

ssrc - the SSRC identifier that we'd like to remove from the array of ssrc identifiers stored by this session.

receiveStreamAdded

protected void receiveStreamAdded(javax.media.rtp.ReceiveStream receiveStream)

Notifies this instance that a specific ReceiveStream has been added to the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance.

Parameters:

receiveStream - the ReceiveStream which has been added to the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance

receiveStreamRemoved

protected void receiveStreamRemoved(javax.media.rtp.ReceiveStream receiveStream)

Notifies this instance that a specific ReceiveStream has been removed from the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance.

Parameters:

receiveStream - the ReceiveStream which has been removed from the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance

setCaptureDeviceFormat

protected void setCaptureDeviceFormat(javax.media.protocol.DataSource captureDevice,
                                      MediaFormatImpl<? extends javax.media.Format> mediaFormat)

setContentDescriptor

public void setContentDescriptor(javax.media.protocol.ContentDescriptor contentDescriptor)

Sets the ContentDescriptor which specifies the content type in which this MediaDeviceSession is to output the media captured by its MediaDevice. The default content type in which MediaDeviceSession outputs the media captured by its MediaDevice is ContentDescriptor.RAW_RTP.

Parameters:

contentDescriptor - the ContentDescriptor which specifies the content type in which this MediaDeviceSession is to output the media captured by its MediaDevice

setFormat

public void setFormat(MediaFormat format)

Sets the MediaFormat in which this MediaDeviceSession outputs the media captured by its MediaDevice.

Parameters:

format - the MediaFormat in which this MediaDeviceSession is to output the media captured by its MediaDevice

setProcessorFormat

protected void setProcessorFormat(javax.media.Processor processor,
                                  MediaFormatImpl<? extends javax.media.Format> mediaFormat)

Sets the MediaFormatImpl in which a specific Processor producing media to be streamed to the remote peer is to output.

Parameters:

processor - the Processor to set the output MediaFormatImpl of

mediaFormat - the MediaFormatImpl to set on processor

setProcessorFormat

protected javax.media.Format setProcessorFormat(javax.media.control.TrackControl trackControl,
                                                MediaFormatImpl<? extends javax.media.Format> mediaFormat,
                                                javax.media.Format format)

Sets the MediaFormatImpl of a specific TrackControl of the Processor which produces the media to be streamed by this MediaDeviceSession to the remote peer. Allows extenders to override the set procedure and to detect when the JMF Format of the specified TrackControl changes.

Parameters:

trackControl - the TrackControl to set the JMF Format of

mediaFormat - the MediaFormatImpl to be set on the specified TrackControl. Though mediaFormat encapsulates a JMF Format, format is to be set on the specified trackControl because it may be more specific. In any case, the two JMF Formats match. The MediaFormatImpl is provided anyway because it carries additional information such as format parameters.

format - the JMF Format to be set on the specified TrackControl. Though mediaFormat encapsulates a JMF Format, the specified format is to be set on the specified trackControl because it may be more specific than the JMF Format of the mediaFormat

Returns:

the JMF Format set on TrackControl after the attempt to set the specified format or null if the specified format was found to be incompatible with trackControl

setMute

public void setMute(boolean mute)

Sets the indicator which determines whether this MediaDeviceSession is set to output "silence" instead of the actual media fed from its CaptureDevice.

Parameters:

mute - true to set this MediaDeviceSession to output "silence" instead of the actual media fed from its CaptureDevice; otherwise, false

addDTMF

public void addDTMF(DTMFInbandTone tone)

Adds a new inband DTMF tone to send.

Parameters:

tone - the DTMF tone to send.

addPlaybackDataSource

public void addPlaybackDataSource(javax.media.protocol.DataSource playbackDataSource)

Adds a specific DataSource to the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance.

Parameters:

playbackDataSource - the DataSource which to be added to the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance

removePlaybackDataSource

public void removePlaybackDataSource(javax.media.protocol.DataSource playbackDataSource)

Removes a specific DataSource from the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance.

Parameters:

playbackDataSource - the DataSource which to be removed from the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance

addReceiveStream

public void addReceiveStream(javax.media.rtp.ReceiveStream receiveStream)

Adds a specific ReceiveStream to the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance.

Parameters:

receiveStream - the ReceiveStream which to be added to the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance

removeReceiveStream

public void removeReceiveStream(javax.media.rtp.ReceiveStream receiveStream)

Removes a specific ReceiveStream from the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance.

Parameters:

receiveStream - the ReceiveStream which to be removed from the list of playbacks of ReceiveStreams and/or DataSources performed by respective Players on the MediaDevice represented by this instance

start

public void start(MediaDirection direction)

Starts the processing of media in this instance in a specific direction.

Parameters:

direction - a MediaDirection value which represents the direction of the processing of media to be started. For example, MediaDirection.SENDRECV to start both capture and playback of media in this instance or MediaDirection.SENDONLY to only start the capture of media in this instance

startedDirectionChanged

protected void startedDirectionChanged(MediaDirection oldValue,
                                       MediaDirection newValue)

Notifies this instance that the value of its startedDirection property has changed from a specific oldValue to a specific newValue. Allows extenders to override and perform additional processing of the change. Overriding implementations must call this implementation in order to ensure the proper execution of this MediaDeviceSession.

Parameters:

oldValue - the MediaDirection which used to be the value of the startedDirection property of this instance

newValue - the MediaDirection which is the value of the startedDirection property of this instance

startProcessorInAccordWithDirection

protected void startProcessorInAccordWithDirection(javax.media.Processor processor)

Starts a specific Processor if this MediaDeviceSession has been started and the specified Processor is not started.

Parameters:

processor - the Processor to start

stop

public void stop(MediaDirection direction)

Stops the processing of media in this instance in a specific direction.

Parameters:

direction - a MediaDirection value which represents the direction of the processing of media to be stopped. For example, MediaDirection.SENDRECV to stop both capture and playback of media in this instance or MediaDirection.SENDONLY to only stop the capture of media in this instance

copyPlayback

public void copyPlayback(MediaDeviceSession deviceSession)

Copies the playback part of a specific MediaDeviceSession into this instance.

Parameters:

deviceSession - the MediaDeviceSession to copy the playback part of into this instance