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