IBM MPEG-4 Multimedia Applet Player IBM MPEG-4 Technologies
IBM MPEG-4 Technologies
Overview
Parameters
Scripting

Parameters

The IBM MPEG-4 Multimedia Applet Player supports the parameters as detailed in this section. There are notes concerning standard applet attributes too.

Param

Parameters are of the form <param name="name" value="value"> and are detailed in the table below.

Text in blue is a description of the values; otherwise the text lists the value choices themselves, which may be separated with a vertical bar | indicating that just one of the choices should be picked. If no param is present it acts as though one is present having the default value; the default value being the one in bold text.


Param nameDescription of value
url This is the source url for the content. For example to access content over RTSP the url value would be something like "rtsp://myserver.com/mycontent.mp4". To access M4Muxed content, from an m4x interleaved file, over http the url value would be something like "http://www.mywebserver.com/mycontent.m4x" or it can be a relative url such as "media/video/myvideo.m4x"

When the url is relative the urlBase param value is also used to locate the content.

urlBase "Codebase" | "Docbase"

Used when a url is relative to locate the content. There are two values supported, "Codebase" and "Docbase", with Docbase being the default. A relative url can thus be specified for content whose location is relative to the location of the applet code (i.e. the location of the applet class file or jar), or for content relative to the location of the html page containing the applet, the docbase.
alt1
alt2
alt3
alt4
alt5
alt6
alt7
alt8
alt9
Allows up to 9 alternate urls. If the content is not accessible from the url param then the applet will try the alternates specified here until either it can connect or until there are no more urls to try. This is intended to provide one or more alternate locations where the content can be located in case the main server, as specified by the url param, is unavailable. A maximum of up to nine alternates can be specified (probably far more than will ever be wanted in practice).
img This is a source url for an optional image to display before the content is started, which is after the MPEG-4 technologies icon image and credits text have been displayed when the applet is started. This can point to a gif or jpg image and can be a relative or absolute url.

When the url is relative the urlBase param value is used to locate the content.

There are two special values that can be used here "_icon" and "_text". _icon will use the MPEG-4 technologies icon image and _text the credits text as the 'image'. These special 'images' are however not affected by the imgDraw parameter as detailed below and are always on a black background.

imgDraw "Clip" | "Fit" | "Scale" | "Fill"

This param controls the way the image is drawn on the applet. The image is rendered to the center of the applet, this is the area above any Control panel that may exist, or the entire area of there is no Control panel.

"Clip" renders the image at its normal size and if necessary clips any borders that do not fit into the applet area.

"Fit" scales the image to the largest size that fits the applet area preserving the original aspect ratio of the image. This may result in borders along the top and bottom, or along the sides, dependent on the aspect ratio of the image compared to that of the applet area.

"Scale" scales the image such that it fills the applet area; the aspect ratio of the image is not preserved but the entire image is visible.

"Fill" scales the image such that not only the aspect ratio is preserved but so that the applet area is completely filled. Borders on the top and bottom, or on the sides of the image that fall outside the applet area will be clipped.

imgBGColor "#RRGGBB"

Specifies a background color that fills any area not taken up by the option image. If an image is not specified then this color will fill the entire area. The default color is black which is the same as MPEG-4 content default background color.

The RRGGBB refer to the red, green and blue components of the color and the specification here is as per the RGB spec for colors as used in HTML, for example yellow is #FFFF00. (Note: HTML color names, e.g. "yellow", are however not supported here).

panel "None" | "Mini" | "Basic" | "Default"

This param allows a Control panel to be selected for the player. The Control panel is the bar at the bottom of the player with buttons for start, stop etc. and potentially other indicators and controls.

"Mini" Control panel has play/pause, stop and mute buttons; it has dimensions of 55x20.

"Basic" Control panel has play/pause, stop and mute buttons like Mini but also includes current time and duration readouts and a progress bar; it has dimensions of 160x22.

"None" means no Control panel

"Default" means that a default preferred Control panel will be selected, currently this is the Basic Control panel.

