IBM Toolkit
for MPEG-4

player
Interface PlayerControl


public interface PlayerControl

MPEG-4 Player Control interface. This is the interface via which the MPEG-4 player subsystem can be controlled. It has high level methods to open content, play, pause, stop etc that control the playback of MPEG-4 media content from files and over a variety of network protocols. There are also methods to get and set other parameters that affect playback such as volume, render rate, scaling etc.

In addition PlayerListener instance(s) can be added to receive state change and other event notifications from the MPEG-4 player subsystem.


Field Summary
static int CLOSED
          Player presentation state 'CLOSED' constant
static int END_ACTION_CONTINUE
          Player constant to set Continue at end action
static int END_ACTION_REPEAT
          Player constant to set Repeat (loop) at end action
static int END_ACTION_STOP
          Player constant to set Stop at end action
static int PAUSED
          Player presentation state 'PAUSED' constant
static int PLAYING
          Player presentation state 'PLAYING' constant
static int RTSP_AUTO
          RTSP Mode Automatic.
static int RTSP_HTTP_TUNNEL
          RTSP Mode HTTP Tunnelling.
static int RTSP_TCP_INTERLEAVE
          RTSP Mode TCP Interleave.
static int RTSP_TCP_INTERLEAVE_UDP
          RTSP Mode TCP Interleave and/or UDP.
static int RTSP_UDP
          RTSP Mode UDP.
static int STOPPED
          Player presentation state 'STOPPED' constant
 
Method Summary
 void addListener(PlayerListener pl)
          Add (register) a player listener.
 boolean canPause()
          Indicates whether the player has the ability to pause the current presentation or not.
 boolean canSeek()
          Return whether the player has the ability to seek into the current presentation or not.
 boolean canSetVolume()
          Indicates whether the player has the ability to set the audio volume.
 void close()
          Close any opened content.
 float getActualFPS()
          Get actual compositor rendering frame rate.
 boolean getAutoSize()
          Indicates the autoSize value
 int getBufferingLevel()
          Gets the player buffering level.
 long getDuration()
          Get the specified (known) duration of the current presentation.
 float getFPS()
          Get the compositor render frame rate that is set
 boolean getMetrics()
          Indicates if pixel metrics are being used for scene.
 boolean getMute()
          Get the mute state.
 int getPlayerEndAction()
          Get the EndAction behavior.
 java.awt.Dimension getPreferredSceneSize()
          Get the desired scene size of the presentation.
 java.awt.Component getRendererComponent()
          Get the player component that contains the rendered output so it can be added to an appropriate container of the applications choosing.
 int getRTSPMode()
          Gets the current RTSP mode set
 long getRTSPPacketOutOfOrderDelay()
          Gets the current RTSP packet out-of-order delay
 boolean getScaling()
          Get the scaling setting.
 PlayerScreenCapture getScreenCapture()
          Returns a PlayerScreenCapture interface to access the pixels captured from the current rendered image.
 java.lang.String[] getScreenCaptureFormats()
          Returns an array of supported formats that can be specified for writing in the PlayerScreenCapture object returned by getScreenCapture().
 java.awt.Dimension getSize()
          Get the actual player Size at this time.
 double getSpeed()
          Get the speed of the presentation.
 boolean getSpeedScaling()
          Gets speed scaling hint
 int getState()
          Get the current MPEG-4 player presentation state.
 java.lang.String getStateName()
          Get the current MPEG-4 player presentation state.
 long getTime()
          Get the current presentation time.
 double getVolume()
          Get the volume level of the presentation.
 boolean hasDuration()
          Return whether the duration of the current presentation is known.
 boolean hasPreferredSceneSize()
          Indicates whether the presentation has a desired scene size.
 boolean isListener(PlayerListener pl)
          Test if PlayerListener object is a registered player listener
 void open(java.lang.String url)
          Open content referenced by the URL.
 void pause()
          Pause the currently playing presentation (playing is resumed with the resume() method).
 boolean playUrl(java.lang.String url)
          Play a URL.
 void registerStreamMonitoring(PlayerStreamMonitoring psm)
          Registers the PlayerStreamMonitoring instance that is to be used to monitor the content of streams.
 void removeListener(PlayerListener pl)
          Remove a player listener
 void resume()
          Resume playing a presentation from where it is currently paused.
 void seek(long presTime)
          Seek to a particular point in the presentation.
 void setAutoSize(boolean autoSize)
          Sets the Player to auto size or not.
 void setBufferingLevel(int percentage)
          Sets the player buffering level.
 void setFPS(float fps)
          Set compositor render frame rate in frames per second.
 void setMute(boolean mute)
          Mute any audio.
 void setPlayerEndAction(int action)
          Set the EndAction.
 boolean setRTSPMode(int mode)
          Sets the RTSP playback mode for when/if media is retrieved using RTSP.
 void setRTSPPacketOutOfOrderDelay(long ms)
          Sets the RTSP packet out-of-order delay.
 void setScaling(boolean scale)
          Set whether presentations in pixel metrics can scale or not (presentations that are in meter metrics always scale such that the display width is +/- one meter and vertical dimension is ratio of height/width as per MPEG-4 Systems specification)
 void setSize(int width, int height)
          Set the actual player Size.
 void setSpeed(double speed)
          Set the speed of the presentation.
 void setSpeedScaling(boolean speedScaling)
          Set speed scaling hint - true to do scaling by speed, false to do quality.
 void setVolume(double volume)
          Set the volume level of the presentation.
 void start()
          Start playing content that has already been opened by a prior call to open(URL).
 void step(long mSecs)
          Step the presentation forward by the given number of milliseconds.
 void stop()
          Stop playing the current presentation, which may be playing, paused, or already stopped.
 boolean stopUrl()
          Stop playing a URL.
 

