annotate DOCS/xml/en/mencoder.xml @ 16095:4d6bd248f7b9

formatting fixes galore

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<chapter id="mencoder">
<title>Basic usage of <application>MEncoder</application></title>

<para>
For the complete list of available <application>MEncoder</application> options
and examples, please see the man page. For a series of hands-on examples and
detailed guides on using several encoding parameters, read the
<ulink url="../../tech/encoding-tips.txt">encoding-tips</ulink> that were
collected from several mailing list threads on MPlayer-users. Search the
<ulink url="http://mplayerhq.hu/pipermail/mplayer-users/">archives</ulink>
for a wealth of discussions about all aspects of and problems related to
encoding with <application>MEncoder</application>.
</para>

<sect1 id="menc-feat-mpeg4">
<title>Encoding two pass MPEG-4 (&quot;DivX&quot;)</title>

<para>
The name comes from the fact that this method encodes the file <emphasis>twice</emphasis>.
The first encoding (dubbed pass) creates some temporary files
(<filename>*.log</filename>) with a size of few megabytes, do not delete
them yet (you can delete the AVI). In the second pass, the two pass output
file is created, using the bitrate data from the temporary files. The
resulting file will have much better image quality. If this is the first
time you heard about this, you should consult some guides available on the
net.
</para>

<example>
<title>copy audio track</title>
<para>
Two pass encode of a DVD to an MPEG-4 (&quot;DivX&quot;) AVI while copying
the audio track.
<screen>
mencoder dvd://2 -ovc lavc -lavcopts vcodec=mpeg4:vpass=1 -oac copy -o <replaceable>movie.avi</replaceable>
mencoder dvd://2 -ovc lavc -lavcopts vcodec=mpeg4:vpass=2 -oac copy -o <replaceable>movie.avi</replaceable>
</screen>
</para>
</example>

<example>
<title>encode audio track</title>
<para>
Two pass encode of a DVD to an MPEG-4 (&quot;DivX&quot;) AVI while encoding
the audio track to MP3.
<screen>
mencoder dvd://2 -ovc lavc -lavcopts vcodec=mpeg4:vpass=1 -oac mp3lame -lameopts vbr=3 -o <replaceable>movie.avi</replaceable>
mencoder dvd://2 -ovc lavc -lavcopts vcodec=mpeg4:vpass=2 -oac mp3lame -lameopts vbr=3 -o <replaceable>movie.avi</replaceable>
</screen>
</para>
</example>
</sect1>

<sect1 id="menc-feat-mpeg">
<title>Encoding to MPEG format</title>
<para>
<application>MEncoder</application> can create MPEG (MPEG-PS) format output
files. It is probably useful only with
<link linkend="ffmpeg"><systemitem class="library">libavcodec</systemitem></link>'s
<emphasis>mpeg1video</emphasis> codec, because players - except
<application>MPlayer</application> - expect MPEG-1 video, and MPEG-1 layer 2 (MP2)
audio streams in MPEG files.
</para>

<para>
This feature is not very useful right now, aside that it probably has many bugs,
but the more importantly because <application>MEncoder</application> currently
cannot encode MPEG-1 layer 2 (MP2) audio, which all other players expect in MPEG files.
</para>

<para>
To change <application>MEncoder</application>'s output file format,
use the <option>-of mpeg</option> option.
</para>

<para>
Example:
<screen>
mencoder -of mpeg -ovc lavc -lavcopts vcodec=mpeg1video -oac copy <replaceable>other_options</replaceable> <replaceable>media.avi</replaceable> -o <replaceable>output.mpg</replaceable>
</screen>
</para>
</sect1>

<sect1 id="menc-feat-rescale">
<title>Rescaling movies</title>

<para>
Often the need to resize movie images' size emerges. Its reasons can be
many: decreasing file size, network bandwidth,etc. Most people even do
rescaling when converting DVDs or SVCDs to DivX AVI. If you wish to rescale,
read the <link linkend="aspect">Preserving aspect ratio</link> section.
</para>

<para>
The scaling process is handled by the <literal>scale</literal> video filter:
<option>-vf scale=<replaceable>width</replaceable>:<replaceable>height</replaceable></option>.
Its quality can be set with the <option>-sws</option> option.
If it is not specified, <application>MEncoder</application> will use 2: bicubic.
</para>

