Preface

The Java^TM Media Framework (JMF) is an application programming interface (API) for incorporating time-based media into Java applications and applets. This guide is intended for Java programmers who want to incorporate time-based media into their applications and for technology providers who are interested in extending JMF and providing JMF plug-ins to support additional media types and perform custom processing and rendering.

About JMF

The JMF 1.0 API (the Java Media Player API) enabled programmers to develop Java programs that presented time-based media. The JMF 2.0 API extends the framework to provide support for capturing and storing media data, controlling the type of processing that is performed during playback, and performing custom processing on media data streams. In addition, JMF 2.0 defines a plug-in API that enables advanced developers and technology providers to more easily customize and extend JMF functionality.

The following classes and interfaces are new in JMF 2.0:

AudioFormat	BitRateControl	Buffer
BufferControl	BufferToImage	BufferTransferHandler
CaptureDevice	CaptureDeviceInfo	CaptureDeviceManager
CloneableDataSource	Codec	ConfigureCompleteEvent
ConnnectionErrorEvent	DataSink	DataSinkErrorEvent
DataSinkEvent	DataSinkListener	Demultiplexer
Effect	EndOfStreamEvent	FileTypeDescriptor
Format	FormatChangeEvent	FormatControl
FrameGrabbingControl	FramePositioningControl	FrameProcessingControl
FrameRateControl	H261Control	H261Format
H263Control	H263Format	ImageToBuffer
IndexedColorFormat	InputSourceStream	KeyFrameControl
MonitorControl	MpegAudioControl	Multiplexer
NoStorageSpaceErrorEvent	PacketSizeControl	PlugIn
PlugInManager	PortControl	Processor
ProcessorModel	PullBufferDataSource	PullBufferStream
PushBufferDataSource	PushBufferStream	QualityControl
Renderer	RGBFormat	SilenceSuppressionControl
StreamWriterControl	Track	TrackControl
VideoFormat	VideoRenderer	YUVFormat

In addition, the MediaPlayer Java Bean has been included with the JMF API in javax.media.bean.playerbean. MediaPlayer can be instantiated directly and used to present one or more media streams.

Future versions of the JMF API will provide additional functionality and enhancements while maintaining compatibility with the current API.

Design Goals for the JMF API

JMF 2.0 supports media capture and addresses the needs of application developers who want additional control over media processing and rendering. It also provides a plug-in architecture that provides direct access to media data and enables JMF to be more easily customized and extended. JMF 2.0 is designed to:

• Be easy to program
• Support capturing media data
• Enable the development of media streaming and conferencing applications in Java
• Enable advanced developers and technology providers to implement custom solutions based on the existing API and easily integrate new features with the existing framework
• Provide access to raw media data
• Enable the development of custom, downloadable demultiplexers, codecs, effects processors, multiplexers, and renderers (JMF plug-ins)
• Maintain compatibility with JMF 1.0

About the JMF RTP APIs

The classes in javax.media.rtp, javax.media.rtp.event, and javax.media.rtp.rtcp provide support for RTP (Real-Time Transport Protocol). RTP enables the transmission and reception of real-time media streams across the network. RTP can be used for media-on-demand applications as well as interactive services such as Internet telephony.

JMF-compliant implementations are not required to support the RTP APIs in javax.media.rtp, javax.media.rtp.event, and javax.media.rtp.rtcp. The reference implementations of JMF provided by Sun Microsystems, Inc. and IBM Corporation fully support these APIs.

The first version of the JMF RTP APIs (referred to as the RTP Session Manager API) enabled developers to receive RTP streams and play them using JMF. In JMF 2.0, the RTP APIs also support the transmission of RTP streams.

The following RTP classes and interfaces are new in JMF 2.0:

SendStream	SendStreamListener	InactiveSendStreamEvent
ActiveSendStreamEvent	SendPayloadChangeEvent	NewSendStreamEvent
GlobalTransmissionStats	TransmissionStats

The RTP packages have been reorganized and some classes, interfaces, and methods have been renamed to make the API easier to use. The package reorganization consists of the following changes:

• The RTP event classes that were in javax.media.rtp.session are now in javax.media.rtp.event.
• The RTCP-related classes that were in javax.media.rtp.session are now in javax.media.rtp.rtcp.
• The rest of the classes in javax.media.rtp.session are now in javax.media.rtp and the javax.media.rtp.session package has been removed.

The name changes consist primarily of the removal of the RTP and RTCP prefixes from class and interface names and the elimination of non-standard abbreviations. For example, RTPRecvStreamListener has been renamed to ReceiveStreamListener. For a complete list of the changes made to the RTP packages, see the JMF 2.0 Beta release notes.

In addition, changes were made to the RTP APIs to make them compatible with other changes in JMF 2.0:

• javax.media.rtp.session.io and javax.media.rtp.session.depacketizer have been removed. Custom RTP packetizers and depacketizers are now supported through the JMF 2.0 plug-in architecture. Existing depacketizers will need to be ported to the new plug-in architecture.
• Buffer is now the basic unit of transfer between the SessionManager and other JMF objects, in place of DePacketizedUnit and DePacketizedObject. RTP-formatted Buffers have a specific format for their data and header objects.
• BaseEncodingInfo has been replaced by the generic JMF Format object. An RTP-specific Format is differentiated from other formats by its encoding string. Encoding strings for RTP-specific Formats end in _RTP. Dynamic payload information can be provided by associating a dynamic payload number with a Format object.

Design Goals for the JMF RTP APIs

The RTP APIs in JMF 2.0 support the reception and transmission of RTP streams and address the needs of application developers who want to use RTP to implement media streaming and conferencing applications. These APIs are designed to:

• Enable the development of media streaming and conferencing applications in Java
• Support media data reception and transmission using RTP and RTCP
• Support custom packetizer and depacketizer plug-ins through the JMF 2.0 plug-in architecture.
• Be easy to program

Partners in the Development of the JMF API

The JMF 2.0 API is being jointly designed by Sun Microsystems, Inc. and IBM Corporation.

The JMF 1.0 API was jointly developed by Sun Microsystems Inc., Intel Corporation, and Silicon Graphics, Inc.

Contact Information

For the latest information about JMF, visit the Sun Microsystems, Inc. website at:

 http://java.sun.com/products/java-media/jmf/

Additional information about JMF can be found on the IBM Corporation website at:

 http://www.software.ibm.com/net.media/

About this Document

This document describes the architecture and use of the JMF 2.0 API. It replaces the Java Media Player Guide distributed in conjunction with the JMF 1.0 releases.

Except where noted, the information in this book is not implementation specific. For examples specific to the JMF reference implementation developed by Sun Microsystems and IBM corporation, see the sample code and solutions available from Sun's JMF website (http://java.sun.com/products/java-media/jmf/index.html).

Guide to Contents

This document is split into two parts:

• Part 1 describes the features provided by the JMF 2.0 API and illustrates how you can use JMF to incorporate time-based media in your Java applications and applets.
• Part 2 describes the support for real-time streaming provided by the JMF RTP APIs and illustrates how to send and receive streaming media across the network.

Part 1 is organized into six chapters:

• "Working with Time-Based Media"--sets the stage for JMF by introducing the key concepts of media content, presentation, processing, and recording.
• "Understanding JMF"--introduces the JMF 2.0 API and describes the high-level architecture of the framework.
• "Presenting Time-Based Media with JMF"--describes how to use JMF Players and Processors to present time-based media.
• "Processing Time-Based Media with JMF"--describes how to manipulate media data using a JMF Processor.
• "Capturing Time-Based Media with JMF"--describes how to record media data using JMF DataSources and Processors.
• "Extending JMF"--describes how to enhance JMF functionality by creating new processing plug-ins and implementing custom JMF classes.

Part 2 is organized into six chapters:

• "Working with Real-Time Media Streams"--provides an overview of streaming media and the Real-time Transport protocol (RTP).
• "Understanding the JMF RTP API"--describes the JMF RTP APIs.
• "Receiving and Presenting RTP Media Streams"--illustrates how to handle RTP Client operations.
• "Transmitting RTP Media Streams"--illustrates how to handle RTP Server operations.
• "Importing and Exporting RTP Media Streams"--shows how to read and write RTP data to a file.
• "Creating Custom Packetizers and Depacketizers"--describes how to use JMF plug-ins to support additional RTP packet formats and codecs.

At the end of this document, you'll find Appendices that contain complete sample code for some of the examples used in these chapters and a glossary of JMF-specific terms.

Change History

Version JMF 2.0 FCS

• Fixed references to TrackControl methods to reflect modified TrackControl API.
• Fixed minor sample code errors.
• Clarified behavior of cloneable data sources.
• Clarified order of events when writing to a file.

Version 0.9

Internal Review Draft

Version 0.8

JMF 2.0 Beta draft:

• Added an introduction to RTP, Working with Real-Time Media Streams, and updated the RTP chapters.
• Updated to reflect API changes since the Early Access release.
• Added an example of registering a plug-in with the PlugInManager.
• Added chapter, figure, table, and example numbers and changed the example code style.

Version 0.7

JMF 2.0 Early Access Release 1 draft:

• Updated and expanded RTP chapters in Part 2.
• Added Demultiplexer example to "Extending JMF".
• Updated to reflect API changes since the public review.

Version 0.6

Internal Review Draft

Version 0.5

JMF 2.0 API public review draft.

• Added new concepts chapter, "Working with Time-Based Media".
• Reorganized architecture information in "Understanding JMF".
• Incorporated RTP Guide as Part 2.

Version 0.4

JMF 2.0 API licensee review draft.

Comments

Please submit any comments or suggestions you have for improving this document to jmf-comments@eng.sun.com.