When a Control panel is used the width and height attributes coded for the applet should make due allowance the Control panel being present along with the content in the space (width x height) allocated for the applet.

panelBGColor "#RRGGBB"

Specifies a background color for the Control panel to override its default color. This can be useful to blend the background of the Control panel more with the web page or content. However the color selection may influence a users ability to easily discern the parts of the Control panel, such as the progress bar, and hence the color should be chosen with that in mind.

See imgBGColor above for detail on how to specify RRGGBB values.

panelParm1-9 Control panel specific parameters in form "name=value". There are currently no specific Control panel parameters supported - this is for potential future use.
showCanvas "true" | "false"

Allows the rendering canvas to be hidden for audio only content.

The canvas area is used to show the applets logo and any visuals for the content. For audio content this can be hidden, if desired, such that only a Control panel is visible.

autoOpen "true" | "false"

Content will be automatically opened when set true from where it can subsequently be started and played. When set false a Control panel must be used to initiate playback of the content and the play button will be activated to do so. Until content is opened, e.g an RTSP connection made etc., any duration etc will not be available. Sometimes it may preferable to present the ability to access content but not make any connection until the user decides to play it.
autoStart "true" | "false"

Content playback will be automatically started when set true. When set false a Control panel may be used to start playback of the content.
scaling "true" | "false"

Content will be scaled to the available area if true; scaling is done such that aspect ratio of the content is maintained. When false content will be clipped if it is larger that the available area. The rendered content is always centered in the available area whether scaling is true or false.

Note: content that is defined using meter metrics is always scaled. Meter versus pixel metrics is a fundamental attribute of the content - please refer to the authoring components of the IBM Toolkit for MPEG-4 for more details.

speedScaling "true" | "false"

Set to true to prefer scaling by speed over quality. If the content has a preferred size, then when the applet is set to prefer scaling by speed, the content is composed using the preferred dimensions and scaled as it is finally drawn on the display. When done by quality the content is originally composed at the final size to which it will be displayed and in that case graphics can be drawn anti-aliased at the right final size etc. The rendered output has a higher quality in this latter case, e.g fonts look smoother, but it can take longer and use more memory. For simple video content there is no difference between speed and quality modes.
atDuration "Continue" | "Stop" | "Repeat"

This is the action the players should take at the end of the content when the content has a defined duration.

"Continue" is the default. Playback continues beyond the defined duration. This is useful if the content is animated and can go on indefinitely but the authored duration indicates some finite limited time.

"Stop" causes playback to cease at the defined duration; any animation etc ends and interaction with the content is no longer possible.

"Repeat" causes playback to start again from the beginning. Content is not cached by the player which will re-open and play the content again; content may be cached locally by the browser for content accessed over http, but this is not the case for content accessed by rtsp. This behavior should be borne in mind before repeat is used.

rtspMode "Auto" | "UDP" | "HTTPTunnel" | "TCPInterleave" | "TCPInterleaveUDP"
This sets the operating mode when accessing content with rtsp:// url from a streaming server.

"Auto" is the default. This is an automatic mode using a combination of the modes below that should work in most cases.

"UDP" mode has the media content streamed from the server using UDP. A firewall or a NAT device between you and the streaming server may result in no content being received.

"HTTPTunnel" has the media content interleaved in with the RTSP control and the whole lot tunneled over HTTP. This mode can be used to stream through firewalls.

"TCPInterleave" has the media content interleaved in with the RTSP control. Since the RTSP uses a TCP connection this may also be used to stream through certain types of firewall.

"TCPInterleaveUDP" has certain streams, that would otherwise be adversely affected by the loss which may occur with UDP, instead interleaved with the RTSP control over it's reliable TCP connection. Of course one could choose TCP Interleave and have all the media over a reliable connection. But for continuous streams like video and audio, from which loss recovery is possible, this mode is an alternative.

endtoPlay Name of another M4Applet on the same web page (in the same frame) to start playing at end of this one.

The target applet should be named using the name attribute of the applet tag. The target applet would normally be setup with no Control panel and autostart set to false; then when the applet with the endToPlay naming the target applet reaches its duration (it must have a known duration and not be indefinite) it will cause the target applet to being playing.

