comparison DOCS/xml/en/usage.xml @ 16407:ba2b36441de7

Avoid some short forms, some consistency, wording and typo fixes.

16406:c2cd00bfa3c0

<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's 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>
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>.
Don't forget to enable the repeat flag in <filename>.lircrc</filename> when
it makes sense (seek, volume, etc). Here's an excerpt from a sample
<filename>.lircrc</filename>:
</para>

<programlisting>
begin

    config = seek 0 1\npause
end<!--
--></programlisting>

<para>
If you don't 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>

play from FTP:
<screen>wget <replaceable>ftp://micorsops.com/something.avi</replaceable> -O - | mplayer -</screen>
</para>

<note><para>
It's 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">

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's 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>

<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 doesn't 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>

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 don't 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="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.

</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:

For both AC3 and DTS, use <option>-afm hwac3</option>
</para></listitem>
</itemizedlist>

<para>
Note that there is a comma ("<keycap>,</keycap>") at the end of
<option>ac=hwac3,</option> and <option>ac=hwdts,</option>. This will make
<application>MPlayer</application> fall back to the codecs it normally uses when
playing a file that doesn't 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="advaudio-surround-matrix">
<title>Matrix-encoded Audio</title>

<para>
<emphasis>***TODO***</emphasis>
</para>
<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 MIT project wherein measurements were taken from
microphones mounted on a dummy human head. See the
<ulink url="http://sound.media.mit.edu/KEMAR.html">project page</ulink> for more
information.
</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 dependant on
the source audio and a matter of personal taste, but it is definitely worth
trying out.
</para>

<para>

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

<para>
If you don't 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><simpara>center front</simpara></listitem>
</orderedlist>

<orderedlist spacing="compact">
<title>Surround 5.1</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><simpara>center front</simpara></listitem>

</sect3>


<sect3 id="advaudio-channels-mono">
<title>Playing Mono in Two Speakers</title>

<para>
Mono sounds a lot better when played through two speakers -- especially when
using headphones. Audio files that truly have 1 channel are automatically played
in two speakers; unfortunately, most files with mono sound are actually encoded
as stereo with one channel silent. The easiest and most foolproof way to make
both speakers output the same audio is with the <option>extrastereo</option>
filter:

<screen>mplayer <replaceable>filename</replaceable> -af extrastereo=0</screen>

</para>

</sect3>


<sect3 id="advaudio-channels-copying">
<title>Channel Copying/Moving</title>

<para>
The <option>channels</option> filter can move any or all channels. Setting up all
the suboptions to channels can be complicated and takes a little care.

<orderedlist spacing="compact">
<listitem><para>
Decide how many output channels you need. This is the first suboption.
</para></listitem>

<bridgehead>Example: one channel in two speakers</bridgehead>

<para>
Here's an example of another way to play one channel in both speakers. Suppose
for this example that the left channel should be played and the right channel
discarded. Following the steps above:
<orderedlist>
<listitem><para>
In order to provide an output channel for each of the two speakers, the first

to itself so it won't be empty. This is a total of two moves, making the second
suboption "2" as well.
</para></listitem>
<listitem><para>
To move the left channel (channel 0) into the right channel (channel 1), the
suboption pair is "0:1". To move the left channel into itself is "0:0".
</para></listitem>
</orderedlist>
Putting that all together gives:

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

<para>
The advantage this example has over <option>extrastereo</option> is that the
volume of each output channel is the same as the input channel. The disadvantage
is that the suboptions must be changed to "2:2:1:0:1:1" when the desired audio
is in the right channel. Also, it's more difficult to remember and type.
</para>

<bridgehead>Example: left channel in two speakers shortcut</bridgehead>

<para>

</sect3>


<sect3 id="advaudio-channels-mixing">
<title>Channel Mixing</title>

<para>
The <option>pan</option> filter can mix channels in user-specified proportions.
This allows for everything the <option>channels</option> filter can do and
more. Unfortunately, the suboptions are much more complicated.

will show when to use which.
</para></listitem>
<listitem><para>
Decide how many channels to feed into <option>pan</option> (further decoded
channels are discarded). This is the first suboption, and it also controls how
many channels are output.
</para></listitem>
<listitem><para>
The remaining suboptions specify how much of each channel gets mixed into each
other channel. This is the complicated part. To break the task down, split the
suboptions into several sets, one set for each output channel. Each suboption

<para>
<option>pan</option> accepts values from 0 to 512, yielding 0% to 51200% of the
original volume. Be careful when using values greater than 1. Not only can this
give you very high volume, but if you exceed the sample range of your sound card
you may hear painful pops and clicks. If you want you can follow
<option>pan</option> with <option>,volume</option> to enable clipping, but it's
best to keep the values of <option>pan</option> low enough that clipping is not
necessary.
</para></listitem>
</orderedlist>
</para>

</para>

<bridgehead>Example: downmixing 6-channel PCM</bridgehead>
<para>
<application>MPlayer</application>'s decoder for 6-channel PCM is not capable of
downmixing. Here's a way to downmix PCM using <option>pan</option>:
<orderedlist>
<listitem><para>
The number of output channels is 2. Since <option>pan</option> will be handling
6 channels, it may be necessary to put <option>,channels=2</option> after pan to
get rid of the extra channels. If your sound card is capable of 6-channel

</sect2>


<sect2 id="advaudio-volume">
<title>Software Volume Adjustment</title>

