path: root/DOCS/xml/en/usage.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<chapter id="usage">
<title>Usage</title>

<sect1 id="commandline">
<title>Command line</title>

<para>
<application>MPlayer</application> utilizes a complex playtree. It consists
of global options written as first, for example

<screen>mplayer -vfm 5</screen>

and options written after filenames, that apply only to the given
filename/URL/whatever, for example:

<screen>mplayer -vfm 5 <replaceable>movie1.avi</replaceable> <replaceable>movie2.avi</replaceable> -vfm 4</screen>
</para>

<para>
You can group filenames/URLs together using <literal>{</literal> and
<literal>}</literal>. It is useful with option <option>-loop</option>:

<screen>mplayer { 1.avi -loop 2 2.avi } -loop 3</screen>

The above command will play files in this order: 1, 1, 2, 1, 1, 2, 1, 1, 2.
</para>

<para>
Playing a file:
<synopsis>
<command>mplayer</command><!--
--> [<replaceable>options</replaceable>]<!--
--> [<replaceable>path</replaceable>/]<replaceable>filename</replaceable>
</synopsis>
</para>

<para>
Another way to play a file:
<synopsis>
<command>mplayer</command><!--
--> [<replaceable>options</replaceable>]<!--
--> <replaceable>file:///uri-escaped-path</replaceable>
</synopsis>
</para>

<para>
Playing more files:
<synopsis>
<command>mplayer</command><!--
--> [<replaceable>default options</replaceable>]<!--
--> [<replaceable>path</replaceable>/]<replaceable>filename1</replaceable><!--
--> [<replaceable>options for filename1</replaceable>]<!--
--> <replaceable>filename2</replaceable><!--
--> [<replaceable>options for filename2</replaceable>] ...
</synopsis>
</para>

<para>
Playing VCD:
<synopsis>
<command>mplayer</command> [<replaceable>options</replaceable>]<!--
--> vcd://<replaceable>trackno</replaceable><!--
--> [-cdrom-device <replaceable>/dev/cdrom</replaceable>]
</synopsis>
</para>

<para>
Playing DVD:
<synopsis>
<command>mplayer</command> [<replaceable>options</replaceable>]<!--
--> dvd://<replaceable>titleno</replaceable><!--
--> [-dvd-device <replaceable>/dev/dvd</replaceable>]
</synopsis>
</para>

<para>
Playing from the WWW:
<synopsis>
<command>mplayer</command> [<replaceable>options</replaceable>]<!--
--> http://<replaceable>site.com/file.asf</replaceable>
</synopsis>
(playlists can be used, too)
</para>

<para>
Playing from RTSP:
<synopsis>
<command>mplayer</command> [<replaceable>options</replaceable>]<!--
--> rtsp://<replaceable>server.example.com/streamName</replaceable>
</synopsis>
</para>

<para>
Examples:
<screen>
mplayer -vo x11 <replaceable>/mnt/Films/Contact/contact2.mpg</replaceable>
mplayer vcd://<replaceable>2</replaceable> -cdrom-device <replaceable>/dev/hdc</replaceable>
mplayer -afm 3 <replaceable>/mnt/DVDtrailers/alien4.vob</replaceable>
mplayer dvd://<replaceable>1</replaceable> -dvd-device <replaceable>/dev/hdc</replaceable>
mplayer -abs 65536 -delay -0.4 -nobps <replaceable>~/movies/test.avi</replaceable><!--
--></screen>
</para>
</sect1>


<sect1 id="control">
<title>Control</title>

<para>
<application>MPlayer</application> has a fully configurable, command
driven, control layer which lets you control
<application>MPlayer</application> with keyboard, mouse, joystick or remote
control (using LIRC). See the man page for the complete list of keyboard controls.
</para>


<sect2 id="ctrl-cfg">
<title>Controls configuration</title>

<para>
<application>MPlayer</application> allows you bind any key/button to any
<application>MPlayer</application> command using a simple config file.
The syntax consist of a key name followed by a command. The default config file location is
<filename>$HOME/.mplayer/input.conf</filename> but it can be overridden
using the <option>-input <replaceable>conf</replaceable></option> option
(relative path are relative to <filename>$HOME/.mplayer</filename>).
</para>

