* doc/vlc-howto.sgml: Spelling mistakes, small updates, harmonization
[vlc.git] / doc / vlc-howto.sgml
1 <!doctype linuxdoc system>
2 <linuxdoc><article>
3 <titlepag>
4  <title>VLC HOWTO</title>
5  <author>Originally written by Henri Fallon, maintained by Johan Bilien<tt><htmlurl url="mailto:jobi@videolan.org" name="<jobi@videolan.org>"></tt></author>
6  <date>v0.0.9, 16 april 2002</date>
7
8  <abstract>
9   This document describes how to use the vlc (VideoLAN client) to read DVDs and mpeg files, locally or from a network.
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 X, Windows 
25    and most Unix 
26    systems
27   </p>
28   <p>
29     You may want to look at the port section on our website : 
30     <htmlurl url="http://www.videolan.org" name="http://www.videolan.org/">.
31   </p>
32  </sect1>
33  
34  <sect1>
35   <heading>What is the VideoLAN project ?</heading>
36   <p>
37     VideoLAN is a complete software solution for video streaming, developed
38     by students at the <htmlurl url="http://www.ecp.fr" name="Ecole Centrale
39     Paris"> and contributors from all over the world, under the General
40     Public License (GPL). It has been designed for streaming MPEG 1 and MPEG
41     2 videos on local area networks (LAN), but it can be extended to
42     metropolitan or wide area networks (MAN, WAN), 
43     thanks to the multicast technology.
44     The VideoLAN solution includes a server, which can stream video from
45     various sources (file, DVD, satellite, camera, ...), a client, which can
46     receive, decode and display MPEG 1 and MPEG 2 streams and, if necessary,
47     a channel server which tells automatically to the client the parameters
48     needed to receive the stream.
49
50     <verb>
51
52         DVD --->-                 Unicast/Broadcast/Multicast
53                   \                           ---
54         File --->--     --------            /     \            --------
55                    |->-| Server |=====>====|  LAN  |---->-----| Client |
56      Satellite ->--    | (VLS)  |           \     /           | (VLC)  |
57                   /     --------              ---              --------
58        MPEG2 -->-                              ^
59       encoder                                  |
60                                                v
61                                         ----------------
62                                        | Channel Server |
63                                        |    (VLCS)      |
64                                         ----------------
65     </verb>
66     More details about the project can be found on the
67     <htmlurl url="http://www.videolan.org" name="VideoLAN Web site">.
68
69   </p>
70  </sect1>
71  <sect1>
72   <heading>The documentation of the project</heading>
73   <p>
74     There are four main documents :
75 <itemize>
76 <item>the <htmlurl
77 url="http://www.videolan.org/doc/videolan-quickstart/videolan-quickstart.html"
78 name="VideoLAN Quickstart">,
79 <item>the <htmlurl url="http://www.videolan.org/network/doc/videolan-howto.html"
80 name="VideoLAN HOWTO">,
81 <item>the <htmlurl url="http://www.videolan.org/vls/doc/vls-guide.html"
82 name="VideoLAN Server user guide">,
83 <item>this VideoLAN Client Howto.
84 </itemize>
85
86 The up-to-date version of these documents can be found on the <htmlurl
87 url="http://www.videolan.org/doc" name="VideoLAN Web Site">.
88
89  <sect1>
90   <heading>Translated versions of this document</heading>
91   <p>
92     No translation is currently available.
93   </p>
94
95   <p>
96    The English version is maintained by Henri Fallon,
97    Johan Bilien, and the VideoLAN team. It can be found at:
98    <htmlurl url="http://www.videolan.org/doc/index.html"
99    name="http://www.videolan.org/doc/index.html">.
100   </p>
101  </sect1>
102
103  <sect1>
104   <heading>Requirements</heading>
105   <sect2>
106    <heading>Operating system</heading>
107    <p>
108     VLC works under the following systems :
109    </p>
110    <p>
111    <itemize>
112     <item> Linux (all distributions, including iPAQ Familiar Linux)
113     <item> Windows (all 32bit versions)
114     <item> Mas OS X
115     <item> FreeBSD, NetBSD, OpenBSD, BSD/OS
116     <item> BeOS
117     <item> QNX RTOS
118     <item> Solaris
119    </itemize>
120    </p>
121    <p>
122     Please note that the Linux, Windows and MacOS X are generally the most
123     uptodate versions.
124   </p>
125    </sect2>
126    <sect2>
127    <heading>Software requirements</heading>
128    <p>
129     Depending on the outputs and inputs you are using, you may need 
130     additionnal libraries. Please see <ref id="modules" name="description">.
131    </p>
132    <p>
133     For playing encrypted DVDs, you will need libdvdcss, which you can found
134     on this page :
135     <htmlurl name="http://www.videolan.org/libdvdcss/download.html"
136     url="http://www.videolan.org/libdvdcss/download.html">.
137    </p>
138   </sect2>
139   <sect2>
140    <heading>Hardware requirements</heading>
141    <p>
142     The hardware power needed depends a lot of the type of stream. 
143     For reading a DVD, a CPU working at around 450 MHz is required.
144    </p>
145    <p>
146     VLC can benefits from hardware acceleration from modern video cards
147     for YUV transformation and window rescaling. it also uses MMX, MMX EXT,
148     SSE, 3Dnow! optimizations if available.
149    </p>
150   </sect2>
151  </sect1>
152  
153
154  <sect1> 
155   <heading>Disclaimer</heading> 
156   <p> 
157    This documentation is given "as is", and any comment and improvement
158    are welcome. 
159   </p>
160
161   <p>
162    In this HOWTO, we consider you already have a little knowledge about
163    Linux, and you know how to use a DVD. If not, good howtos can be
164    found on the Linux Documentation Projet.
165   </p>
166  </sect1>
167
168  <sect1> 
169   <heading>Legal</heading> 
170   <p> 
171    Copyright (©) 2001 by the VideoLAN project. This document may be
172    distributed only subject to the terms and conditions set forth in
173    <htmlurl url="http://metalab.unc.edu/LDP/LDP-COPYRIGHT.html" 
174    name="the LDP license">.
175   </p> 
176  </sect1> 
177 </sect>
178
179 <sect>
180  <heading>Quick start</heading>
181   
182   <p> This section will help you get, install and use vlc without giving you
183   much details.
184   </p>
185
186  <sect1>
187   <heading>Get and install vlc from binary packages</heading>
188   <p>
189    The first thing to do is to get an archive, on our web site 
190    <htmlurl url="http://www.videolan.org/download.html" name="http://www.videolan.org/download.html">
191   </p>
192  
193   <sect2>
194    <heading>Which package to chose ?</heading>
195    <p>
196     There are different packages because vlc has "plugins" which provide 
197     features but also enlarge the executable and require external libraries. 
198    </p>
199    <p>
200     SDL is a lib which allows you to have an accelerated video output.
201     You will need libsdl > 1.1.6
202    </p>
203    <p>
204     If you're using the enlightened sound daemon, you may want to try 
205     the esd-aware vlc.
206    </p>
207    <p>
208     Generally, when you don't know what a module name is, you don't 
209     need/use it :-)
210    </p>
211   </sect2>
212   
213   <sect2>
214    <heading>Debian package</heading>
215    <p>
216     Just use dpkg :
217     <verb>
218      dpkg -i vlc-x.x.x.deb
219     </verb>
220    </p>
221    <p>
222     Depending on the package you have downloaded, you may have dependency
223     problems. You have to solve them, by installing the required libraries.
224    </p>
225   </sect2>
226    
227   <sect2>
228     <heading>RPM package</heading>
229    <p>
230     Install vlc just as you would install any rpm package : 
231     <verb>
232      rpm -i vlc-x.x.x.rpm
233     </verb>
234    </p>
235    <p>
236     You may have to install external libraries to meet dependencies, depending on
237     the package you downloaded (gnome, gtk, esd, ...).
238    </p>
239   </sect2>
240
241   <sect2>
242    <heading>BeOS users</heading>
243    <p>
244     Double-click on the archive. It should open your favorite archive extracter.
245     You can then execute the vlc from there, or extract the archive to a 
246     directory and run it from there.
247    </p>
248   </sect2>
249   
250   <sect2>
251    <heading>MacOS X users</heading>
252    <p>
253     To be completed
254    </p>
255   </sect2> 
256   <sect2>
257    <heading>Windows users</heading>
258    <p>
259     Launch the installer by double-clicking on it, and follow the installation
260     instructions. Please note that in most cases you will need administrator
261     rights to install it under Windows NT, 2000 and XP
262    </p>
263   </sect2>
264  </sect1>
265  
266  <sect1>
267   <heading>Get libdvdcss</heading>
268   <p>
269    In order to read CSSsrambled DVDs, you will need libdvdcss. 
270    You can find binary
271    packages for your distribution here : <htmlurl 
272    name="http://www.videolan.org/libdvdcss/download.html" 
273    url="http://www.videolan.org/libdvdcss/download.html">
274   </p>
275   <p>
276    For Windows users, libdvdcss is statically linked in the 
277    Windows binary, so you don't have to install it.
278   </p>
279  </sect1>
280  
281  <sect1>
282   <heading>Use the vlc for DVD reading</heading>
283   <p>
284   Launch the application simply by typing vlc in a terminal (or by 
285   double-clicking on its icon in a graphical shell). You should see
286   the graphical interface appear.
287   </p>
288
289   <p> 
290   For reading a DVD (or a VCD), click on the "Disc" button. The new window 
291   you must then enter the path to your DVD or VCD drive :
292
293    <sect2>
294     <heading>Linux users</heading>
295     <p>
296      Usually, you dvd device is /dev/hd? (if you have an ide drive).
297      For instance, if you DVD player is master on the second IDE device,
298      it will be /dev/hdc.
299     </p>
300     <p>
301      It is very useful to create a symlink to this file, called /dev/dvd. 
302      To do this, as root, type (if your dvd device is /dev/hdc for example) :
303      <verb>
304       ln -s /dev/hdc /dev/dvd
305      </verb>
306      Also make sure you have read AND write permission to the device 
307      (otherwise dvd decryption won't work).
308     </p>
309    </sect2>
310    <sect2>
311     <heading>Windows users</heading>
312     <p>
313      The path to your DVD drive usually is D:\ or E:\. You may have a look
314      in "My Computer" and look to which letter your DVD drive is assigned.
315     </p>
316    </sect2>
317    <sect2>
318     <heading>BeOS users</heading>
319     <p>
320       Under BeOS, the dvd device looks like 
321       "/dev/disk/ide/atapi/1/slave/0/raw" for example, if your dvd device is 
322       slave on your first (not sure) ide device.
323     </p>
324    </sect2>
325    <sect2>
326     <heading>Other OS</heading>
327     <p>
328     To do ...
329     </p>
330    </sect2>
331   <sect1>
332    <heading>Use the vlc for network streaming</heading>
333    <p>
334     This is the vlc original usage. 
335    </p>
336    
337    <p>
338     Launch the vlc as you would have for DVD reading. Then click on the 
339     "Network" button. 
340     </p>
341     <sect2>
342      <heading>If using a VideoLAN Channel Server</heading>
343      <p>
344       The only thing you have to do is to check the "Channel server" box
345       and to enter the IP address and port 
346       of this channel
347       server. Ask your administrator if you don't have it. Then click on OK.
348      </p>
349      <p>
350       You will see a new "Channel" field in the interface. You may now
351       enter the selected channel and click on OK. After a few seconds,
352       if a program is being sent in this channel, you should see the program
353       start.
354      </p>
355      <p>
356       If nothing appears and you are sure that a program is streamed in
357       this channel, you may try once again, because a problem of communication
358       with the channel server could have occured (in you launched vlc from
359       a terminal, you should see "Network error: no answer from vlcs").
360      </p>
361     </sect2>
362     <sect2>
363      <heading>Without VideoLAN Channel Server</heading>
364      <p>
365       Simply choose clicking on the network button, then on ok should be 
366       sufficient in most cases.
367      </p>
368      <p>
369       After clicking on OK, and if a program is being sent, you should see
370       a window open with your program.
371      </p>
372     </sect2>
373 </sect>    
374     
375 <sect>
376  <heading>The graphical interface</heading>
377  <p>
378   Please note that the gnome, gtk and win32 interfaces are currently the most
379   advanced. The following descriptions refer to them.
380  </p>
381  <sect1>
382   <heading>Opening a stream</heading>
383   <p>
384    For opening streams through the graphical interface, click on either
385    "File" for opening a file stored on your hard drive, "Disc" for 
386    opening a DVD or a VCD, "Network" for reading a stream from a vls 
387    or through http input, or "Satellite" for reading directly 
388    from a satellite card.
389   </p>
390  <sect1>
391   <heading>Basic stream control</heading>
392   <p>
393    You have at your disposal all the classical control of a video player.
394    For example when playing local streams, you can do pauses, speed up or
395    slow down the stream ... Just use the corresponding buttons.
396   </p>
397  <sect1>
398   <heading>DVD and VCD navigation</heading>
399   <p>
400    When reading a DVD or a VCD, you can change chapter and title either 
401    by using the 
402    right-click menu or by using the dedicated bar that appears when reading
403    from a disc.
404   </p>
405  </sect1>
406  
407  <sect1>
408   <heading>Programs, audio and subtitles</heading>
409   <p>
410    When reading a multiprogram stream, you can change the current program
411    by selecting it in the "View/Programs" submenu, or using the "right click"
412    menu from the video output window.
413   </p>
414   <p>
415    In DVDs, if different angles are availables, they will be treated as
416    different programs.
417   </p>
418   <p>
419    At any time you can change the audio/subtitles channel using either the 
420    "setting" menu from the interface or using the "right click" menu from
421    the video output window.
422   </p>
423  <sect1>
424   <heading>Preferences window</heading>
425   <p>
426    By choosing "Preferences" in the "Settings" menu, you will open 
427    the preferences window. This window is generated dynamically according
428    to the modules that were compiled.
429   </p>
430   <p>
431    In every tab, you may click on "Save" to store your settings in your
432    ~/.videolan/vlcrc file.
433   </p>
434   <sect2>
435    <heading>Interface tab</heading>
436    <p>
437     In that tab, you can select which interface you would like to use on next
438     start. Click on the choosen interface, click on "Select" then on "Save".
439    </p>
440   </sect2>
441   <sect2>
442    <heading>Audio tab</heading>
443    <p>
444     In this tab, you can select the audio output you would like to use on 
445     next start. You may also specify some other settings such as the output
446     level, the audio frequency, ...
447    </p>
448   </sect2>
449   <sect2>
450    <heading>Video tab</heading>
451    <p>
452     In this tab, you can select which video output will be used on next start,
453     and add a video filter module. You may also specify some video settings,
454     such as the window size or if you would like fullscreen display.
455    </p>
456   </sect2>
457   <sect2>
458    <heading>Input tab</heading>
459    <p>
460     In this tab, you can enter the input method with options (for example
461     <tt>udp:@239.255.255.42</tt>) that will be used on next start. You can 
462     also add some settings, such as the channel server address ...
463    </p>
464   </sect2>
465   <sect2>
466    <heading>Decoders tab</heading>
467    <p>
468     In this tab, you can select which decoder you want to use for MPEG audio
469     and AC3 streams.
470    </p>
471   </sect2>
472   <sect2>
473    <heading>CPU tab</heading>
474    <p>
475     In this tab, you may disable the use of some CPU extensions such as 
476     MMX or SSE.
477    </p>
478   </sect2>
479   <sect2>
480    <heading>Playlist tab</heading>
481    <p>
482     In this tab, you can select some playlist options, such as looping the
483     playlist.
484    </p>
485   </sect2>
486   <sect2>
487    <heading>Miscellanous tab</heading>
488    <p>
489     In this tab, you can select which memcpy version you want to use. Some 
490     of them uses MMX 3Dnow! extensions.
491    </p>
492   </sect2>  
493  </sect1>
494 </sect>
495 <sect>
496  <heading>Command line options</heading>
497  <p>
498  Many options are only available through command line. They are detailled here.
499  </p>
500  <sect1>
501   <heading>Opening streams</heading>
502   <p> 
503   The following commands start vlc and add a first element to the playlist.
504   </p>
505   <sect2>
506    <heading>Opening a file</heading>
507    <p>
508     Simply start vlc with <tt>vlc my_file.mpg</tt>. 
509    </p>
510    <p>
511     You may tell vlc what input to use, for example add <tt>--input ts</tt>
512     when playing a ts MPEG, although vlc should be able to recognize the type
513     of MPEG.
514    </p>
515   </sect2>
516   <sect2>
517    <heading>Opening a DVD or VCD</heading>
518    <p>
519     Simply start vlc with <tt>vlc dvd:DVDDRIVE</tt> or <tt> vlc vcd:CDROMDRIVE
520     </tt>, where DVDDRIVE/CDROMDRIVE is the complete
521     path to your dvd/cdrom drive.
522    </p>
523    <p>
524     You may add <tt>-t X -T Y</tt> to start directly from the Xth chapter, Yth
525     title.
526    </p>
527   </sect2>
528   <sect2>
529   <heading>Start a network stream</heading>
530    <p>
531     To receive an UDP stream (being sent from a VLS), start vlc with 
532     <tt> vlc udpstream:[@&lt;bind address&gt;[:&lt;server port&gt;]] </tt>.
533    </p>
534    <p>
535     Please note that bind address refers to the destination address, for 
536     example your broadcast address. If the stream is being broadcasted, 
537     <verb> vlc udpstream:</verb> should be sufficient. If the stream
538     is multicasted, you must specify the multicast address, for example 
539     <verb> vlc udpstream:@239.255.255.42  </verb>
540    <p>
541     To receive a http stream, start vlc with <tt>vlc &lt;your URL&gt;</tt>.
542
543    
544    </p>
545   </sect2>
546  </sect1>
547  
548  <sect1>
549   <heading>Modules selection</heading>
550   <p>
551    The vlc tries to select the most appropriate interface, input and output
552    modules, among the ones available on the system, according to
553    the stream he is given to read. However, you may wish to force
554    the use of a specific module with the following options:
555    
556    <p> <verb>--intf &lt;interface module&gt;</verb>
557    allows you to select the interface module </p>
558
559    <p> <verb>--input &lt;input module&gt;</verb>
560    allows you to select the input module.</p>
561
562    <p> <verb>--vout &lt;video output module&gt;</verb>
563    allows you to select the video output.</p>
564
565    <p> <verb>--aout &lt;audio output module&gt;</verb>
566    allows you to select the audio output.</p>
567
568    <p> <verb>--filter &lt;video filter module&gt;</verb>
569    allows you to add a video filter module.</p>
570
571    <p> <verb>--mpeg_adec &lt;MPEG audio decoder module&gt;</verb>
572    allows you to select the audio MPEG decoder.</p>
573
574    <p> <verb>--ac3_adec &lt;AC3 audio decoder module&gt;</verb>
575    allows you to select the audio AC3 decoder.</p>
576   
577  </sect1>
578  <sect1>
579   <heading>Other options</heading>
580   <sect2>
581    <heading>Help options:</heading>
582    
583    <p> <verb>--help</verb>
584    gives you all the available options.</p>  
585    <p> <verb>--longhelp</verb>
586    gives you a more detailled version of the available options.</p>  
587    <p> <verb>--version</verb>
588    gives you information about the current version.</p>  
589    <p> <verb>--list</verb>
590    gives you the list of all available plugins.</p>
591    <p> <verb>--warning X or -vvvv (X times)</verb>
592    set the level of warning messages.</p>
593    <p> <verb>--stat</verb>
594    gives statistic outputs.</p>
595   </sect2>
596   
597   <sect2>
598    <heading>Audio options:</heading>
599    
600
601    <p> <verb>--noaudio</verb>
602    disables the audio output</p>
603    <p> <verb>--mono</verb>
604    forces the vlc to treat the stream in mono audio.</p>
605    <p> <verb>--volume &lt;integer&gt;</verb>
606    set the level of audio output.</p>
607    <p> <verb>--rate &lt;integer&gt;</verb>
608    set the audio output frequency (Hz)</p>
609    <p> <verb>--desync &lt;integer&gt;</verb>
610    compensates desynchronization of audio (ms)</p>
611   </sect2>
612
613   <sect2>
614    <heading>Video options:</heading>
615    
616    <p> <verb>--novideo</verb>
617    disables the video output</p>
618    <p> <verb>--width &lt;integer&gt;</verb>
619        <verb>--height &lt;integer&gt;</verb>
620    set the video window dimensions.</p>
621    <p> <verb>--grayscale</verb>
622    turns video output into grayscale mode.</p>
623    <p> <verb>--fullscreen</verb>
624    set fullscreen video.</p>
625    <p> <verb>--nooverlay</verb>
626    disables hardware acceleration for the video output</p>
627    <p> <verb>--spumargin &lt;integer&gt;</verb>
628    force subtitles position.</p>
629
630   </sect2>
631   <sect2>
632    <heading>Input options:</heading>
633
634
635    <p> <verb>--network-channel</verb>
636    Start with channel server enabled.</p>
637    <p> <verb>--channel_server &lt;string&gt;</verb>
638    Specify the channel server address.</p>
639    <p> <verb>--channel_port &lt;integer&gt;</verb>
640    Specify the channel server port.</p>
641    <p> <verb>--iface &lt;string&gt;</verb>
642    Select the network interface to use.</p>
643    <p> <verb>--input_program &lt;integer&gt;</verb>
644    Select the program to use (for streams with 
645    several programs, as those coming from satellite).</p>
646    <p> <verb>--input_audio &lt;integer&gt;</verb>
647    Select the audio channel to use.</p>
648    <p> <verb>--input_subtitle &lt;integer&gt;</verb>
649    Select the subtitle.</p>
650    <p> <verb>--input_channel &lt;integer&gt;</verb>
651    Select the channel number.</p>
652    <p> <verb>--dvd_device &lt;string&gt;</verb>
653    Specify the default dvd device.</p>
654    <p> <verb>--vcd_device &lt;string&gt;</verb>
655    Specify the default vcd device.</p>
656    <p> <verb>--ipv4</verb>
657    Force IPv4.</p>
658    <p> <verb>--ipv6</verb>
659    Force IPv6.</p>
660   </sect2>
661   
662   <sect2>
663    <heading>CPU options</heading>
664    <p> <verb>--nommx</verb>
665    disable the use of mmx CPU extensions.</p>
666    <p> <verb>--no3dn</verb>
667    disable the use of 3D Now! CPU extensions.</p>
668    <p> <verb>--nommxext</verb>
669    disable the use of mmx ext CPU extensions.</p>
670    <p> <verb>--noaltivec</verb>
671    disable the use of AltiVec CPU extensions.</p>
672   </sect2>
673  </sect1>
674  
675
676
677    
678
679  
680
681 <sect>
682  <heading>Building the vlc from sources</heading>
683  <p>
684   You can choose either to take the latest release, or a CVS source. Note that
685   CVS snapshots may be broken, although we do our best to prevent this from
686   happening.
687  </p>
688  <p>
689   From here, you have to be a little experienced, even more if you want to use
690   the cvs.
691  </p>
692  <sect1>
693   <heading>Getting an archive</heading>
694   <p>
695    You have guessed it, the first thing to do is to get the source.
696    Until there, everyone should understand :)
697   </p>
698   <sect2>
699    <heading>Web site</heading>
700    <p>
701     Source packages can be found in the "tarballs" section of the download page :
702     <htmlurl url="http://www.videolan.org/download.html" name="http://www.videolan.org/dowload.html">.
703    </p>
704    <p>
705     CVS snapshots are available from the address : 
706     <htmlurl url="http://www.videolan.org/packages/snapshots/" 
707     name="http://www.videolan.org/packages/snapshots/">.
708    </p>
709    <p>
710     Then untar the archive :
711     <verb>
712      tar xzf vlc-x-x-x.tar.gz
713     </verb>
714    </p>
715   </sect2>
716   <sect2>
717    <heading>Directly from CVS</heading>
718    <p> <label id="cvs">
719     Firs log in as suer anonymous with an empty password :
720     <verb>
721      cvs -d :pserver:anonymous@anoncvs.videolan.org:/var/cvs/videolan login
722     </verb>
723    Then retrieve the repository :
724    <verb>
725     cvs -d :pserver:anonymous@anoncvs.videolan.org:/var/cvs/videolan -z3 checkout vlc
726    </verb>
727    </p>
728   </sect2>
729   <sect2>
730    <heading>libdvdcss</heading>
731    <p>
732    To compile vlc with dvd support, you need to get and install libdvdcss.
733    </p>
734    <p>
735    It is available for download here : 
736    <htmlurl url="http://www.videolan.org/libdvdcss/download.html"
737    name="http://www.videolan.org/libdvdcss/download.html">
738
739    Decompress the tarball in a directory of your choice and build it :
740    <verb>
741     tar -xvzf libdvdcss-x.x.x.tar.gz
742     cd libdvdcss-x.x.x
743     ./configure
744     make
745     [as root] make install
746    </verb>
747
748    You can also find binaries packages for many distributions.
749  </sect1>
750  
751  <sect1>
752   <heading>Building the program</heading>
753   <p><label id="compile">
754    Go into the vlc directory and run the configure script :
755    <verb>
756     ./configure
757    </verb>
758     If you want to enable options, you may add "--enable-option" 
759     to the previous line.
760     For example, to build with the xvideo extension, and alsa support, 
761     you should type :
762     <verb>
763     ./configure --enable-xvideo --enable-alsa
764     </verb>
765    To get the list of the available options, and know if they are 
766    enabled by default,
767    you can try :
768    <verb>
769     ./configure --help
770    </verb>
771   </p>
772   <p>
773    Also have a look on the <ref id="modules" name="following modules 
774    descriptions">.
775   </p>
776   <p>
777    A very typical installation, on a XFree 4.1 system, recent video card, with 
778    gnome, is :
779    <verb>
780     ./configure --enable-esd --enable-gnome
781    </verb>
782   <p>
783  </sect1>
784  <sect1>
785   <heading>Plugins, builtins ...</heading>
786   <p>
787    The configure script should create a Makefile.opts file, which you can edit and modify.
788    Indeed you can chose to have features (as esd support, for example) built as plugins
789    or inside the program.
790   </p>
791   <p>
792    If you build a feature as a plugin, it can lead to a little loss of performance.
793    It you build it inside the code, it'll enlarge a bit the size of the executable.
794   </p>
795   <p>
796    When you're done with Makefile.opts (which also works if you leave it 
797    untouched), just 
798    type:
799     <verb>
800     make
801     </verb>
802    It should compile without any error. If there are, please check you 
803    have the required libraries 
804    installed on your system, as the configure script can't check them all.
805   </p>
806   <p>
807    When you're done with it, as root, type :
808    <verb>
809     make install
810    </verb>
811   if you wish to have vlc fully installed on your system. If you prefer 
812   to keep in in the 
813   current directory, you may skip the "make install". You'll then have 
814   to cd into the vlc 
815   directory and type "./vlc" instead of just typing vlc.
816   </p>
817  </sect1>
818 </sect>
819
820 <sect>
821  <heading>Modules description</heading>
822  <p> 
823   <label id="modules">
824   Here is a description of nearly all the available modules for the 
825   vlc. If you wish to compile one which is stated disabled by default,
826   you have to launch the configure script with 
827   <verb> ./configure --enable-module_name </verb>. See <ref 
828   name="compilation instructions" id="compile">.
829  <sect1>
830   <heading>Video outputs</heading>
831   <sect2>
832    <heading>x11</heading>
833    <p>default :enabled </p>
834    <p>
835     This is the basic x11 video output. It only requires a 
836     working X11 server. You will need xlibs headers to compile it
837     (xlibs-dev package on Debian systems).
838    </p>
839   </sect2>
840   
841   <sect2>
842    <heading>xvideo</heading>
843    <p>default : enabled</p>    
844    <p>
845     It requires an xvideo compliant graphic card (it is the case for 
846     nearly all the modern card). It uses hardware acceleration for 
847     yuv transformation and for rescaling.
848    </p>
849   </sect2>
850   
851   <sect2>
852    <heading>sdl</heading>
853    <p>default : enabled</p>
854    <p>
855     This video output uses sdl libraries. You need at least version 1.1.6 of
856     this libraries.
857    </p>
858    <p> 
859     You may indicate the path to the sdl-config program with the
860     <verb> --with-sdl-config-path=PATH </verb> option given to the <verb>
861     configure</verb> script.
862    </p>
863   </sect2>
864   
865   <sect2>
866    <heading>directx</heading>
867    <p>default: enabled on win32</p>
868    <p>
869     This video output uses Microsoft Direct X libraries. It is recommended 
870     for the win32 port.
871    </p>
872    <p>
873     You may indicate the path to directx libraries and headers with
874     the <verb>--with-directx=PATH</verb> option.
875   </sect2>
876   
877   <sect2>
878    <heading>fb</heading>
879    <p>default: enabled on Linux</p>
880    <p>
881     This is the frame buffer video output. It requires that your kernel 
882     was compiled with frame buffer support.
883    </p>
884   </sect2>
885   
886   <sect2>
887    <heading>glide</heading>
888    <p>default: disabled</p>
889    <p>
890    This video output uses Glide libraries (hardware acceleration for
891    3Dfx cards).
892    </p>
893    <p> 
894     You may indicate the path to the library with the 
895    <verb>--with-glide=PATH</verb> compilation option.
896    </p>
897   </sect2>
898   
899   <sect2>
900    <heading>mga</heading>
901    <p>default: disabled</p>
902    <p> 
903    It provides hardware acceleration for Matrox cards on Linux.
904    </p>
905   </sect2>
906
907   <sect2>
908    <heading>ggi</heading>
909    <p>default: disabled</p>
910   </sect2>
911   
912   <sect2>
913    <heading>aa</heading>
914    <p>default: disabled</p>
915    <p>
916     This video output uses the aalib library to display video
917     through ASCII art. It requires aalib headers (aalib1-dev under Debian)
918     to compile.
919    </p>
920   </sect2>
921  </sect1>
922  <sect1>
923   <heading>Video filters modules</heading>
924   <sect2>
925    <heading>deinterlace</heading>
926    <p>default: enabled</p>
927    <p>
928     This filter deinterlaces video. It is usefull with streams coming 
929     from a satellite broadcast.
930    </p>
931   </sect2>
932   
933   <sect2>
934    <heading>wall</heading>
935    <p>default: enabled</p>
936    <p>
937     This filter allows you to have the video cut in pieces in several 
938     windows, which you can order as you wish. It can be used to generate
939     image walls with several sources. Start it with 
940    <verb> --filter wall:XxY</verb> in order to have the video cut in X rows
941    and Y columns
942    </p>
943   </sect2>
944   <sect2>
945    <heading>distort</heading>
946    <p>default: enable</p>
947    <p>
948     This filter adds a distortion effect to the video. Who said it
949     was useless ;-) ?
950    </p>
951   </sect2>
952   
953   <sect2>
954    <heading>transform</heading>
955    <p>default: enable</p>
956    <p>
957     This filter rotates the video window of 90 degrees.
958    </p>
959   </sect2>
960   
961   <sect2>
962    <heading>invert</heading>
963    <p>default: enabled</p>
964    <p>
965     This filter inverses colors.
966    </p>
967   </sect2>
968  </sect1>
969  <sect1>
970   <heading>Sound outputs</heading>
971   <sect2>
972    <heading>dsp</heading>
973    <p>default: enabled on Linux</p>
974    <p>
975     This is the Linux /dev/dsp output. It requires that your kernel 
976     was compiled with support for your sound card.
977    </p>
978    </sect2>
979    
980    <sect2>
981     <heading>alsa</heading>
982     <p>default: disabled</p>
983     <p>
984      This is the sound output for Advanced Linux Sound Architecture. 
985      It requires that you installed the alsa drivers and libraries.
986     </p>
987    </sect2>
988    
989    <sect2>
990     <heading>esd</heading>
991     <p>default: disabled</p>
992     <p>
993      This sound output has Enlightened Sound Daemon support
994      (usually used with Gnome). 
995      You must have the daemon and its libraries installed.
996     </p>
997    </sect2>
998    <sect2>
999     <heading>arts</heading>
1000     <p>default: disabled</p>
1001     <p>
1002      This sound output has aRts (KDE's sound server) support.
1003      You must have the daemon and its libraries installed.
1004     </p>
1005    </sect2>
1006    
1007    <sect2>
1008     <heading>waveout</heading>
1009     <p>default: enabled on win32</p>
1010     <p>
1011      This is the Wave output, which is used by the win32 port.
1012     </p>
1013    </sect2>
1014  </sect1>
1015  
1016  <sect1>
1017   <heading>Input modules</heading>
1018   <sect2>
1019    <heading>dvd</heading>
1020    <p>default: enabled</p>
1021    <p>
1022     This is the DVD input module. It will need libdvdcss, which can
1023     be found <htmlurl url="http://www.videolan.org/libdvdcss/" 
1024     name="http://www.videolan.org/libdvdcss/">.
1025    </p>
1026   </sect2>
1027   
1028   <sect2>
1029    <heading>dvdread</heading>
1030    <p>default: disabled</p>
1031    <p>
1032     This is an alternative to the previous one, it uses libdvdread 
1033     (which also needs libdvdcss).
1034    </p>
1035   </sect2>
1036   <sect2>
1037    <heading>vcd</heading>
1038    <p>default: enabled</p>
1039    <p>
1040     This is the VideoCD input. 
1041    </p>
1042   </sect2>
1043   <sect2>
1044    <heading>http</heading>
1045    <p>default: enabled</p>
1046    <p>
1047     This is the http input. You can use it for Video On Demand.
1048    </p>
1049   </sect2>
1050   <sect2>
1051    <heading>satellite</heading>
1052    <p>default: disabled</p>
1053    <p>
1054     This is an input module that allows to read directly from a
1055     Hauppauge WinTV Nova card under Linux. It requires drivers 0.9.4 
1056     available from 
1057    <htmlurl url="http://www.linuxtv.org/" name="linuxtv.org">.
1058    </p>
1059   </sect2>
1060  </sect1>
1061  
1062  <sect1>
1063   <heading>Interface modules</heading>
1064   <sect2>
1065    <heading>gtk</heading>
1066    <p>default: enabled</p>
1067    <p>
1068     This is the GTK+ interface. It needs gtk libraries (libgtk1.2 package
1069     on Debian) and headers files if you are compiling it (libgtk1.2-dev 
1070     package on Debian). Note that it can be used under Windows.
1071    </p>
1072   </sect2>
1073   <sect2>
1074    <heading>gnome</heading>
1075    <p>default: disabled</p>
1076    <p>
1077     This is the Gnome interface. It needs gnome libraries (libgnome32 under
1078     Debian) and headers (libgnome-dev) if you wish to compile it.
1079    </p>
1080   </sect2>
1081   <sect2>
1082    <heading>intfwin</heading>
1083    <p>default: enabled on win32</p>
1084    <p>
1085     This is the Windows native interface. It requires Borland C++ builder 
1086     to compile. You may use <verb>--with-bc-builder=PATH</verb> option
1087     to specify the path to this application.
1088    </p>
1089   </sect2>
1090
1091   <sect2>
1092    <heading>qt</heading>
1093    <p>default: disabled</p>
1094    <p>
1095     This is the QT libraries interface module. You will need the libraries
1096     (libqt2 package on Debian) and headers (libqt-dev) if you wish to 
1097     compile it.
1098    </p>
1099   </sect2>
1100   <sect2>
1101    <heading>kde</heading>
1102    <p>default: disabled</p>
1103    <p>
1104     This is the KDE interface module.  You will need the libraries
1105     (kdelib package on Debian) and headers (kde-devel) if you wish to 
1106     compile it.
1107    </p>
1108   </sect2>
1109
1110   <sect2>
1111    <heading>rc</heading>
1112    <p>default: enable</p>
1113    <p>
1114     This is the Remote Control interface module. With this one, vlc
1115     is controled by sending him commands, such as play, stop, ... so 
1116     that you may control vlc through a script.
1117    </p>
1118   </sect2>
1119
1120   <sect2>
1121    <heading>ncurses</heading>
1122    <p>default: disabled</p>
1123    <p>
1124     This is a text interface, using ncurses library. You will need
1125     ncurses headers if you want to compile it (libncurses5-dev on Debian).
1126    </p>
1127   </sect2>
1128   <sect2>
1129    <heading>lirc</heading>
1130    <p>default: disabled</p>
1131    <p>
1132     This interface module allows you to control vlc through a remote.
1133     A lircrc example is provided to help you configure it to your remote
1134     (see doc/lirc/example.lircrc).
1135    </p>
1136   </sect2>
1137  </sect1>
1138  <sect1>
1139   <heading>OS support modules</heading>
1140   <p> The following modules add support or different OSs. </p>
1141   <sect2>
1142    <heading>macosx</heading>
1143    <p>default: enabled on MacOS X</p>
1144    <p>
1145     This is the MacOS X support module, including a native interface.
1146    </p>
1147   </sect2>
1148   
1149   <sect2>
1150    <heading>qnx</heading>
1151    <p>default: enabled on qnx</p>
1152    <p>
1153     This is the QNX RTOS support module.
1154    </p>
1155   </sect2>
1156  </sect1>    
1157
1158 <sect>
1159  <heading>Specific use of the vlc</heading>
1160  <sect1>
1161   <heading>Use the vlc as a viever and decoder for the Hauppauge WinTV 
1162   Nova card</heading>
1163   <sect2>
1164    <heading>What is required ?</heading>
1165    <p>
1166     At the present time, the satellite input only works under Linux. 
1167     It requires that drivers version 0.9.4 of the card, drivers
1168     that are being developped by the <htmlurl name="linuxtv.org"
1169     url="http://www.linuxtv.org/">. 
1170    </p>
1171   </sect2>
1172   <sect2>
1173    <heading>Building the vlc with satellite support</heading>
1174    <p>
1175     Get the sources, either from our last .tar.gz release, 
1176     or best from the cvs (see <ref name="cvs instructions"
1177     id="cvs">).
1178    </p>
1179    <p>
1180     Move to the vlc directory, then launch
1181     <verb>
1182      ./configure --enable-satellite
1183     </verb>
1184     You may add other compilation options, see <ref 
1185     name="compilation instructions" id="compile">.
1186     Then launch the compilation with
1187     <verb>
1188      make
1189     </verb>
1190     You may install it with (as root)
1191     <verb>
1192      make install
1193     </verb>
1194     or run it from the current directory.
1195    </p>
1196   </sect2>
1197   <sect2>
1198    <heading>Running it from the command line</heading>
1199    <p>
1200    Run the vlc with 
1201     <verb>
1202      vlc satellite:&lt;frequency(Hz)&gt;,&lt;polarization(0 for V,
1203      1 for H)&lt;,
1204      &gt;FEC (1 for 1/2, 2 for 2/3 ...)&gt;,&lt;symbol rate (kbytes/sec)&gt;
1205     </verb>
1206     You then have to select your program, either with the command line option
1207     <verb>
1208      --input_program <program_number (also called service ID)>
1209     </verb>
1210     or by choosing it in the view/programs menu.
1211    </sect2>
1212    <sect2>
1213     <heading>Running it from the GTK/Gnome interface</heading>
1214     <p>
1215      Click on the "Sat" icon. In the opening box, you may enter 
1216      your transponder settings, then click on "Ok". 
1217     </p>
1218     <p>
1219      After a few seconds, the word satellite should appear under the command
1220      buttons. You may now choose your program from the View/Programs menu.
1221     </p>
1222    </sect2>
1223   </sect1>
1224   <sect1>
1225    <heading>Use the vlc to create image walls.</heading>
1226    <p>
1227     The idea is to use several video sources, each one displaying a part 
1228     of the whole image, to get a bigger result.
1229    </p>
1230    <p> 
1231     Vlc and the VideoLAN solution can provide a good way to create
1232     such displays : a vls broadcasts a stream in several vlc each
1233     display a part of image.
1234    </p>
1235    <p>
1236     For this, you should use the wall filter : start vlc with 
1237     <verb>
1238      vlc udp: --filter wall:&lt;number of rows&gt;x&lt;number of columns&gt;
1239      :&lt;number of the part to diplay&gt;
1240     </verb>
1241    </p>
1242   </sect1>
1243
1244 </sect>
1245 <sect>
1246   <heading>Get more help</heading>
1247   <p>
1248    First of all, it something seems to go wrong, read and try to 
1249    understand the error messages. You can have detailed messages by
1250    choosing messages in the view menu, in GTK, Gnome and Win32 interfaces.
1251   </p>
1252   <p>
1253    There is a FAQ page on our website :
1254    <htmlurl url="http://www.videolan.org/doc/index.html" name="http://www.videolan.org/doc/index.html">.
1255    If you think one question should be in the FAQ, please contact
1256    <htmlurl url="mailto:videolan@videolan.org" name="videolan@videolan.org">
1257   </p>
1258   <p>
1259    Finally, there's a users mailing list (English speaking). To subscribe, send a mail to 
1260    <htmlurl url="mailto:listar@videlan.org" name="listar@videlan.org"> containing
1261    "subscribe vlc" as message body.
1262   </p>
1263 </sect>
1264 </article></linuxdoc>