NAME¶
mozplugger - a streaming multimedia plugin for UNIX mozilla
DESCRIPTION¶
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.
You can configure mozplugger by changing the file
mozpluggerrc which can
be located in any of the following directories:
$MOZPLUGGER_HOME/
$HOME/.mozplugger/
$HOME/.netscape/
$HOME/.mozilla/
$HOME/.opera/
$MOZILLA_HOME/
$OPERA_HOME/
/usr/local/netscape/
/etc/
/usr/local/mozilla/
/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
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
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¶
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.
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
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. 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
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¶
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.
- 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¶
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
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 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.
- 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 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.
- 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 Mozplugger.
- MOZPLUGGER_HOME
- If MOZPLUGGER_HOME is defined, the folder $MOZPLUGGER_HOME is checked for
the configuration file 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 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¶
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
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 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.
AUTHORS¶
Fredrik Hubinette, hubbe@hubbe.net
Louis Bavoil, louis@bavoil.net
Peter Leese, peter@leese.net