* ./modules/video_filter/adjust.c: properly fixed margin handling (partially
[vlc.git] / doc / vlc-howto.sgml
index fcf4425..7746ead 100644 (file)
@@ -2,11 +2,11 @@
 <linuxdoc><article>
 <titlepag>
  <title>VLC HOWTO</title>
- <author>by the Videolan Team<tt><htmlurl url="mailto:videolan@videlan.org" name="videolan@videlan.org"></tt></author>
+ <author>Originally written by Henri Fallon, maintained by Johan Bilien<tt><htmlurl url="mailto:jobi@videolan.org" name="<jobi@videolan.org>"></tt></author>
  <date>v0.0.9, 16 april 2002</date>
 
  <abstract>
-  This document describes how to use the vlc (VideoLAN client) to read DVDs and mpeg files and DVDs.
+  This document describes how to use the vlc (VideoLAN client) to read DVDs and mpeg files, locally or from a network.
  </abstract>
 </titlepag>
 
   <heading>What is VideoLAN ?</heading>
   <p>
    VideoLAN is a project of sudents of the École Centrale Paris which aims 
-   to broadcast video on the campus, and provide the students with a MPEG
+   at broadcasting video on the campus, and providing the students with an MPEG-
    software-only decoder. VideoLAN is an OpenSource project which will thus 
    allow anyone to watch DVD movies under Linux, BeOS, MacOS X, Windows 
-   and most Unix 
-   systems
+   and most UNIX systems. Recent additions allow to read .avi files,
+   and MPEG-4/DivX-encoded movies.
   </p>
   <p>
     You may want to look at the port section on our website : 
  </sect1>
  
  <sect1>
-  <heading>What is the vlc</heading>
+  <heading>What is the VideoLAN project ?</heading>
   <p>
-   Vlc stands for VideoLAN client. It is the name of the program which is
-   capable of decoding MPEG streams, and displaying them onto your screen,
-   so you can watch you favourite movies, confortably sit in your armchair
-   :-).
+
+   VideoLAN is a complete software solution for video streaming, developed
+   by students at the <htmlurl url="http://www.ecp.fr" name="Ecole Centrale
+   Paris"> and contributors from all over the world, under the <htmlurl
+   url="http://www.gnu.org/copyleft/gpl.html" name="General Public License
+   (GPL)">. It has been designed for streaming MPEG 1 and MPEG 2 videos on
+   local area networks (LAN), but it can be extended to metropolitan or
+   wide area networks (MAN, WAN), thanks to the multicast technology.
+
+   The VideoLAN solution includes a server, which can stream video from
+   various sources (file, DVD, satellite and MPEG 2 encoder), a client, which can
+   receive, decode and display MPEG 1 and MPEG 2 streams and, if necessary,
+   a channel server which tells automatically to the client the parameters
+   needed to receive the stream.
+
+   Here is an illustration of the complete VideoLAN solution :
+
+   <verb>
+
+        DVD --->-                 Unicast/Broadcast/Multicast
+                  \                           ---
+        File --->--     --------            /     \            --------
+                   |->-| Server |=====>====|  LAN  |---->-----| Client |
+     Satellite ->--    | (VLS)  |           \     /           | (VLC)  |
+                  /     --------              ---              --------
+       MPEG2 -->-                              ^
+      encoder                                  |
+                                               v
+                                        ----------------
+                                       | Channel Server |
+                                       |    (VLCS)      |
+                                        ----------------
+   </verb>
+
+   More details about the project can be found on the
+   <htmlurl url="http://www.videolan.org" name="VideoLAN Web site">.
+
   </p>
  </sect1>
