NAME

DESCRIPTION

CONFIGURE FILE

For mozilla (and chromium) browsers

$MOZPLUGGER_HOME/
$XDG_CONFIG_HOME/mozplugger/
$HOME/.config/mozplugger/
$HOME/.mozplugger/
$HOME/.mozilla/
$MOZILLA_HOME/
/etc/
/usr/etc/
/usr/local/mozilla/

For netscape browsers

$MOZPLUGGER_HOME/
$XDG_CONFIG_HOME/mozplugger/
$HOME/.config/mozplugger/
$HOME/.mozplugger/
$HOME/.netscape/
/etc/
/usr/etc/
/usr/local/netscape/

For opera browsers

$MOZPLUGGER_HOME/
$XDG_CONFIG_HOME/mozplugger/
$HOME/.config/mozplugger/
$HOME/.mozplugger/
$HOME/.opera/
$OPERA_HOME/
/etc/
/usr/etc/

The command mozplugger-update must be run after installation and each time the configuration file changes or new helper applications are added to the system or old helper applications removed.

mozplugger-update will use the first mozpluggerrc it finds and ignore any others for each different browser installed on the system. The search order is from top of the list above, but skipping places not applicable to the particular browser that the config is being parsed for. mozplugger-update then caches processed results in files located at $XDG_CACHE_HOME/mozplugger/

The format of mozpluggerrc is very simple. The file is subdivided into sections. Each section starts with a plugin name and version in square brackets. This represents a class of mozplugger plugin. The name and version will be displayed as a separate plugin when viewing installed plugins in your browser. Some java script relies on the name and version of a plugin matching some value, hence the reason for seperate sections in mozpluggerrc. Two brackets are required because m4 processing needs to escape the brackets. e.g.

[[multimedia player @ 10.1]]

Within each section, the general layout is to have one or more lines describing mime types followed by one or more lines describing commands used to handle those mime types. Lines beginning with # are considered comments and are ignored. Here is a simple example:

video/mpeg: mpeg: Mpeg video
video/quicktime: qt,mov: Mpeg video
: xanim +W$window -Zr +q +Ze +f $file

Each line describing a mime type has three fields:

mime type : extensions : description

mime type

The mime type is the standardized name for the content type you want MozPlugger to handle. This must be the same type as the web server claims the file to be, or MozPlugger will not be used for that file, regardless of the extension. Note: Some web servers incorrectly report the wrong mime type, blame the web server adminstrator not mozplugger.

extensions

This is a comma separated list of extensions that should be associated with this particular mime type. The extensions are only used when a web server does not report what type of file it is, or when loading files directly from disk.

description

This is the description that shows up in about:plugins and in the application preferences section in Mozilla.

Lines that describe what command to use for a mime type must begin

with a whitespace and have two fields:

flags : command

flags

This is a space separated list of flags associated with the command and tells mozplugger how to handle this command. See below for further details.

command

This is a command which is sent to /bin/sh when handling this mime type. Mozplugger assumes the command line starts with the name of an application followed by various arguments passed to that application.

USING M4

FINDING THE RIGHT COMMAND

When a matching mimetype is found, it tries to figure out which command to use. Commands that have the flags loop, embed, noembed, link and fmatch will be rejected if they do not match what is expected from the associated HTML code (see later for details).

In addition for a command to be chosen the application has to be available. This will have been checked by mozplugger-update which will have assumed the first word of the command is the name of an application and search $PATH for that application. If that application is not found mozplugger-update will not have cached that in the processed config files. The output from mozplugger-update will indicate when applications have not been found.

Of the commands that remain, Mozplugger looks for the first command that has the stream flag set. If there is not such a command line, Mozplugger then downloads the file and picks the first (of the remaining) commands.

WORKING WITH JAVA SCRIPT

isPlaying

This property has the value true if the application that mozplugger launched to handle the embedded object is running and false if either no application was launched or that application has now terminated.

WHEN IT DOESNT WORK