Field Detail

CLOSED

public static final int CLOSED
Player presentation state 'CLOSED' constant

See Also:
Constant Field Values

STOPPED

public static final int STOPPED
Player presentation state 'STOPPED' constant

See Also:
Constant Field Values

PLAYING

public static final int PLAYING
Player presentation state 'PLAYING' constant

See Also:
Constant Field Values

PAUSED

public static final int PAUSED
Player presentation state 'PAUSED' constant

See Also:
Constant Field Values

END_ACTION_CONTINUE

public static final int END_ACTION_CONTINUE
Player constant to set Continue at end action

See Also:
Constant Field Values

END_ACTION_STOP

public static final int END_ACTION_STOP
Player constant to set Stop at end action

See Also:
Constant Field Values

END_ACTION_REPEAT

public static final int END_ACTION_REPEAT
Player constant to set Repeat (loop) at end action

See Also:
Constant Field Values

RTSP_AUTO

public static final int RTSP_AUTO
RTSP Mode Automatic. Tries 'Http tunnel' mode first and if that fails tries 'TCP Interleave and/or UDP'

See Also:
Constant Field Values

RTSP_UDP

public static final int RTSP_UDP
RTSP Mode UDP. Media channels are setup using UDP as transport

See Also:
Constant Field Values

RTSP_TCP_INTERLEAVE

public static final int RTSP_TCP_INTERLEAVE
RTSP Mode TCP Interleave. Media channels are setup as interleaved channels in RTSP TCP connection

See Also:
Constant Field Values

RTSP_HTTP_TUNNEL

public static final int RTSP_HTTP_TUNNEL
RTSP Mode HTTP Tunnelling. RTSP is tunneled over HTTP and media channels are setup as interleaved channels in RTSP TCP connection

See Also:
Constant Field Values

RTSP_TCP_INTERLEAVE_UDP

public static final int RTSP_TCP_INTERLEAVE_UDP
RTSP Mode TCP Interleave and/or UDP. Media channels are setup either as interleaved or UDP dependent on media type and reliability requirements

See Also:
Constant Field Values
Method Detail

addListener

public void addListener(PlayerListener pl)
Add (register) a player listener. After being added the PlayerListener will receive callbacks to inform of state change etc

Parameters:
pl - The PlayerListener

isListener

public boolean isListener(PlayerListener pl)
Test if PlayerListener object is a registered player listener