Note: the target will also begin playing if the present applet's playback is explicitly stopped.

endtoURL URL to invoke in the web browser at end of play.

A url may be specified to be launched within the browser when play ends at the defined duration.

Note: the url will also begin invoked if the present applet's playback is explicitly stopped.

endtoTarget A target for the endtoURL above so frames can be used.

A named target frame or window for the URL can be specified where endtoTarget has the same values as are supported on the target attribute of html <a> tag.

timerEvent1-999 timerEvent1 through timerEvent999 are up to 999 timed events that can be defined which will generate timer callbacks if the timer event function is set using the jsTimerEventFn param. Timer events need not be listed in temporal order so that you can add more later. However the numeric sequence of 1 to 999 must not have any gaps; if a gap is found, i.e. a missing number in the sequence, then no more timerEvent params will be evaluated.

Timer events are defined in form "time ; ID" where time is in milliseconds and ID is a string identifier which will be passed to the timer event function to identify the event when it occurs. E.g "1000 ; My Event at 1 second" will pass the string My Event at 1 second to the timer event function at 1000 milliseconds (1 second) into the playback. The time should just be numeric with no trailing 'ms'. If events are defined for exactly the same time the order of those events is undefined and will not necessarily be the same order as given by the params; i.e. if you do this do not rely on any ordering for identically timed events.

jsTimerEventFn The name of a global JavaScript function that will be called when any timer events are generated. The identifier portion (ID) of the particular timerEvent param is passed to the method as a string.

If this param is not specified then no timer events will be generated.

jsStateEventFn The name of a global JavaScript function that will be called when player state changes.

If this param is not specified then no state events will be generated.

Player states are passed to the function as strings; the following are the set of player states that can be passed to the designated function.

  • CLOSED
  • STOPPED
  • PLAYING
  • PAUSED
jsControlEventFn The name of a global JavaScript function that will be called when player control changes occur. Player control events are for events other than state that occur if control settings are altered e.g scaling.

If this param is not specified then no control events will be generated.

Control changes result in one the following String forms being passed to the function to represent the control change.

  • PREFERSIZE iWidth iHeight
  • METRICS ["pixel" | "meter"]
  • VOLUME dVolume
  • MUTE ["true" | "false"]
  • URL url
  • SPEED dSpeed
  • SCALING ["true" | "false"]

The above syntax is now explained along with examples of control events so the forms can be better understood. iWidth is for example an integer (i for integer), dSpeed is a double (d for double) and "true", a string in quotes means the actual string. Others such as url are strings that will be replaced by the actual string (the url of the content in this particular case e.g. http://myserver/mycontent.m4x). [ a | b] means one of a or b will be there, so for METRICS either "pixel" or "meter" will follow.

 "PREFERSIZE 320 240"
 "PREFERSIZE -1 -1"
 "METRICS pixel"
 "METRICS meter"
 "VOLUME 0.4"
 "MUTE true"
 "URL http://myserver.com/mycontent.mx4"
 "SPEED 2.0"                 
jsCmdModeAsync "true" | "false"

When true certain of the JavaScript API methods of the applet will be processed in an asynchronous manner; instead of the default synchronous mode. See Scripting section for more detail.
jsStatusEventFn The name of a global JavaScript function that will be called when a JavaScript method, which has been processed asynchronously, completes.

The following events can be generated.

  • OK : n
  • ERROR : n : A message concerning the error/exception
Where n is the command sequence identifier as returned in the "PENDING : n" status response to the initial JavaScript method invocation. See Scripting section for further information.

Attributes

When playing visual content the width of the applet should be specified the same as the content's width to allow it to be played at its normal size. The height of the applet must allow for the presence of a Control panel or not. See "panel" param for more information.

If the content is purely audio then the renderer canvas, upon which the visuals would be drawn, can be kept hidden and the applet then only needs to be big enough to hold the selected Control panel.


  IBM Home | Research Home | MPEG-4 Technologies | alphaWorks | © Copyright IBM Corp. 1998, 2005. All Rights Reserved.