Understanding the JMF RTP API

You can play incoming RTP streams locally, save them to a file, or both.
 

Figure 8-1: RTP reception.

You can use the RTP APIs to transmit captured or stored media streams across the network. Outgoing RTP streams can originate from a file or a capture device. The outgoing streams can also be played locally, saved to a file, or both.
 

Figure 8-2: RTP transmission.

RTP Architecture

The JMF RTP APIs are designed to work seamlessly with the capture, presentation, and processing capabilities of JMF.

• Players and processors are used to present and manipulate RTP media streams just like any other media content.
• You can transmit media streams that have been captured from a local capture device using a capture DataSource or that have been stored to a file using a DataSink.

Figure 8-3: High-level JMF RTP architecture.

Session Manager

In JMF, a SessionManager is used to coordinate an RTP session.

• It keeps track of the session participants and the streams that are being transmitted.
• It handles the RTCP control channel, and supports RTCP for both senders and receivers.

The SessionManager interface defines methods that enable an application to initialize and start participating in a session, remove individual streams created by the application, and close the entire session.

Session Statistics

The session manager maintains statistics on all of the RTP and RTCP packets sent and received in the session. Statistics are tracked for the entire session on a per-stream basis.

Session Participants

The session manager keeps track of all of the participants in a session. Each participant is represented by an instance of a class that implements the Participantinterface. SessionManager create a Participant whenever an RTCP packet arrives that contains a source description (SDES) with a canonical name(CNAME) that has not been seen before.

A participant can own more than one stream, each of which is identified by the synchronization source identifier (SSRC) used by the source of the stream.

Session Streams

The SessionManager maintains an RTPStream object for each stream of RTP data packets in the session. There are two types of RTP streams:

• ReceiveStream represents a stream that's being received from a remote participant.
• SendStream represents a stream of data coming from the Processor or input DataSource that is being sent over the network.

A ReceiveStreamis constructed automatically whenever the session manager detects a new source of RTP data. To create a new SendStream, you call the SessionManagercreate.SendStreammethod.

RTP Events

Several RTP-specific events are defined in javax.media.rtp.event. These events are used to report on the state of the RTP session and streams.

Figure 8-4: RTP events.

To receive notification of RTP events, you implement the appropriate RTP listener and register it with the session manager:

• SessionListener: Receives notification of changes in the state of the session.
• SendStreamListener: Receives notification of changes in the state of an RTP stream that's being transmitted.
• ReceiveStreamListener: Receives notification of changes in the state of an RTP stream that's being received.
• RemoteListener: Receives notification of events or RTP control messages received from a remote participant.

Session Listener

There are two types of session-wide events:

• NewParticipantEvent: Indicates that a new participant has joined the session.
• LocalCollisionEvent: Indicates that the participant's synchronization source is already in use.

Send Stream Listener

There are five types of events associated with a SendStream:

• NewSendStreamEvent: Indicates that a new send stream has been created by the local participant.
• ActiveSendStreamEvent: Indicates that the transfer of data from the DataSource used to create the send stream has started.
• InactiveSendStreamEvent: Indicates that the transfer of data from the DataSource used to create the send stream has stopped.
• LocalPayloadChangeEvent: Indicates that the stream's format or payload has changed.
• StreamClosedEvent: Indicates that the stream has been closed.

Receive Stream Listener

There are seven types of events associated with a ReceiveStream:

• NewReceiveStreamEvent: Indicates that the session manager has created a new receive stream for a newly-detected source.
• ActiveReceiveStreamEvent: Indicates that the transfer of data has started.
• InactiveReceiveStreamEvent: Indicates that the transfer of data has stopped.
• TimeoutEvent: Indicates that the data transfer has timed out.
• RemotePayloadChangeEvent: Indicates that the format or payload of the receive stream has changed.
• StreamMappedEvent: Indicates that a previously orphaned receive stream has been associated with a participant.
• ApplicationEvent: Indicates that an RTCP APP packet has been received.

Remote Listener

There are three types of events associated with a remote participant:

• ReceiverReportEvent: Indicates that an RTP receiver report has been received.
• SenderReportEvent: Indicates that an RTP sender report has been received.
• RemoteCollisionEvent: Indicates that two remote participants are using the same synchronization source ID (SSRC).

RTP Data

The streams within an RTP session are represented by RTPStream objects. There are two types of RTPStreams: ReceiveStream and SendStream. Each RTP stream has a buffer data source associated with it. For ReceiveStreams, this DataSource is always a PushBufferDataSource.

RTP Data Formats

All RTP-specific data uses an RTP-specific format encoding as defined in the AudioFormat and VideoFormat classes.

AudioFormat defines four standard RTP-specific encoding strings:

public static final String ULAW_RTP = "JAUDIO_G711_ULAW/rtp";
public static final String DVI_RTP = "dvi/rtp";
public static final String G723_RTP = "g723/rtp";
public static final String GSM_RTP = "gsm/rtp";

VideoFormat defines three standard RTP-specific encoding strings:

public static final String JPEG_RTP = "jpeg/rtp";
public static final String H261_RTP = "h261/rtp";
public static final String H263_RTP = "h263/rtp";

RTP Controls

RTPControl  provides methods for accessing session statistics and getting the current payload Format.
 

Reception

The presentation of an incoming RTP stream is handled by a Player. To receive and present a single stream from an RTP session, you can use a MediaLocator that describes the session to construct a Player. A media locator for an RTP session is of the form:

    rtp://address:port[:ssrc]/content-type/[ttl]

The Player is constructed and connected to the first stream in the session.

If there are multiple streams in the session that you want to present, you need to use a session manager. You can receive notification from the session manager whenever a stream is added to the session and construct a Player for each new stream. Using a session manager also enables you to directly monitor and control the session.

Transmission

To create a send stream to transmit data from a live capture source:

1. Create, initialize, and start a SessionManager for the session.
2. Construct a Processor using the appropriate capture DataSource.
3. Set the output format of the Processor to an RTP-specific format.
4. Retrieve the output DataSource from the Processor.
5. Call createSendStream on the session manager and pass in the DataSource.

You control the transmission through the SendStream start and stop methods.