Update to MPlayer SVN rev 29473 and FFmpeg SVN rev 19572.
[vaapi:athaifas-mplayer.git] / DOCS / xml / en / .svn / text-base / install.xml.svn-base
1 <?xml version="1.0" encoding="utf-8"?>
2 <!-- $Revision$ -->
3 <chapter id="install">
4 <title>Installation</title>
5
6 <para>
7 A quick installation guide can be found in the <filename>README</filename>
8 file. Please read it first and then come back here for the rest of the gory
9 details.
10 </para>
11
12 <para>
13 In this section you will be guided through the compilation and configuration
14 process of <application>MPlayer</application>. It's not easy, but it won't
15 necessarily be hard. If you experience a behavior different from this
16 description, please search through this documentation and you'll find your
17 answers.
18 </para>
19
20
21 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
22
23
24 <sect1 id="softreq">
25 <title>Software requirements</title>
26
27 <itemizedlist>
28 <listitem><para>
29   <emphasis role="bold">POSIX system</emphasis> - You need a POSIX-compatible
30   shell and POSIX-compatible system tools like grep, sed, awk, etc. in your
31   path.
32 </para></listitem>
33 <listitem><para>
34   <emphasis role="bold">GNU make</emphasis> 3.81 or later
35 </para></listitem>
36 <listitem><para>
37   <emphasis role="bold">binutils</emphasis> - GNU binutils 2.11 or later
38   is known to work.
39 </para></listitem>
40 <listitem><para>
41   <emphasis role="bold">compiler</emphasis> - We mostly use gcc, the
42   recommended versions on x86 are 2.95 and 3.4+. On PowerPC, use 4.x+.
43   icc 10.1+ is also known to work.
44 </para></listitem>
45 <listitem><para>
46   <emphasis role="bold">Xorg/XFree86</emphasis> - recommended version is
47   4.3 or later. Make sure the
48   <emphasis role="bold">development packages</emphasis> are installed,
49   too, otherwise it won't work.
50   You don't absolutely need X, some video output drivers work without it.
51 </para></listitem>
52 <listitem><para>
53   <emphasis role="bold">FreeType</emphasis> - 2.0.9 or later is required
54   for the OSD and subtitles
55 </para></listitem>
56 <listitem><para>
57   <emphasis role="bold">ALSA</emphasis> - optional, for ALSA audio output
58   support. At least 0.9.0rc4 is required.
59 </para></listitem>
60 <listitem><para>
61   <emphasis role="bold">libjpeg</emphasis> -
62   required for the optional JPEG video output driver
63 </para></listitem>
64 <listitem><para>
65   <emphasis role="bold">libpng</emphasis> -
66   required for the optional PNG video output driver
67 </para></listitem>
68 <listitem><para>
69   <emphasis role="bold">directfb</emphasis> - optional, 0.9.13 or later
70   required for the directfb video output driver
71 </para></listitem>
72 <listitem><para>
73   <emphasis role="bold">lame</emphasis> - 3.90 or later is recommended,
74   necessary for encoding MP3 audio with <application>MEncoder</application>.
75 </para></listitem>
76 <listitem><para>
77   <emphasis role="bold">zlib</emphasis> - recommended, many codecs use it.
78 </para></listitem>
79 <listitem><para>
80   <emphasis role="bold"><ulink url="http://www.live555.com/mplayer/">LIVE555 Streaming Media</ulink></emphasis>
81   - optional, needed for some RTSP/RTP streams
82 </para></listitem>
83 <listitem><para>
84   <emphasis role="bold">cdparanoia</emphasis> - optional, for CDDA support
85 </para></listitem>
86 <listitem><para>
87   <emphasis role="bold">libxmms</emphasis> - optional, for XMMS input plugin
88   support. At least 1.2.7 is required.
89 </para></listitem>
90 <listitem><para>
91   <emphasis role="bold">libsmb</emphasis> - optional, for SMB networking support
92 </para></listitem>
93 <listitem><para>
94   <emphasis role="bold"><ulink url="http://www.underbit.com/products/mad/">libmad</ulink></emphasis>
95   - optional, for fast integer-only MP3 decoding on FPU-less platforms
96 </para></listitem>
97 </itemizedlist>
98 </sect1>
99
100
101 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
102
103
104 <sect1 id="features">
105 <title>Features</title>
106
107 <itemizedlist>
108 <listitem><para>
109   Decide if you need GUI. If you do, see the <link linkend="gui">GUI</link>
110   section before compiling.
111 </para></listitem>
112 <listitem><para>
113   If you want to install <application>MEncoder</application> (our great
114   all-purpose encoder), see the
115   <link linkend="mencoder"><application>MEncoder</application></link> section.
116 </para></listitem>
117 <listitem><para>
118   If you have a V4L compatible <emphasis role="bold">TV tuner</emphasis> card,
119   and wish to watch/grab and encode movies with
120   <application>MPlayer</application>,
121   read the <link linkend="tv-input">TV input</link> section.
122 </para></listitem>
123 <listitem><para>
124   If you have a V4L compatible <emphasis role="bold">radio tuner</emphasis>
125   card, and wish to listen and capture sound with
126   <application>MPlayer</application>,
127   read the <link linkend="radio">radio</link> section.
128 </para></listitem>
129 <listitem><para>
130   There is a neat <emphasis role="bold">OSD Menu</emphasis> support ready to be
131   used. Check the <link linkend="subosd">OSD menu</link> section.
132 </para></listitem>
133 </itemizedlist>
134
135 <para>
136 Then build <application>MPlayer</application>:
137 <screen>
138 ./configure
139 make
140 make install
141 </screen>
142 </para>
143
144 <para>
145 At this point, <application>MPlayer</application> is ready to use.
146 Check if you have a <filename>codecs.conf</filename> file in your home
147 directory at (<filename>~/.mplayer/codecs.conf</filename>) left from old
148 <application>MPlayer</application> versions. If you find one, remove it.
149 </para>
150
151 <para>
152 Debian users can build a .deb package for themselves, it's very simple.
153 Just exec
154 <screen>fakeroot debian/rules binary</screen>
155 in <application>MPlayer</application>'s root directory. See
156 <link linkend="debian">Debian packaging</link> for detailed instructions.
157 </para>
158
159 <para>
160 <emphasis role="bold">Always browse the output of</emphasis>
161 <filename>./configure</filename>, and the
162 <filename>configure.log</filename> file, they contain information about
163 what will be built, and what will not. You may also want to view
164 <filename>config.h</filename> and <filename>config.mak</filename> files.
165 If you have some libraries installed, but not detected by
166 <filename>./configure</filename>, then check if you also have the proper
167 header files (usually the -dev packages) and their version matches. The
168 <filename>configure.log</filename> file usually tells you what is missing.
169 </para>
170
171 <para>
172 Though not mandatory, the fonts should be installed in order to gain OSD,
173 and subtitle functionality. The recommended method is installing a TTF
174 font file and telling <application>MPlayer</application> to use it.
175 See the <link linkend="subosd">Subtitles and OSD</link> section for details.
176 </para>
177 </sect1>
178
179
180 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
181
182
183 <sect1 id="gui">
184 <title>What about the GUI?</title>
185
186 <para>
187 The GUI needs GTK 1.2.x or GTK 2.0 (it isn't fully GTK, but the panels are),
188 so <systemitem class="library">GTK</systemitem> (and the devel stuff, usually
189 called <systemitem class="library">gtk-dev</systemitem>) has to be installed.
190 You can build it by specifying <option>--enable-gui</option> during
191 <filename>./configure</filename>. Then, to turn on GUI mode, you have to
192 execute the <command>gmplayer</command> binary.
193 </para>
194
195 <para>
196 As <application>MPlayer</application> doesn't have a skin included, you
197 have to download one if you want to use the GUI. See the <ulink
198 url="http://www.mplayerhq.hu/dload.html">download page</ulink>.
199 It should be extracted to the usual system-wide directory (<filename
200 class="directory">$PREFIX/share/mplayer/skins</filename>), or to <filename
201 class="directory">$HOME/.mplayer/skins</filename>.
202 <application>MPlayer</application> by default looks in these directories
203 for a directory named <filename class="directory">default</filename>, but
204 you can use the <option>-skin <replaceable>newskin</replaceable></option>
205 option, or the <literal>skin=newskin</literal> config file directive to use
206 the skin in the <filename class="directory">*/skins/newskin</filename>
207 directory.
208 </para>
209 </sect1>
210
211
212 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
213
214
215 <sect1 id="fonts-osd">
216 <title>Fonts and OSD</title>
217
218 <para>
219 You need to tell <application>MPlayer</application> which font to use to
220 enjoy OSD and subtitles. Any TrueType font or special bitmap fonts will
221 work. However, TrueType fonts are recommended as they look far better,
222 can be properly scaled to the movie size and cope better with different
223 encodings.
224 </para>
225
226 <!-- ********** -->
227
228 <sect2 id="truetype-fonts">
229 <title>TrueType fonts</title>
230
231 <para>
232 There are two ways to get TrueType fonts to work. The first is to pass
233 the <option>-font</option> option to specify a TrueType font file on
234 the command line. This option will be a good candidate to put in your
235 configuration file (see the manual page for details).
236 The second is to create a symlink called <filename>subfont.ttf</filename>
237 to the font file of your choice. Either
238 <screen>
239 ln -s <replaceable>/path/to/sample_font.ttf</replaceable> ~/.mplayer/subfont.ttf
240 </screen>
241 for each user individually or a system-wide one:
242 <screen>
243 ln -s <replaceable>/path/to/sample_font.ttf</replaceable> $PREFIX/share/mplayer/subfont.ttf
244 </screen>
245 </para>
246
247 <para>
248 If <application>MPlayer</application> was compiled with
249 <systemitem class="library">fontconfig</systemitem> support, the above methods
250 won't work, instead <option>-font</option> expects a
251 <systemitem class="library">fontconfig</systemitem> font name
252 and defaults to the sans-serif font. Example:
253 <screen>
254 mplayer -font <replaceable>'Bitstream Vera Sans'</replaceable> <replaceable>anime.mkv</replaceable>
255 </screen>
256 </para>
257
258 <para>
259 To get a list of fonts known to
260 <systemitem class="library">fontconfig</systemitem>,
261 use <command>fc-list</command>.
262 </para>
263 </sect2>
264
265 <!-- ********** -->
266
267 <sect2 id="bitmap-fonts">
268 <title>bitmap fonts</title>
269
270 <para>
271 If for some reason you wish or need to employ bitmap fonts, download a set
272 from our homepage. You can choose between various
273 <ulink url="http://www.mplayerhq.hu/MPlayer/releases/fonts/">ISO fonts</ulink>
274 and some sets of fonts
275 <ulink url="http://www.mplayerhq.hu/MPlayer/contrib/fonts/">contributed by users</ulink>
276 in various encodings.
277 </para>
278
279 <para>
280 Uncompress the file you downloaded to
281 <filename class="directory">~/.mplayer</filename> or
282 <filename class="directory">$PREFIX/share/mplayer</filename>.
283 Then rename or symlink one of the extracted directories to
284 <filename class="directory">font</filename>, for example:
285 <screen>
286 ln -s <replaceable>~/.mplayer/arial-24</replaceable> ~/.mplayer/font
287 </screen>
288 <screen>
289 ln -s <replaceable>$PREFIX/share/mplayer/arial-24</replaceable> $PREFIX/share/mplayer/font
290 </screen>
291 </para>
292
293 <para>
294 Fonts should have an appropriate <filename>font.desc</filename> file
295 which maps Unicode font positions to the actual code page of the
296 subtitle text. Another solution is to have UTF-8-encoded subtitles
297 and use the <option>-utf8</option> option or give the subtitles
298 file the same name as your video file with a <filename>.utf</filename>
299 extension and have it in the same directory as the video file.
300 </para>
301 </sect2>
302
303 <!-- ********** -->
304
305 <sect2 id="osdmenu">
306 <title>OSD menu</title>
307
308 <para>
309 <application>MPlayer</application> has a completely user-definable
310 OSD Menu interface.
311 </para>
312
313 <note><para>
314 the Preferences menu is currently UNIMPLEMENTED!
315 </para></note>
316
317 <orderedlist>
318 <title>Installation</title>
319 <listitem><para>
320   compile <application>MPlayer</application> by passing the
321   <option>--enable-menu</option> to <filename>./configure</filename>
322 </para></listitem>
323 <listitem><para>
324   make sure you have an OSD font installed
325 </para></listitem>
326 <listitem><para>
327   copy <filename>etc/menu.conf</filename> to your
328   <filename class="directory">.mplayer</filename> directory
329 </para></listitem>
330 <listitem><para>
331   copy <filename>etc/input.conf</filename> to your
332   <filename class="directory">.mplayer</filename> directory, or to the
333   system-wide <application>MPlayer</application> config dir (default:
334   <filename class="directory">/usr/local/etc/mplayer</filename>)
335 </para></listitem>
336 <listitem><para>
337   check and edit <filename>input.conf</filename> to enable menu movement keys
338   (it is described there).
339 </para></listitem>
340 <listitem><para>
341   start <application>MPlayer</application> by the following example:
342   <screen>mplayer -menu <replaceable>file.avi</replaceable></screen>
343   </para></listitem>
344 <listitem><para>
345   push any menu key you defined
346 </para></listitem>
347 </orderedlist>
348 </sect2>
349 </sect1>
350
351
352 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
353
354
355 <sect1 id="codec-installation">
356 <title>Codec installation</title>
357
358 <!-- ********** -->
359
360 <sect2 id="xvid">
361 <title>Xvid</title>
362
363 <para>
364 <ulink url="http://www.xvid.org">Xvid</ulink> is a free software MPEG-4 ASP
365 compliant video codec. Note that Xvid is not necessary to decode Xvid-encoded
366 video. <systemitem class="library">libavcodec</systemitem> is used by
367 default as it offers better speed.
368 </para>
369
370 <procedure>
371 <title>Installing <systemitem class="library">Xvid</systemitem></title>
372 <para>
373   Like most open source software, it is available in two flavors:
374   <ulink url="http://www.xvid.org/downloads.html">official releases</ulink>
375   and the CVS version.
376   The CVS version is usually stable enough to use, as most of the time it
377   features fixes for bugs that exist in releases.
378   Here is what to do to make <systemitem class="library">Xvid</systemitem>
379   CVS work with <application>MEncoder</application>:
380 </para>
381 <step><para>
382   <screen>cvs -z3 -d:pserver:anonymous@cvs.xvid.org:/xvid login</screen>
383 </para></step>
384 <step><para>
385   <screen>cvs -z3 -d:pserver:anonymous@cvs.xvid.org:/xvid co xvidcore</screen>
386 </para></step>
387 <step><para>
388   <screen>cd xvidcore/build/generic</screen>
389 </para></step>
390 <step><para>
391   <screen>./bootstrap.sh &amp;&amp; ./configure</screen>
392   You may have to add some options (examine the output of
393   <command>./configure --help</command>).
394 </para></step>
395 <step><para>
396   <screen>make &amp;&amp; make install</screen>
397 </para></step>
398 <step><para>
399   Recompile <application>MPlayer</application>.
400 </para></step>
401 </procedure>
402 </sect2>
403
404 <!-- ********** -->
405
406 <sect2 id="x264">
407 <title><systemitem class="library">x264</systemitem></title>
408
409 <para>
410 <ulink url="http://developers.videolan.org/x264.html"><systemitem class="library">x264</systemitem></ulink>
411 is a library for creating H.264 video.
412 <application>MPlayer</application> sources are updated whenever
413 an <systemitem class="library">x264</systemitem> API change
414 occurs, so it is always suggested to use
415 <application>MPlayer</application> from Subversion.
416 </para>
417
418 <para>
419 If you have a GIT client installed, the latest x264
420 sources can be gotten with this command:
421 <screen>git clone git://git.videolan.org/x264.git</screen>
422
423 Then build and install in the standard way:
424 <screen>./configure &amp;&amp; make &amp;&amp; make install</screen>
425
426 Now rerun <filename>./configure</filename> for
427 <application>MPlayer</application> to pick up
428 <systemitem class="library">x264</systemitem> support.
429 </para>
430 </sect2>
431
432 <!-- ********** -->
433
434 <sect2 id="aac">
435 <title>AAC</title>
436
437 <para>
438 An open source AAC decoder called FAAD2 is available from
439 <ulink url="http://www.audiocoding.com/downloads.html"/>.
440 <application>MPlayer</application> includes a copy of it in its source tree.
441 If you want to use the external library instead, install it and pass
442 <option>--enable-faad-external</option> to <filename>./configure</filename>.
443 </para>
444
445 <para>
446 FAAD2 binaries are not available from audiocoding.com, but you can (apt-)get
447 Debian packages from
448 <ulink url="http://www.debian-multimedia.org/">Christian Marillat</ulink>,
449 Mandrake/Mandriva RPMs from the <ulink url="http://plf.zarb.org">P.L.F</ulink>
450 and Fedora/CentOS/RHEL RPMs from <ulink url="http://rpmfusion.org/">RPMFusion</ulink>.
451 </para>
452 <para>
453 If you choose to build from source, you do not need all of FAAD2 to decode
454 AAC files, libfaad is enough. Build it like this:
455 <screen>
456 cd faad2/
457 sh bootstrap
458 ./configure
459 cd libfaad
460 make
461 make install
462 </screen>
463 </para>
464 </sect2>
465
466 <!-- ********** -->
467
468 <sect2 id="amr">
469 <title>AMR</title>
470
471 <para>
472 MPlayer can use the OpenCORE AMR libraries through FFmpeg.
473 Download the libraries for AMR-NB and AMR-WB from the
474 <ulink url="http://sourceforge.net/projects/opencore-amr/">opencore-amr</ulink>
475 project and install them according to the instructions on that page.
476 </para>
477 </sect2>
478
479 <sect2 id="xmms">
480 <title>XMMS</title>
481
482 <para>
483 <application>MPlayer</application> can use <application>XMMS</application> input
484 plugins to play many file formats. There are plugins for SNES game tunes, SID
485 tunes (from Commodore 64), many Amiga formats, .xm, .it, VQF, Musepack, Bonk,
486 shorten and many others. You can find them at the
487 <ulink url="http://www.xmms.org/plugins.php?category=input">XMMS input plugin page</ulink>.
488 </para>
489
490 <para>
491 For this feature you need to have <application>XMMS</application> and compile
492 <application>MPlayer</application> with
493 <filename>./configure --enable-xmms</filename>.
494 </para>
495 </sect2>
496
497 </sect1>
498
499
500 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
501
502
503 <sect1 id="rtc">
504 <title>RTC</title>
505
506 <para>
507 There are three timing methods in <application>MPlayer</application>.
508
509 <itemizedlist>
510 <listitem><para>
511   <emphasis role="bold">To use the old method</emphasis>, you don't have to do
512   anything. It uses <systemitem>usleep()</systemitem> to tune
513   A/V sync, with +/- 10ms accuracy. However sometimes the sync has to be
514   tuned even finer.
515 </para></listitem>
516 <listitem>
517   <para>
518   <emphasis role="bold">The new timer</emphasis> code uses the RTC (RealTime
519   Clock) for this task, because it has precise 1ms timers.
520   The <option>-rtc</option> option enables it,
521   but a properly set up kernel is required.
522   If you are running kernel 2.4.19pre8 or later you can adjust the maximum RTC
523   frequency for normal users through the <systemitem class="systemname">/proc
524   </systemitem> file system. Use one of the following two commands to
525   enable RTC for normal users:
526   <screen>echo 1024 &gt; /proc/sys/dev/rtc/max-user-freq</screen>
527   <screen>sysctl dev/rtc/max-user-freq=1024</screen>
528   You can make this setting permanent by adding the latter to
529   <filename>/etc/sysctl.conf</filename>.
530   </para>
531   <para>
532   You can see the new timer's efficiency in the status line.
533   The power management functions of some notebook BIOSes with speedstep CPUs
534   interact badly with RTC. Audio and video may get out of sync. Plugging the
535   external power connector in before you power up your notebook seems to help.
536   In some hardware combinations (confirmed during usage of non-DMA DVD drive
537   on an ALi1541 board) usage of the RTC timer causes skippy playback. It's
538   recommended to use the third method in these cases.
539   </para>
540 </listitem>
541 <listitem><para>
542   <emphasis role="bold">The third timer code</emphasis> is turned on with the
543   <option>-softsleep</option> option. It has the efficiency of the RTC, but it
544   doesn't use RTC. On the other hand, it requires more CPU.
545 </para></listitem>
546 </itemizedlist>
547 </para>
548 </sect1>
549
550 </chapter>