net.java.sip.communicator.service.media
Interface MediaService

All Known Implementing Classes:

MediaServiceImpl

public interface MediaService

The service is meant to be a wrapper of media libraries such as JMF, (J)FFMPEG, JMFPAPI, and others. It takes care of all media play and capture as well as media transport (e.g. over RTP). Before being able to use this service calls would have to make sure that it is initialized (i.e. consult the isInitialized() method).

Author:

Emil Ivov, Martin Andre, Ryan Ricard, Symphorien Wanko

Field Summary

static int	BIND_RETRIES_DEFAULT_VALUE The default number of binds that a Media Service Implementation should execute in case a port is already bound to (each retry would be on a new random port).
static String	BIND_RETRIES_PROPERTY_NAME The name of the property containing the number of binds that a Media Service Implementation should execute in case a port is already bound to (each retry would be on a new random port).
static String	DISABLE_VIDEO_SUPPORT_PROPERTY_NAME With this property video support can be disabled (enabled by default).
static String	MAX_PORT_NUMBER_PROPERTY_NAME The name of the property that contains the maximum port number that we'd like our RTP managers to bind upon.
static String	MIN_PORT_NUMBER_PROPERTY_NAME The name of the property that contains the minimum port number that we'd like our RTP managers to bind upon.

Method Summary

void	addMediaListener(MediaListener listener) Adds a listener that will be listening for incoming media and changes in the state of the media listener.
CallSession	createCallSession(Call call) Creates a call session for call.
RtpFlow	createRtpFlow(String localIP, int localPort, String remoteIP, int remotePort, Map<String,List<String>> mediaEncodings) Create a RtpFlow which will manage media data transfer on the specified addresses and ports, using the specified codec.
double	getDataSourceDurationSeconds(Call call) Returns the duration (in milliseconds) of the data source being used for the given call.
String[]	getSupportedAudioEncodings() Give an array of Strings containing audio formats in the order of preference.
String[]	getSupportedVideoEncodings() Give an array of Strings containing video formats in the order of preference.
boolean	isStarted() Returns true if the media service implementation is initialized and ready for use by other services, and false otherwise.
void	removeMediaListener(MediaListener listener) Removes a listener that was listening for incoming media and changes in the state of the media listener
void	setCallDataSink(Call call, URL dataSinkURL) Sets the Data Destination for call to the URL dataSinkURL instead of the default data destination.
void	setCallDataSource(Call call, URL dataSourceURL) Sets the data source for call to the URL dataSourceURL instead of the default data source.
void	unsetCallDataSink(Call call) Unsets the data sink for call, which will now send data to the default output devices (sound card and/or screen).
void	unsetCallDataSource(Call call) Unsets any custom data sources that have been previously set for call through the setCallDataSource(Call, URL) method and revert it to the default data source.

Field Detail

BIND_RETRIES_PROPERTY_NAME

static final String BIND_RETRIES_PROPERTY_NAME

The name of the property containing the number of binds that a Media Service Implementation should execute in case a port is already bound to (each retry would be on a new random port).

See Also:

Constant Field Values

MIN_PORT_NUMBER_PROPERTY_NAME

static final String MIN_PORT_NUMBER_PROPERTY_NAME

The name of the property that contains the minimum port number that we'd like our RTP managers to bind upon.

See Also:

Constant Field Values

MAX_PORT_NUMBER_PROPERTY_NAME

static final String MAX_PORT_NUMBER_PROPERTY_NAME

The name of the property that contains the maximum port number that we'd like our RTP managers to bind upon.

See Also:

Constant Field Values

BIND_RETRIES_DEFAULT_VALUE

static final int BIND_RETRIES_DEFAULT_VALUE

The default number of binds that a Media Service Implementation should execute in case a port is already bound to (each retry would be on a new random port).

See Also:

Constant Field Values

DISABLE_VIDEO_SUPPORT_PROPERTY_NAME

static final String DISABLE_VIDEO_SUPPORT_PROPERTY_NAME

