Add a comment that explains why this header has no multiple inclusion guards.
[mplayer/greg.git] / README
blob7b697ee9fb12efe81dfd498648cf5b85413109ee
1 Welcome to MPlayer, The Movie Player. MPlayer can play most standard video
2 formats out of the box and almost all others with the help of external codecs.
3 MPlayer currently works best from the command line, but visual feedback for
4 many functions is available from its onscreen status display (OSD), which is
5 also used for displaying subtitles. MPlayer also has a GUI with skin support and
6 several unofficial alternative graphical frontends are available.
8 MEncoder is a command line video encoder for advanced users that can be built
9 from the MPlayer source tree. Unofficial graphical frontends exist but are
10 not included.
12 This document is for getting you started in a few minutes. It cannot answer all
13 of your questions. If you have problems, please read the documentation in
14 DOCS/HTML/en/index.html, which should help you solve most of your problems.
15 Also read the man page to learn how to use MPlayer.
18 Requirements:
19 - You need a working development environment that can compile programs.
20   On popular Linux distributions, this means having the glibc development
21   package(s) installed.
22 - To compile MPlayer with X11 support, you need to have the X Window System
23   development packages (like for XFree86 or X.Org) installed.
24 - For the GUI you need the GTK development packages.
27 Before you start...
28 Make sure that your version of X has Xvideo support, without it even very
29 fast machines may not be able to properly play high resolution videos in
30 fullscreen mode. Consult DOCS/HTML/en/video.html for details. There you may
31 also find out about special card-specific video output drivers that can yield
32 optimal performance.
35 ______________________
36 STEP0: Getting MPlayer
37 ~~~~~~~~~~~~~~~~~~~~~~
39 Official releases and Subversion snapshots, as well as binary codec packages
40 and a number of different skins for the GUI are available from the download
41 section of our homepage at
43   http://www.mplayerhq.hu/dload.html
45 The GUI needs at least one skin and codec packages add support for some more
46 video and audio formats. MPlayer does not come with any of these by default,
47 you have to download and install them separately.
49 You can also get MPlayer via Subversion. Issue the following commands to get
50 the latest sources:
52   svn checkout svn://svn.mplayerhq.hu/mplayer/trunk mplayer
54 A directory named 'mplayer' will be created. It will include all necessary
55 FFmpeg libraries, you don't need to get them separately as was the case in
56 the past. You can later update your sources by saying
58   svn update
60 from within that directory.
63 _______________________________
64 STEP1: Installing Binary Codecs
65 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
67 MPlayer has builtin support for the most common audio and video formats. For a
68 few formats no native decoder exists and external binary codecs are required
69 to handle them, for example newer RealVideo variants and a variety of uncommon
70 formats. This step is not mandatory, but recommended for getting MPlayer to
71 play a broader range of formats. Please note that binary codecs only work on
72 the processor architecture they were compiled for.
74 Unpack the codecs archives and put the contents in a directory where MPlayer
75 will find them. The default directory is /usr/local/lib/codecs/ (it used to be
76 /usr/local/lib/win32 in the past, this also works) but you can change that to
77 something else by passing the '--codecsdir' option to './configure'.
80 __________________________
81 STEP2: Configuring MPlayer
82 ~~~~~~~~~~~~~~~~~~~~~~~~~~
84 MPlayer can be adapted to all kinds of needs and hardware environments. Run
86   ./configure
88 to configure MPlayer with the default options. GUI support has to be enabled
89 separately, run
91   ./configure --enable-gui
93 if you want to use the GUI.
95 If something does not work as expected, try
97   ./configure --help
99 to see the available options and select what you need.
101 The configure script prints a summary of enabled and disabled options. If you
102 have something installed that configure fails to detect, check the file
103 configure.log for errors and reasons for the failure. Repeat this step until
104 you are satisfied with the enabled feature set.
107 ________________________
108 STEP3: Compiling MPlayer
109 ~~~~~~~~~~~~~~~~~~~~~~~~
111 Now you can start the compilation by typing
113   make
115 You can install MPlayer with
117   make install
119 provided that you have write permission in the installation directory.
121 If all went well, you can run MPlayer by typing 'mplayer'. A help screen with a
122 summary of the most common options and keyboard shortcuts should be displayed.
124 If you get 'unable to load shared library' or similar errors, run
125 'ldd ./mplayer' to check which libraries fail and go back to STEP 3 to fix it.
126 Sometimes running 'ldconfig' is enough to fix the problem.
128 NOTE: If you run Debian you can configure, compile and build a proper Debian
129 .deb package with only one command:
131   fakeroot debian/rules binary
133 If you want to pass custom options to configure, you can set up the
134 DEB_BUILD_OPTIONS environment variable. For instance, if you want GUI
135 and OSD menu support you would use:
137   DEB_BUILD_OPTIONS="--enable-gui --enable-menu" fakeroot debian/rules binary
139 You can also pass some variables to the Makefile. For example, if you want
140 to compile with gcc 3.4 even if it's not the default compiler:
142   CC=gcc-3.4 DEB_BUILD_OPTIONS="--enable-gui" fakeroot debian/rules binary
144 To clean up the source tree run the following command:
146   fakeroot debian/rules clean
148 ______________________________________
149 STEP4: Choose an onscreen display font
150 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
152 You can use any TrueType font installed on your system. Just pass '-font
153 /path/to/font.ttf' on the command line or add 'font=/path/to/font.ttf' to
154 your configuration file. The manual page has more details. Alternatively
155 you can create a symbolic link from either ~/.mplayer/subfont.ttf or
156 /usr/local/share/mplayer/subfont.ttf to your TrueType font.
159 ____________________________
160 STEP5: Installing a GUI skin
161 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
163 Unpack the archive and put the contents in /usr/local/share/mplayer/skins/ or
164 ~/.mplayer/skins/. MPlayer will use the skin in the subdirectory named default
165 of /usr/local/share/mplayer/skins/ or ~/.mplayer/skins/ unless told otherwise
166 via the '-skin' switch. You should therefore rename your skin subdirectory or
167 make a suitable symbolic link.
170 __________________
171 STEP6: Let's play!
172 ~~~~~~~~~~~~~~~~~~
174 That's it for the moment. To start playing movies, open a command line and try
176   mplayer <moviefile>
178 or for the GUI
180   gmplayer <moviefile>
182 gmplayer is a symbolic link to mplayer created by 'make install'.
183 Without <moviefile>, gmplayer will start with the GUI filepicker.
185 To play a VCD track or a DVD title, try:
187   mplayer vcd://2 -cdrom-device /dev/hdc
188   mplayer dvd://1 -alang en -slang hu -dvd-device /dev/hdd
190 See 'mplayer -help' and 'man mplayer' for further options.
192 'mplayer -vo help' will show you the available video output drivers. Experiment
193 with the '-vo' switch to see which one gives you the best performance.
194 If you get jerky playback or no sound, experiment with the '-ao' switch (see
195 '-ao help') to choose between different audio drivers. Note that jerky playback
196 is caused by buggy audio drivers or a slow processor and video card. With a
197 good audio and video driver combination, one can play DVDs and 720x576 MPEG-4
198 files smoothly on a Celeron 366. Slower systems may need the '-framedrop'
199 option.
201 Questions you may have are probably answered in the rest of the documentation.
202 The places to start reading are the man page, DOCS/HTML/en/index.html and
203 DOCS/HTML/en/faq.html. If you find a bug, please report it, but first read
204 DOCS/HTML/en/bugreports.html.