[MPlayer-DOCS] mplay man page

[Ziying Sherwin]

Dear Mplayer Colleagues,

When trying to execute the command "man mplayer" on a Sun workstation under
Solaris 8, we observe the following:

   Reformatting page.  Please Wait...nroff: Out of temp file space; line 4218, file /depot/man/man1/mplayer.1
    done

which, it has been suggested, is a result of "man" being set up incorrectly
on our systems.  Au contraire.  This results from the man page being written
in a manner which is radically inconsistent with longstanding procedure for
such documents, generated under nroff.  I am *guessing* (with no evidence)
that this document may have been generated on a machine using groff or
some other nroff follow-on, which has extended the originally defined behavior
of nroff.

I have attached a revised version of *part* of the file (I did not have time
to rewrite the whole thing -- but note below that I am volunteering to do
just that, if you help fet the GUI going on Solaris! :), using *standard*
nroff -man markup, which works just fine.

Several specific comments:

1) The original n/troff does not recognize macro names longer than two
   characters in length, whereas the mplayer man page defines many macros
   using names of more than two characters.

2) The use of the following:
      .SH NAME
      mplayer  \- Movie Player for Linux
      .br
      mencoder \- Movie Encoder for Linux
   is undesireable, as it breaks many related systems which assume a *one line*
   NAME content line -- for example, the use of the "windex" or "catman -w"
   commands to create a searchable index of NAME lines which can be examined
   using "apropos" or "man -k".  One fix is to combine the lines as I have
   in my example.  A better one is to create multiple man pages,
   cross-referencing them where appropriate (using internal references, and
   entries in the "SEE ALSO" section), to reduce the need to replicate
   information between them.

Please do not misconstrue this message as a criticism -- I support the
use of Linux, and am an emphatic supporter of both open standards and open
source software -- and I think the mplayer effort is a fantastic contribution!
However, if mplayer is going to be a truly portable package, it needs to
respect the originally defined behavior of nroff, which dates back to the
earliest days of UNIX.  None of the macro "enhancements" that I
observed in the supplied version of mplayer.1 seem to be critical, and I am
certain that the output could be made to look as desired using the traditional
-man macros.  In my haste to produce this document, I may have inadvertently
put some of the SYNOPSIS arguments in the wrong case, or made other minor
errors, but that is easily overcome by a quick read and some corrective editing
using *standard* -man macros. (if I had had a clear printable version of
the document, I would have probably come closer to the desired output).
There are a number of classical documents on writing standard UNIX manual
pages, which may prove helpful.  If I had had time, I would have made many
more adjustments to the document, which still deviates in considerable measure
from historical practive.  If you guys really help us get the GUI running
properly under Solaris, I will rewrite the man page for you in standard
-man macros.  I attach the work that I did do, which represents perhaps
10 percent of the document (large part of the center of the document is
omitted here).  It formats very smoothly on our systems.