+ <sect1>
+  <heading>The documentation of the project</heading>
+  <p>
+    There are four main documents :
+<itemize>
+<item>the <htmlurl
+url="http://www.videolan.org/doc/videolan-quickstart/videolan-quickstart.html"
+name="VideoLAN Quickstart">,
+<item>the <htmlurl url="http://www.videolan.org/network/doc/videolan-howto.html"
+name="VideoLAN HOWTO">,
+<item>the <htmlurl url="http://www.videolan.org/vls/doc/vls-guide.html"
+name="VideoLAN Server user guide">,
+<item>this VideoLAN Client Howto.
+</itemize>
+
+The up-to-date version of these documents can be found on the <htmlurl
+url="http://www.videolan.org/doc" name="VideoLAN Web Site">.
 
  <sect1>
   <heading>Translated versions of this document</heading>
   <p>
    The English version is maintained by Henri Fallon,
    Johan Bilien, and the VideoLAN team. It can be found at:
-   <htmlurl url="http://www.videolan.org/doc.html"
-   name="http://www.videolan.org/doc.html">.
+   <htmlurl url="http://www.videolan.org/doc/index.html"
+   name="http://www.videolan.org/doc/index.html">.
+  </p>
+ </sect1>
+
+ <sect1>
+  <heading>Requirements</heading>
+  <sect2>
+   <heading>Operating system</heading>
+   <p>
+    VLC works under the following systems :
+   </p>
+   <p>
+   <itemize>
+    <item> Linux (all distributions, including iPAQ Familiar Linux)
+    <item> Windows (all 32bit versions)
+    <item> Mac OS X
+    <item> FreeBSD, NetBSD, OpenBSD, BSD/OS
+    <item> BeOS
+    <item> QNX RTOS
+    <item> Solaris
+   </itemize>
+   </p>
+   <p>
+    Please note that the Linux, Windows and MacOS X versions are generally the most
+    up-to-date ones.
   </p>
+   </sect2>
+   <sect2>
+   <heading>Software requirements</heading>
+   <p>
+    Depending on the outputs and inputs you are using, you may need 
+    additional libraries. Please see <ref id="modules" name="description">.
+   </p>
+   <p>
+    For playing encrypted DVDs, you will need libdvdcss, which you can find
+    on this page :
+    <htmlurl name="http://www.videolan.org/libdvdcss/download.html"
+    url="http://www.videolan.org/libdvdcss/download.html">.
+   </p>
+  </sect2>
+  <sect2>
+   <heading>Hardware requirements</heading>
+   <p>
+    The hardware power needed depends a lot of the type of stream. 
+    For reading a DVD, a CPU working at around 450 MHz is required.
+   </p>
+   <p>
+    VLC can benefits from hardware acceleration from modern video cards
+    for YUV transformation and window rescaling. it also uses MMX, MMX EXT,
+    SSE, 3Dnow! optimizations if available.
+   </p>
+  </sect2>
  </sect1>
 
  <sect1> 
   <heading>Disclaimer</heading> 
   </p>
 
   <p>
-   In this HOWTO, we consider you already have a little knowledge about
-   Linux, and you know how to use a DVD. If not, good howtos can be
-   found on the Linux Documentation Projet.
+
+   In this HOWTO, we consider you already have a little knowledge
+   about Linux, and you know how to use a DVD. If not, good howtos
+   can be found on the <htmlurl url="http://www.tldp.org" name="Linux
+   Documentation Projet">.
+
   </p>
  </sect1>
 
  <sect1> 
   <heading>Legal</heading> 
   <p> 
-   Copyright (©) 2001 by the VideoLAN project. This document may be
-   distributed only subject to the terms and conditions set forth in
-   <htmlurl url="http://metalab.unc.edu/LDP/LDP-COPYRIGHT.html" 
-   name="the LDP license">.
+
+   Copyright (©) 2002 by the VideoLAN project.
+
+   Permission is granted to copy, distribute and/or modify this document
+   under the terms of the GNU Free Documentation License, Version
+   1.1 or any later version published by the Free Software Foundation ;
+   with no Invariant Sections, with no Front-Cover Texts, and with no
+   Back-Cover Texts. The text of the license can be found on <htmlurl
+   url="http://www.gnu.org/copyleft/fdl.html">.
+
   </p> 
  </sect1> 
 </sect>
    <heading>Which package to chose ?</heading>
    <p>
     There are different packages because vlc has "plugins" which provide 