<para>
You can get a full list of supported key names by running
<command>mplayer -input keylist</command>
and a full list of available commands by running
<command>mplayer -input cmdlist</command>.
</para>

<example>
<title>A simple input control file</title>
<programlisting>
##
## MPlayer input control file
##

RIGHT seek +10
LEFT seek -10
- audio_delay 0.100
+ audio_delay -0.100
q quit
&gt; pt_step 1
&lt; pt_step -1
ENTER pt_step 1 1<!--
--></programlisting>
</example>
</sect2>


<sect2 id="lirc">
<title>Control from LIRC</title>

<para>
Linux Infrared Remote Control - use an easy to build home-brewn IR-receiver,
an (almost) arbitrary remote control and control your Linux box with it!
More about it on the <ulink url="http://www.lirc.org">LIRC homepage</ulink>.
</para>

<para>
If you have the LIRC package installed, <filename>configure</filename> will
autodetect it. If everything went fine, <application>MPlayer</application>
will print &quot;<systemitem>Setting up LIRC support...</systemitem>&quot;
on startup. If an error occurs it will tell you. If there is no message about
LIRC there is no support compiled in. That's it :-)
</para>

<para>
The application name for <application>MPlayer</application> is - surprise -
<filename>mplayer</filename>. You can use any <application>MPlayer</application>
commands and even pass more than one command by separating them with
<literal>\n</literal>.
Do not forget to enable the repeat flag in <filename>.lircrc</filename> when
it makes sense (seek, volume, etc). Here is an excerpt from a sample
<filename>.lircrc</filename>:
</para>

<programlisting>
begin
     button = VOLUME_PLUS
     prog = mplayer
     config = volume 1
     repeat = 1
end

begin
    button = VOLUME_MINUS
    prog = mplayer
    config = volume -1
    repeat = 1
end

begin
    button = CD_PLAY
    prog = mplayer
    config = pause
end

begin
    button = CD_STOP
    prog = mplayer
    config = seek 0 1\npause
end<!--
--></programlisting>

<para>
If you do not like the standard location for the lirc-config file
(<filename>~/.lircrc</filename>) use the <option>-lircconf
<replaceable>filename</replaceable></option> switch to specify another
file.
</para>
</sect2>


<sect2 id="slave-mode">
<title>Slave mode</title>
<para>
The slave mode allows you to build simple frontends to
<application>MPlayer</application>. When run with the
<option>-slave</option> option <application>MPlayer</application> will
read commands separated by a newline (\n) from stdin.
The commands are documented in the
<ulink url="../../tech/slave.txt">slave.txt</ulink> file.
</para>
</sect2>
</sect1>


<sect1 id="streaming">
<title>Streaming from network or pipes</title>

<para>
<application>MPlayer</application> can play files from the network, using the
HTTP, FTP, MMS or RTSP/RTP protocol.
</para>

<para>
Playing works simply by passing the URL on the command line.
<application>MPlayer</application> honors the <envar>http_proxy</envar>
environment variable, using a proxy if available. Proxies can also be forced:
<screen>mplayer <replaceable>http_proxy://proxy.micorsops.com:3128/http://micorsops.com:80/stream.asf</replaceable></screen>
</para>

<para>
<application>MPlayer</application> can read from stdin
(<emphasis>not</emphasis> named pipes). This can for example be used to
play from FTP:
<screen>wget <replaceable>ftp://micorsops.com/something.avi</replaceable> -O - | mplayer -</screen>
</para>

<note><para>
It is also recommended to enable <option>-cache</option> when playing
from the network:
<screen>wget <replaceable>ftp://micorsops.com/something.avi</replaceable> -O - | mplayer -cache 8192 -</screen>
</para></note>

<sect2 id="streaming-save">
<title>Saving streamed content</title>
<para>
  Once you succeed in making <application>MPlayer</application> play
  your favorite internet stream, you can use the option
  <option>-dumpstream</option> to save the stream into a file.
  For example:
<screen>
  mplayer <replaceable>http://217.71.208.37:8006</replaceable> -dumpstream -dumpfile <replaceable>stream.asf</replaceable>
