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