Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Tour the JMC Playback API
The default control panel provided by JMediaPlayer is mostly useful, but doesn't have the classy look that's associated with Web-based media players.
Fortunately, you don't need to stick with this control panel—you can create a media player with a control panel that looks much slicker and provides more capabilities. Before you can do this, however, you need to understand JMC's Playback API.
We'll start our API tour with JMediaPlayer, which subclasses javax.swing.JComponent. Along with the aforementioned constructor, JMediaPlayer offers the following constructor and methods:
- public JMediaPlayer() creates a media player with no initial media content.
- public void play() plays the current media stream from the start or most recent pause point.
- public void stop() stops a playing media stream.
- public void pause() pauses a playing media stream.
- public void setSource(URI uri) specifies the uri-identified media content to this media player.
- public URI getSource() returns this media player's current media content uniform resource identifier.
- public float setVolume(float volume) sets the audio volume to volume, a value from 0.0f (mute) through 1.0f (full blast).
- public float getVolume() returns this media player's current volume setting.
- public void setMute(boolean mute) disables (pass true to mute) or enables (pass false to mute) this media player's audio.
- public boolean isMute() returns this media player's current mute setting.
- public void setRepeating(boolean repeats) tells this media player to automatically repeat the playing media after this media finishes (pass true to repeat) or not repeat the playing media (pass false to repeat).
- public boolean isRepeating() returns this media player's current repeating setting.
- public void setAutoPlay(boolean autoPlay) tells this media player to automatically start playing the media that's specified by and following a call to setSource().
- public boolean isAutoPlay() returns this media player's current autoplay setting.
JMediaPlayer is largely a wrapper for com.sun.media.jmc.JMediaPane, another subclass of JComponent. JMediaPane provides media playback without also providing user interface controls.
This class offers the following constructors and methods:
- public JMediaPane() creates a media player with no initial media content.
- public JMediaPane(URI uri) creates a media player with the uri-specified media content.
- public void setSource(URI uri) specifies the uri-identified media content to this media player.
- public URI getSource() returns this media player's current media content uniform resource identifier.
- public void play() plays the current media stream from the start or most recent pause point.
- public void stop() stops a playing media stream.
- public void pause() pauses a playing media stream.
- public float setVolume(float volume) sets the audio volume to volume, a value from 0.0f (mute) through 1.0f (full blast).
- public float getVolume() returns this media player's current volume setting.
- public void setMute(boolean mute) disables (pass true to mute) or enables (pass false to mute) this media player's audio.
- public boolean isMute() returns this media player's current mute setting.
- public void setRepeating(boolean repeat) tells this media player to automatically repeat the playing media after this media finishes (pass true to repeat) or not repeat the playing media (pass false to repeat).
- public boolean isRepeating() returns this media player's current repeating setting.
- public void setAutoPlay(boolean autoPlay) tells this media player to automatically start playing the media that's specified by and following a call to setSource().
- public boolean isAutoPlay() returns this media player's current autoplay setting.
- public boolean isSeekable() returns true if the media is seekable.
- public double seek(double offset) is a synonym for setMediaTime().
- public double setMediaTime(double mediaTime) sets the point at which media will be played to mediaTime.
- public double getMediaTime() returns this media player's current media time setting.
- public double getDuration() returns the media's duration (in seconds).
- public double setStartTime(double startTime) sets the starting point for playing a subset of the media to startTime.
- public double setStopTime(double stopTime) sets the stopping point for playing a subset of the media to stopTime.
- public double setRate(double rate) sets the rate at which the media will be played to rate.
- public double getRate() returns this media player's current rate setting.
- public boolean isPlaying() returns true if the media is currently playing.
- public void setPreserveAspectRatio(boolean preserve) specifies that this media player should preserve the media's aspect ratio when resized (pass true to preserve) or stretch the media to accommodate the new size (pass false to preserve).
- public boolean isPreserveAspectRatio() returns this media player's current preserve aspect ratio setting.
- public void addNotificationTime(double time, com.sun.media.jmc.event.MediaTimeListener listener) registers with this media player a listener whose code executes at the specified time.
- public boolean isNotificationTimeSupported() returns true if this media player is capable of providing notification of significant points during media playback—this method is implemented to always return true.
- public void removeNotificationTime(double time, MediaTimeListener listener) unregisters a listener that was previously registered with this media player to execute at the specified time.
Because I noticed that the addNotificationTime() method appears to always throw a com.sun.media.jmc.OperationUnsupportedException object, it doesn't seem possible to take advantage of notification times, which could have led to all sorts of interesting scenarios (synchronizing a window of advertisements to a playing video, for example).
We can take advantage of JMediaPane and some of its methods to create a media player with a custom control panel, which presents information not accessible via JMediaPlayer.
For example, our custom control panel can let users choose whether or not to preserve the media's aspect ratio when the player's window is resized, and also display the media's duration. Check out Listing 2.
Listing 2 XMP1.java
// XMP1 (eXperimental Media Player #1).java
import java.awt.BorderLayout;
import java.awt.EventQueue;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import java.net.URI;
import javax.swing.JButton;
import javax.swing.JCheckBox;
import javax.swing.JFrame;
import javax.swing.JLabel;
import javax.swing.JPanel;
import javax.swing.event.ChangeEvent;
import javax.swing.event.ChangeListener;
import com.sun.media.jmc.JMediaPane;
public class XMP1 extends JFrame
{
JMediaPane mp;
public XMP1 (String mediaURI)
{
super ("XMP1: "+mediaURI);
setDefaultCloseOperation (EXIT_ON_CLOSE);
try
{
mp = new JMediaPane (new URI (mediaURI));
}
catch (Exception e)
{
System.out.println ("Error opening media: "+e.toString ());
System.exit (1);
}
JPanel panel = new JPanel ();
panel.setLayout (new BorderLayout ());
panel.add (mp, BorderLayout.CENTER);
panel.add (createControlPanel (), BorderLayout.SOUTH);
setContentPane (panel);
pack ();
setVisible (true);
}
public JPanel createControlPanel ()
{
JPanel panel = new JPanel ();
JButton btnPlay = new JButton ("Play");
ActionListener alPlay = new ActionListener ()
{
public void actionPerformed (ActionEvent ae)
{
mp.play ();
}
};
btnPlay.addActionListener (alPlay);
panel.add (btnPlay);
JButton btnPause = new JButton ("Pause");
ActionListener alPause = new ActionListener ()
{
public void actionPerformed (ActionEvent ae)
{
mp.pause ();
}
};
btnPause.addActionListener (alPause);
panel.add (btnPause);
JButton btnStop = new JButton ("Stop");
ActionListener alStop = new ActionListener ()
{
public void actionPerformed (ActionEvent ae)
{
mp.stop ();
}
};
btnStop.addActionListener (alStop);
panel.add (btnStop);
JCheckBox cbPAR = new JCheckBox ("Preserve Aspect Ratio", true);
ChangeListener clPAR = new ChangeListener ()
{
public void stateChanged (ChangeEvent ce)
{
JCheckBox cb;
cb = (JCheckBox) ce.getSource ();
mp.setPreserveAspectRatio (cb.isSelected ());
}
};
cbPAR.addChangeListener (clPAR);
panel.add (cbPAR);
panel.add (new JLabel ("Duration: "+mp.getDuration ()));
return panel;
}
public static void main (final String [] args)
{
if (args.length != 1)
{
System.err.println ("usage: java XMP1 mediaURI");
return;
}
Runnable r = new Runnable ()
{
public void run ()
{
new XMP1 (args [0]);
}
};
EventQueue.invokeLater (r);
}
}
Compile and run this experimental media player application via commands that are similar to those shown earlier.
Figure 2 shows the resulting media player's user interface.
)
Figure 2 In addition to letting you play, pause, and stop media, this custom control panel lets you determine whether the media's aspect ratio is preserved during a window resize, and reports the media's duration (in seconds).
JMediaPane internally works with the com.sun.media.jmc.MediaProvider class, which is a low-level media player control that provides access to the various controls responsible for rendering the media.
This class offers the following constructors and methods:
- public MediaProvider() creates a media player with no initial media content.
- public MediaProvider(URI uri) creates a media player with the uri-specified media content.
- public static java.util.List<com.sun.media.jmc.type.ContainerType> getSupportedContainerTypes() returns a list of ContainerType objects that identify the various media containers (AVI, SWF, MOV, MP4, MIDI, and so on) supported by this media player.
- public static boolean renderingControlSupported(URI uri) returns true if uri ends with the .ogg extension.
- public static List<com.sun.media.jmc.type.ProtocolType> getSupportedProtocols(com.sun.media.jmc.type.EncodingType type) always returns null.
- public static List<EncodingType> getSupportedEncodings(ContainerType type) always returns null.
- public <T extends com.sun.media.jmc.control.MediaControl> T getControl(Class<T> controlClass) returns the instance of the controlClass-identified media control, cast to the controlClass type, that's being used by this media player, or null if there is no such instance—pass com.sun.media.jmc.control.AudioControl.class, com.sun.media.jmc.control.VideoControl.class, com.sun.media.jmc.control.VideoRenderControl.class, com.sun.media.jmc.control.TrackControl.class, or com.sun.media.jmc.control.PlayControl.class to controlClass.
- public List<MediaControl> getControls() returns a list of all MediaControl instances that are being used by this media player.
- public java.util.Map<com.sun.media.jmc.MediaProvider.CapabilityKey, Object> getCapabilities() returns a map of capability names and (currently) Boolean objects whose true/false values indicate whether or not specific capabilities are supported by this media player.
- public <T> T getCapability(CapabilityKey key, Class<T> capValueClass) returns the value of the capability setting identified by key. Example: getCapability (CapabilityKey.SUPPORTS_SEEKING, Boolean.class) returns a Boolean whose value tells you if this media player will let you seek to arbitrary points in the media stream.
- public <T extends MediaControl> List<T> getControls(Class<T> controlClass) returns a list of all MediaControl instances that are being used by this media player and whose type matches controlClass.
- public void setSource(URI uri) specifies the uri-identified media content to this media player.
- public URI getSource() returns this media player's current media content uniform resource identifier.
- public void play() plays the current media stream from the start or most recent pause point.
- public void pause() pauses a playing media stream.
- public double setMediaTime(double mediaTime) sets the point at which media will be played to mediaTime.
- public double getMediaTime() returns this media player's current media time setting.
- public double setStartTime(double startTime) sets the starting point for playing a subset of the media to startTime.
- public double getStartTime() returns this media player's current start time setting.
- public double setStopTime(double stopTime) sets the stopping point for playing a subset of the media to stopTime.
- public double getStopTime() returns this media player's current stop time setting.
- public double getDuration() returns the media's duration (in seconds).
- public double setRate(double rate) sets the rate at which the media will be played to rate.
- public double getRate() returns this media player's current rate setting.
- public boolean isPlaying() returns true if the media is currently playing.
- public void addNotificationTime(double time, MediaTimeListener listener, boolean unknown) invokes the method below when false is passed to unknown.
- public void addNotificationTime(double time, MediaTimeListener listener) registers with this media player a listener whose code executes at the specified time.
- public void removeNotificationTime(double time, MediaTimeListener listener) unregisters a listener that was previously registered with this media player to execute at the specified time.
- public boolean isNotificationTimeSupported() returns true if this media player is capable of providing notification of significant points during media playback.
- public void setRepeating(boolean repeating) tells this media player to automatically repeat the playing media after this media finishes (pass true to repeat) or not repeat the playing media (pass false to repeat).
- public boolean isRepeating() returns this media player's current repeating setting.
- public void setPlayCount(int count) informs this media player to play the media count times.
- public int getPlayCount() returns the number of times that the media is to be played.
- public void setCurrentPlayCount(int count) informs this media player that the media has played count times.
- public int getCurrentPlayCount() returns the number of times that the media has played.
- public String getName() returns this control's name, "MediaProvider Play Control".
- public void addMediaDurationListener(com.sun.media.jmc.event.MediaDurationListener listener) registers a listener with this media player that's informed whenever the media's duration changes.
- public void removeMediaDurationListener(MediaDurationListener listener) unregisters the previously registered listener from this media player.
- public void addBufferDownloadListener(com.sun.media.jmc.event.BufferDownloadListener listener) registers a listener with this media player that's informed whenever additional media content is downloaded.
- public void removeBufferDownloadListener(BufferDownloadListener listener) unregisters the previously registered listener from this media player.
- public void addMediaStateListener(com.sun.media.jmc.event.MediaStateListener listener) registers a listener with this media player that's informed whenever this media player's state changes—end-of-media, player starting, and player stopping are examples.
- public void removeMediaStateListener(MediaStateListener listener) unregisters the previously registered listener from this media player.
- public void addMediaSizeListener(com.sun.media.jmc.event.MediaSizeListener listener) registers a listener with this media player that's informed whenever the size of the component on which the media is rendered changes.
- public void removeMediaSizeListener(MediaSizeListener listener) unregisters the previously registered listener from this media player.
- public void addPropertyChangeListener(java.beans.PropertyChangeListener listener) registers a listener with this media player that's informed whenever one of its properties (such as playback rate), or whenever one its control's properties (such as the audio control's mute property) changes.
- public void removePropertyChangeListener(PropertyChangeListener listener) unregisters the previously registered listener from this media player.
To create a more interesting and useful media player, you need to become familiar with the Playback API's control classes.
Although you've just encountered one such class, MediaProvider, this API also provides the following control classes: AudioControl, TrackControl, VideoControl, and VideoRenderControl.
I built an experimental media player that showcases MediaProvider, AudioControl, and VideoRenderControl. AudioControl is used to mute/unmute audio playback— audio is not MediaProvider's responsibility. VideoRenderControl is needed to render an overlay (content appearing over other content), as illustrated in Figure 3.
)
Figure 3 Each video frame is overlaid with my javajeff.mb.ca brand in its upper-left corner.
The media player (see Listing 3 for its source code) creates a television-like branding effect, in which a station logo appears near the screen's lower-right corner, via an overlay. However, the overlay is located near each video frame's upper-left corner.
Antialiasing makes the foreground text look sharp; different opacities for the background rectangle and the foreground text allow each video frame to show through.
Listing 3 XMP2.java
// XMP2 (eXperimental Media Player #2).java
import java.awt.AlphaComposite;
import java.awt.BorderLayout;
import java.awt.Color;
import java.awt.Dimension;
import java.awt.EventQueue;
import java.awt.Font;
import java.awt.Graphics;
import java.awt.Graphics2D;
import java.awt.Rectangle;
import java.awt.RenderingHints;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import java.awt.geom.Rectangle2D;
import java.net.URI;
import javax.swing.JButton;
import javax.swing.JCheckBox;
import javax.swing.JFrame;
import javax.swing.JLabel;
import javax.swing.JPanel;
import javax.swing.event.ChangeEvent;
import javax.swing.event.ChangeListener;
import com.sun.media.jmc.MediaProvider;
import com.sun.media.jmc.control.AudioControl;
import com.sun.media.jmc.control.VideoRenderControl;
import com.sun.media.jmc.event.VideoRendererEvent;
import com.sun.media.jmc.event.VideoRendererListener;
public class XMP2 extends JFrame
{
MediaProvider mp;
public XMP2 (String mediaURI)
{
super ("XMP2: "+mediaURI);
setDefaultCloseOperation (EXIT_ON_CLOSE);
try
{
mp = new MediaProvider (new URI (mediaURI));
}
catch (Exception e)
{
System.out.println ("Error opening media: "+e.toString ());
System.exit (1);
}
JPanel panel = new JPanel ();
panel.setLayout (new BorderLayout ());
panel.add (new MediaPanel (mp), BorderLayout.CENTER);
panel.add (createControlPanel (), BorderLayout.SOUTH);
setContentPane (panel);
pack ();
setVisible (true);
}
public JPanel createControlPanel ()
{
JPanel panel = new JPanel ();
JButton btnPlay = new JButton ("Play");
ActionListener alPlay = new ActionListener ()
{
public void actionPerformed (ActionEvent ae)
{
mp.play ();
}
};
btnPlay.addActionListener (alPlay);
panel.add (btnPlay);
JButton btnPause = new JButton ("Pause");
ActionListener alPause = new ActionListener ()
{
public void actionPerformed (ActionEvent ae)
{
mp.pause ();
}
};
btnPause.addActionListener (alPause);
panel.add (btnPause);
JButton btnStop = new JButton ("Stop");
ActionListener alStop = new ActionListener ()
{
public void actionPerformed (ActionEvent ae)
{
mp.pause ();
mp.setMediaTime (0.0);
}
};
btnStop.addActionListener (alStop);
panel.add (btnStop);
JCheckBox cbMute = new JCheckBox ("Mute");
ChangeListener clMute = new ChangeListener ()
{
public void stateChanged (ChangeEvent ce)
{
JCheckBox cb;
cb = (JCheckBox) ce.getSource ();
AudioControl ac;
ac = mp.getControl (AudioControl.class);
ac.setMute (cb.isSelected ());
}
};
cbMute.addChangeListener (clMute);
panel.add (cbMute);
panel.add (new JLabel ("Duration: "+mp.getDuration ()));
return panel;
}
public static void main (final String [] args)
{
if (args.length != 1)
{
System.err.println ("usage: java XMP2 mediaURI");
return;
}
Runnable r = new Runnable ()
{
public void run ()
{
new XMP2 (args [0]);
}
};
EventQueue.invokeLater (r);
}
}
class MediaPanel extends JPanel
{
private AlphaComposite ac1 =
AlphaComposite.getInstance (AlphaComposite.SRC_OVER, 0.1f);
private AlphaComposite ac2 =
AlphaComposite.getInstance (AlphaComposite.SRC_OVER, 0.3f);
private Dimension frameSize;
private Font font = new Font ("Arial", Font.BOLD, 16);
private Rectangle frame = new Rectangle (0, 0, 0, 0);
private Rectangle2D r2d = new Rectangle2D.Double (0.0, 0.0, 0.0, 0.0);
private VideoRenderControl vrc;
MediaPanel (MediaProvider mp)
{
vrc = mp.getControl (VideoRenderControl.class);
if (vrc == null)
{
System.err.println ("no video renderer control");
System.exit (-1);
}
frameSize = vrc.getFrameSize ();
VideoRendererListener vrl;
vrl = new VideoRendererListener ()
{
public void videoFrameUpdated (VideoRendererEvent vre)
{
repaint ();
}
};
vrc.addVideoRendererListener (vrl);
setPreferredSize (new Dimension (frameSize.width/2, frameSize.height/2));
}
protected void paintComponent (Graphics g)
{
frame.width = getWidth ();
frame.height = getHeight ();
vrc.paintVideoFrame (g, frame);
double ar1 = frame.width/(double) frameSize.width;
double ar2 = frame.height/(double) frameSize.height;
double x, y;
if (ar1 < ar2)
{
x = (frame.width-frameSize.width*ar1)/2+10.0;
y = (frame.height-frameSize.height*ar1)/2+10.0;
}
else
{
x = (frame.width-frameSize.width*ar2)/2+10.0;
y = (frame.height-frameSize.height*ar2)/2+10.0;
}
Graphics2D g2d = (Graphics2D) g;
g2d.setRenderingHint (RenderingHints.KEY_ANTIALIASING,
RenderingHints.VALUE_ANTIALIAS_ON);
g2d.setComposite (ac1);
g2d.setPaint (Color.black);
r2d.setFrame (x, y, 125.0, 50.0);
g2d.fill (r2d);
g2d.setComposite (ac2);
g2d.setFont (font);
g2d.setPaint (Color.yellow);
g2d.drawString ("javajeff.mb.ca", (int) x+10, (int) y+30);
}
}
Unlike JMediaPlayer and JMediaPane, MediaProvider isn't a component. As a result, Listing 3 declares a MediaPanel instance that will serve as the Swing component on which video frames are rendered.
This class's constructor is passed a MediaProvider instance so that a VideoRenderControl instance can be obtained.
The VideoRenderControl instance is obtained via a call to MediaProvider's getControl() method. A com.sun.media.jmc.event.VideoRendererListener is registered with this control so that it will repaint the MediaPanel component each time the videoFrameUpdated() method is invoked.
The repaint() method call within videoFrameUpdated() triggers a request to Swing to invoke MediaPanel's paintComponent() method.
This method first invokes VideoRenderControl's public abstract void paintVideoFrame(Graphics g, Rectangle rect) method to render the video frame. It then renders the previously discussed overlay.
The paintComponent() method has the potential to be called extremely often—more than 100,000 times for a 30-frame-per-second/60-minute video.
If it creates even one object, we'll probably end up with a huge number of objects in the heap.
This could result in garbage collection activity that disrupts playback. To reduce this possibility, paintComponent() reuses objects (such as frame).
There is another point of interest within paintComponent()— specifically, the calculation of the overlay's upper-left corner coordinates.
Because each video frame will be rendered at the correct aspect ratio and in the center of the media panel, it's necessary to calculate the actual video frame size and media panel aspect ratios (width/height) and use them in calculations that help determine the proper coordinates.
There are two more items to consider. First, stopping a media stream requires calls to pause() followed by setMediaTime() with a 0.0 argument because MediaProvider doesn't provide a stop() method.
Second, muting the audio requires an AudioControl instance because MediaProvider doesn't provide a setMute() method.
The Playback API contains many more classes and interfaces to explore. For example, the com.sun.media.jmc.JMediaView class describes yet another Swing component for integrating a media player into a Swing GUI.
However, our exploration of the Playback API has come to an end for reasons of brevity and also because I've presented sufficient material for use in constructing an advanced media player.