</screen>
  will save the content streamed from
  <replaceable>http://217.71.208.37:8006</replaceable> into
  <replaceable>stream.asf</replaceable>.
  This works with all protocols supported by
  <application>MPlayer</application>, like MMS, RSTP, and so forth.
</para>
</sect2>

</sect1>

<sect1 id="mpst" xreflabel="Remote streams">
<title>Remote streams</title>

<para>
Remote streams allow you to access most <application>MPlayer</application>
stream type from a remote host. The main purpose of this feature is to make
it possible to directly use the CD or DVD drive of another computer on the
network (provided you have the required bandwidth). On the downside some
stream type (currently TV and MF) are not usable remotely because they are
implemented at the demuxer level. It is sad for MF but TV stream would anyway
require an insane amount of bandwidth.
</para>

<sect2 id="compile_mpst_server">
<title>Compiling the server</title>
<para>
After having compiled <application>MPlayer</application> go to the
<filename>TOOLS/netstream</filename> directory and enter
<application>make</application> to build the server binary.
You can then copy the <application>netstream</application> binary
to the right place on your system (usually
<filename class="directory">/usr/local/bin</filename> on Linux).
</para>
</sect2>

<sect2 id="use_mpst">
<title>Using remote streams</title>
<para>
First you have to start the server on the computer you intend to remotely
access. Currently the server is very basic and does not have any commands
line arguments so just enter <filename>netstream</filename>. Now you can
for example play the second track of a VCD on the server with :
<screen>
mplayer -cache 5000 <replaceable>mpst://servername/vcd://2</replaceable>
</screen>
You can also access files on this server :
<screen>
mplayer -cache 5000 <replaceable>mpst://servername//usr/local/movies/lol.avi</replaceable>
</screen>
Note that paths which aren't starting with a / will be relative to
the directory where the server is running. The <option>-cache</option> option is not
needed but highly recommended.
</para>

<para>
Be aware that currently the server is not secure at all. So do not complain
about the numerous exploits which are possible through this. Instead send
some (good) patch to make it better or start writing your own server.
</para>

</sect2>

</sect1>

<sect1 id="edl" xreflabel="Edit Decision Lists (EDL)">
<title>Edit Decision Lists (EDL)</title>

<para>
The edit decision list (EDL) system allows you to automatically skip
or mute sections of videos during playback, based on a movie specific
EDL configuration file.
</para>

<para>
This is useful for those who may want to watch a film in "family-friendly"
mode. You can cut out any violence, profanity, Jar-Jar Binks .. from a movie
according to your own personal preferences. Aside from this, there are other
uses, like automatically skipping over commercials in video files you watch.
</para>

<para>
The EDL file format is pretty bare-bones. There is one command per line that
indicates what to do (skip/mute) and when to do it (using pts in seconds).
</para>

<sect2 id="edl_using">
<title>Using an EDL file</title>
<para>
Include the <option>-edl &lt;filename&gt;</option> flag when you run
<application>MPlayer</application>, with the name of the EDL file you
want applied to the video.
</para>
</sect2>

<sect2 id="edl_making">
<title>Making an EDL file</title>
<para>
The current EDL file format is:
<programlisting>
[begin second] [end second] [action]
</programlisting>
Where the seconds are floating-point numbers and the action is either
<literal>0</literal> for skip or <literal>1</literal> for mute. Example:
<programlisting>
5.3   7.1    0
15    16.7   1
420   422    0
</programlisting>
This will skip from second 5.3 to second 7.1 of the video, then mute at
15 seconds, unmute at 16.7 seconds and skip from second 420 to second 422
of the video. These actions will be performed when the playback timer
reaches the times given in the file.
</para>

<para>
To create an EDL file to work from, use the <option>-edlout &lt;filename&gt;</option>
flag. During playback, just hit <keycap>i</keycap> to mark the beginning and 
end of a skip block. A corresponding entry will be written to the file for
that time. You can then go back and fine-tune the generated EDL file as well as
change the default operation which is to skip the block described by each line.
</para>
</sect2>

</sect1>