-    features but also enlarge the executable and require external libs. 
+    features but also enlarge the executable and require external libraries. 
    </p>
    <p>
     SDL is a lib which allows you to have an accelerated video output.
    </p>
    <p>
     Depending on the package you have downloaded, you may have dependency
-    problems. You have to solve them, by installing the required libs.
+    problems. You have to solve them, by installing the required libraries.
    </p>
   </sect2>
    
   <sect2>
     <heading>RPM package</heading>
    <p>
-    Install vlc just as you would install any rpm package : 
+    Install vlc just as you would install any RPM package : 
     <verb>
      rpm -i vlc-x.x.x.rpm
     </verb>
    </p>
    <p>
-    You may have to install external libs to meet dependencies, depending on
+    You may have to install external libraries to meet dependencies, depending on
     the package you downloaded (gnome, gtk, esd, ...).
    </p>
   </sect2>
    <p>
     Double-click on the archive. It should open your favorite archive extracter.
     You can then execute the vlc from there, or extract the archive to a 
-    diretory and run it from there.
+    directory and run it from there.
    </p>
   </sect2>
   
   <sect2>
-   <heading>MacOS X users</heading>
+   <heading>Mac OS X users</heading>
    <p>
-    To be completed
+    Double-click on the archive, and copy the vlc file to your Applications
+    folder.
    </p>
   </sect2> 
   <sect2>
    <heading>Windows users</heading>
    <p>
-    Decompress the archive with your favourite extracter in a directory of your
-    choice.
+    Launch the installer by double-clicking on it, and follow the installation
+    instructions. Please note that in most cases you will need administrator
+    rights to install it under Windows NT, 2000 and XP.
    </p>
   </sect2>
  </sect1>
    In order to read CSSsrambled DVDs, you will need libdvdcss. 
    You can find binary
    packages for your distribution here : <htmlurl 
-   name="http://www.videolan.org/libdvdcss/download/index.html" 
-   url="http://www.videolan.org/libdvdcss/download/index.html">
+   name="http://www.videolan.org/libdvdcss/download.html" 
+   url="http://www.videolan.org/libdvdcss/download.html">
+  </p>
+  <p>
+   For Windows, BeOS and Mac OS X users, libdvdcss is statically linked in the 
+   Windows binary, so you don't have to install it.
   </p>
  </sect1>
  
    <sect2>
     <heading>Linux users</heading>
     <p>
-     Usually, you dvd device is /dev/hd? (if you have an ide drive).
+     Usually, your dvd device is /dev/hd? (if you have an ide drive).
      For instance, if you DVD player is master on the second IDE device,
      it will be /dev/hdc.
     </p>
    <sect2>
     <heading>Windows users</heading>
     <p>
-     The path to your DVD drive usually is D: or E:. You may have a look
+     The path to your DVD drive usually is D:\ or E:\. You may have a look
      in "My Computer" and look to which letter your DVD drive is assigned.
     </p>
    </sect2>
       start.
      </p>
      <p>
-      If nothing appears and you are sure that a program is broadcasted in
+      If nothing appears and you are sure that a program is streamed in
       this channel, you may try once again, because a problem of communication