Parameters:
pl - The PlayerListener

removeListener

public void removeListener(PlayerListener pl)
Remove a player listener

Parameters:
pl - The PlayerListener

getRendererComponent

public java.awt.Component getRendererComponent()
Get the player component that contains the rendered output so it can be added to an appropriate container of the applications choosing.

Returns:
The player Component that is used for rendering

playUrl

public boolean playUrl(java.lang.String url)
Play a URL. Regardless of state, this will cause the MPEG-4 player to open and start playing the content specified by a new URL. No exceptions are thrown. Instead success or failure is signalled with a return value.

Parameters:
url - URL of the presentation.
Returns:
true if the play was successfully started.

stopUrl

public boolean stopUrl()
Stop playing a URL. Regardless of state, this will cause the MPEG-4 player be put in a Closed state. No exceptions are thrown. Instead, success or failure is signalled with a return value.

Returns:
true if the play was successfully stopped.

getState

public int getState()
Get the current MPEG-4 player presentation state.

Returns:
The presentation state; one of the constants CLOSED, STOPPED etc

getStateName

public java.lang.String getStateName()
Get the current MPEG-4 player presentation state.

Returns:
The presentation state as a String e.g. "Closed", "Stopped" etc

open

public void open(java.lang.String url)
          throws java.io.IOException,
                 java.lang.IllegalStateException
Open content referenced by the URL. Valid urls depend on the network support modules available. To access a file "C:\myFolder\x.mp4" etc, the file:// protocol can be omitted or explicitly specified eg "file:///C:/myFolder/x.mp4". Other protocols may be supported such as "rtsp://myServer.com/x.mp4", "http://www.myWeb.com/x.mx4"

This will initialize the various components of the player and go to the Stopped state, so it will not start playing the presentation . A network connection will be established as needed to access the content (e.g. when using RTSP a session will be established with the media server). In this state information about the content is now available such as its duration, whether the content can be paused and seek supported. This information can be used to set-up the user interface before the presentation is started. To start playback, a call to start() must be made.

Parameters:
url - URL string referencing the content.
Throws:
java.io.IOException - If there's an I/O problem with this URL.
java.lang.IllegalStateException - If there's a presentation already open (state must be Closed).

close

public void close()
           throws java.io.IOException
Close any opened content. This will release all resources related to the opened URL regardless of the presentation state. Any playing or paused presentation will first be stopped.

Throws:
java.io.IOException - If there's an I/O problem closing.

start

public void start()
           throws java.io.IOException,
                  java.lang.IllegalStateException
Start playing content that has already been opened by a prior call to open(URL). The player should be in Stopped state.

Note: if start() is called when the player is in Closed state the PlayerListener method playRequestWhenClosed() is called. This to allow a main player shell to use the various PlayerControlPanels and have the Play button enabled even though content has not been opened. Since opening content creates a network connection and allocates resources it may be undesirable to open content unless the user wants to play it - e.g. in an applet setting on a web page there may be content presented this way such that the play button indicates it can be played. The main shell should implement the playRequestWhenClosed() method if it uses the PlayerControlPanel feature to enable play button in Closed state. In the implementation the player should open(url) for the content and then start() to play the content as per the users request.

Throws:
java.io.IOException - If there's an I/O problem starting.
java.lang.IllegalStateException - If the state is Playing or Paused

stop

public void stop()
          throws java.io.IOException,
                 java.lang.IllegalStateException
Stop playing the current presentation, which may be playing, paused, or already stopped. This will put the player in Stopped state.

Throws:
java.io.IOException - If there's an I/O problem stopping.
java.lang.IllegalStateException - If there's no presentation open (so the state may not be Closed).

setPlayerEndAction

public void setPlayerEndAction(int action)
Set the EndAction. This is the action the MPEG-4 player will take when the presentation reaches the specified duration for the content, the specified duration being that returned by getDuration(). If the content has no duration, i.e its unknown, then no end action will occur as the duration is indefinite. End actions that can be specified are Continue, Stop and Repeat. Continue will allow the presentation to continue beyond any specified duration, so for instance any in-scene animations will continue etc; for media such as video or audio that have a finite length this option is not so useful. Stop will stop() the presentation at the specified duration and Repeat will stop() and start() it, i.e. repeat (loop) the content.