Next run the browser from the shell (xterm or equivalent) passing the appropriate browser command line flag to enable output from stdout and stderr to be displayed.

For example, for firefox the command line string is:

firefox -debug

This should allow any output from the application to be visible at the shell and hopefully lead to a diagnosis of the fault.

FLAGS

autostart

This flag indicates that the command uses the $autostart environment variable. That is mozplugger will run the command on the assumption that the command/application will check the value of the $autostart environment variable. If this flag is not present and the HTML code for the embedded object indicates autostart is false, mozplugger will not run the command but instead draw a single start button.

repeat

This flag indicates that the command uses the $repeats environment variable. That is mozplugger will run the command on the assumption that the command/application will check the value of the $repeats environment variable and perform the repeats. If this flag is not set, mozplugger will perform the required number of repeats as indicated in the HTML code by calling the command $repeats times.

loop

This indicates that the command loops forever. If the HTML code for the embedded object indicates don't loop/repeat forever (e.g. the loop attribute is not present or not set to true), the command on this line will not be used.

stream

This indicates that this command can take an url. In this case, the environment variable $file contains the URL of the file to play and the browser does not download it. It is assumed that the command can handle the URL. Note: if a username and password is required for this URL, the command/application will have to obtain this as it is not passed to it from the browser.

ignore_errors

This flag tells MozPlugger to ignore the exit status of the command. For example is mozplugger is repeating the command 'n' times and the command exits with an error, normally mozplugger would terminate at this time. With this flag set, mozplugger continues the repeats.

noisy

This flag tells MozPlugger to redirect the stdout and stderr of the command to /dev/null.

swallow (name)

This flag tells mozplugger that the command will open a window with the specified name and that Mozplugger will then move this window inside your browser. If name is prefixed with '=' then mozplugger looks for an exact match with the window name, if the prefix is '~' then mozplugger looks for a case insensitive match, if prefixed with '*' then mozplugger looks for a window name that starts with 'name' and is case insensitive. If none of these prefixes then, mozplugger checks if name occurs anywhere in the window name, but is case sensitive. Note any spaces between the brackets are counted as part of the window name. The window name to use in mozpluggerrc can be obtained by using the utility xprop(). Run the command in question, type "xprop WM_CLASS" at a shell prompt and then click on the application window. In addition any occurance of %f in the name is replaced with the filename being loaded (without path), %p is replaced with the full filename including path. Some applications do not like to be swallowed and some window managers do not like windows being managed by mozplugger, so avoid using this option where possible.

fmatch (string)

This flag defines a command that will be used only if the filename or url (i.e. $file) contains 'string'. If 'string' is prefixed with '*' then mozplugger defines a match when the file starts with 'string' (the check is case insensitive). If 'string' is prefixed with '%' then mozplugger defines a match when the file ends with 'string' (the check is case insenstive and ignores any parameters at the end of a url {i.e. '?xxx=yyy'}). If none of these prefixes then mozplugger defines a match when the 'string' is found somewhere in the file (but this time match is case sensitive). Note any spaces between the brackets are counted as part of the 'string'.

nokill

This flag tells MozPlugger to not try to kill the command when leaving the page, and to not start the command in a loop. This is normally used for applications that are not swallowed and can play multiple files, such as xmms.

exits

This flag tells MozPlugger that the command will exits straight away and hence does not need to be killed when leaving the page, and to not start the command in a loop. This is normally used for applications that just display an image in the $window and then exit.

fill

This flag tells MozPlugger to maximize a swallowed window.

maxaspect

This flag tells Mozplugger to maximize a swallowed window while keeping the width/height ratio constant.

controls

This flag tells MozPlugger to draw controls and is typically used with audio files to display a controller with the buttons play, pause and stop. Be aware if the embedded object has no sub-window defined within the browser's window (e.g. if the HTML uses the tag hidden = true) then the controls will not appear.

embed

This flags tells Mozplugger to only use this command if the associated HTML refers to an embedded object that is a small part of a HTML page.