-      with the channel server could have occured (in you launched vlc from
+      with the channel server could have occurred (if you launched vlc from
       a terminal, you should see "Network error: no answer from vlcs").
      </p>
     </sect2>
     <sect2>
      <heading>Without VideoLAN Channel Server</heading>
      <p>
-      Simply choose clicking on the network button, then on ok should be 
+      Simply clicking on the network button, then on ok should be 
       sufficient in most cases.
      </p>
      <p>
   </p>
   <p>
    In every tab, you may click on "Save" to store your settings in your
-   ~/.videolan/vlrrc file.
+   ~/.videolan/vlcrc file.
   </p>
   <sect2>
    <heading>Interface tab</heading>
 <sect>
  <heading>Command line options</heading>
  <p>
- Many options are only available through command line. They are detailled here.
+ Many options are only available through command line. They are detailed here.
  </p>
  <sect1>
   <heading>Opening streams</heading>
     <verb> vlc udpstream:</verb> should be sufficient. If the stream
     is multicasted, you must specify the multicast address, for example 
     <verb> vlc udpstream:@239.255.255.42  </verb>
+   <p>
+    To receive a http stream, start vlc with <tt>vlc &lt;your URL&gt;</tt>.
 
    
    </p>
    <p> <verb>--intf &lt;interface module&gt;</verb>
    allows you to select the interface module </p>
 
-   <p> <verb>--input &lt;input module&gt;</verb>
-   allows you to select the input module.</p>
-
    <p> <verb>--vout &lt;video output module&gt;</verb>
    allows you to select the video output.</p>
 
    <p> <verb>--filter &lt;video filter module&gt;</verb>
    allows you to add a video filter module.</p>
 
-   <p> <verb>--mpeg_adec &lt;MPEG audio decoder module&gt;</verb>
+   <p> <verb>--mpeg-adec &lt;MPEG audio decoder module&gt;</verb>
    allows you to select the audio MPEG decoder.</p>
 
-   <p> <verb>--ac3_adec &lt;AC3 audio decoder module&gt;</verb>
+   <p> <verb>--ac3-adec &lt;AC3 audio decoder module&gt;</verb>
    allows you to select the audio AC3 decoder.</p>
   
  </sect1>
    gives you information about the current version.</p>  
    <p> <verb>--list</verb>
    gives you the list of all available plugins.</p>
-   <p> <verb>--warning X or -vvvv (X times)</verb>
+   <p> <verb>-vvvv (X times)</verb>
    set the level of warning messages.</p>
-   <p> <verb>--stat</verb>
+   <p> <verb>--stats</verb>
    gives statistic outputs.</p>
   </sect2>
   
 
    <p> <verb>--network-channel</verb>
    Start with channel server enabled.</p>
-   <p> <verb>--channel_server &lt;string&gt;</verb>
+   <p> <verb>--channel-server &lt;string&gt;</verb>
    Specify the channel server address.</p>
-   <p> <verb>--channel_port &lt;integer&gt;</verb>
+   <p> <verb>--channel-port &lt;integer&gt;</verb>
    Specify the channel server port.</p>
    <p> <verb>--iface &lt;string&gt;</verb>
    Select the network interface to use.</p>
-   <p> <verb>--input_program &lt;integer&gt;</verb>
+   <p> <verb>--input-program &lt;integer&gt;</verb>
    Select the program to use (for streams with 
    several programs, as those coming from satellite).</p>
-   <p> <verb>--input_audio &lt;integer&gt;</verb>
+   <p> <verb>--audio-type &lt;integer&gt;</verb>
    Select the audio channel to use.</p>
-   <p> <verb>--input_subtitle &lt;integer&gt;</verb>
+   <p> <verb>--subtitle-channel &lt;integer&gt;</verb>
    Select the subtitle.</p>
-   <p> <verb>--input_channel &lt;integer&gt;</verb>
+   <p> <verb>--audio_channel &lt;integer&gt;</verb>
    Select the channel number.</p>
-   <p> <verb>--dvd_device &lt;string&gt;</verb>
+   <p> <verb>--dvd &lt;string&gt;</verb>
    Specify the default dvd device.</p>
-   <p> <verb>--vcd_device &lt;string&gt;</verb>
+   <p> <verb>--vcd &lt;string&gt;</verb>
    Specify the default vcd device.</p>
-   <p> <verb>--ipv4</verb>
+   <p> <verb>-4, --ipv4</verb>
    Force IPv4.</p>
-   <p> <verb>--ipv6</verb>
+   <p> <verb>-6, --ipv6</verb>
    Force IPv6.</p>
   </sect2>
   
   <sect2>
    <heading>Directly from CVS</heading>
    <p> <label id="cvs">
-    Firs log in as suer anonymous with an empty password :
+    First log in as user anonymous with an empty password :
     <verb>
      cvs -d :pserver:anonymous@anoncvs.videolan.org:/var/cvs/videolan login
     </verb>
     make
     </verb>
    It should compile without any error. If there are, please check you 
-   have the required libs 
+   have the required librarie
    installed on your system, as the configure script can't check them all.
   </p>
   <p>
    <p>
     This is the basic x11 video output. It only requires a 
     working X11 server. You will need xlibs headers to compile it
-    (xlibs-dev packet on Debian systems).
+    (xlibs-dev package on Debian systems).
    </p>
   </sect2>
   
    <heading>deinterlace</heading>
    <p>default: enabled</p>
    <p>
-    This filter deinterlaces video. It is usefull with streams coming 
+    This filter deinterlaces video. It is useful with streams coming 
     from a satellite broadcast.
    </p>
   </sect2>
     This is the VideoCD input. 
    </p>
   </sect2>
+  <sect2>
+   <heading>http</heading>
+   <p>default: enabled</p>
+   <p>
+    This is the http input. You can use it for Video On Demand.
+   </p>
+  </sect2>
   <sect2>
    <heading>satellite</heading>
    <p>default: disabled</p>
    <htmlurl url="http://www.linuxtv.org/" name="linuxtv.org">.
    </p>
   </sect2>
+  <sect2>
+   <heading>avi</heading>
+   <p>default: enabled</p>
+   <p>
+    This input module allows to read .avi files.
+   </p>
+  </sect2>
+
  </sect1>
  
  <sect1>
    </p>
   </sect2>
  </sect1>
+ <sect1>
+  <heading>Codec modules</heading>
+  <p> The following modules add codec support. </p>
+  <sect2>
+   <heading>a52</heading>
+   <p>default: disabled</p>
+   <p>
+    This is a better AC3/A52 decoder than the built-in one, based on
+    liba52 : 
+   <htmlurl url="http://liba52.sf.net/" name="liba52">.
+   </p>
+  </sect2>
+  <sect2> 
+   <heading>ffmpeg</heading>
+   <p>default: disabled</p>
+   <p>
+    This is a free MPEG-4/DivX/OpenDivX codec :
+   <htmlurl url="http://ffmpeg.sf.net/" name="ffmpeg">.        
+   </p>
+  </sect2>
+ </sect1>
+
  <sect1>
   <heading>OS support modules</heading>
   <p> The following modules add support or different OSs. </p>
   <heading>Get more help</heading>
   <p>
    First of all, it something seems to go wrong, read and try to 
-   understand the error messages. If you are a confirmed user, you 
-   may try the "-vvv" option which makes the vlc very verbose.
+   understand the error messages. You can have detailed messages by
+   choosing messages in the view menu, in GTK, Gnome and Win32 interfaces.
   </p>
   <p>
    There is a FAQ page on our website :
-   <htmlurl url="http://www.videolan.org/doc.html" name="http://www.videolan.org/doc.html">.
+   <htmlurl url="http://www.videolan.org/doc/index.html" name="http://www.videolan.org/doc/index.html">.
    If you think one question should be in the FAQ, please contact
-   <htmlurl url="mailto:videolan@videlan.org" name="videolan@videlan.org">
+   <htmlurl url="mailto:videolan@videolan.org" name="videolan@videolan.org">
   </p>
   <p>
-   Finally, there's a users mailing list (English speaking). To subscribe, send a mail to 
+   Finally, there's a users mailing list (English-speaking). To subscribe, send a mail to 
    <htmlurl url="mailto:listar@videlan.org" name="listar@videlan.org"> containing
    "subscribe vlc" as message body.
   </p>