de.humatic.dsj.src.rtp
Class RTPHandler

java.lang.Object
  de.humatic.dsj.src.rtp.RTPHandler

public class RTPHandler
extends java.lang.Object

Base class for mediatype specific RTP depacketizers and packetizers. RTPHandlers are setup by an RTPChannel and do both take care of initially configuring mediatypes as well as stripping any unnecessary rtp related headers from the bitstream during playback when in input mode or splitting up media samples into rtp packets when in output mode.
Applications can provide their own RTPHandlers to either replace dsj internal implementations or to support more formats by extending this class and linking their implementation with a specific media type, see setHandlerForType(...). All methods in this base class are public for that purpose and should otherwise not be called by application code.

RTPHandler implementations were public in dsj 0_8_5 despite the classes not really having methods to be used by application code. In an attempt to clean up the api dsj 0_8_6 makes the internal implementations package-private, which does not change anything about the functionality. Here is a listing of the available handlers and the underlying RFCs:

AAC / MPEG4-generic: Payload (de)packetizer according to RFC 3640. Supports interleaved AccessUnits.
ADPCM: RTPHandler / decoder for some 4 and 8 bit ulaw/alaw/adpcm audio encodings. This supports audio payload types 0 (PCMU, ulaw), 8 (PCMA, alaw) and 5, 6, 16 and 17 (DVI4), supports packetizing for ulaw and alaw.
AMR: Basic implementation of a payload (de)packetizer according to RFC 3267. This currently only supports octet-aligned, non-interleaved payloads.
GSM: handler for input data according to RFC 3551. This is not really a depacketizer, but rather transforms RTP packaged GSM frames into the format expected by Windows' GSM 6.10 codec. New in dsj 0_8_6.
G726: Depacketizer for input data according to RFC 3551. (Note that the most prominent ACM G726 decoder - Sharp G726 audio codec - prefers G726-32 (4bit))
H263: Depacketizer for payload types as specified in RFC4629.
H264: (De)packetizer for payload types as specified in RFC3984.
JPEG: Depacketizer for payload types as specified in RFC2035.
MP4V: Elementary stream RTP (de)packetizer for payload types as specified in RFC 3016.
MP4A: Elementary stream (de)packetizer for audio payload types as specified in RFC2250.
MPEG1: Depacketizer for video payload types as specified in RFC2250.
MPA: (De)packetizer for audio payload types as specified in RFC2250.
MP2T: Depacketizer for transport streams via rtp as described in RFC2250.
Quicktime: Depacketizer for generic payload types as specified in 'Letters from the icefloe', dispatch026.

(Only those implementations marked as "(de)packetizer" are available for streaming out!)

Constructor Summary

RTPHandler(DSMediaType mt, RTPChannel owner)
When extending RTPHandler you must override this constructor.

Method Summary

int	checkForHeader(byte[] stack, int readPos) In input mode called from RTPChannel during normal read operation.
static RTPHandler	forMediaType(DSMediaType mt, RTPChannel owner) Returns the mediatype specific handler implementation.
java.lang.String	getMIMEType()
boolean	handlePacket(byte[] data, int dataOffset, int dataLength, int seqNumber, int rtpTimeStamp, int flags) Main packet handling method (input mode) called from the RTPChannel after a sample has been completely received.
byte[][]	handleSample(SampleBuffer sb, int headerLength) Sample packetizing method (output mode), called from RTSPSink with full video or audio samples.
void	newPacket(int readPos) In input mode called from RTPChannel on the start of a new sample fragment.
void	notifyStreamEvent(int event, int param) Called by RTPChannel, currently only used with seeking.
boolean	prescan(byte[] data, int dataLength) In input mode called during setup, returns true when enough information has been collected to validate the media type passed in on constructiuon.
static void	setHandlerForType(DSMediaType mediaType, java.lang.String fullyQualifiedClassName) Allows to set a preferred RTPHandler for the given media type.
void	setSDPCodecInfo(java.lang.String info) Passes the (eventually base64 encoded) extra info, that some payload types require to the handler.

Methods inherited from class java.lang.Object

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

Constructor Detail

RTPHandler

public RTPHandler(DSMediaType mt,
                  RTPChannel owner)

When extending RTPHandler you must override this constructor.

Method Detail

forMediaType

public static RTPHandler forMediaType(DSMediaType mt,
                                      RTPChannel owner)
                               throws DSJException

Returns the mediatype specific handler implementation.

Throws:

DSJException

setHandlerForType

public static void setHandlerForType(DSMediaType mediaType,
                                     java.lang.String fullyQualifiedClassName)

Allows to set a preferred RTPHandler for the given media type. This can both be used to replace dsj internal handlers as well as for adding support for more media types. The class whose fully qualified name you pass in here must be on the classpath at runtime, must extend de.humatic.dsj.RTPHandler and must provide a constructor with DSMediaType and RTPChannel arguments. The DSMediaType argument only needs major and subtype to be specified
Sun's trail on extension class loading at http://java.sun.com/docs/books/tutorial/ext/basics/index.html has more information.

getMIMEType

public java.lang.String getMIMEType()

setSDPCodecInfo

public void setSDPCodecInfo(java.lang.String info)

Passes the (eventually base64 encoded) extra info, that some payload types require to the handler.

notifyStreamEvent

public void notifyStreamEvent(int event,
                              int param)

Called by RTPChannel, currently only used with seeking.

newPacket

public void newPacket(int readPos)

In input mode called from RTPChannel on the start of a new sample fragment. %readPos passes the current read position in the frame currently assembled. Not all dsj RTP Handlers override this method, because the tracking variable is accessible for them in the rtp package, but an external implementation will need to make use of this method if it needs to remove extra headers between sample fragments.

checkForHeader

public int checkForHeader(byte[] stack,
                          int readPos)

In input mode called from RTPChannel during normal read operation. Both RTP and RTSP sources read data in single bytes, so this will be called very frequently. RTPHandler implementations should immediately return %readPos unmodified unless it falls on a known header boundary (fragment start position as transferred by newPacket(int)+headerlength). If that is the case it is up to the handler implementation to either reset the read position by the header length (i.e. return %readPos-headerlength) which will result in the headerbytes being overwritten by subsequent reads or to keep the header and return %readPos unmodified or to do whatever else is appropriate.

prescan

public boolean prescan(byte[] data,
                       int dataLength)

In input mode called during setup, returns true when enough information has been collected to validate the media type passed in on constructiuon.

handlePacket

public boolean handlePacket(byte[] data,
                            int dataOffset,
                            int dataLength,
                            int seqNumber,
                            int rtpTimeStamp,
                            int flags)

Main packet handling method (input mode) called from the RTPChannel after a sample has been completely received. The RTPHandler then "depacketizes" the data and calls RTPChannel.sendPacket(...) to deliver raw sample data to the source filter. Note that in order to strip headers it is enough to alter %dataOffset and call sendPacket(...) with the data byte[] otherwise unmodified, although some formats may require to copy data into a secondary buffer before sending it back.

handleSample

public byte[][] handleSample(SampleBuffer sb,
                             int headerLength)

Sample packetizing method (output mode), called from RTSPSink with full video or audio samples. Returns RTP packetized data with each packet preceeded by %headerLength bytes into which the sink inserts RTP header information.