diff options
Diffstat (limited to 'DOCS/xml/en/install.xml')
-rw-r--r-- | DOCS/xml/en/install.xml | 894 |
1 files changed, 894 insertions, 0 deletions
diff --git a/DOCS/xml/en/install.xml b/DOCS/xml/en/install.xml new file mode 100644 index 0000000000..d7c039b484 --- /dev/null +++ b/DOCS/xml/en/install.xml @@ -0,0 +1,894 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<sect1 id="install"> +<title>Installation</title> + +<para> +In this section I'll try to guide you through the compiling and configuring +process of <application>MPlayer</application>. It's not easy, but it won't +necessarily be hard. If you experience a different behavior than what I +explain, please search through this documentation and you'll find your +answers. If you see links, please follow them and read carefully what they +contain. It will take some time, but it DOES worth it. +</para> + +<para> +You need a fairly recent system. On Linux, 2.4.x kernels are recommended. +</para> + + +<sect2 id="softreq"> +<title>Software requirements</title> + +<itemizedlist> +<listitem><para> + <emphasis role="bold">binutils</emphasis> - suggested version is <emphasis role="bold">2.11.x</emphasis>. + This program is responsible for generating MMX/ 3DNow!/etc instructions, + thus very important. +</para></listitem> +<listitem><para> + <emphasis role="bold">gcc</emphasis> - suggested versions are: <emphasis role="bold">2.95.3</emphasis> + (maybe <emphasis role="bold">2.95.4</emphasis>) and <emphasis role="bold">3.2+</emphasis>. + <emphasis role="bold">Never</emphasis> use 2.96 or 3.0.x! They generate faulty code for + <application>MPlayer</application>. If you decide to change gcc from + 2.96, then don't decide in favor of 3.0.x just because it's newer! Early + releases of 3.0.x were even more buggy than 2.96. So downgrade to 2.95.x + (downgrade <systemitem class="library">libstdc++</systemitem> too, other + programs may need it) or don't up/downgrade at all (but in this case, be + prepared for runtime problems). If you vote for 3.x.x, try to use the + latest version, early releases had various bugs, so be sure you use at + least 3.1, it's tested and working. For detailed information about gcc 2.96's + bugs (that are still NOT fixed, they have been WORKED AROUND in + <application>MPlayer</application>!),see the <link linkend="gcc-296">gcc 2.96</link> + section and the <xref linkend="faq"/>. + </para></listitem> +<listitem><para> + <emphasis role="bold">XFree86</emphasis> - suggested version is <emphasis role="bold">always the + newest</emphasis> (4.2.1). Normally, everyone wants this, as starting + with XFree86 4.0.2, it contains the <link linkend="xv">XVideo</link> + extension (somewhere referred to as <emphasis role="bold">Xv</emphasis>) + which is needed to enable the hardware YUV acceleration (fast image display) + on cards that support it. + Make sure its <emphasis role="bold">development package</emphasis> is installed, + too, otherwise it won't work. + For some video cards you don't need XFree86. See list below. + </para></listitem> +<listitem><para> + <emphasis role="bold">make</emphasis> - suggested version is + <emphasis role="bold">always the newest</emphasis> (at least 3.79.x). This + usually isn't important. + </para></listitem> +<listitem><para> + <emphasis role="bold">SDL</emphasis> - it's not mandatory, but can help in + some cases (bad audio, video cards that lag strangely with the xv driver). + Always use the newest (beginning from 1.2.x). + </para></listitem> +<listitem><para> + <emphasis role="bold">libjpeg</emphasis> - optional JPEG decoder, used by the <option>-mf</option> + option and some QT MOV files. Useful for both MPlayer and MEncoder if + you plan to work with jpeg files. + </para></listitem> +<listitem><para> + <emphasis role="bold">libpng</emphasis> - recommended and default (M)PNG decoder. Required for GUI. + Useful for both <application>MPlayer</application> and + <application>MEncoder</application>. + </para></listitem> +<listitem><para> + <emphasis role="bold">lame</emphasis> - recommended, needed for encoding MP3 audio with + <application>MEncoder</application>, suggested version is + <emphasis>always the newest</emphasis> (at least 3.90). + </para></listitem> +<listitem><para> + <emphasis role="bold">libogg</emphasis> - optional, needed for playing OGG file format. + </para></listitem> +<listitem><para> + <emphasis role="bold">libvorbis</emphasis> - optional, needed for playing OGG Vorbis audio. + </para></listitem> +<listitem><para> + <emphasis role="bold"><ulink url="http://www.live.com/mplayer/">LIVE.COM Streaming Media</ulink></emphasis> + - optional, needed for playing RTSP/RTP streams. + </para></listitem> +<listitem><para> + <emphasis role="bold">directfb</emphasis> - optional, from + <ulink url="http://www.directfb.org"/> + </para></listitem> +<listitem><para> + <emphasis role="bold">cdparanoia</emphasis> - optional, for CDDA support + </para></listitem> +<listitem><para> + <emphasis role="bold">libfreetype</emphasis> - optional, for TTF fonts + support. At least 2.0.9 is required. + </para></listitem> +<listitem><para> + <emphasis role="bold">libxmms</emphasis> - optional, for XMMS input plugin + support. At least 1.2.7 is required. + </para></listitem> +</itemizedlist> +</sect2> + + +<sect2> +<title>Codecs</title> + +<itemizedlist> +<listitem><para> + <emphasis role="bold">libavcodec</emphasis>: This codec package is capable + of decoding H263/MJPEG/RV10/DivX3/DivX4/DivX5/MP41/MP42/WMV1 encoded video + streams and WMA (Windows Media Audio) v1/v2 audio streams, on multiple + platforms. It is also known to be the fastest for this task. See the + <link linkend="ffmpeg">this section</link> section for details. Features: + <itemizedlist> + <listitem><simpara> + gain decoding of videos mentioned above, on non-x86 machines + </simpara></listitem> + <listitem><simpara> + encoding with most of the mentioned codecs + </simpara></listitem> + <listitem><simpara> + this codec is the <emphasis role="bold">fastest codec available</emphasis> for + DivX/3/4/5 and other MPEG4 types. Recommended! + </simpara></listitem> + </itemizedlist> + </para></listitem> +<listitem><para> + <emphasis role="bold">Win32 codecs</emphasis>: If you plan to use + <application>MPlayer</application> on x86 architecture, you will possibly need + them. Download the Win32 codecs from our + <ulink url="http://www.mplayerhq.hu/MPlayer/releases/codecs/">codecs page</ulink> + and install them to <filename class="directory">/usr/lib/win32</filename> + <emphasis role="bold">BEFORE</emphasis> compiling <application>MPlayer</application>, + otherwise no Win32 support will be compiled! + <note><para>The avifile project has similar codecs package, but it + differs from ours, so if you want to use all supported codecs, then use + our package (do not worry, avifile works with it without problems).</para> + </note> + Features: + <itemizedlist> + <listitem><simpara> + you need this if you want to play or encode for example movies recorded + with various hardware compressors, like tuner cards, digital cameras + (example: DV, ATI VCR, MJPEG) + </simpara></listitem> + <listitem><simpara> + needed if you want to play <emphasis role="bold">WMV8, WMV9/WMA9 movies</emphasis>. + </simpara></listitem> + <listitem><simpara> + Not needed for old ASF's with MP41 or MP42 video (though VoxWare audio is + frequent for these files - it's done by the Win32 codec), or WMV7. Also not + needed for WMA (Windows Media Audio), libavcodec has opensource decoder for that. + </simpara></listitem> + </itemizedlist> + </para></listitem> +<listitem><para> + <emphasis role="bold">QuickTime codecs</emphasis>: on x86 platforms these + codecs can be used to decode Sorenson v1/v3, RPZA, and other QuickTime video, + and QDesign audio streams. Installation instructions can be found in the + <link linkend="sorenson">Sorenson video codec</link> section. + </para></listitem> +<listitem><para> + <emphasis role="bold">DivX4/DivX5</emphasis>: information about this codec is + available in the <link linkend="divx4-5">DivX4/DivX5</link>. You possibly + don't want this codec as <emphasis role="bold">libavcodec</emphasis> (see + above) is much faster and has better quality than this, for both decoding + and encoding. Features: + <itemizedlist> + <listitem><simpara> + 1 pass or 2 pass encoding with <link linkend="mencoder">MEncoder</link> + </simpara></listitem> + <listitem><simpara> + can play old <emphasis role="bold">DivX3</emphasis> movies much faster than + the Win32 DLL but slower than <emphasis role="bold">libavcodec</emphasis>! + </simpara></listitem> + <listitem><simpara> + it's closed-source, and only a x86 version is available. + </simpara></listitem> + </itemizedlist> + </para></listitem> +<listitem><para> + <emphasis role="bold">XviD</emphasis>: Open source encoding alternative to + Divx4Linux. Features: + <itemizedlist> + <listitem><simpara> + 1 pass or 2 pass encoding with <link linkend="mencoder">MEncoder</link> + </simpara></listitem> + <listitem><simpara> + it's open-source, so it's multiplatform. + </simpara></listitem> + <listitem><simpara> + it's about 2 times faster than divx4 when encoding - about the same + quality + </simpara></listitem> + </itemizedlist> + </para></listitem> +<listitem><para> + The <emphasis role="bold"><link linkend="xanim">XAnim codecs</link></emphasis> + are the best (full screen, hardware YUV zoom) for decoding + <emphasis role="bold">3ivx</emphasis> and Indeo 3/4/5 movies, and some old + formats. And they are multiplatform, so this is the only way to play Indeo on + non-x86 platforms (well, apart from using XAnim:). But for example Cinepak movies + are best played with <application>MPlayer</application>'s own Cinepak decoder! + </para></listitem> +<listitem><para> + For <emphasis role="bold">Ogg Vorbis</emphasis> audio decoding you need to + install <systemitem class="library">libvorbis</systemitem> properly. Use + deb/rpm packages if available, or compile from + <ulink url="http://ogg.org/ogg/vorbis/download/vorbis_nightly_cvs.tgz">source</ulink> + (this is a nightly updated tarball of Vorbis CVS). + </para></listitem> +<listitem><para> + <application>MPlayer</application> can use the libraries of RealPlayer 8 + or RealONE to play files with <emphasis role="bold">RealVideo 2.0-4.0</emphasis> + video, and Sipro/Cook audio. See <link linkend="realmedia">RealMedia file format</link> + section for installation instructions and more information. + </para></listitem> +</itemizedlist> +</sect2> + + +<sect2 id="video-cards"> +<title>Video cards</title> + +<para> +There are generally two kind of video cards. One kind (the newer cards) has +<emphasis role="bold">hardware scaling and YUV acceleration</emphasis> support, +the other cards don't. +</para> + + +<sect3 id="yuv-cards"> +<title>YUV cards</title> + +<para> +They can display and scale (zoom) the picture to any size that fits in +their memory, with <emphasis role="bold">small CPU usage</emphasis> (even when +zooming), thus fullscreen is nice and very fast. + +<itemizedlist> +<listitem><para> + <emphasis role="bold">Matrox G200/G400/G450/G550 cards</emphasis>: although a + <link linkend="vidix">Vidix driver</link> is provided, it is recommended to + use the mga_vid module instead, for it works much better. + Please see the <link linkend="mga_vid">mga_vid</link> section about its + installation and usage. It is important to do these steps + <emphasis>before</emphasis> compiling <application>MPlayer</application>, + otherwise no mga_vid support will be built. Also check out the + <link linkend="tvout-mga-g400">Matrox TV-out</link> section. If you + <emphasis role="bold"> If you don't use Linux</emphasis>, your only + possibility is the VIDIX driver: read <link linkend="vidix">VIDIX</link> section. + </para></listitem> +<listitem><para> + <emphasis role="bold">3Dfx Voodoo3/Banshee cards</emphasis>: please see + <link linkend="tdfxfb">tdfxfb</link> section in order to gain big speedup. + It is important to do these steps <emphasis role="bold">before</emphasis> + compiling <application>MPlayer</application>, otherwise no 3Dfx support will be + built. Also see the <link linkend="tvout-voodoo">3dfx TV-out section</link>. + If you use X, use at least <emphasis role="bold">4.2.0</emphasis>, as 3dfx Xv + driver was broken in 4.1.0, and earlier releases. + </para></listitem> +<listitem><para> + <emphasis role="bold">ATI cards</emphasis>: <link linkend="vidix">VIDIX</link> + driver is provided for the following cards: + <emphasis role="bold">Radeon, Rage128, Mach64</emphasis> (Rage XL/Mobility, Xpert98). + Also see the <link linkend="tvout-ati">ATI cards section</link> of the TV-out documentation, + to know if you card's TV-out is supported under Linux/<application>MPlayer</application>. + </para></listitem> +<listitem><para> + <emphasis role="bold">S3 cards</emphasis>: the Savage and Virge/DX chips have + hardware acceleration. Use as new XFree86 version as possible, older drivers are + buggy. Savage chips have problems with YV12 display, see <link linkend="s3">S3 Xv + section</link> for details. Older, Trio cards have no, or slow hardware + support. + </para></listitem> +<listitem><para> + <emphasis role="bold">nVidia cards</emphasis>: very bad choice for video playing. + If you do not have a GeForce2 (or newer) card, it's not likely to work without bugs. + <emphasis role="bold">the built-in nVidia driver in XFree86 doesn't contain + support for hardware YUV acceleration for all nVidia cards.</emphasis> You have + to download nVidia's closed-source drivers from nVidia.com. See the <link + linkend="nvidia">nVidia Xv driver</link> section for details. Please also check + the <link linkend="tvout-nvidia">nVidia TV-out section</link> if you wish to + use a TV. + </para></listitem> +<listitem><para> + <emphasis role="bold">3DLabs GLINT R3 and Permedia3</emphasis>: a VIDIX driver + is provided (pm3_vid). Please see the <link linkend="vidix">VIDIX</link> section + for details. + </para></listitem> +<listitem><para> + <emphasis role="bold">Other cards</emphasis>: none of the above? + <itemizedlist> + <listitem><simpara> + Try if the XFree86 driver (and your card) supports hardware + acceleration. See the <link linkend="xv">Xv section</link> for details. + </simpara></listitem> + <listitem><simpara> + If it doesn't, then your card's video features aren't supported under + your operating system :( If it does hardware scaling under Windows, it + doesn't mean it will do the same under Linux or other OS, it depends on + the drivers. Most manufacturers don't make Linux drivers nor release chip + specs - so you're unlucky if using their cards. + See <xref linkend="non-yuv-cards"/>. + </simpara></listitem> + </itemizedlist> + </para></listitem> +</itemizedlist> +</para> +</sect3> + + +<sect3 id="non-yuv-cards" xreflabel="Non-YUV cards"> +<title>Non-YUV cards</title> + +<para> +Fullscreen playing can be achieved by either enabling <emphasis role="bold"> +software scaling</emphasis> (use the <option>-zoom</option> or <option>-vop</option>, +but i warn you: this is slow), or switching to a smaller video mode, for example +352x288. If you don't have YUV acceleration, this latter method is recommended. +Video mode switching can be enabled by using the <option>-vm</option> option and +it works with the following drivers: +<itemizedlist> +<listitem><simpara> + <emphasis role="bold">using</emphasis> XFree86: see details in <link linkend="dga">DGA driver</link> and + <link linkend="x11">X11 driver</link> sections. DGA is recommended! Also + try DGA via SDL, sometimes it's better. + </simpara></listitem> +<listitem><simpara> + <emphasis role="bold">not using</emphasis> XFree86: try the drivers in the + following order: + <link linkend="vesa">vesa</link>, + <link linkend="fbdev">fbdev</link>, + <link linkend="svgalib">svgalib</link>, + <link linkend="aalib">aalib</link>. + </simpara></listitem> +</itemizedlist> +</para> +</sect3> + +<!-- FIXME: find a more logical organization for this section --> +<sect3 id="cirrus-logic-cards" xreflabel="Cirrus-Logic cards"> +<title>Cirrus-Logic cards</title> +<itemizedlist> +<listitem><para> + GD 7548: present on-board and tested in Compaq Armada 41xx notebook series. + <itemizedlist> + <listitem><simpara> + XFree86 3: works in 8/16bpp modes. However, the driver is dramatically slow + and buggy in 800x600@16bpp. <emphasis role="bold">Recommended: 640x480@16bpp</emphasis> + </simpara></listitem> + <listitem><simpara> + XFree86 4: the Xserver freezes soon after start unless acceleration is + disabled, but then the whole thing gets slower than XFree86 3. No XVideo. + </simpara></listitem> + <listitem><simpara> + FBdev: framebuffer can be turned on with the <systemitem>clgenfb</systemitem> + driver in the kernel, though for me it worked only in 8bpp, thus unusable. + The clgenfb source had to be extended with the 7548 ID before compilation. + </simpara></listitem> + <listitem><simpara> + VESA: the card is only VBE 1.2 capable, so VESA output can't be used. Can't + be workarounded with UniVBE. + </simpara></listitem> + <listitem><simpara> + SVGAlib: detects an older Cirrus chip. Usable but slow with + <option>-bpp 8</option>. + </simpara></listitem> +</itemizedlist> +</para></listitem> +</itemizedlist> +</sect3> +</sect2> + + +<sect2 id="sounc-cards"> +<title>Sound cards</title> + +<itemizedlist> +<listitem><simpara> + <emphasis role="bold">Soundblaster Live!</emphasis>: with this card you can use + 4 or 6 (5.1) channels AC3 decoding instead of 2. Read the + <link linkend="swac3">Software AC3 decoding</link> section. For hardware AC3 + passthrough you <emphasis role="bold">must</emphasis> use ALSA 0.9 oss emulation! + </simpara></listitem> +<listitem><simpara> + <emphasis role="bold">C-Media with SP/DIF out</emphasis>: hardware AC3 + passthrough is possible with these cards, see + <link linkend="hwac3">Hardware AC3 decoding</link> section. + </simpara></listitem> +<listitem><simpara> + Features of <emphasis role="bold">other cards</emphasis> aren't supported by + <application>MPlayer</application>. <emphasis role="bold">It's very recommended + to read the <link linkend="audio-dev">sound card</link> section!</emphasis> + </simpara></listitem> +</itemizedlist> +</sect2> + + +<sect2> +<title>Features</title> + +<itemizedlist> +<listitem><para> + Decide if you need GUI. If you do, see the <link linkend="gui">GUI + section</link> before compiling. + </para></listitem> +<listitem><para> + If you want to install <application>MEncoder</application> (our great + all-purpose encoder), see the <link linkend="mencoder">MEncoder section</link>. + </para></listitem> +<listitem><para> + If you have a V4L compatible <emphasis role="bold">TV tuner</emphasis> card, + and wish to watch/grab and encode movies with <application>MPlayer</application>, + read the <link linkend="tv-input">TV input</link> section. + </para></listitem> +<listitem><para> + There is a neat <emphasis role="bold">OSD Menu</emphasis> support ready to be + used. Check the <link linkend="subosd">OSD menu</link> section. + </para></listitem> +</itemizedlist> + +<para> +Then build <application>MPlayer</application>: +<screen> +./configure +make +make install</screen> +</para> + +<para> +At this point, <application>MPlayer</application> is ready to use. The +directory <filename class="directory">$PREFIX/share/mplayer</filename> +contains the <filename>codecs.conf</filename> file, which is used to tell +the program all the codecs and their capabilities. This file should always +be kept up to date together with the main binary. Check if you have +<filename>codecs.conf</filename> in your home directory +(<filename>~/.mplayer/codecs.conf</filename>) left from old +<application>MPlayer</application> versions, and remove it. +</para> + +<para> +Debian users can build a .deb package for themselves, it's very simple. +Just exec +<screen>fakeroot debian/rules binary</screen> +in <application>MPlayer</application>'s root directory. See +<link linkend="debian">Debian packaging</link> for detailled instructions. +</para> + +<para> +<emphasis role="bold">Always browse the output of</emphasis> +<filename>./configure</filename>, and the +<filename>configure.log</filename> file, they contain information about +what will be built, and what will not. You may also want to view +<filename>config.h</filename> and <filename>config.mak</filename> files. +If you have some libraries installed, but not detected by +<filename>./configure</filename>, then check if you also have the proper +header files (usually the -dev packages) and their version matches. The +<filename>configure.log</filename> file usually tells you what is missing. +</para> + +<para> +Though not mandatory, the fonts should be installed in order to gain OSD, +and subtitle functionality. The recommended method is installing a TTF +font file and telling MPlayer to use it. See the <link linkend="subosd">Subtitles +and OSD</link> section for details. +</para> + +</sect2> +</sect1> + +<!-- ********** --> + +<sect1 id="gui"> +<title>What about the GUI?</title> + +<para> +The GUI needs GTK 1.2.x (it isn't fully GTK, but the panels are). The skins +are stored in PNG format, so GTK, <systemitem class="library">libpng</systemitem> +(and their devel stuff, usualy called <systemitem class="library">gtk-dev</systemitem> +and <systemitem class="library">libpng-dev</systemitem>) has to be installed. +You can build it by specifying <option>--enable-gui</option> during +<filename>./configure</filename>. Then, to turn on GUI mode, you either +<itemizedlist> +<listitem><para> + specify <literal>gui=yes</literal> in your config file + </para></listitem> +<listitem><para> + execute + <screen>ln -s $PREFIX/bin/mplayer $PREFIX/bin/gmplayer</screen> + and call <command>gmplayer</command> instead. + </para></listitem> +</itemizedlist> +</para> + +<para> +Currently you can't use the <option>-gui</option> option on the command +line, due to technical reasons. +</para> + +<para> +As <application>MPlayer</application> doesn't have a skin included, you +have to download them if you want to use the GUI. See the <ulink +url="http://www.mplayerhq.hu/homepage/dload.html">download page</ulink>. +They should be extracted to the usual system-wide directory (<filename +class="directory">$PREFIX/share/mplayer/Skin</filename>), or to <filename +class="directory">$HOME/.mplayer/Skin</filename>. +<application>MPlayer</application> by default looks in these directories +for a directory named <filename class="directory">default</filename>, but +you can use the <option>-skin <replaceable>newskin</replaceable></option> +option, or the <literal>skin=newskin</literal> config file directive to use +the skin in <filename class="directory">*/Skin/newskin</filename> +directory. +</para> +</sect1> + +<!-- ********** --> + +<sect1 id="subosd"> +<title>Subtitles and OSD</title> + +<para> +MPlayer can display subtitles along with movie files. Currently the +following formats are supported: +<itemizedlist> +<listitem><para>VobSub</para></listitem> +<listitem><para>OGM</para></listitem> +<listitem><para>CC (closed caption)</para></listitem> +<listitem><para>Microdvd</para></listitem> +<listitem><para>SubRip</para></listitem> +<listitem><para>SubViewer</para></listitem> +<listitem><para>Sami</para></listitem> +<listitem><para>VPlayer</para></listitem> +<listitem><para>RT</para></listitem> +<listitem><para>SSA</para></listitem> +<listitem><para><link linkend="mpsub">MPsub</link></para></listitem> +<listitem><para>AQTitle</para></listitem> +<listitem><para>JACOsub</para></listitem> +</itemizedlist> +</para> + +<para> +MPlayer can dump the previously listed subtitle formats +(<emphasis role="bold">except the three first</emphasis>) into the following +destination formats, with the given options: +<itemizedlist> +<listitem><para>MPsub: <option>-dumpmpsub</option></para></listitem> +<listitem><para>SubRip: <option>-dumpsrtsub</option></para></listitem> +<listitem><para>Microdvd: <option>-dumpmicrodvdsub</option></para></listitem> +<listitem><para>JACOsub: <option>-dumpjacosub</option></para></listitem> +<listitem><para>Sami: <option>-dumpsami</option></para></listitem> +</itemizedlist> +</para> + +<para> +The command line options differ slightly for the different formats: +</para> + +<formalpara> +<title>VobSub subtitles</title> +<para> +VobSub subtitles consist of a big (some megabytes) <filename>.SUB</filename> file, +and optional <filename>.IDX</filename> and/or <filename>.IFO</filename> +files. If you have files like <filename>sample.sub</filename>, +<filename>sample.ifo</filename> (optional), <filename>sample.idx</filename> - +you have to pass <application>MPlayer</application> the +<option>-vobsub sample [-vobsubid <replaceable>id</replaceable>]</option> options +(full path optional). The <option>-vobsubid</option> option is like +<option>-sid</option> for DVDs, you can choose between subtitle tracks +(languages) with it. In case that <option>-vobsubid</option> is omitted, +<application>MPLayer</application> will try to use the languages given by the +<option>-slang</option> option and fall back to the <systemitem>langidx</systemitem> +in the <filename>.IDX</filename> file to set the subtitle language. If it fails, +there will be no subtitles. +</para> +</formalpara> + +<formalpara> +<title>Other subtitles</title> +<para> +The other formats consist of a single text file containing timing, +placement and text information. Usage: If you have a file like +<filename>sample.txt</filename>, you have to pass the option <option>-sub +sample.txt</option> (full path optional). +</para> +</formalpara> + +<variablelist> +<title>Adjusting subtitle timing and placement:</title> +<varlistentry> + <term><option>-subdelay <replaceable>sec</replaceable></option></term> + <listitem><simpara> + Delays subtitles by <option><replaceable>sec</replaceable></option> seconds. + Can be negative. + </simpara></listitem> +</varlistentry> +<varlistentry> + <term><option>-subfps <replaceable>RATE</replaceable></option></term> + <listitem><simpara> + Specify frame/sec rate of subtitle file (float number). + </simpara></listitem> +</varlistentry> +<varlistentry> + <term><option>-subpos <replaceable>0-100</replaceable></option></term> + <listitem><simpara> + Specify the position of subtitles. + </simpara></listitem> +</varlistentry> +</variablelist> + +<para> +If you experience a growing delay between the movie and the subtitles when +using a MicroDVD subtitle file, most likely the frame rate of the movie and +the subtitle file are different. Please note that the MicroDVD subtitle +format uses absolute frame numbers for its timing, and therefore the +<option>-subfps</option> option cannot be used with this format. As +<application>MPlayer</application> has no way to guess the frame rate of +the subtitle file, you have to manually convert the frame rate. There is a +little perl script in the <filename class="directory">contrib</filename> +directory of the MPlayer FTP site to do this conversion for you. +</para> + +<para> +About DVD subtitles, read the <link linkend="dvd">DVD section</link>. +</para> + + +<sect2 id="mpsub"> +<title>MPlayer's own subtitle format</title> + +<para> +<application>MPlayer</application> introduces a new subtitle format called +<emphasis role="bold">MPsub</emphasis>. It was designed by Gabucino. Basically +its main feature is being <emphasis>dynamically</emphasis> time-based (although +it has frame-based mode too). Example (from <ulink +url="../../tech/mpsub.sub">DOCS/tech/mpsub.sub</ulink>): +<programlisting> +# first number : wait this much after previous subtitle disappeared +# second number : display the current subtitle for this many seconds + +15 3 +A long long, time ago... + +0 3 +in a galaxy far away... + +0 3 +Naboo was under an attack.<!-- +--></programlisting> +</para> + +<para> +So you see, the main goal was to <emphasis role="bold">make subtitle +editing/timing/joining/cutting easy</emphasis>. And, if you - say - get an +SSA subtitle but it's badly timed/delayed to your version of the movie, you +simply do a +<screen>mplayer dummy.avi -sub source.ssa -dumpmpsub</screen> +A <filename>dump.mpsub</filename> file will be created in the +current directory, which will contain the source subtitle's text, but in +<emphasis role="bold">MPsub</emphasis> format. Then you can freely add/subtract +seconds to/from the subtitle. +</para> + +<para> +Subtitles are displayed with a technique called <emphasis role="bold">'OSD', +On Screen Display</emphasis>.OSD is used to display current time, volume bar, +seek bar etc. +</para> +</sect2> + + +<sect2 id="mpsub-install"> +<title>Installing OSD and subtitles</title> + +<para> +You need an MPlayer font package to be able to use OSD/SUB feature. +There are many ways to get it: +</para> + +<itemizedlist> +<listitem><para> + Download ready-to-use font packages from MPlayer site. Note: currently + available fonts are limited for ISO 8859-1/2 support, but there are some + other (including Korean, Russian, ISO 8859-8 etc) fonts at contrib/font + section of FTP, made by users. + </para><para> + <!-- FIXME: this para should be before the list --> + Font should have appropriate <filename>font.desc</filename> file which + maps unicode font positions to the actual code page of the subtitles + text. Other solution is to have subtitles encoded in UTF8 encoding and + use <option>-utf8</option> option or just name the subtitles file + <filename><video_name>.utf</filename> and have it in the same dir + as the video file. Recoding from different codepages to UTF8 could be + <!-- FIXME: iconv (Debian) konwert (Red Hat) instead? --> + done by using <command>konwert</command> (Debian) or + <command>iconv</command> (Red Hat) programs. + </para><para> + + <table> + <title>Some URLs</title> + <tgroup cols="2"> + <thead> + <row><entry>URL</entry><entry>Comment</entry></row> + </thead> + <tbody> + <row><entry> + <ulink url="ftp://ftp.mplayerhq.hu/MPlayer/releases/"></ulink> + </entry><entry> + ISO fonts + </entry></row> + <row><entry> + <ulink url="ftp://ftp.mplayerhq.hu/MPlayer/contrib/fonts/"></ulink> + </entry><entry> + various fonts by users + </entry></row> + <row><entry> + <ulink url="http://realtime.ssu.ac.kr/~lethean/mplayer"></ulink> + </entry><entry> + Korean fonts and RAW plugin + </entry></row> + </tbody> + </tgroup> + </table> + + </para></listitem> +<listitem><para> + Use the font generator tool at <filename + class="directory">TOOLS/subfont-c</filename>. It's a complete tool to + convert from TTF/Type1/etc font to mplayer font pkg. (read + <filename>TOOLS/subfont-c/README</filename> for details) + </para></listitem> +<listitem><para> + Use the font generator GIMP plugin at <filename + class="directory">TOOLS/subfont-GIMP</filename> (note: you must have HSI + RAW plugin too, see URL below) + <!-- FIXME: where's that URL? --> + </para></listitem> +<listitem><para> + using a TrueType (TTF) font, by the means of the <systemitem class="library">freetype</systemitem> +library. Version 2.0.9 or greater is mandatory! Then you have two methods: + <itemizedlist> + <listitem><para> + use the <option>-font /path/to/arial.ttf</option> option to specify a + TrueType font file on every occasion + </para></listitem> + <listitem><para> + create a symlink:<screen>ln -s /path/to/arial.ttf ~/.mplayer/subfont.ttf</screen> + </para></listitem> + </itemizedlist> + </para></listitem> +</itemizedlist> + +<para> +If you chose non-TTF fonts, UNZIP the file you downloaded to <filename +class="directory">~/.mplayer</filename> or <filename +class="directory">$PREFIX/share/mplayer</filename>. Then rename or symlink +one of the extracted directories to <filename>font</filename>, for example: + +<screen>ln -s ~/.mplayer/arial-24 ~/.mplayer/font</screen> + +Now you have to see a timer at the upper left corner of the movie (switch +it off with the <keycap>o</keycap> key). +</para> + +<para> +OSD has 4 states (switch with <keycap>o</keycap>): + +<orderedlist> +<listitem><simpara> + volume bar + seek bar (default) + </simpara></listitem> +<listitem><simpara> + volume bar + seek bar + timer + file position percentage on seeking + </simpara></listitem> +<listitem><simpara> + volume bar + seek bar + timer + total duration of the media + </simpara></listitem> +<listitem><simpara> + subtitles only + </simpara></listitem> +</orderedlist> + +You can change default behaviour by setting <varname>osdlevel</varname> +variable in config file, or the <option>-osdlevel</option> command line option. + +</para> +</sect2> + + +<sect2 id="osdmenu"> +<title>OSD menu</title> + +<para> +MPlayer has a completely user definiable OSD Menu interface. +</para> + +<note><simpara> +the Preferences menu is currently UNIMPLEMENTED! +</simpara></note> + +<orderedlist> +<title>Installation</title> +<listitem><simpara> + compile <application>MPlayer</application> by passing the <option>--enable-menu</option> + to <filename>./configure</filename> + </simpara></listitem> +<listitem><simpara> + make sure you have an OSD font installed + </simpara></listitem> +<listitem><simpara> |