The EndAction can be set before or during playback. If the playback point is already beyond the specified duration then the endAction will occur as soon as the new action is set. The player is initialized with behavior of END_ACTION_CONTINUE

Parameters:
action - The action required - END_ACTION_CONTINUE, END_ACTION_STOP, END_ACTION_REPEAT

getPlayerEndAction

public int getPlayerEndAction()
Get the EndAction behavior.

Returns:
The end action value

canPause

public boolean canPause()
Indicates whether the player has the ability to pause the current presentation or not. Note, that this information is dependent on the URL and is therefore not available until after the URL has been opened.

Returns:
true if the presentation can be paused, false otherwise

pause

public void pause()
           throws java.io.IOException,
                  java.lang.IllegalStateException
Pause the currently playing presentation (playing is resumed with the resume() method). If the presentation is already paused this will have no effect (i.e the method call is ignored in this state).

Throws:
java.io.IOException - Pause may require a remote server to be notified and an IO error may occur if there are network problems
java.lang.IllegalStateException - If state is Stopped or Closed, or if pause is not supported

resume

public void resume()
            throws java.io.IOException,
                   java.lang.IllegalStateException
Resume playing a presentation from where it is currently paused. If the presentation is already playing this will have no effect.

Throws:
java.io.IOException - Resume may require a remote server to be notified and an IO error may occur if there are network problems
java.lang.IllegalStateException - If state is Stopped or Closed

canSeek

public boolean canSeek()
Return whether the player has the ability to seek into the current presentation or not. Note, that this information is dependent on the URL and is therefore not available until after the URL has been opened.

Returns:
true if the presentation is seekable, false otherwise.

seek

public void seek(long presTime)
          throws java.io.IOException,
                 java.lang.IllegalStateException
Seek to a particular point in the presentation.

Note: currently this is not supported by the player

Parameters:
presTime - Absolute time in the presentation to seek to, in milliseconds.
Throws:
java.io.IOException - Seek may require a remote server to be notified and an IO error may occur if there are network problems
java.lang.IllegalStateException - If state is Closed, or if seek is not supported

step

public void step(long mSecs)
          throws java.io.IOException,
                 java.lang.IllegalStateException
Step the presentation forward by the given number of milliseconds. This feature is only available if pause() is possible as returned by canPause().

Note: currently this is not supported by the player

Parameters:
mSecs - Step size in milliseconds.
Throws:
java.io.IOException
java.lang.IllegalStateException

getTime

public long getTime()
Get the current presentation time.

Returns:
Presentation time in milliseconds, or 0 if not started.

hasDuration

public boolean hasDuration()
Return whether the duration of the current presentation is known. Note, that this information is dependent on the URL and is therefore not available until after the URL has been opened.

Returns:
true if the duration is available, false otherwise.

getDuration

public long getDuration()
Get the specified (known) duration of the current presentation.

Returns:
The duration in milliseconds, or 0 if not known (i.e indefinite).

setSpeed

public void setSpeed(double speed)
Set the speed of the presentation.

Note: this is not supported in a limited fashion by the player. Playback of all media is affected except audio. Speed is also reset back to a factor of 1 when the content playback is stopped.

Parameters:
speed - Speed factor, with 1 is regular speed, 1/2 is a slow down by a factor of 2, 2 is speed-up by a factor of 2, etc.

getSpeed

public double getSpeed()
Get the speed of the presentation.

Returns:
The speed of the presentation.

setScaling

public void setScaling(boolean scale)
Set whether presentations in pixel metrics can scale or not (presentations that are in meter metrics always scale such that the display width is +/- one meter and vertical dimension is ratio of height/width as per MPEG-4 Systems specification)


getScaling

public boolean getScaling()
Get the scaling setting.

Returns:
The current scaling setting

setSpeedScaling

