mozplugger(7)mozplugger(7)NAMEmozplugger - a multimedia plugin for UNIX Web browsers that supports
the mozilla npapi
DESCRIPTION
MozPlugger is a browser plugin which can show many types of multimedia
inside your Browser. To accomplish this, MozPlugger uses external pro‐
grams such as mplayer, xanim, mtv, timidity and tracker.
CONFIGURE FILE
You can configure mozplugger by changing the mozpluggerrc file(s).
These can be located in any of the following directories depending on
the browser:
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 ver‐
sion of a plugin matching some value, hence the reason for seperate
sections in mozpluggerrc. Two brackets are required because m4 pro‐
cessing 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 com‐
mand 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
When running, mozplugger-update it will pass the mozpluggerrc file
through m4, a general purpose macro processor (assuming m4 is
installed). This provides the ablity to use macros within mozpluggerrc
especially for those commonly used command lines. m4 brings text
replacement, parameter substitution, file inclusion, string manipula‐
tion, conditional evaluation, arthemtic expressions, etc to mozplug‐
gerrc. Please see m4 documentation for more details.
FINDING THE RIGHT COMMAND
When MozPlugger is called from your browser, it looks through the
cached processed configuration files and finds a matching mime type.
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 avail‐
able. 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 applica‐
tions 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, Moz‐
plugger then downloads the file and picks the first (of the remaining)
commands.
WORKING WITH JAVA SCRIPT
Mozplugger supports a JavaScript interface that allows the state of the
embedded object (i.e. mozplugger) to be queried from JavaScript. Cur‐
rently mozplugger supports the following properties.
isPlaying
This property has the value true if the application that moz‐
plugger 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
If for some reason the embedded object fails to be rendered in the
browser, this could be a fault with the application as opposed to Moz‐
Plugger. To diagnosis the fault it is suggested that first you make
sure that any output from the application will be visible to you by
removing the noisy flag (if set in mozpluggerrc).
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 envi‐
ronment 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 environ‐
ment 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 num‐
ber of repeats as indicated in the HTML code by calling the com‐
mand $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 pass‐
word 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 com‐
mand. 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 win‐
dows 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 file‐
name or url (i.e. $file) contains 'string'. If 'string' is pre‐
fixed 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
There are some envirnoment variables that control the behaviour of Moz‐
plugger.
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. Com‐
mand/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 dig‐
its.
$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
You have to run mozplugger-update after changing the configuration, or
nothing will happen.
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 mozplug‐
gerrc file and passed in necessary proxy setiings via the command line.
It has been found that certain combinations of browser, embedded appli‐
cations 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
Fredrik Hubinette, author of plugger which mozplugger is a fork of.
Louis Bavoil
Peter Leese
2013 Feb 09 mozplugger(7)
