* Corrected vlc-howto thanks to Arnaud Gomes-do-Vale
[vlc.git] / doc / vlc-howto.sgml
1 <!doctype linuxdoc system>
2 <linuxdoc><article>
3 <titlepag>
4  <title>VLC HOWTO</title>
5  <author>by the Videolan Team<tt><htmlurl url="mailto:videolan-faq@videlan.org" name="videolan-faq@videlan.org"></tt></author>
6  <date>v0.0.3, 21 apr 2001</date>
7
8  <abstract>
9   This document describes how to use the vlc (VideoLAN client) to read DVDs and mpeg files and DVDs.
10  </abstract>
11 </titlepag>
12
13 <toc>
14
15 <sect>
16  <heading>Introduction</heading>
17
18  <sect1>
19   <heading>What is VideoLAN ?</heading>
20   <p>
21    VideoLAN is a project of sudents of the École Centrale Paris which aims 
22    to broadcast video on the campus, and provide the students with a MPEG2 
23    software-only decoder. VideoLAN is an OpenSource project which will thus 
24    allow anyone to watch DVD movies under Linux, BeOS, MacOS and most Unix 
25    systems
26   </p>
27   <p>
28     You may want to look at the port section on our website : 
29     <htmlurl url="http://www.videolan.org" name="http://www.videolan.org/">.
30   </p>
31  </sect1>
32  
33  <sect1>
34   <heading>What is the vlc</heading>
35   <p>
36    Vlc stands for VideoLAN client. It is the name of the program which is
37    capable of decoding MPEG streams, and displaying them onto your screen,
38    so you can watch you favourite movies, confortably sit in your armchair
39    :-).
40   </p>
41  </sect1>
42
43  <sect1>
44   <heading>Translated versions of this document</heading>
45   <p>
46     No translation is currently available.
47   </p>
48
49   <p>
50    The English version is maintained by Henri Fallon,
51    and the VideoLAN team. It can be found at:
52    <htmlurl url="http://www.videolan.org/doc.html"
53    name="http://www.videolan.org/doc.html">.
54   </p>
55  </sect1>
56
57  <sect1> 
58   <heading>Disclaimer</heading> 
59   <p> 
60    This documentation is given "as is", and any comment and improvement
61    are welcome. 
62   </p>
63
64   <p>
65    In this HOWTO, we consider you already have a little knowledge about Linux, and you 
66    know how to use a DVD. If not, good howtos can be found on the Linux Documentation
67    Projet.
68   </p>
69  </sect1>
70   
71  <sect1>
72   <heading>Legal</heading>
73   <p>
74    Copyright (©) 2001 by the VideoLAN project. This document may be distributed only
75    subject to the terms and conditions set forth in 
76    <htmlurl url="http://metalab.unc.edu/LDP/LDP-COPYRIGHT.html" name="the LDP license">.
77   </p>
78  </sect1>
79 </sect>
80
81 <sect>
82  <heading>Installing the vlc : the packages</heading>
83   <p>
84    This is certainly the simplest way to intsall the vlc on your system,
85    especially if you're using a packaged OS.
86   </p>
87
88   <p>
89    The first thing to do is to get an archive, on our web site 
90    <htmlurl url="http://www.videolan.org/download.html" name="http://www.videolan.org/download.html">
91   </p>
92  
93  <sect1>
94   <heading>Linux/Unix users</heading>
95   <sect2>
96    <heading>Which package to chose ?</heading>
97    <p>
98     There are different packages because vlc has "plugins" which provide features 
99     but also enlarge the executable and require external libs. 
100    </p>
101    <p>
102     SDL is a lib which allows you to have an accelerated video output.
103     You will need libsdl > 1.1.6
104    </p>
105    <p>
106     If you're using the enlightened sound daemon, you may want to try 
107     the esd-aware vlc.
108    </p>
109    <p>
110     Generally, when you don't know what a module name is, you don't need/use it :-)
111    </p>
112   </sect2>
113   
114   <sect2>
115    <heading>Binary archive</heading>
116    <p>
117     Untar it typing
118     <verb>
119      tar xvzf vlc-x.x.x.tar.gz
120     </verb>
121      Go in the vlc directory and get to the 'How to play movies' section If
122      you wish not to keep vlc in this single directory but install it fully
123      on your system, you may, as root, type
124     <verb>
125      make install
126     </verb>
127    </p>
128   </sect2>
129    
130   <sect2>
131    <heading>Debian package</heading>
132    <p>
133     Just use dpkg :
134     <verb>
135      dpkg -i vlc-x.x.x.deb
136     </verb>
137    </p>
138    <p>
139     Depending on the package you have downloaded, you may have dependency
140     problems. You have to solve them, by installing the required libs.
141    </p>
142   </sect2>
143    
144   <sect2>
145     <heading>RPM package</heading>
146    <p>
147     Install vlc just as you would install any rpm package : 
148     <verb>
149      rpm -i vlc-x.x.x.rpm
150     </verb>
151    </p>
152    <p>
153     You may have to install external libs to meet dependencies, depending on
154     the package you downloaded (gnome, gtk, esd, ...).
155    </p>
156   </sect2>
157  </sect1>
158
159  <sect1>
160   <heading>BeOS users</heading>
161   <p>
162    Double-click on the archive. It should open your favorite archive extracter.
163    You can then execute the vlc from there, or extract the archive to a 
164    diretory and run it from there.
165   </p>
166  </sect1>
167  
168  <sect1>
169   <heading>MacOS X users</heading>
170   <p>
171    To be completed
172   </p>
173  </sect1> 
174 </sect>    
175     
176 <sect>
177  <heading>Using the vlc</heading>
178  <p>
179   Good job, you have installed the vlc on your system. Now, it's time to 
180   use it. Don't worry, it's not that difficult.
181  </p>
182  <sect1>
183   <heading>Lauching</heading>
184   <sect2>
185    <heading>The graphical interface</heading>
186    <p>
187     Basically, double clicking on the vlc icon, or typing 'vlc' in a 
188     console should launch a graphical interface On Linux/Unix, you may want
189     to specify gnome or gtk interface, with the "--intf" option.
190    </p>
191   </sect2>
192
193   <sect2>
194    <heading>In case it doesn't work</heading>
195    <p>
196     In case this does not work, you'll have to use command line options.
197     Usually, to play a file, you'll use :
198     <verb>
199      vlc [file name]
200     </verb>
201     To play a dvd, if your dvd device is "/dev/dvd", you'll type :
202     <verb>
203      vlc dvd:/dev/dvd
204     </verb>
205    On BeOS, the dvd device looks like "/dev/disk/ide/atapi/1/slave/0/raw"
206    </sect2>  
207  </sect1>
208  
209  <sect1>
210   <heading>Using the interface</heading>
211   <p>
212    By now you should see a beautiful interface, with buttons and menus.
213    The text should be quite self-explaining : "Open file", "Open Disc", ...
214   </p>
215   <p>
216    For Dvd's you can choose directly from the "open" box the title & chapter 
217    you want to play.
218   </p>
219  </sect1>
220  <sect1>
221   <heading>Fullscreen - chapters - features</heading>
222   <p>
223    Some of the following features don't work yet on some platforms.
224    We're doing our best to get the ports in sync.
225   </p>
226   <p>
227    At any time you can change the audio/subtitles channel using either the 
228    "setting" menu from the interface or using the "right click" menu from
229    the video output window.
230   </p>
231   <p>
232    To change chapter, you can use the right-click menu or the interface. 
233    Please note that the gnome interface is more advanced than the gtk or 
234    qt ones.
235   </p>
236   <p>
237    Using the 'f' key when using SDL or XVideo output toggles the 
238    fullscreen mode. Be warned that "right click" menus are a bit 
239    unstable.
240   </p>
241  </sect1>
242  <sect1>
243   <heading>User help</heading>
244   <p>
245    First of all, it something seems to go wrong, read and try try to 
246    understand the error messages. If you are a confirmed user, you 
247    may try the "-vvv" option which makes the vlc very verbose.
248   </p>
249   <p>
250    There is a FAQ page on our website :
251    <htmlurl url="http://www.videolan.org/doc.html" name="http://www.videolan.org/doc.html">.
252    If you think one question should be in the FAQ, please contact
253    <htmlurl url="mailto:videolan-faq@videlan.org" name="videolan-faq@videlan.org">
254   </p>
255   <p>
256    Finally, there's a users mailing list (English speaking). To subscribe, send a mail to 
257    <htmlurl url="mailto:listar@videlan.org" name="listar@videlan.org"> containing
258    "subscribe vlc" as message body.
259   </p>
260 </sect> 
261
262 <sect>
263  <heading>Advanced use of the vlc</heading>
264  <sect1>
265   <heading>Command line options</heading>
266   <sect2>
267    <heading>Choosing the video output</heading>
268    <p>
269     You have to use the "-V" otpion. For example :
270     <verb>
271      vlc -V xvideo
272     </verb>
273    </p>
274   </sect2>
275   
276   <sect2>
277    <heading>Choosing the audio output</heading>
278    <p>
279     Use the "-A" option. For example :
280     <verb>
281      vlc -A alsa
282     </verb>
283    </p>
284   </sect2>
285
286   <sect2>
287    <heading>Specifying a file</heading>
288    <p>
289     Simply put the file name at the end of the command line, you won't need then 
290     to click "open" when the interface launches :
291     <verb>
292      vlc myfile.mpeg
293     </verb>
294    </p>
295   </sect2>
296   
297   <sect2>
298    <heading>Specifying the title and chapter where to start</heading>
299    <p>
300     Use the "-t" and "-T" to specify title and chapter. For example, to go to the 12th 
301     chapter of the 2nd title, you'll type :
302     <verb>
303      vlc -t 2 -T 12
304     </verb>
305    </p>
306   </sect2>
307  </sect1>
308 </sect> 
309
310 <sect>
311  <heading>For real men : building your vlc :-)</heading>
312  <p>
313   You can choose either to take the latest release, or a CVS source. Note that
314   CVS snapshots may be broken, although we do our best to prevent this from
315   happening.
316  </p>
317  <p>
318   From here, you have to be a little experienced, even more if you want to use
319   the cvs.
320  </p>
321  <sect1>
322   <heading>Getting an archive</heading>
323   <p>
324    You have guessed it, the first thing to do is to get the source.
325    Until there, everyone should understand :)
326   </p>
327   <sect2>
328    <heading>Web site</heading>
329    <p>
330     Source packages can be found in the "tarballs" section of the download page :
331     <htmlurl url="http://www.videolan.org/download.html" name="http://www.videolan.org/dowload.html">.
332    </p>
333    <p>
334     CVS snapshots are available from the address : 
335     <htmlurl url="http://www.videolan.org/packages/snapshots/" 
336     name="http://www.videolan.org/packages/snapshots/">.
337    </p>
338    <p>
339     Then untar the archive :
340     <verb>
341      tar xzf vlc-x-x-x.tar.gz
342     </verb>
343    </p>
344   </sect2>
345   <sect2>
346    <heading>Directly from CVS</heading>
347    <p>
348     Firs log in as suer anonymous with an empty password :
349     <verb>
350      cvs -d :pserver:anonymous@anoncvs.videolan.org:/var/cvs/videolan login
351     </verb>
352    Then retrieve the repository :
353    <verb>
354     cvs -d :pserver:anonymous@anoncvs.videolan.org:/var/cvs/videolan -z3 checkout vlc
355    </verb>
356    </p>
357   </sect2>
358  </sect1>
359  
360  <sect1>
361   <heading>Building the program</heading>
362   <p>
363    Go into the vlc directory and run the configure script :
364    <verb>
365     ./configure
366    </verb>
367    If you want to enable options, you may add "--enable-option" to the previous line.
368    For example, to build with the xvideo extension, and alsa support, you should type :
369    <verb>
370     ./configure --enable-xvideo --enable-alsa
371    </verb>
372    To get the list of the available options, and know if they are enabled by default,
373    you can try :
374    <verb>
375     ./configure --help
376    </verb>
377    A very typical installation, on a XFree 4.1 system, recent video card, with gnome, is :
378    <verb>
379     ./configure --enable-xvideo --enable-esd --enable-gnome
380    </verb>
381   <p>
382  </sect1>
383  <sect1>
384   <heading>Plugins, builtins ...</heading>
385   <p>
386    The configure script should create a Makefile.opts file, which you can edit and modify.
387    Indeed you can chose to have features (as esd support, for example) built as plugins
388    or inside the program.
389   </p>
390   <p>
391    If you build a feature as a plugin, it can lead to a little loss of performance.
392    It you build it inside the code, i'll enlarge a bit the size of the executable.
393   </p>
394   <p>
395    When you're done with Makefile.opts (which also works if you leave it untouched), just 
396    type:
397     <verb>
398     make
399     </verb>
400    It should compile without any error. If there are, please check you have the required libs 
401    installed on your system, as the configure script can't check them all.
402   </p>
403   <p>
404    When you're done with it, as root, type :
405    <verb>
406     make install
407    </verb>
408   if you wish to have vlc fully installed on your system. If you prefer to keep in in the 
409   current directory, you may skip the "make install". You'll then have to cd into the vlc 
410   directory and type "./vlc" instead of just typing vlc.
411   </p>
412  </sect1>
413 </sect>
414
415 <sect>
416  <heading>Really advanced use</heading>
417  <sect1>
418   <heading>Using the videolan network solution</heading>
419   <p>
420    I'll only speak about the vlc here. There will be a howto on the whole network solution.
421    You have to tell the vlc that it will receive network streams. This can be done either by
422    using the "network" button of the interface, or in the command line : 
423    <verb>
424     vlc ts://server[:port]
425    </verb>
426   </p>
427   <p>
428    This works for unicast. If you are receiving a broadcasted stream, you have to specify the 
429    broadcast address : 
430    <verb>
431     vlc --broadcast broadcast_addr ts://server[:port]
432    </verb>
433   </p>
434  </sect1>
435
436  <sect1>
437   <heading>Developping the vlc</heading>
438   <p>
439    Christophe Massiot has written a documentation for developpers.
440   </p>
441  </sect1>
442
443 </sect>
444
445 </article></linuxdoc>