<para>
Usage:
<screen>
mencoder <replaceable>input.mpg</replaceable> -ovc lavc -lavcopts vcodec=mpeg4 -vf scale=640:480 -o <replaceable>output.avi</replaceable>
</screen>
</para>
</sect1>


<sect1 id="menc-feat-streamcopy">
<title>Stream copying</title>

<para>
<application>MEncoder</application> can handle input streams in two ways:
<emphasis role="bold">encode</emphasis> or <emphasis role="bold">copy</emphasis>
them. This section is about <emphasis role="bold">copying</emphasis>.
</para>

<itemizedlist>
<listitem><para>
  <emphasis role="bold">Video stream</emphasis> (option <option>-ovc copy</option>):
  nice stuff can be done :) Like, putting (not converting!) FLI or VIVO or
  MPEG-1 video into an AVI file! Of course only
  <application>MPlayer</application> can play such files :) And it probably
  has no real life value at all. Rationally: video stream copying can be
  useful for example when only the audio stream has to be encoded (like,
  uncompressed PCM to MP3).
  </para></listitem>
<listitem><para>
  <emphasis role="bold">Audio stream</emphasis> (option <option>-oac copy</option>):
  straightforward. It is possible to take an external audio file (MP3,
  WAV) and mux it into the output stream. Use the
  <option>-audiofile <replaceable>filename</replaceable></option> option
  for this.
  </para></listitem>
</itemizedlist>
</sect1>


<sect1 id="menc-feat-enc-images">
<title>Encoding from multiple input image files (JPEG, PNG, TGA, SGI)</title>

<para>
<application>MEncoder</application> is capable of creating movies from one
or more JPEG, PNG or TGA files. With simple framecopy it can create MJPEG
(Motion JPEG), MPNG (Motion PNG) or MTGA (Motion TGA) files.
</para>

<orderedlist>
<title>Explanation of the process:</title>
<listitem><para>
  <application>MEncoder</application> <emphasis>decodes</emphasis> the input image(s) with
  <systemitem class="library">libjpeg</systemitem> (when decoding PNGs, it
  will use <systemitem class="library">libpng</systemitem>).
  </para></listitem>
<listitem><para>
  <application>MEncoder</application> then feeds the decoded image to the
  chosen video compressor (DivX4, XviD, FFmpeg msmpeg4, etc.).
  </para></listitem>
</orderedlist>

<formalpara>
<title>Examples</title>
<para>
The explanation of the <option>-mf</option> option is in the man page.

<informalexample>
<para>
Creating an MPEG-4 file from all the JPEG files in the current directory:
<screen>
mencoder mf://*.jpg -mf w=800:h=600:fps=25:type=jpg -ovc lavc -lavcopts vcodec=mpeg4 -oac copy -o <replaceable>output.avi</replaceable>
</screen>
</para>
</informalexample>

<informalexample>
<para>
Creating an MPEG-4 file from some JPEG files in the current directory:
<screen>
mencoder mf://<replaceable>frame001.jpg,frame002.jpg</replaceable> -mf w=800:h=600:fps=25:type=jpg -ovc lavc -lavcopts vcodec=mpeg4 -oac copy -o <replaceable>output.avi</replaceable>
</screen>
</para>
</informalexample>

<informalexample>
<para>
Creating a Motion JPEG (MJPEG) file from all the JPEG files in the current
directory:
<screen>
mencoder mf://*.jpg -mf w=800:h=600:fps=25:type=jpg -ovc copy -oac copy -o <replaceable>output.avi</replaceable>
</screen>
</para>
</informalexample>

<informalexample>
<para>
Creating an uncompressed file from all the PNG files in the current directory:
<screen>
mencoder mf:// -mf w=800:h=600:fps=25:type=png -ovc raw -oac copy -o <replaceable>output.avi</replaceable>
</screen>
</para>
</informalexample>

<note><para>
Width must be integer multiple of 4, it is a limitation of the RAW RGB AVI format.
</para></note>

<informalexample>
<para>
Creating a Motion PNG (MPNG) file from all the PNG files in the current
directory:
<screen>
mencoder mf://*.png -mf w=800:h=600:fps=25:type=png -ovc copy -oac copy -o <replaceable>output.avi</replaceable> <!--
--></screen>
</para>
</informalexample>

