net.java.sip.communicator.service.neomedia
Interface MediaStream

All Known Subinterfaces:

AudioMediaStream, VideoMediaStream

All Known Implementing Classes:

AbstractMediaStream, AudioMediaStreamImpl, MediaStreamImpl, VideoMediaStreamImpl

public interface MediaStream

The MediaStream class represents a (generally) bidirectional RTP stream between exactly two parties. The class reflects one media stream, in the SDP sense of the word. MediaStream instances are created through the openMediaStream() method of the MediaService.

Author:

Emil Ivov, Lyubomir Marinov

Field Summary

static String	PNAME_LOCAL_SSRC The name of the property which indicates whether the remote SSRC is currently available.
static String	PNAME_REMOTE_SSRC The name of the property which indicates whether the local SSRC is currently available.

Method Summary

void	addDynamicRTPPayloadType(byte rtpPayloadType, MediaFormat format) Adds a new association in this MediaStream of the specified RTP payload type with the specified MediaFormat in order to allow it to report rtpPayloadType in RTP flows sending and receiving media in format.
void	addPropertyChangeListener(PropertyChangeListener listener) Adds a property change listener to this stream so that it would be notified upon property change events like for example an SSRC ID which becomes known.
void	addRTPExtension(byte extensionID, RTPExtension rtpExtension) Adds or updates an association in this MediaStream mapping the specified extensionID to rtpExtension and enabling or disabling its use according to the direction attribute of rtpExtension.
void	close() Releases the resources allocated by this instance in the course of its execution and prepares it to be garbage collected.
Map<Byte,RTPExtension>	getActiveRTPExtensions() Returns a map containing all currently active RTPExtensions in use by this stream.
MediaDevice	getDevice() Gets the device that this stream uses to play back and capture media.
MediaDirection	getDirection() Gets the direction in which this MediaStream is allowed to stream media.
Map<Byte,MediaFormat>	getDynamicRTPPayloadTypes() Gets the existing associations in this MediaStream of RTP payload types to MediaFormats.
MediaFormat	getFormat() Returns the MediaFormat that this stream is currently transmitting in.
long	getLocalSourceID() Returns the synchronization source (SSRC) identifier of the local participant or -1 if that identifier is not yet known at this point.
String	getName() Returns the name of this stream or null if no name has been set.
InetSocketAddress	getRemoteControlAddress() Returns the address that this stream is sending RTCP traffic to.
InetSocketAddress	getRemoteDataAddress() Returns the address that this stream is sending RTP traffic to.
long	getRemoteSourceID() Returns the synchronization source (SSRC) identifier of the remote participant or -1 if that identifier is not yet known at this point.
SrtpControl	getSrtpControl() The ZrtpControl which controls the ZRTP for this stream.
MediaStreamTarget	getTarget() Returns the target of this MediaStream to which it is to send and from which it is to receive data (e.g.
boolean	isMute() Determines whether this MediaStream is set to transmit "silence" instead of the media being fed from its MediaDevice.
boolean	isStarted() Determines whether start() has been called on this MediaStream without stop() or close() afterwards.
void	removePropertyChangeListener(PropertyChangeListener listener) Removes the specified property change listener from this stream so that it won't receive further property change events.
void	setConnector(StreamConnector connector) Sets the StreamConnector to be used by this MediaStream for sending and receiving media.
void	setDevice(MediaDevice device) Sets the device that this stream should use to play back and capture media.
void	setDirection(MediaDirection direction) Sets the direction in which media in this MediaStream is to be streamed.
void	setFormat(MediaFormat format) Sets the MediaFormat that this MediaStream should transmit in.
void	setMute(boolean mute) Causes this MediaStream to stop transmitting the media being fed from this stream's MediaDevice and transmit "silence" instead.
void	setName(String name) Sets the name of this stream.
void	setRTPTranslator(RTPTranslator rtpTranslator) Sets the RTPTranslator which is to forward RTP and RTCP traffic between this and other MediaStreams.
void	setTarget(MediaStreamTarget target) Sets the target of this MediaStream to which it is to send and from which it is to receive data (e.g.
void	start() Starts capturing media from this stream's MediaDevice and then streaming it through the local StreamConnector toward the stream's target address and port.
void	stop() Stops all streaming and capturing in this MediaStream and closes and releases all open/allocated devices/resources.

Field Detail

PNAME_LOCAL_SSRC

static final String PNAME_LOCAL_SSRC

The name of the property which indicates whether the remote SSRC is currently available.

See Also:

Constant Field Values

PNAME_REMOTE_SSRC

static final String PNAME_REMOTE_SSRC

The name of the property which indicates whether the local SSRC is currently available.

See Also:

Constant Field Values

Method Detail

start

void start()

Starts capturing media from this stream's MediaDevice and then streaming it through the local StreamConnector toward the stream's target address and port. The method also puts the MediaStream in a listening state that would make it play all media received from the StreamConnector on the stream's MediaDevice.

stop

void stop()

Stops all streaming and capturing in this MediaStream and closes and releases all open/allocated devices/resources. This method has no effect on an already closed stream and is simply ignored.

close

void close()

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

setFormat

void setFormat(MediaFormat format)

Sets the MediaFormat that this MediaStream should transmit in.

Parameters:

format - the MediaFormat that this MediaStream should transmit in.

getFormat

MediaFormat getFormat()

Returns the MediaFormat that this stream is currently transmitting in.

Returns:

the MediaFormat that this stream is currently transmitting in.

setConnector

void setConnector(StreamConnector connector)

Sets the StreamConnector to be used by this MediaStream for sending and receiving media.

Parameters:

connector - the StreamConnector to be used by this MediaStream for sending and receiving media

setDevice

void setDevice(MediaDevice device)

Sets the device that this stream should use to play back and capture media.

Parameters:

device - the MediaDevice that this stream should use to play back and capture media.

getDevice

MediaDevice getDevice()

Gets the device that this stream uses to play back and capture media.

Returns:

the MediaDevice that this stream uses to play back and capture media.

getRemoteSourceID

long getRemoteSourceID()

Returns the synchronization source (SSRC) identifier of the remote participant or -1 if that identifier is not yet known at this point.

Returns:

the synchronization source (SSRC) identifier of the remote participant or -1 if that identifier is not yet known at this point.

getLocalSourceID

long getLocalSourceID()

Returns the synchronization source (SSRC) identifier of the local participant or -1 if that identifier is not yet known at this point.

Returns:

the synchronization source (SSRC) identifier of the local participant or -1 if that identifier is not yet known at this point.

getRemoteControlAddress

InetSocketAddress getRemoteControlAddress()

Returns the address that this stream is sending RTCP traffic to.

Returns:

an InetSocketAddress instance indicating the address that we are sending RTCP packets to.

getRemoteDataAddress

InetSocketAddress getRemoteDataAddress()

Returns the address that this stream is sending RTP traffic to.

Returns:

an InetSocketAddress instance indicating the address that we are sending RTP packets to.

addPropertyChangeListener

void addPropertyChangeListener(PropertyChangeListener listener)

Adds a property change listener to this stream so that it would be notified upon property change events like for example an SSRC ID which becomes known.

Parameters:

listener - the listener that we'd like to register for PropertyChangeEvents

removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener listener)

Removes the specified property change listener from this stream so that it won't receive further property change events.

Parameters:

listener - the listener that we'd like to remove.

setTarget

void setTarget(MediaStreamTarget target)

Sets the target of this MediaStream to which it is to send and from which it is to receive data (e.g. RTP) and control data (e.g. RTCP).

Parameters:

target - the MediaStreamTarget describing the data (e.g. RTP) and the control data (e.g. RTCP) locations to which this MediaStream is to send and from which it is to receive

getTarget

MediaStreamTarget getTarget()

Returns the target of this MediaStream to which it is to send and from which it is to receive data (e.g. RTP) and control data (e.g. RTCP).

Returns:

the MediaStreamTarget describing the data (e.g. RTP) and the control data (e.g. RTCP) locations to which this MediaStream is to send and from which it is to receive

See Also:

setTarget(MediaStreamTarget)

addDynamicRTPPayloadType

void addDynamicRTPPayloadType(byte rtpPayloadType,
                              MediaFormat format)

Adds a new association in this MediaStream of the specified RTP payload type with the specified MediaFormat in order to allow it to report rtpPayloadType in RTP flows sending and receiving media in format. Usually, rtpPayloadType will be in the range of dynamic RTP payload types.

Parameters:

rtpPayloadType - the RTP payload type to be associated in this MediaStream with the specified MediaFormat

format - the MediaFormat to be associated in this MediaStream with rtpPayloadType

getDynamicRTPPayloadTypes

Map<Byte,MediaFormat> getDynamicRTPPayloadTypes()

Gets the existing associations in this MediaStream of RTP payload types to MediaFormats. The returned Map only contains associations previously added in this instance with addDynamicRTPPayloadType(byte, MediaFormat) and not globally or well-known associations reported by MediaFormat.getRTPPayloadType().

Returns:

a Map of RTP payload type expressed as Byte to MediaFormat describing the existing (dynamic) associations in this instance of RTP payload types to MediaFormats. The Map represents a snapshot of the existing associations at the time of the getDynamicRTPPayloadTypes() method call and modifications to it are not reflected on the internal storage

addRTPExtension

void addRTPExtension(byte extensionID,
                     RTPExtension rtpExtension)

Adds or updates an association in this MediaStream mapping the specified extensionID to rtpExtension and enabling or disabling its use according to the direction attribute of rtpExtension.

Parameters:

extensionID - the ID that is mapped to rtpExtension for the lifetime of this MediaStream.

rtpExtension - the RTPExtension that we are mapping to extensionID.

getActiveRTPExtensions

Map<Byte,RTPExtension> getActiveRTPExtensions()

Returns a map containing all currently active RTPExtensions in use by this stream.

Returns:

a map containing all currently active RTPExtensions in use by this stream.

setDirection

void setDirection(MediaDirection direction)

Sets the direction in which media in this MediaStream is to be streamed. If this MediaStream is not currently started, calls to start() later on will start it only in the specified direction. If it is currently started in a direction different than the specified, directions other than the specified will be stopped.

Parameters:

direction - the MediaDirection in which this MediaStream is to stream media when it is started

getDirection

MediaDirection getDirection()

Gets the direction in which this MediaStream is allowed to stream media.

Returns:

the MediaDirection in which this MediaStream is allowed to stream media

isStarted

boolean isStarted()

Determines whether start() has been called on this MediaStream without stop() or close() afterwards.

Returns:

true if start() has been called on this MediaStream without stop() or close() afterwards

setMute

void setMute(boolean mute)

Causes this MediaStream to stop transmitting the media being fed from this stream's MediaDevice and transmit "silence" instead. "Silence" for video is understood as video data which is not the captured video data and may represent, for example, a black image.

Parameters:

mute - true if we are to start transmitting "silence" and false if we are to use media from this stream's MediaDevice again.

isMute

boolean isMute()

Determines whether this MediaStream is set to transmit "silence" instead of the media being fed from its MediaDevice. "Silence" for video is understood as video data which is not the captured video data and may represent, for example, a black image.

Returns:

true if this MediaStream is set to transmit "silence" instead of the media fed from its MediaDevice; false, otherwise

getName

String getName()

Returns the name of this stream or null if no name has been set. A stream name is used by some protocols, for diagnostic purposes mostly. In XMPP for example this is the name of the content element that describes a stream.

Returns:

the name of this stream or null if no name has been set.

setName

void setName(String name)

Sets the name of this stream. Stream names are used by some protocols, for diagnostic purposes mostly. In XMPP for example this is the name of the content element that describes a stream.

Parameters:

name - the name of this stream or null if no name has been set.

getSrtpControl

SrtpControl getSrtpControl()

The ZrtpControl which controls the ZRTP for this stream.

Returns:

the ZrtpControl which controls the ZRTP for this stream

setRTPTranslator

void setRTPTranslator(RTPTranslator rtpTranslator)

Sets the RTPTranslator which is to forward RTP and RTCP traffic between this and other MediaStreams.

Parameters:

rtpTranslator - the RTPTranslator which is to forward RTP and RTCP traffic between this and other MediaStreams