With this property video support can be disabled (enabled by default).

See Also:

Constant Field Values

Method Detail

getSupportedAudioEncodings

String[] getSupportedAudioEncodings()

Give an array of Strings containing audio formats in the order of preference.

Returns:

an array of Strings containing audio formats in the order of preference.

getSupportedVideoEncodings

String[] getSupportedVideoEncodings()

Give an array of Strings containing video formats in the order of preference.

Returns:

an array of Strings containing video formats in the order of preference.

createCallSession

CallSession createCallSession(Call call)
                              throws MediaException

Creates a call session for call. The method allocates audio and video ports which won't be released until the corresponding call gets into a DISCONNECTED state. If a session already exists for call, it is returned and no new session is created. Once created a session follows the state changes of the call it encapsulates and automatically adapts to them by starting or stopping transmission and/or reception of data. A CallSession would auto destroy when the Call it encapsulates enters the CALL_ENDED CallState.

Parameters:

call - the Call that we'll be encapsulating in the newly created session.

Returns:

a CallSession encapsulating call.

Throws:

MediaException - with code IO_ERROR if we fail allocating ports.

createRtpFlow

RtpFlow createRtpFlow(String localIP,
                      int localPort,
                      String remoteIP,
                      int remotePort,
                      Map<String,List<String>> mediaEncodings)
                      throws MediaException

Create a RtpFlow which will manage media data transfer on the specified addresses and ports, using the specified codec.

Parameters:

localIP - local IP of this flow

localPort - local port of for this flow

remoteIP - remote IP of this flow

remotePort - remote port of for this flow

mediaEncodings - encoding used for media on this flow

Returns:

a RtpFlow with the corresponding parameters

Throws:

MediaException - throw a media exception if we fail to create the flow

addMediaListener

void addMediaListener(MediaListener listener)

Adds a listener that will be listening for incoming media and changes in the state of the media listener.

Parameters:

listener - the listener to register

removeMediaListener

void removeMediaListener(MediaListener listener)

Removes a listener that was listening for incoming media and changes in the state of the media listener

Parameters:

listener - the listener to remove

setCallDataSource

void setCallDataSource(Call call,
                       URL dataSourceURL)
                       throws MediaException

Sets the data source for call to the URL dataSourceURL instead of the default data source. This is used (for instance) to play audio from a file instead of the microphone.

Parameters:

call - the call whose data source will be changed

dataSourceURL - the URL of the new data source

Throws:

MediaException - if we fail to initialize the data source

unsetCallDataSource

void unsetCallDataSource(Call call)

Unsets any custom data sources that have been previously set for call through the setCallDataSource(Call, URL) method and revert it to the default data source. If no custom data sources have been set for Call, the method has no effect.

Parameters:

call - the call whose data source mapping will be released

setCallDataSink

void setCallDataSink(Call call,
                     URL dataSinkURL)
                     throws MediaException

Sets the Data Destination for call to the URL dataSinkURL instead of the default data destination. This is used (for instance) to record incoming data to a file instead of playing it on the speakers/screen

Parameters:

call - the call whose data destination will be changed

dataSinkURL - the URL of the new data sink.

Throws:

MediaException - if we fail to initialize the data sink

unsetCallDataSink

void unsetCallDataSink(Call call)

Unsets the data sink for call, which will now send data to the default output devices (sound card and/or screen).

Parameters:

call - the call whose data sink mapping will be released

getDataSourceDurationSeconds

double getDataSourceDurationSeconds(Call call)

Returns the duration (in milliseconds) of the data source being used for the given call. If the data source is not time-based, i.e. a microphone, the method returns -1.

Parameters:

call - the call whose data source duration will be retrieved

Returns:

the duration of the data currently available in the call specific data source or -1 if we are using a microphone/webcam.

isStarted

boolean isStarted()

Returns true if the media service implementation is initialized and ready for use by other services, and false otherwise.

Returns:

true if the service implementation is initialized and ready for use and false otherwise.