Best Regards, Rick Rodgers
--------------------------------------------------------------------------------
.TH mplayer 1 "16 Jan 2004" "MPlayer Project"
.SH NAME
mplayer/mencoder  \- movie player/encoder for Linux
.SH SYNOPSIS
.B mplayer
.RI [ options ]
.RI [ file | URL | playlist | - ]
.br
.B mplayer
.RB [ "global options" ]
.I file1
.RB [ "specific options" ]
.RI [ file2 ]
.RB [ "specific options" ]
.br
.B mplayer
.RB [ "global options" ]
.RB { "group of files and options" }
.RB [ "group specific options" ]
.br
.B mplayer
.RB [ mms[t] | http | http_proxy
.RB | rt[s]p | ftp ]://
.RI [ user : passwd@ ] URL [: port ]
.RB [ options ]
.br
.B mplayer
.BI dvd:// title
.RB [ options ]
.br
.B mplayer
.BI vcd:// track
.RI [ /device ]
.RB [ options ]
.br
.B mplayer
.BR tv:// [
.IR channel ]
.RB [ options ]
.br
.B mplayer
.BI mf:// filemask
.RB [ options ]
.br
.B mplayer
.RB [ cdda | cddb ] ://
.I track
.RB [ :
.IR speed ][
.BI / device
.R ]
.RB [ options ]
.br
.B mplayer
.BI cue:// file
.RB [ :
.IR track ]
.RB [ options ]
.br
.B mplayer
.BI sdp:// file
.RB [ options ]
.br
.B mplayer
.BI mpst:// host
.RB [ :
.IR port ]
.BI / URL
.RB [ options ]
.br
.B mplayer
.RR dvb:// [
.I card_number
.BR @ ]
.I channel
.RB [ options ]
.br
.B mencoder
.RB [ options ]
.RI [ file | URL | \- ]
.RB [ \-o
.IR file ]
.br
.B gmplayer
.RB [ options ]
.RB [ \-skin
.IR skin ]
.SH DESCRIPTION
The
.B mplayer
application is a movie player for LINUX
(that runs on many other Unices and non\-x86 CPUs,
see the documentation).
It plays most MPEG/\:VOB, AVI, ASF/\:WMA/\:WMV, RM, QT/\:MOV/\:MP4, OGG/\:OGM,
VIVO, FLI, NuppelVideo, yuv4mpeg, FILM and RoQ files, supported by many
native, XAnim, and Win32 DLL codecs.
You can watch VideoCD, SVCD, DVD, 3ivx, DivX\ 3/\:4/\:5 and even WMV movies,
too (without using the avifile library).
.PP
Another great feature of MPlayer is the wide range of supported output
drivers.
It works with X11, Xv, DGA, OpenGL, SVGAlib, fbdev, AAlib, libcaca, DirectFB,
Quartz, but you can also use GGI, SDL (and all their drivers), VESA (on every
VESA compatible card, even without X11), some low level card-specific drivers
(for Matrox, 3Dfx and ATI) and some hardware MPEG decoder boards, such as the
Siemens DVB, DXR2 and DXR3/\:Hollywood+.
Most of them support software or hardware scaling, so you can enjoy movies in
fullscreen.
.PP
MPlayer has an onscreen display (OSD) for status information, nice big
antialiased shaded subtitles and visual feedback for keyboard controls.
European/\:ISO 8859-1,2 (Hungarian, English, Czech, etc), Cyrillic and Korean
fonts are supported along with 11 subtitle formats (MicroDVD, SubRip,
SubViewer, Sami, VPlayer, RT, SSA, AQTitle, JACOsub, PJS and our own: MPsub) and
DVD subtitles (SPU streams, VobSub and Closed Captions).
.PP
.B mencoder
(MPlayer's Movie Encoder) is a simple movie encoder, designed to encode
MPlayer-playable movies (see above) to other MPlayer-playable formats (see
below).
It encodes to DivX4, XviD, one of the libavcodec codecs and PCM/\:MP3/\:VBRMP3
audio in 1, 2 or 3\ passes.
Furthermore it has stream copying abilities, a powerful plugin system (crop,
expand, flip, postprocess, rotate, scale, noise, rgb/\:yuv conversion) and
more.
.PP
.B gmplayer
is MPlayer with a graphical user interface.
It has the same options as MPlayer.
.PP
.B Also see the HTML documentation!
.SH "KEYBOARD CONTROL"
MPlayer has a fully configurable, command driven, control layer
which allow you to control MPlayer using keyboard, mouse, joystick
or remote control (using
.IR lirc ).
.LP
The default configuration file for the input system is
.B ~/.mplayer/\:input.conf
but it can be overridden using the
.B \-input
conf option.
.LP
These keys may/\:may not work, depending on your video output driver.
.TP
.SS "General Control"
.TP
.BR <\- " and " \->
Seek backward/\:forward 10 seconds
.TP
.BR up " and " down
Seek backward/\:forward  1 minute
.TP
.BR pgup " and " pgdown
Seek backward/\:forward 10 minutes
.TP
.BR < " and " >
Backward/\:forward in playlist
.TP
.BR HOME " and " END
Go to next/\:previous playtree entry in the parent list
.TP
.BR INS " and " DEL
Go to next/\:previous alternative source (asx playlist only)
.TP
.BR p / SPACE
Pause movie (any key unpauses)
.TP
.BR q / ESC
Stop playing and quit
.TP
.BR + " and " -
Adjust audio delay by +/\:- 0.1 second
.TP
.BR / " and " *
Decrease/\:increase volume
.TP
.BR 9 " and " 0
Decrease/\:increase volume
.TP
.B m
Mute sound
.TP
.B f
Toggle fullscreen
.TP
.B T
Toggle stay-on-top.
Supported by drivers which use X11, except SDL, as well as directx and gl2 under Windows.
.TP
.BR w " and " e
Decrease/\:increase panscan range
.TP
.B o
Toggle between OSD states: none / seek / seek+timer
.TP
.B d
Toggle between frame dropping states: none / skip display / skip decoding
(see \-framedrop and \-hardframedrop)
.TP
.B v
Toggle subtitle visibility
.TP
.B j
Switch subtitle language
.TP
.B F
Toggle display of "forced subtitles"
.TP
.B a
Toggle subtitle aligment: top/middle/bottom
.TP
.BR z " and " x
Adjust subtitle delay by +/\:- 0.1 second
.TP
.BR r " and " t
Adjust subtitle position
.TP
.B i
Set EDL mark
.PP
(The following keys are valid only when using a hardware accelerated video
output (xv, (x)vidix, (x)mga, etc), or the software equalizer filter
(\-vf eq or \-vf eq2).
.TP
.BR 1 " and " 2
Adjust contrast
.TP
.BR 3 " and " 4
Adjust brightness
.TP
.BR 5 " and " 6
Adjust hue
.TP
.BR 7 " and " 8
adjust saturation
.SS "GUI Keyboard Control"
.TP
.B ENTER
Start playing
.TP
.B s
Stop playing
.TP
.B l
Load file
.TP
.B c
Skin browser
.TP
.B p
Toggle playlist
.SS "TV Input Control"
.TP
.BR h " and " k
Select previous/\:next channel
.TP
.B n
Change norm
.TP
.B u
Change channel list
.SH "OPTIONS"
.SS "Notes"
Every 'flag' option has a 'noflag' counterpart, e.g.\& the opposite of the
.B \-fs
option is
.BR \-nofs .
.PP
If an option is marked as (XXX only),
it will only work in combination with the XXX option or if XXX is compiled in.
.PP
You can put all of the options in a configuration file which will be read
every time MPlayer is run.
The system-wide configuration file 'mplayer.conf' is in your configuration
directory (e.g.\& /etc/\:mplayer or /usr/\:local/\:etc/\:mplayer), the user
specific one is '~/\:.mplayer/\:config'.
User specific options override system-wide options and options given on the
command line override either.
The syntax of the configuration files is 'option=<value>', everything after
a '#' is considered a comment.
Options that work without values can be enabled by setting them to 'yes'
or '1' and disabled by setting them to 'no' or '0'.
Even suboptions can be specified in this way.
.SS "Example"
.LP
.nf
.nh
# Use Matrox driver by default.
vo=xmga
# I love practicing handstands while watching videos.
flip=yes
# Decode/\:encode multiple files from png,
# start with mf://filemask
mf=type=png:fps=25
# Eerie negative images are cool.
vf=eq2=1.0:-0.8
.fi
.hy
.PP
You can also write file-specific configuration files.
If you wish to have a configuration file for a file called 'movie.avi', create a file
named 'movie.avi.conf' with the file-specific options in it and put it in
~/.mplayer or in the same directory as the file.
.SS "General Options"
.TP
.BI \-codecs-file " filename"
Use the specified file instead of system wide installed or builtin codecs.conf.
See also
.BRT \-afm ,
.BR \-ac ,
.BR \-vfm and \-vc .
.TP
.BR \-include " <configuration file>"
Specify configuration file to be parsed after the default ones.
.TP
.B \-quiet
With this option the status line (i.e. A:   0.7 V:   0.6 A-V:  0.068 ...)
will not be displayed.
Particularly useful on slow terminals or broken ones that do not properly
handle carriage return (i.e. \\r).
.TP
.BR \-v , " \-verbose"
Increment verbose level (more \-v means more verbosity).
.RS
.TP
.B 0
Only some informational output (default)
.RP
.B 1
Some basic debug infos, avi header, function values (init debug)
.TP
.B 2
Print avi indexes, chunk inputs, more debug infos (player debug)
.TP
.B 3
Prints everything related to input parsers (parser debug)
.RE
.SH "Player Options (mplayer only)"
.TP
.BI \-autoq " quality"
Dynamically changes the level of postprocessing depending on available spare
CPU time.
The number you specify will be the maximum level used.
Usually you can use some big number.
You have to use
.BR \-vf [s]pp
without parameters in order to use this.
.TP
.BI \-autosync " factor"
Gradually adjusts the A/\:V sync based on audio delay measurements.
Specifying \-autosync\ 0, the default, will cause frame timing to be based
entirely on audio delay measurements.
Specifying \-autosync\ 1 will do the same, but will subtly change the A/\:V
correction algorithm used.
An uneven video frame rate in a movie which plays fine with \-nosound can
often be helped by setting this to an integer value greater than 1.
The higher the value, the closer the timing will be to \-nosound.
Try \-autosync\ 30 to smooth out problems with sound drivers which do
not implement a perfect audio delay measurement.
With this value, if large A/\:V sync offsets occur, they will only take about
1 or 2\ seconds to settle out.
This delay in reaction time to sudden A/\:V offsets should be the only
side-effect of turning this option on, for all sound drivers.
.TP
.B \-benchmark
Prints some statistics on CPU usage and dropped frames at the end.
Use in combination with \-nosound and \-vo null for benchmarking only the
video codec.
.LP
.I NOTE:
With this option MPlayer will also ignore frame duration when playing
only video (you can think of that as infinite fps).
.TP
.BR \-colorkey " number"
Changes the colorkey to an RGB value of your choice.
0x000000 is black and 0xffffff is white.
Only supported by the cvidix, fbdev, svga, vesa, winvidix, xmga, xvidix and
xover video out drivers.
.TP
.B \-nocolorkey
Disables colorkeying.
Only supported by the cvidix, fbdev, svga, vesa, winvidix, xmga, xvidix and
xover video out drivers.
.TP
.BI \-edl " filename"
Enables edit decision list (EDL) actions during playback.
Video will be skipped over and audio will be muted and unmuted according to
the entries in the given file.
See DOCS/HTML/en/edl.html for details on how to use this.
.TP
.BI \-edlout " filename"
Creates a new file and writes edit decision list (EDL) records to that file.
During playback, when the user hits 'i', an entry to skip over the last two
seconds of playback will be written to the file.
This provides a starting point from which the user can fine-tune EDL entries
later.
See DOCS/HTML/en/edl.html for details.
.TP
.BI \-enqueue
Enqueue files given on the command line in the playlist
instead of playing them immediately (GUI only).
.TP
.B \-fixed-vo
Enforces a fixed video system for multiple files
(one (un)initialisation for all files).
Therefore only one window will be opened for all files.
Currently the following drivers are fixed-vo compliant: gl2, mga, svga, x11,
xmga, xv and xvidix.
(BETA CODE!).
.TP
.B \-framedrop
Skip displaying some frames to maintain A/\:V sync on slow systems.
Video filters are not applied to such frames.
For B frames even decoding is skipped completely.
(also see
.BR \-hardframedrop )
.TP
.BR \-h , " \-help" , " \-\-help"
Show short summary of options.
.TP
.B \-hardframedrop
More intense frame dropping (breaks decoding).
Leads to image distortion!
.TP
.B \-identify
Show file parameters in easy parsable format.
The wrapper script TOOLS/midentify suppresses the other MPlayer output and
(hopefully) shellescapes the filenames.
.TP
.B \-input <commands>
This option can be used to configure certain parts of the input system.
Paths are relative to ~/\:.mplayer/.
.LP
.I NOTE:
Autorepeat is currently only supported by joysticks.
.LP
Available commands are:
.RS
.TP
.BI conf= file
Read alternative input.conf.
If given without pathname, ~/\:.mplayer is assumed.
.TP
.B ar-delay
Delay in msec before we start to autorepeat a key (0 to disable).
.TP
.B ar-rate
How many key presses per second when we autorepeat.
.TP
.B keylist
Prints all keys that can be bound.
.TP
.B cmdlist
Prints all commands that can be bound.
.TP
.B js-dev
Specifies the joystick device to use (default is /dev/\:input/\:js0).
.TP
.B file
Read commands from the given file.
Mostly useful with a fifo.
.LP
.I NOTE:
When the given file is a fifo MPlayer opens both ends so you can do
several 'echo "seek 10" > mp_pipe' and the pipe will stay valid.
.RE
.TP
.BI \-lircconf " file"
Specifies a configuration file for LIRC (Linux Infrared Remote Control, see
http://www.lirc.org) if you don't like the default ~/\:.lircrc.
(LIRC only).
.TP
.B \-list-options
Prints out all the available options.
.TP
.BI \-loop " number"
Loops movie playback
.I number
times;
0 means forever.
.TP
.B \-menu
Turn on OSD menu support (OSD menu only).
.TP
.BI \-menu-cfg " file"
Use an alternative
.I menu.conf
OSD menu only).
.TP
.BI \-menu-root " value"
Specify the main menu (OSD menu only).
.TP
.B \-nojoystick
Turns off joystick support.
Default is on, if compiled in.
.TP
.B \-nolirc
Turns off LIRC support.
.TP
.B \-nomouseinput
Disable mouse button press/release input (mozplayerxp's context menu relies
on this option).  (X11 only).
.TP
.B \-nortc
Turns off usage of the Linux RTC (real-time clock \- /dev/\:rtc) as timing
mechanism.  (RTC only).
.TP
.BI \-playlist " file"
Play files according to a playlist (1 file per row or Winamp or ASX format).
.LP
.I NOTE:
This option is considered an entry so options found after it will apply
only to the elements of this playlist.
.TP
.B \-really-quiet
Display even less output and status messages.
.TP
.B \-shuffle
Play files in random order.
.TP
.BI \-skin " skin_directory"
Load skin from the given directory (WITHOUT path name).
(GUI only).
For example:
.RS
.IP
.B "\-skin fittyfene"
.LP
tries Skin/fittyfene.
It first checks
.I /usr/local/share/mplayer/
and afterwards
.IR ~/.mplayer/ .
.RE
.TP
.B \-slave
This option switches on slave mode.
This is intended for use of MPlayer as a backend to other programs.
Instead of intercepting keyboard events, MPlayer will read simplistic command
lines from its stdin.
.TP
.B \-softsleep
Uses high quality software timers.
As precise as the RTC without requiring special privileges.
Comes at the price of higher CPU consumption.
.TP
.BR \-speed " rate"
Set playback speed rate, where
.I rate
varies from 0.01 to 100.
.TP
.BI \-sstep " sec"
Specifies seconds between displayed frames.
Useful for slideshows.
.TP
.B \-use-stdin
The standard input (aka. stdin) will be used to read data instead of key
events.  If you open /dev/stdin (or the equivalent on your system), use stdin
in a playlist or intend to read from stdin later on via the loadfile or
loadlist commands you
.B need
this option.
.SH "DEMUXER/STREAM OPTIONS"
.TP
.BI \-a52drc " level"
Select the Dynamic Range Compression level for AC3 audio streams,
where
.I level
is a float value ranging from 0 to 1, where 0 means no compression
and 1 (which is the default) means full compression (make loud passages more
silent and vice versa).
This option only shows an effect if the AC3 stream contains the required range
compression information.
.TP
.BI \-aid " id"
Select audio channel [MPEG: 0\-31 AVI/\:OGM: 1\-99 ASF/\:RM: 0\-127
VOB(AC3): 128\-159 VOB(LPCM): 160\-191 MPEG-TS 17\-8190].
MPlayer prints the available IDs when running in verbose (\-v) mode.
When playing an MPEG-TS stream, MPlayer/Mencoder will use the first program
(if present) with the chosen audio stream.
(Also see \-alang option).
.TP
.BI \-alang " code"
Works only for DVD playback,
where
.I code
is a two-letter country code.
It selects the DVD audio language and always tries to play audio streams whose
language matches the given code.
For the list of available languages,
use with the
.B \-v
option and look at the output.
(Also see
.B \-aid
option).
For example:
.RS
.IP
.B "\-alang hu,en"
.LP
plays Hungarian and falls back to English if Hungarian is not available.
.RE
.TP
.BI \-audio-demuxer " number"
Force audio demuxer type for \-audiofile.
Give the demuxer ID as defined in libmpdemux/demuxer.h.
Use \-audio-demuxer 17 to force .mp3 detection.
.RB ( \-audiofile
only).
.TP
.BI \-audiofile " filename"
Play audio from an external file (WAV, MP3 or Ogg Vorbis) while viewing a
movie.
.TP
.BI \-audiofile-cache " kBytes"
Enables caching for the stream used by
.BR \-audiofile ,
using the specified amount of memory.
.PP
[.. deletions here ...]
.SH AUTHORS
MPlayer was initially written by Arpad Gereoffy.
See the AUTHORS file for a list of some of the many other contributors.
.TP
MPlayer is (C) 2000\-2004
.B The MPlayer Team
.TP
This man page is written and maintained by
.B Gabucino
.br
.B Diego Biurrun
.br
.B Jonas Jermann
.PP
Please send mails about it to the MPlayer-DOCS mailing list.
.SH "STANDARD DISCLAIMER"
Use only at your own risk!
There may be errors and inaccuracies that could be damaging to your system or
your eye.
Proceed with caution, and although this is highly unlikely, the authors don't
take any responsibility for that!
.\" end of file