noembed

This flags tells Mozplugger to only use this command if the associated HTML refers to a separate window that only contains the object.

links

This flag tells Mozplugger to display as a button within the browser and when pressed to run the command without embedding in the browser. This can be used when swallow does not work.

needs_xembed

Some applications when embedded requires the Xembed protocol, other applications don't want the Xembed protocol. Add or remove this flag if you find that you cannot move keyboard focus to the embedded window. Currently it appears QT4 based applications require this flag.

ENVIRONMENT VARIABLES

MOZPLUGGER_HOME

If MOZPLUGGER_HOME is defined, the folder $MOZPLUGGER_HOME is checked for the configuration file mozpluggerrc and is also used for the base of storing the results of processing mozpluggerrc

MOZPLUGGER_TMP

If MOZPLUGGER_TMP is defined, then any temporary files are placed in $MOZPLUGGER_TMP.

TMPDIR

If MOZPLUGGER_TMP is not defined, but TMPDIR is defined, then any temporary files are placed in $TMPDIR/mozplugger-xxx/ where xxx = PID.

PATH

mozplugger-update uses PATH to look for executables

MozPlugger gives some variables to /bin/sh when running the command,

these variables are:

$autostart

This variable contains 1 or 0. When set to 1 it indicates that the command should start playing/showing the associated media. By default it is 0 if controls flag is present and 1 otherwise, but it is overridden if the associated HTML contains the attribute autostart or autoplay. Command/applications that use this environment variable should also have the autostart flag set.

$repeats

This variable contains how many times the file should be played. By default it is once, but it is overridden if the associated HTML contains the attribute loop, numloop or playcount. Command/applications which use this environment variable should also have the repeat flag set.

$window

This is the X window Mozilla has given the plugin. This can be used with applications such as MPlayer to display graphics inside the mozilla window. Be aware if the embedded object has no sub-window defined within the browser's window (e.g. if the HTML uses the tag hidden = true) then the variable will have the value zero (null).

$hexwindow

Same as $window except the value is expressed as an hexidecimal string in the form 0xNNNNNN where NNNNNN is the hexadecimal digits.

$width

This is the horizontal resolution in pixels and is taken from the width attribute in the HTML code.

$height

This is the vertical resolution in pixels and is taken from the height attribute in the HTML code.

$file

This is the file to play. If the command has the stream flag set, this variable contains the URL of the file to play. This is taken from the associated HTML code. The value is that of the attribute src, data, href, qtsrc, filename, url or location depending on which is present and whether the <EMBED> or <OBJECT> tag is used. If the stream is not set, this variable contains a local temporary file that the browser has created.

$fragment

This is the part of the original URL that appears after the # if it exists. Sometimes this contains additional information that could be useful for the application e.g. starting page number in a pdf document

$mimetype

This variable contains the mime type of $file.

$VAR_<parameter_name>

All the parameters of the <EMBED> or <OBJECT> tags are made available in mozpluggerrc through environment variables. For example the parameter loop="1" in an <EMBED> tag defines the variable VAR_loop=1.

BUGS

Netscape 3.x will not play anything for <EMBED> tags for which height or width are zero. This too is a Netscape bug.

Occassionally you may notice some zombie mozplugger-helper processes (defunct), this is not a bug, this is by design. The zombie processes occur when either the application exits or when using nokill flag (without exiting the page with the embedded object). The zombie(s) are reaped when closing the web page containing the associated embedded objects.

If using behind a non-transparent HTTP proxy, it may be found that the commands using the stream flag do not work. This is because the proxy settings are not passed to the application in the command line. To work around this situation, don't use the stream flag OR edit the mozpluggerrc file and passed in necessary proxy setiings via the command line.

It has been found that certain combinations of browser, embedded applications and window managers do not play nicely with the swallow flag. If this happens to you first try adding or removing the "needs_xembed" flag from the associated command in mozpluggerrc, if this fails remove the swallow flag and perhaps use the links flag instead.

AUTHORS