<para>
Some audio tracks are too quiet to be heard comfortably without amplification.
This becomes a problem when your audio equipment cannot amplify the signal for
you. The <option>-softvol</option> option directs

original volume. For example, <option>-softvol-max 200</option> would allow the
volume to be adjusted up to twice its original level.
It is safe to specify a large value with
<option>-softvol-max</option>; the higher volume will not be used until you
use the volume adjustment keys. The only disadvantage of a large value is that,
since <application>MPlayer</application> adjusts volume by percentage of the
maximum, you will not have as precise control when using the volume adjustment
keys. Use a lower value with <option>-softvol-max</option> and/or specify
<option>-volstep 1</option> if you need higher precision.
</para>

16407:ba2b36441de7

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

    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>

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">

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>

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

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="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.

</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:

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="advaudio-surround-matrix">
<title>Matrix-encoded audio</title>

<para>
<emphasis>***TODO***</emphasis>
</para>
<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>

<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><simpara>center front</simpara></listitem>
</orderedlist>

<orderedlist spacing="compact">
<title>surround 5.1</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><simpara>center front</simpara></listitem>

</sect3>


<sect3 id="advaudio-channels-mono">
<title>Playing mono with two speakers</title>

<para>
Mono sounds a lot better when played through two speakers - especially when
using headphones. Audio files that truly have one channel are automatically
played through two speakers; unfortunately, most files with mono sound are
actually encoded as stereo with one channel silent. The easiest and most
foolproof way to make both speakers output the same audio is the
<option>extrastereo</option> filter:

<screen>mplayer <replaceable>filename</replaceable> -af extrastereo=0</screen>

</para>

</sect3>


<sect3 id="advaudio-channels-copying">
<title>Channel copying/moving</title>

<para>
The <option>channels</option> filter can move any or all channels.
Setting up all the suboptions for the <option>channels</option>
filter can be complicated and takes a little care.

<orderedlist spacing="compact">
<listitem><para>
Decide how many output channels you need. This is the first suboption.
</para></listitem>

<bridgehead>Example: one channel in two speakers</bridgehead>

<para>
Here is an example of another way to play one channel in both speakers. Suppose
for this example that the left channel should be played and the right channel
discarded. Following the steps above:
<orderedlist>
<listitem><para>
In order to provide an output channel for each of the two speakers, the first

to itself so it won't be empty. This is a total of two moves, making the second
suboption "2" as well.
</para></listitem>
<listitem><para>
To move the left channel (channel 0) into the right channel (channel 1), the
suboption pair is "0:1", "0:0" moves the left channel onto itself.
</para></listitem>
</orderedlist>
Putting that all together gives:

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

<para>
The advantage this example has over <option>extrastereo</option> is that the
volume of each output channel is the same as the input channel. The disadvantage
is that the suboptions must be changed to "2:2:1:0:1:1" when the desired audio
is in the right channel. Also, it is more difficult to remember and type.
</para>

<bridgehead>Example: left channel in two speakers shortcut</bridgehead>

<para>

</sect3>


<sect3 id="advaudio-channels-mixing">
<title>Channel mixing</title>

<para>
The <option>pan</option> filter can mix channels in user-specified proportions.
This allows for everything the <option>channels</option> filter can do and
more. Unfortunately, the suboptions are much more complicated.

will show when to use which.
</para></listitem>
<listitem><para>
Decide how many channels to feed into <option>pan</option> (further decoded
channels are discarded). This is the first suboption, and it also controls how
many channels to employ for output.
</para></listitem>
<listitem><para>
The remaining suboptions specify how much of each channel gets mixed into each
other channel. This is the complicated part. To break the task down, split the
suboptions into several sets, one set for each output channel. Each suboption

<para>
<option>pan</option> accepts values from 0 to 512, yielding 0% to 51200% of the
original volume. Be careful when using values greater than 1. Not only can this
give you very high volume, but if you exceed the sample range of your sound card
you may hear painful pops and clicks. If you want you can follow
<option>pan</option> with <option>,volume</option> to enable clipping, but it is
best to keep the values of <option>pan</option> low enough that clipping is not
necessary.
</para></listitem>
</orderedlist>
</para>

</para>

<bridgehead>Example: downmixing 6-channel PCM</bridgehead>
<para>
<application>MPlayer</application>'s decoder for 6-channel PCM is not capable of
downmixing. Here is a way to downmix PCM using <option>pan</option>:
<orderedlist>
<listitem><para>
The number of output channels is 2. Since <option>pan</option> will be handling
6 channels, it may be necessary to put <option>,channels=2</option> after pan to
get rid of the extra channels. If your sound card is capable of 6-channel

</sect2>


<sect2 id="advaudio-volume">
<title>Software Volume adjustment</title>

<para>
Some audio tracks are too quiet to be heard comfortably without amplification.
This becomes a problem when your audio equipment cannot amplify the signal for
you. The <option>-softvol</option> option directs

original volume. For example, <option>-softvol-max 200</option> would allow the
volume to be adjusted up to twice its original level.
It is safe to specify a large value with
<option>-softvol-max</option>; the higher volume will not be used until you
use the volume adjustment keys. The only disadvantage of a large value is that,
since <application>MPlayer</application> adjusts volume by a percentage of the
maximum, you will not have as precise control when using the volume adjustment
keys. Use a lower value with <option>-softvol-max</option> and/or specify
<option>-volstep 1</option> if you need higher precision.
</para>