Update to MPlayer SVN rev 31722 and FFmpeg SVN rev 24213.
[vaapi:jj-mplayer.git] / README
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.
7
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.
11
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.
16
17
18 Requirements:
19 - POSIX system: You need a POSIX-compatible shell and POSIX-compatible system
20   tools like grep, sed, awk, etc. in your path.
21 - You need a working development environment that can compile programs.
22   On popular Linux distributions, this means having the glibc development
23   package(s) installed.
24 - To compile MPlayer with X11 support, you need to have the X Window System
25   development packages (like for XFree86 or X.Org) installed.
26 - For the GUI you need the GTK development packages.
27
28
29 Before you start...
30 Make sure that your version of X has Xvideo support, without it even very
31 fast machines may not be able to properly play high resolution videos in
32 fullscreen mode. Consult DOCS/HTML/en/video.html for details. There you may
33 also find out about special card-specific video output drivers that can yield
34 optimal performance.
35
36
37 ______________________
38 STEP0: Getting MPlayer
39 ~~~~~~~~~~~~~~~~~~~~~~
40
41 Official releases and Subversion snapshots, as well as binary codec packages
42 and a number of different skins for the GUI are available from the download
43 section of our homepage at
44
45   http://www.mplayerhq.hu/dload.html
46
47 MPlayer has builtin support for the most common audio and video formats. For a
48 few formats no native decoder exists and external binary codecs are required
49 to handle them. Examples are newer RealVideo variants and a variety of rare
50 formats. However, binary codecs are NOT required in this day and age, they are
51 strictly optional.
52
53 Please note that binary codecs only work on the processor architecture they
54 were compiled for. Choose the correct package for your processor. No other
55 package is necessary.
56
57 The GUI needs at least one skin and codec packages add support for some more
58 video and audio formats. MPlayer does not come with any of these by default,
59 you have to download and install them separately.
60
61 You can also get MPlayer via Subversion. Issue the following commands to get
62 the latest sources:
63
64   svn checkout svn://svn.mplayerhq.hu/mplayer/trunk mplayer
65
66 A directory named 'mplayer' will be created. It will include all necessary
67 FFmpeg libraries, you don't need to get them separately as was the case in
68 the past. You can later update your sources by saying
69
70   svn update
71
72 from within that directory.
73
74
75 _______________________________
76 STEP1: Installing Binary Codecs
77 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
78
79 Unpack the codecs archives and put the contents in a directory where MPlayer
80 will find them. The default directory is /usr/local/lib/codecs/ (it used to be
81 /usr/local/lib/win32 in the past, this also works) but you can change that to
82 something else by passing the '--codecsdir' option to './configure'.
83
84
85 __________________________
86 STEP2: Configuring MPlayer
87 ~~~~~~~~~~~~~~~~~~~~~~~~~~
88
89 MPlayer can be adapted to all kinds of needs and hardware environments. Run
90
91   ./configure
92
93 to configure MPlayer with the default options. GUI support has to be enabled
94 separately, run
95
96   ./configure --enable-gui
97
98 if you want to use the GUI.
99
100 If something does not work as expected, try
101
102   ./configure --help
103
104 to see the available options and select what you need.
105
106 The configure script prints a summary of enabled and disabled options. If you
107 have something installed that configure fails to detect, check the file
108 config.log for errors and reasons for the failure. Repeat this step until
109 you are satisfied with the enabled feature set.
110
111
112 ________________________
113 STEP3: Compiling MPlayer
114 ~~~~~~~~~~~~~~~~~~~~~~~~
115
116 Now you can start the compilation by typing
117
118   make
119
120 You can install MPlayer with
121
122   make install
123
124 provided that you have write permission in the installation directory.
125
126 If all went well, you can run MPlayer by typing 'mplayer'. A help screen with a
127 summary of the most common options and keyboard shortcuts should be displayed.
128
129 If you get 'unable to load shared library' or similar errors, run
130 'ldd ./mplayer' to check which libraries fail and go back to STEP 3 to fix it.
131 Sometimes running 'ldconfig' is enough to fix the problem.
132
133 NOTE: If you run Debian you can configure, compile and build a proper Debian
134 .deb package with only one command:
135
136   fakeroot debian/rules binary
137
138 If you want to pass custom options to configure, you can set up the
139 DEB_BUILD_OPTIONS environment variable. For instance, if you want GUI
140 and OSD menu support you would use:
141
142   DEB_BUILD_OPTIONS="--enable-gui --enable-menu" fakeroot debian/rules binary
143
144 You can also pass some variables to the Makefile. For example, if you want
145 to compile with gcc 3.4 even if it's not the default compiler:
146
147   CC=gcc-3.4 DEB_BUILD_OPTIONS="--enable-gui" fakeroot debian/rules binary
148
149 To clean up the source tree run the following command:
150
151   fakeroot debian/rules clean
152
153 ______________________________________
154 STEP4: Choose an onscreen display font
155 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
156
157 You can use any TrueType font installed on your system. Just pass '-font
158 /path/to/font.ttf' on the command line or add 'font=/path/to/font.ttf' to
159 your configuration file. The manual page has more details. Alternatively
160 you can create a symbolic link from either ~/.mplayer/subfont.ttf or
161 /usr/local/share/mplayer/subfont.ttf to your TrueType font.
162
163
164 ____________________________
165 STEP5: Installing a GUI skin
166 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167
168 Unpack the archive and put the contents in /usr/local/share/mplayer/skins/ or
169 ~/.mplayer/skins/. MPlayer will use the skin in the subdirectory named default
170 of /usr/local/share/mplayer/skins/ or ~/.mplayer/skins/ unless told otherwise
171 via the '-skin' switch. You should therefore rename your skin subdirectory or
172 make a suitable symbolic link.
173
174
175 __________________
176 STEP6: Let's play!
177 ~~~~~~~~~~~~~~~~~~
178
179 That's it for the moment. To start playing movies, open a command line and try
180
181   mplayer <moviefile>
182
183 or for the GUI
184
185   gmplayer <moviefile>
186
187 gmplayer is a symbolic link to mplayer created by 'make install'.
188 Without <moviefile>, gmplayer will start with the GUI filepicker.
189
190 To play a VCD track or a DVD title, try:
191
192   mplayer vcd://2 -cdrom-device /dev/hdc
193   mplayer dvd://1 -alang en -slang hu -dvd-device /dev/hdd
194
195 See 'mplayer -help' and 'man mplayer' for further options.
196
197 'mplayer -vo help' will show you the available video output drivers. Experiment
198 with the '-vo' switch to see which one gives you the best performance.
199 If you get jerky playback or no sound, experiment with the '-ao' switch (see
200 '-ao help') to choose between different audio drivers. Note that jerky playback
201 is caused by buggy audio drivers or a slow processor and video card. With a
202 good audio and video driver combination, one can play DVDs and 720x576 MPEG-4
203 files smoothly on a Celeron 366. Slower systems may need the '-framedrop'
204 option.
205
206 Questions you may have are probably answered in the rest of the documentation.
207 The places to start reading are the man page, DOCS/HTML/en/index.html and
208 DOCS/HTML/en/faq.html. If you find a bug, please report it, but first read
209 DOCS/HTML/en/bugreports.html.