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