Java™ Media Framework API Guide

265 Pages·1999·2.86 MB·English

i
Java“ Media Framework
API Guide
November 19,1999
JMF 2.0 FCS
ii JMF API Guide
iii
(cid:211)
1998-99 Sun Microsystems, Inc.
2550 Garcia Avenue, Mountain View, California 94043-1100 U.S.A.
All rights reserved.
The images of the video camera, video tape, VCR, television, and speakers
on page 12 copyright www.arttoday.com.
RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the
U.S. Government is subject to restrictions of FAR 52.227-14(g)(2)(6/87)
and FAR 52.227-19(6/87), or DFAR 252.227-7015(b)(6/95) and DFAR
227.7202-1(a).
The release described in this document may be protected by one or more
U.S. patents, foreign patents, or pending applications.
Sun, the Sun logo, Sun Microsystems, JDK, Java, and the Java Coffee Cup
logo are trademarks or registered trademarks of Sun Microsystems, Inc. in
the United States and other countries.
THIS PUBLICATION IS PROVIDED (cid:210)AS IS(cid:211) WITHOUT WARRANTY OF
ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES
OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY
ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE
INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN
MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR
CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S)
DESCRIBED IN THIS PUBLICATION AT ANY TIME.
iv JMF API Guide
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiii
About JMF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Design Goals for the JMF API. . . . . . . . . . . . . . . . . . . . . . . xiv
About the JMF RTP APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . .xv
Design Goals for the JMF RTP APIs. . . . . . . . . . . . . . . xvi
Partners in the Development of the JMF API. . . . . . . . . .xvii
Contact Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvii
About this Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvii
Guide to Contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvii
Change History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xx
Part 1: Java“ Media Framework. . . . . . . . . . . . . . . . . . . . . . . .1
Working with Time-Based Media. . . . . . . . . . . . . . . . . . . . . . .3
Streaming Media . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Content Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Media Streams. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Common Media Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Media Presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Presentation Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Latency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Presentation Quality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
v
vi JMF API Guide
Media Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
Demultiplexers and Multiplexers . . . . . . . . . . . . . . . . . . . . . .9
Codecs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Effect Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Renderers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Compositing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Media Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Capture Devices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Capture Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Understanding JMF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
High-Level Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
Time Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Managers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
Event Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Data Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
Push and Pull Data Sources. . . . . . . . . . . . . . . . . . . . . . .17
Specialty DataSources. . . . . . . . . . . . . . . . . . . . . . . . . . . .18
Data Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Standard Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
User Interface Components . . . . . . . . . . . . . . . . . . . . . . . . . .23
Extensibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
Presentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Players. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Player States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Methods Available in Each Player State. . . . . . . . . . . . .28
Processors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Presentation Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Standard User Interface Components . . . . . . . . . . . . . .30
Controller Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Processor States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Methods Available in Each Processor State. . . . . . . . . .35
Processing Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Data Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
vii
Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Media Data Storage and Transmission. . . . . . . . . . . . . . . . . . . . 37
Storage Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Extensibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Implementing Plug-Ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Implementing MediaHandlers and DataSources. . . . . . . . 39
MediaHandler Construction. . . . . . . . . . . . . . . . . . . . . . 39
DataSource Construction. . . . . . . . . . . . . . . . . . . . . . . . . 42
Presenting Time-Based Media with JMF . . . . . . . . . . . . . . . .43
Controlling a Player. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Creating a Player. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Blocking Until a Player is Realized. . . . . . . . . . . . . . . . . 44
Using a ProcessorModel to Create a Processor . . . . . . 44
Displaying Media Interface Components . . . . . . . . . . . . . . 45
Displaying a Visual Component. . . . . . . . . . . . . . . . . . . 45
Displaying a Control Panel Component . . . . . . . . . . . . 45
Displaying a Gain-Control Component. . . . . . . . . . . . . 46
Displaying Custom Control Components. . . . . . . . . . . 46
Displaying a Download-Progress Component. . . . . . . 47
Setting the Playback Rate. . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Setting the Start Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Frame Positioning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Preparing to Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Realizing and Prefetching a Player. . . . . . . . . . . . . . . . . 49
Determining the Start Latency . . . . . . . . . . . . . . . . . . . . 50
Starting and Stopping the Presentation. . . . . . . . . . . . . . . . 50
Starting the Presentation . . . . . . . . . . . . . . . . . . . . . . . . . 50
Stopping the Presentation . . . . . . . . . . . . . . . . . . . . . . . . 50
Stopping the Presentation at a Specified Time. . . . . . . 51
Releasing Player Resources. . . . . . . . . . . . . . . . . . . . . . . . . . 52
Querying a Player . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Getting the Playback Rate . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Getting the Media Time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Getting the Time-Base Time . . . . . . . . . . . . . . . . . . . . . . . . . 54
Getting the Duration of the Media Stream . . . . . . . . . . . . . 54
viii JMF API Guide
Responding to Media Events . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Implementing the ControllerListener Interface . . . . . . . . .54
Using ControllerAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
Synchronizing Multiple Media Streams . . . . . . . . . . . . . . . . . . .56
Using a Player to Synchronize Controllers . . . . . . . . . . . . .57
Adding a Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Controlling Managed Controllers. . . . . . . . . . . . . . . . . .58
Removing a Controller . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Synchronizing Players Directly. . . . . . . . . . . . . . . . . . . . . . .60
Example: Playing an MPEG Movie in an Applet. . . . . . . . . . . .61
Overview of PlayerApplet. . . . . . . . . . . . . . . . . . . . . . . . . . .62
Initializing the Applet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Controlling the Player. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Responding to Media Events. . . . . . . . . . . . . . . . . . . . . . . . .66
Presenting Media with the MediaPlayer Bean. . . . . . . . . . . . . .66
Presenting RTP Media Streams . . . . . . . . . . . . . . . . . . . . . . . . . .68
Listening for RTP Format Changes. . . . . . . . . . . . . . . . . . . .69
Processing Time-Based Media with JMF. . . . . . . . . . . . . . . .71
Selecting Track Processing Options . . . . . . . . . . . . . . . . . . .72
Converting Media Data from One Format to Another. . . . . . .73
Specifying the Output Data Format . . . . . . . . . . . . . . . . . . .73
Specifying the Media Destination . . . . . . . . . . . . . . . . . . . . . . . .73
Selecting a Renderer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Writing Media Data to a File . . . . . . . . . . . . . . . . . . . . . . . . .74
Connecting a Processor to another Player. . . . . . . . . . . . . .75
Using JMF Plug-Ins as Stand-alone Processing Modules. . . . .75
Capturing Time-Based Media with JMF . . . . . . . . . . . . . . . .77
Accessing Capture Devices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
Capturing Media Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Allowing the User to Control the Capture Process. . . . . . . . . .78
ix
Storing Captured Media Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Example: Capturing and Playing Live Audio Data . . . . . . . . . 79
Example: Writing Captured Audio Data to a File. . . . . . . . . . . 80
Example: Encoding Captured Audio Data . . . . . . . . . . . . . . . . 82
Example: Capturing and Saving Audio and Video Data. . . . . 83
Extending JMF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Implementing JMF Plug-Ins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Implementing a Demultiplexer Plug-In. . . . . . . . . . . . . . . . 85
Implementing a Codec or Effect Plug-In. . . . . . . . . . . . . . . 88
Effect Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Example: GainEffect Plug-In . . . . . . . . . . . . . . . . . . . . . . 89
Implementing a Multiplexer Plug-In. . . . . . . . . . . . . . . . . . 94
Implementing a Renderer Plug-In . . . . . . . . . . . . . . . . . . . . 95
Example: AWTRenderer . . . . . . . . . . . . . . . . . . . . . . . . . 95
Registering a Custom Plug-In. . . . . . . . . . . . . . . . . . . . . . . 101
Implementing Custom Data Sources and Media Handlers. . 102
Implementing a Protocol Data Source. . . . . . . . . . . . . . . . 102
Example: Creating an FTP DataSource . . . . . . . . . . . . 103
Integrating a Custom Data Source with JMF . . . . . . . . . . 103
Implementing a Basic Controller . . . . . . . . . . . . . . . . . . . . 104
Example: Creating a Timeline Controller . . . . . . . . . . 104
Implementing a DataSink . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Integrating a Custom Media Handler with JMF . . . . . . . 105
Registering a Capture Device with JMF. . . . . . . . . . . . . . . . . . 106
Part 2: Real-Time Transport Protocol . . . . . . . . . . . . . . . . . .107
Working with Real-Time Media Streams. . . . . . . . . . . . . . .109
Streaming Media . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Protocols for Streaming Media. . . . . . . . . . . . . . . . . . . . . . 109
Real-Time Transport Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 110
RTP Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
x JMF API Guide
RTP Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
Data Packets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
Control Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
RTP Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Receiving Media Streams From the Network. . . . . . . . . .115
Transmitting Media Streams Across the Network. . . . . .115
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
Understanding the JMF RTP API . . . . . . . . . . . . . . . . . . . . . 117
RTP Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
Session Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Session Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Session Participants. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Session Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
RTP Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Session Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Send Stream Listener. . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Receive Stream Listener . . . . . . . . . . . . . . . . . . . . . . . . .123
Remote Listener. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
RTP Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
Data Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
RTP Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Reception. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Transmission. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
Extensibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
Implementing Custom Packetizers and Depacketizers. .127
Receiving and Presenting RTP Media Streams. . . . . . . . . . 129
Creating a Player for an RTP Session . . . . . . . . . . . . . . . . . . . .130
Listening for Format Changes. . . . . . . . . . . . . . . . . . . . . . .131
Creating an RTP Player for Each New Receive Stream . . . . .132
Handling RTP Payload Changes. . . . . . . . . . . . . . . . . . . . .136
Controlling Buffering of Incoming RTP Streams . . . . . . .137
Presenting RTP Streams with RTPSocket. . . . . . . . . . . . . . . . .138