<sect1 id="advaudio" xreflabel="Advanced Audio">
<title>Advanced audio</title>

<sect2 id="advaudio-surround">
<title>Surround/Multichannel playback</title>

<sect3 id="advaudio-surround-DVD">
<title>DVDs</title>
<para>
Most DVDs and many other files include surround sound.
<application>MPlayer</application> supports surround playback but does not
enable it by default because stereo equipment is by far more common. To play a
file that has more than two channels of audio use <option>-channels</option>.
For example, to play a DVD with 5.1 audio:

<screen>mplayer dvd://1 -channels 6</screen>

Note that despite the name "5.1" there are actually six discrete channels.
If you have surround sound equipment it is safe to put the
<option>channels</option> option in your <application>MPlayer</application>
configuration file <filename>~/.mplayer/config</filename>. For example, to make
quadraphonic playback the default, add this line:

<programlisting>channels=4</programlisting>

<application>MPlayer</application> will then output audio in four channels when
all four channels are available.
</para>
</sect3>


<sect3 id="advaudio-surround-stereoinfour">
<title>Playing stereo files to four speakers</title>

<para>
<application>MPlayer</application> does not duplicate any channels by default,
and neither do most audio drivers. If you want to do that manually:

<screen>mplayer <replaceable>filename</replaceable> -af channels=2:2:0:1:0:0</screen>

See the section on
<link linkend="advaudio-channels-copying">channel copying</link> for an
explanation.
</para>

</sect3>


<sect3 id="advaudio-surround-passthrough">
<title>AC3/DTS Passthrough</title>

<para>
DVDs usually have surround audio encoded in AC3 (Dolby Digital) or DTS
(Digital Theater System) format. Some modern audio equipment is capable of
decoding these formats internally. <application>MPlayer</application> can be
configured to relay the audio data without decoding it. This will only work if
you have a S/PDIF (Sony/Philips Digital Interface) jack in your sound card.
</para>

<para>
If your audio equipment can decode both AC3 and DTS, you can safely enable
passthrough for both formats. Otherwise, enable passthrough for only the format
your equipment supports.
</para>

<itemizedlist>
<title>To enable passthrough on the command line:</title>
<listitem><para>
For AC3 only, use <option>-ac hwac3</option>
</para></listitem>
<listitem><para>
For DTS only, use <option>-ac hwdts</option>
</para></listitem>
<listitem><para>
For both AC3 and DTS, use <option>-afm hwac3</option>
</para></listitem>
</itemizedlist>

<itemizedlist>
<title>To enable passthrough in the <application>MPlayer</application>
configuration file: </title>
<listitem><para>
For AC3 only, use <option>ac=hwac3,</option>
</para></listitem>
<listitem><para>
For DTS only, use <option>ac=hwdts,</option>
</para></listitem>
<listitem><para>
For both AC3 and DTS, use <option>afm=hwac3</option>
</para></listitem>
</itemizedlist>

<para>
Note that there is a comma (",") at the end of
<option>ac=hwac3,</option> and <option>ac=hwdts,</option>. This will make
<application>MPlayer</application> fall back on the codecs it normally uses when
playing a file that does not have AC3 or DTS audio. <option>afm=hwac3</option>
does not need a comma; <application>MPlayer</application> will fall back anyway
when an audio family is specified.
</para>

</sect3>

<sect3 id="hwmpa-surround-passthrough">
<title>MPEG audio Passthrough</title>

<para>
Digital TV transmissions (such as DVB and ATSC) and some DVDs usually have 
MPEG audio streams (in particular MP2).
Some MPEG hardware decoders such as full-featured DVB cards and DXR2 
adapters can natively decode this format. 
<application>MPlayer</application> can be configured to relay the audio data 
without decoding it.
</para>

<para>
To use this codec:
<screen> mplayer -ac hwmpa </screen>
</para>
</sect3>

<sect3 id="advaudio-surround-matrix">
<title>Matrix-encoded audio</title>

