.TH mozplugger 7  "2010 Aug 07"
.SH NAME
mozplugger \- a streaming multimedia plugin for UNIX mozilla

.SH DESCRIPTION
.I MozPlugger
is a  Mozilla plugin which can show many types of multimedia
inside your Mozilla. To accomplish this, MozPlugger uses external
programs such as mplayer, xanim, mtv, timidity and tracker.

.SH CONFIGURE FILE
You can configure mozplugger by changing the file
.I mozpluggerrc
which can be located in any of the following directories:

	$MOZPLUGGER_HOME/
.br
	$HOME/.mozplugger/
.br
	$HOME/.netscape/
.br
	$HOME/.mozilla/
.br
	$HOME/.opera/
.br
	$MOZILLA_HOME/
.br
	$OPERA_HOME/
.br
	/usr/local/netscape/
.br
	/etc/
.br
	/usr/local/mozilla/
.br
	/usr/local/netscape/

MozPlugger will use the first mozpluggerrc it finds and ignore
any others. The search order is from top of the list above.

The format of
.I mozpluggerrc
is very simple. 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
.br
	video/quicktime: qt,mov: Mpeg video
.br
		: xanim +W$window \-Zr +q +Ze +f $file

Each line describing a mime type has three fields:

	
.B mime type
:
.B extensions
:
.B description

.TP
.B 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.
.TP
.B 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.
.TP
.B description
This is the description that shows up in about:plugins and in the
application preferences section in Mozilla.


.TP
Lines that describe what command to use for a mime type must begin
with a whitespace and have two fields:

	
.B flags
:
.B command

.TP
.B 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.
.TP
.B 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.

.SH USING M4

When loading, MozPlugger 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 manipulation, conditional 
evaluation, arthemtic expressions, etc to mozpluggerrc. Please see m4
documentation for more details. 

.SH FINDING THE RIGHT COMMAND

When MozPlugger is called from your browser, it looks through the
configuration file 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 
.B loop, embed, noembed, link 
and 
.B 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. That is, MozPlugger will assume 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 will skip that command line.

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

.SH 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. Currently
mozplugger supports the following properties.
.TP
.B 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.

.SH 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 MozPlugger. 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
.B 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:

        
.B  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.

.SH FLAGS
.TP
.B 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.
.TP
.B 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.
.TP
.B 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.
.TP
.B 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. 
.TP
.B 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.
.TP
.B noisy
This flag tells MozPlugger to redirect the stdout and stderr of the 
command to /dev/null.
.TP
.B 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.

.TP
.B 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'.
.TP
.B 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.
.TP
.B 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.
.TP
.B fill
This flag tells MozPlugger to maximize a swallowed window.
.TP
.B maxaspect
This flag tells Mozplugger to maximize a swallowed window while keeping the
width/height ratio constant.
.TP
.B 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.
.TP
.B 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.
.TP
.B noembed
This flags tells Mozplugger to only use this command if the associated
HTML refers to a separate window that only contains the object.
.TP
.B links
This flag tells Mozplugger to only use this command for embedded objects
that are really links to external applications (such objects typically use the
target and href variables to indicate a clickable link). Embedded 
Quicktime objects sometimes use this mechanism.
.TP
.B 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.
.SH ENVIRONMENT VARIABLES
There are some envirnoment variables that control the behaviour of Mozplugger.
.TP
.B MOZPLUGGER_HOME
If MOZPLUGGER_HOME is defined, the folder $MOZPLUGGER_HOME is checked for the 
configuration file mozpluggerrc
.TP
.B MOZPLUGGER_TMP
If MOZPLUGGER_TMP is defined,  then any temporary files
are placed in $MOZPLUGGER_TMP.  
.TP
.B TMPDIR
If MOZPLUGGER_TMP is not defined, but TMPDIR is defined, then any
temporary files are placed in $TMPDIR/mozplugger-xxx/ where xxx = PID.
.TP
.B PATH
Mozplugger uses PATH to look for executables

.TP
MozPlugger gives some variables to /bin/sh when running the command,
these variables are:

.TP
.B $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 
.B autostart 
flag set.
.TP
.B $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
.B repeat
flag set.
.TP
.B $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).
.TP
.B $hexwindow
Same as $window except the value is expressed as an hexidecimal string in
the form 0xNNNNNN where NNNNNN is the hexadecimal digits.
.TP
.B $width
This is the horizontal resolution in pixels and is taken from the width
attribute in the HTML code.
.TP
.B $height
This is the vertical resolution in pixels and is taken from the height
attribute in the HTML code.
.TP
.B $file
This is the file to play.
If the command has the
.B 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
.B stream
is not set, this variable contains a local temporary file that the browser
has created.
.TP
.B $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
.TP
.B $mimetype
This variable contains the mime type of $file.
.TP
.B $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.

.SH BUGS
You have to remove ~/.netscape/plugin-list or ~/.mozilla/firefox/pluginreg.dat
after changing the configuration, or nothing will happen. This is a
Netscape/Mozilla/Firefox bug, not a MozPlugger bug.

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
.B 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
.B 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 and embedded application
don't allow keyboard focus in the embedded application, if this happens to you
try adding or removing the "needs_xembed" flag from the associated command in
mozpluggerrc. 

.SH AUTHORS
Fredrik Hubinette, hubbe@hubbe.net
.br
Louis Bavoil, louis@bavoil.net
.br
Peter Leese, peter@leese.net