<informalexample>
<para>
Creating a Motion TGA (MTGA) file from all the TGA files in the current
directory:
<screen>
mencoder mf://*.tga -mf w=800:h=600:fps=25:type=tga -ovc copy -oac copy -o <replaceable>output.avi</replaceable><!--
--></screen>
</para>
</informalexample>

</para>
</formalpara>
</sect1>


<sect1 id="menc-feat-extractsub">
<title>Extracting DVD subtitles to VOBsub file</title>

<para>
<application>MEncoder</application> is capable of extracting subtitles from
a DVD into VOBsub formatted files. They consist of a pair of files ending in
<filename>.idx</filename> and <filename>.sub</filename> and are usually
packaged in a single <filename>.rar</filename> archive.
<application>MPlayer</application> can play these with the
<option>-vobsub</option> and <option>-vobsubid</option> options.
</para>

<para>
You specify the basename (i.e without the <filename>.idx</filename> or
<filename>.sub</filename> extension) of the output files with
<option>-vobsubout</option> and the index for this subtitle in the
resulting files with <option>-vobsuboutindex</option>.
</para>

<para>
If the input is not from a DVD you should use <option>-ifo</option> to
indicate the <filename>.ifo</filename> file needed to construct the
resulting <filename>.idx</filename> file.
</para>

<para>
If the input is not from a DVD and you do not have the
<filename>.ifo</filename> file you will need to use the
<option>-vobsubid</option> option to let it know what language id to put in
the <filename>.idx</filename> file.
</para>

<para>
Each run will append the running subtitle if the <filename>.idx</filename>
and <filename>.sub</filename> files already exist. So you should remove any
before starting.
</para>

<example>
<title>Copying two subtitles from a DVD while doing two pass encoding</title>
<screen>
rm subtitles.idx subtitles.sub
mencoder dvd://1 -oac copy -ovc lavc -lavcopts vcodec=mpeg4:vpass=1 -vobsubout subtitles -vobsuboutindex 0 -sid 2
mencoder dvd://1 -oac copy -ovc lavc -lavcopts vcodec=mpeg4:vpass=2 -vobsubout subtitles -vobsuboutindex 1 -sid 5<!--
--></screen>
</example>

<example>
<title>Copying a french subtitle from an MPEG file</title>
<screen>
rm subtitles.idx subtitles.sub
mencoder <replaceable>movie.mpg</replaceable> -ifo <replaceable>movie.ifo</replaceable> -vobsubout subtitles -vobsuboutindex 0 -vobsuboutid fr -sid 1 -nosound -ovc copy
</screen>
</example>

</sect1>

<sect1 id="aspect">
<title>Preserving aspect ratio</title>
<para>
DVDs and SVCDs (i.e. MPEG-1/2) files contain an aspect ratio value, which
describes how the player should scale the video stream, so humans will not
have egg heads (ex.: 480x480 + 4:3 = 640x480). However when encoding to AVI
(DivX) files, you have be aware that AVI headers do not store this value.
Rescaling the movie is disgusting and time consuming, there has to be a better
way!
</para>

<para>There is</para>

<para>
MPEG-4 has an unique feature: the video stream can contain its needed aspect
ratio. Yes, just like MPEG-1/2 (DVD, SVCD) and H.263 files. Regretfully, there are
<emphasis role="bold">no</emphasis> video players outside which support this
attribute of MPEG-4, except <application>MPlayer</application>.
</para>

<para>
This feature can be used only with
<link linkend="ffmpeg"><systemitem class="library">libavcodec</systemitem></link>'s
<systemitem>mpeg4</systemitem> codec. Keep in mind: although
<application>MPlayer</application> will correctly play the created file,
other players will use the wrong aspect ratio.
</para>

<para>
You seriously should crop the black bands over and below the movie image.
See the man page for the usage of the <systemitem>cropdetect</systemitem> and
<systemitem>crop</systemitem> filters.
</para>

<para>
Usage
<screen>mencoder <replaceable>sample-svcd.mpg</replaceable> -ovc lavc -lavcopts vcodec=mpeg4:autoaspect -vf crop=714:548:0:14 -oac copy -o <replaceable>output.avi</replaceable></screen>
</para>
</sect1>

</chapter>