<para>
<emphasis>***TODO***</emphasis>
</para>
<para>
This section has yet to be written and cannot be completed until somebody
provides sample files for us to test. If you have any matrix-encoded audio
files, know where to find some, or have any information that could be helpful,
please send a message to the
<ulink url="http://mplayerhq.hu/mailman/listinfo/mplayer-docs">MPlayer-DOCS</ulink>
mailing list. Put "[matrix-encoded audio]" in the subject line.
</para>
<para>
If no files or further information are forthcoming this section will be dropped.
</para>

<para>
Good links:
<itemizedlist>
<listitem><para>
<ulink url="http://electronics.howstuffworks.com/surround-sound5.htm">http://electronics.howstuffworks.com/surround-sound5.htm</ulink>
</para></listitem>
<listitem><para>
<ulink url="http://www.extremetech.com/article2/0,1697,1016875,00.asp">http://www.extremetech.com/article2/0,1697,1016875,00.asp</ulink>
</para></listitem>
</itemizedlist>
</para>

</sect3>


<sect3 id="advaudio-surround-hrtf">
<title>Surround emulation in headphones</title>

<para>
<application>MPlayer</application> includes an HRTF (Head Related Transfer
Function) filter based on an
<ulink url="http://sound.media.mit.edu/KEMAR.html">MIT project</ulink>
wherein measurements were taken from microphones mounted on a dummy human head.
</para>

<para>
Although it is not possible to exactly imitate a surround system,
<application>MPlayer</application>'s HRTF filter does provide more spatially
immersive audio in 2-channel headphones. Regular downmixing simply combines all
the channels into two; besides combining the channels, <option>hrtf</option>
generates subtle echoes, increases the stereo separation slightly, and alters
the volume of some frequencies. Whether HRTF sounds better may be dependent on
the source audio and a matter of personal taste, but it is definitely worth
trying out.
</para>

<para>
To play a DVD with HRTF:

<screen>mplayer dvd://1 -channels 6 -af hrtf</screen>

</para>

<para>
<option>hrtf</option> only works well with 5 or 6 channels. Also,
<option>hrtf</option> requires 48 kHz audio. DVD audio is already 48 kHz, but if
you have a file with a different sampling rate that you want to play using
<option>hrtf</option> you must resample it:

<screen>mplayer <replaceable>filename</replaceable> -channels 6 -af resample=48000,hrtf</screen>

</para>

</sect3>


<sect3 id="advaudio-surround-troubleshooting">
<title>Troubleshooting</title>

<para>
If you do not hear any sound out of your surround channels, check your mixer
settings with a mixer program such as <application>alsamixer</application>;
audio outputs are often muted and set to zero volume by default.
</para>

</sect3>

</sect2>


<sect2 id="advaudio-channels">
<title>Channel manipulation</title>

<sect3 id="advaudio-channels-general">
<title>General information</title>

<para>
Unfortunately, there is no standard for how channels are ordered. The orders
listed below are those of AC3 and are fairly typical; try them and see if your
source matches. Channels are numbered starting with 0.

<orderedlist spacing="compact">
<title>mono</title>
<listitem override="0"><simpara>center</simpara></listitem>
</orderedlist>

<orderedlist spacing="compact">
<title>stereo</title>
<listitem override="0"><simpara>left</simpara></listitem>
<listitem><simpara>right</simpara></listitem>
</orderedlist>

<orderedlist spacing="compact">
<title>quadraphonic</title>
<listitem override="0"><simpara>left front</simpara></listitem>
<listitem><simpara>right front</simpara></listitem>
<listitem><simpara>left rear</simpara></listitem>
<listitem><simpara>right rear</simpara></listitem>
</orderedlist>

<orderedlist spacing="compact">
<title>surround 4.0</title>
<listitem override="0"><simpara>left front</simpara></listitem>
<listitem><simpara>right front</simpara></listitem>
<listitem><simpara>center rear</simpara></listitem>
<listitem><simpara>center front</simpara></listitem>
</orderedlist>

<orderedlist spacing="compact">
<title>surround 5.0</title>
<listitem override="0"><simpara>left front</simpara></listitem>
<listitem><simpara>right front</simpara></listitem>
<listitem><simpara>left rear</simpara></listitem>
<listitem><simpara>right rear</simpara></listitem>
<listitem&g