public void setSpeedScaling(boolean speedScaling)
Set speed scaling hint - true to do scaling by speed, false to do quality. When true, and when the content has a preferred size, scaling is done at the final point of rendering, the composition being created at the preferred size. This can be quite a bit faster than when set false which creates the composition at the final size. The latter though can be done at a higher quality with anti aliasing etc and fonts and graphics can be drawn at the final size and thus can look much better than when scaling is done using speed hint.


getSpeedScaling

public boolean getSpeedScaling()
Gets speed scaling hint


getScreenCaptureFormats

public java.lang.String[] getScreenCaptureFormats()
Returns an array of supported formats that can be specified for writing in the PlayerScreenCapture object returned by getScreenCapture(). The possible set of formats returned are the FORMAT_xxx constants in PlayerScreenCapture

The current encodings supported are BMP (all VMs), JPG (Java 1.2 and above with Sun codec, or 1.4 and above with ImageIO), PNG (Java 1.4 and above with ImageIO). The actual list returned will be dependent on the VM environment; minimally this will return bmp, but in the presence of the other capabilities listed above, and when supported, the other formats would be included too.

Returns:
An array of output formats supported.

getScreenCapture

public PlayerScreenCapture getScreenCapture()
Returns a PlayerScreenCapture interface to access the pixels captured from the current rendered image. An array of pixels can then be accessed and/or the pixels written in one of the supported formats as listed by getScreenCaptureFormats().

The captured image is that which is being used for rendering. Generally this will be exactly what is displayed, i.e same size. However, in the case of scaling by speed being set, see setSpeedScaling(), the image will be as if the player is rendering at x1 size even if the display is scaled (this is because scaling by speed creates the composite image at x1 preferred size and then finally scales when its drawn).

Returns:
PlayerScreenCapture or null if no image being rendered

hasPreferredSceneSize

public boolean hasPreferredSceneSize()
Indicates whether the presentation has a desired scene size. Note, that this information is dependent on the URL and is therefore not available until after the URL has been opened.

Returns:
true if there is a desired scene size, false otherwise.

getPreferredSceneSize

public java.awt.Dimension getPreferredSceneSize()
Get the desired scene size of the presentation. Note, that this information is dependent on the URL and is therefore not available until after the URL has been opened.

Returns:
The desired size of the presentation in pixels, with the width stored at index 0 and the height at index 1.

getMetrics

public boolean getMetrics()
Indicates if pixel metrics are being used for scene. Note, that this information is dependent on the URL and is therefore not available until after the URL has been opened.

Returns:
true for pixel metrics, false for meters

getSize

public java.awt.Dimension getSize()
Get the actual player Size at this time.


setSize

public void setSize(int width,
                    int height)
Set the actual player Size. This sets the size of the RendererComponent.

Note concerning Size, Pixel versus Meter metrics and Preferred Size. The size of the player as set here is always in pixels. MPEG-4 content can specify dimensions within the scene as pixels or in meters. MPEG-4 content is rendered using center of the display as 0,0 with x and y positive directions being to the right and up respectively.

In both cases the preferred size, when set, acts as a guide for the initial dimensions although a player can choose to ignore this indication if it so chooses and does not have to set the size that the content (author) has expressed a preference for.


setMute

public void setMute(boolean mute)
Mute any audio. Player can be muted independent of the content so this method may be used in any state.

Parameters:
mute - Mutes audio playback, i.e turns it off if true, on if false.

getMute

public boolean getMute()
Get the mute state.

Returns:
True if audio playback muted, false otherwise

canSetVolume

public boolean canSetVolume()
Indicates whether the player has the ability to set the audio volume. The volume level, as set by setVolume() and returned by getVolume() is always managed, however it may not be possible to affect the final volume; this is the case when the audio playback is based on the Sun Audio classes (ie no JavaSound support).

Returns:
True if the volume setting will have an effect

setVolume

public void setVolume(double volume)
Set the volume level of the presentation.

Parameters:
volume - Volume in the range [0,1].

getVolume

public double getVolume()
Get the volume level of the presentation.

Returns:
Volume in the range [0,1].

setFPS

public void setFPS(float fps)
Set compositor render frame rate in frames per second. If the rate specified is 0 or negative number is treated as 'auto' which attempts adaptive rendering with a target of 30fps.

