Browser Integration

Foreword

GPAC can be embedded in Mozilla-based web browsers since 0.4.0 (Osmozilla), and in MS Internet Explorer since 0.4.2 (GPAX), using the standard XHTML

GPAC can be embedded in HTML/XHTML web pages through an ActiveX control (GPAX) or a Mozilla plugin (Osmozillla). All features of GPAC clients are available in these plugins, like progressive loading (IsoMedia or progressive SAX on XMT, X3D or SVG), real-time streaming, web-radios support, etc. As usual, these features are controled through GPAC’s configuration file.
To install the plugins: on Windows, use the GPAC installer because installation of mozilla plugin is a bit tricky; on other platforms simply use ‘make install’.

GPAC Declaration in (X)HTML

As with any embedded object, GPAC can be declared through both <object> and <embed> tags in an HTML file. However, the result may differ depending on web browsers. In order to limit these problems, it is stringly recommended to only use declaration through an<object> tag.

Depending on the web browser used, some attributes of the <object> element may be ignored, or even worse, the whole element may be ignored if some special attributes are used. When faced with such issues, web designers use nested <object> and <embed> tags, but this is a rather heavy workaround. GPAC plugins have been designed to avoid such problems.

Declaration Syntax

<object type=”…” width=”…” height=”…”
classid=”clsid:181D18E6-4DC1-4B55-B72E-BE2A10064995″ >
<param name=”…” value=”…” />
…
<param name=”…” value=”…” />
Your browser does not support GPAC …
</object>

Semantics

  • type : identifies the content mime type. To make sure GPAC is loaded, use the private mime type application/x-gpac. GPAC plugins are by default registered to handle a good set of mime types:
    • application/x-gpac : generic identifier for embedding GPAC.
    • application/mp4 : MPEG-4 movies with interaction
    • application/sdp : Streaming presentations
    • audio/aac : AAC audio (WebRadios)
    • audio/amr : AMR audio (Furture WebRadios ??)
    • audio/mp4 : MP4 Audio (iTunes & co)
    • audio/mpeg : MP3 Audio (WebRadios)
    • image/svg+xml : SVG document
    • model/vrml : VRML world
    • model/x3d+vrml : X3D world in VRML text format
    • model/x3d+xml : X3D world in XML format
    • video/mp4 : MPEG-4 movie
    • video/3gpp : 3GPP movie
    • video/3gpp2 : 3GPP2 movie
    • video/avi : AVI movie
    • video/mpeg : MPEG-1/2 movie
  • width , height : size of the GPAC window in your web page.
  • classid : UUID identifier of GPAC ActiveX control.
    • GPAC’s classid is 181D18E6-4DC1-4B55-B72E-BE2A10064995
    • As a general rule, DO NOT SPECIFY THE CLASSID ATTRIBUTE, since mozilla browsers ignore <object> whenever a classid attribute is specified. The ActiveX plugin has been designed to avoid using the CLASSID, and relies on mime type associations.
    • The only case where you have to use classid is for Pocket Internet Explorer, which currently does not handle mime type associations for ActiveX controls.

Parameters for GPAC plugins

Plugin parameters are declared with the <param> tag. DO NOT try to declare parameters as attributes of the <object>, behaviour may differ upon browsers. The following parameters are used:

  • “src” : location of the media ressource to play with GPAC. Any URL supported by GPAC can be specified here. The URL may be absolute or relative.
  • “use3d” : indicates that GPAC 3D renderer is needed to play the content. This overrides the GPAC configuration variable, allowing co-existence of several plugins in a same page with different renderers. Value is either true or false, the default value being false.
  • “autostart” : specifies if content shall start playing upon load of the plugin or not. Value is either true or false, the default value being true. If the value is false, scripting will be required to trigger playback.
  • “aspectratio” : specifies how aspect ratio shall be preserved by GPAC. This parameter can take the following values:
    • keep : aspect ratio is preserved.
    • 16:9 : forces usage of a 16:9 aspect ratio.
    • 4:3 : forces usage of a 4:3 aspect ratio.
    • fill : content is stretched to fill the entire object display area, without aspect ratio preservation.

Scripting the plugin

The browser plugins may be controled dynamically from the HTML page through scripting. The current scripting API is very basic and will be enhanced in the near future. Do not hesitate to send us suggestions/requests for the scripting side.

NOTE: Scripting with osmozilla is currently not supported as of  firefox version 3.6, as the XPCom API  has been removed. It however still works with older versions of Firefox.

 

Setting up the plugin for scripting

All you have to do is assign an ID to the GPAC object element, and use it in JavaScript calls.

<object width=”100″ height=”100″ type=”application/x-gpac” id=”gpac” >
<param name=”src” value=”file.mp4″ />
</object>
<input onclick=”gpac.Pause();” value=”Pause” type=”button” />

Plugins Methods

The following methods are defined in the plugins:

  • Play() : connects the current URL if needed, and plays it. This is mainly used when the plugin has been declared with autostart set to false. Function doesn’t take any parameter.
  • Stop() : disconnects the current URL. Function doesn’t take any parameter.
  • Pause() : plays/pause media playback. Function doesn’t take any parameter.
  • Update(type, scene_data) : sends an update to GPAC. Updates can be any kind of updates supported by GPAC scene manager (BT, XMT, LASeR+XML), or a complete scene. Parameters are:
    • type : mime type of the update language used. Accepted values are:
      • application/x-bt : update is a BT scene or a set of BT commands.
      • application/x-xmt : update is a XMT scene or a set of XMT commands.
      • model/vrml : update is a VRML world.
      • model/x3d+vrml : update is an X3D world in VRML format.
      • model/x3d+xml : update is an X3D world in XML format.
      • image/svg+xml : update is an SVG document.
      • application/x-laser+xml : update is a LASeR document or a set of LASeR updates, in XML format.
    • scene_data : the textual scene data to process.

    Note that this assumes you have some knowledge of the scene being played by GPAC, since you will have to access scene nodes by their IDs. For example, consider the plugin is playing a BT file showing a rectangle with a Material2D defined as MAT. You may control the material in BT as follows:

    <object width=”100″ height=”100″ type=”application/x-gpac” id=”gpac” >
    <param name=”src” value=”rect.bt” />
    </object>
    <input onclick=”gpac.Update(‘application/x-bt’, ‘REPLACE MAT.emissiveColor BY 1 0 0’);” value=”red” type=”button” />
    <input onclick=”gpac.Update(‘application/x-bt’, ‘REPLACE MAT.emissiveColor BY 0 0 1’);” value=”blue” type=”button” />

Hyperlinking handling

Whenever an hyperlink is clicked in an embedded GPAC object (MPEG-4/VRML Anchor, SVG a), the following process occurs:

  • If GPAC supports the URL, any parameter associated with the hyperlink are ignored, GPAC just replaces the current presentation with the given URL.
  • If GPAC doesn’t support the URL, it gives it to the web browser with the associated parameter (_parent, _blank, _new, _top, _target=FrameID). Note that this is not supported for Pocket Internet Explorer at the current time.