Parameters:
fps -

getFPS

public float getFPS()
Get the compositor render frame rate that is set

Returns:
Rendering frame rate as set by setFPS()

getActualFPS

public float getActualFPS()
Get actual compositor rendering frame rate. The rendering rate of setFPS() is used as a target and this returns the actual frame rate of the images rendered to the player. This can be used as an indication but the figure returned is only updated if painting actually occurs (ie the number is averaged during painting and if painting ceases the figure will not be updated until painting starts again - a paint could be caused by a window refresh during resize so that would cause it to be updated.)

Returns:
Averaged frame rate for the frames that were rendered

setAutoSize

public void setAutoSize(boolean autoSize)
Sets the Player to auto size or not. If auto size is true, this is how the player used to work and is kept as the default, the container holding the Mpeg4Player Panel is forcibly resized to meet the preferred dimensions. To allow the application control over the size the autosize can be disabled - in which case the listener, who is the owner of the container holding the MPeg4Player panel, can adjust the size as desired when receiving the preferSize() call.

Parameters:
autoSize - True for forced automatic re-sizing, false to do it manually.

getAutoSize

public boolean getAutoSize()
Indicates the autoSize value

Returns:
true if auto sizing set, false otherwise

setRTSPMode

public boolean setRTSPMode(int mode)
Sets the RTSP playback mode for when/if media is retrieved using RTSP. Media can be conveyed

In addition there is an AUTO mode that uses a combination approach to its connection attempt.

Note: the mode will only become effective when the next content is opened, or any existing content re-opened, it will thus not affect any ongoing playback.

Parameters:
mode - One of the RTSP_xxxx playback mode constants
Returns:
True if have RTSP support and mode set, false if no RTSP support

getRTSPMode

public int getRTSPMode()
Gets the current RTSP mode set

Returns:
The RTSP playback mode

setRTSPPacketOutOfOrderDelay

public void setRTSPPacketOutOfOrderDelay(long ms)
Sets the RTSP packet out-of-order delay. Internally this is used to be able to re-sequence UDP packets which are delivered out of order, where the out-of-order packet arrives no later than this amount of time after it was expected.

Note: this method provides advanced control over the player behavior. This can be changed to reduce the startup delay when using RTSP, however note that any out-of-order packets arriving after the delay specified will be dropped.

Note: the value will only become effective when the next content is opened, or any existing content re-opened, it will thus not affect any ongoing playback.

Parameters:
ms - Out-of-order delay in milliseconds. A negative value will restore this to the built-in default.

getRTSPPacketOutOfOrderDelay

public long getRTSPPacketOutOfOrderDelay()
Gets the current RTSP packet out-of-order delay

Returns:
The out-of-order delay in milliseconds

setBufferingLevel

public void setBufferingLevel(int percentage)
Sets the player buffering level. This is to accomodate variances at runtime such as jitter and skew of media streams.

Note: this method provides advanced control over the player behavior. This can be changed to reduce the startup delay, however note that delivery variances may cause media not to be played correctly if the level is set too low.

Note: the value will only become effective when the next content is opened, or any existing content re-opened, it will thus not affect any ongoing playback.

Parameters:
percentage - Percentage of computed buffering to actually use. Valid values are 0 to 100. Any value outside that range will set the percentage back to the default 100% level.

getBufferingLevel

public int getBufferingLevel()
Gets the player buffering level.

Returns:
The player buffering level - a value from 0 to 100 representing the percentage of the computed buffering value that is actually in use.

registerStreamMonitoring

public void registerStreamMonitoring(PlayerStreamMonitoring psm)
Registers the PlayerStreamMonitoring instance that is to be used to monitor the content of streams.

Parameters:
psm - A PlayerStreamMonitoring instance which will be notified as new stream monitors are created. Set to null to stop any future streams from being monitored - any existing stream monitors will though continue.
See Also:
PlayerStreamMonitoring

IBM Toolkit
for MPEG-4

© Copyright IBM Corp. 1998, 2006. All Rights Reserved.