VLC HOWTO

- - VLC HOWTO - Originally written by Henri Fallon, maintained by Johan Bilien - v0.0.9, 16 april 2002 - - - This document describes how to use the vlc (VideoLAN client) to read DVDs and mpeg files, locally or from a network. - - - - - - - Introduction - - - What is VideoLAN ? -

- VideoLAN is a project of sudents of the École Centrale Paris which aims - at broadcasting video on the campus, and providing the students with an MPEG-2 - 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. Recent additions allow to read .avi files, - and MPEG-4/DivX-encoded movies. -

- You may want to look at the port section on our website : - . -

- - - - What is the VideoLAN project ? -

- - VideoLAN is a complete software solution for video streaming, developed - by students at the and contributors from all over the world, under the . 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 : - - - - DVD --->- Unicast/Broadcast/Multicast - \ --- - File --->-- -------- / \ -------- - |->-| Server |=====>====| LAN |---->-----| Client | - Satellite ->-- | (VLS) | \ / | (VLC) | - / -------- --- -------- - MPEG2 -->- ^ - encoder | - v - ---------------- - | Channel Server | - | (VLCS) | - ---------------- - - - More details about the project can be found on the - . - -

- - - The documentation of the project -

- There are four main documents : - -the , -the , -the , -this VLC Howto. - - -The up-to-date version of these documents can be found on the . - - - Translated versions of this document -

- No translation is currently available. -

- -

- The English version is maintained by Henri Fallon, - Johan Bilien, and the VideoLAN team. It can be found at: - . -

- - - - Requirements - - Operating system -

- VLC works under the following systems : -

- - Linux (all distributions, including iPAQ Familiar Linux) - Windows (all 32bit versions) - Mac OS X - FreeBSD, NetBSD, OpenBSD, BSD/OS - BeOS - QNX RTOS - Solaris - -

- Please note that the Linux, Windows and MacOS X versions are generally the most - up-to-date ones. -

- - - Software requirements -

- Depending on the outputs and inputs you are using, you may need - additional libraries. Please see . -

- For playing encrypted DVDs, you will need libdvdcss, which you can find - on this page : - . -

- - - Hardware requirements -

- 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. -

- 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. -

- - - - - - Disclaimer -

- This documentation is given "as is", and any comment and improvement - are welcome. -

- -

- - 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 . - -

- - - - Legal -

- - 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 . - -

- - - - - Quick start - -

This section will help you get, install and use vlc without giving you - much details. -

- - - Get and install vlc from binary packages -

- The first thing to do is to get an archive, on our web site - -

- - - Which package to chose ? -

- There are different packages because vlc has "plugins" which provide - features but also enlarge the executable and require external libraries. -

- SDL is a lib which allows you to have an accelerated video output. - You will need libsdl > 1.1.6 -

- If you're using the enlightened sound daemon, you may want to try - the esd-aware vlc. -

- Generally, when you don't know what a module name is, you don't - need/use it :-) -

- - - - Debian package -

- Just use dpkg : - - dpkg -i vlc-x.x.x.deb - -

- Depending on the package you have downloaded, you may have dependency - problems. You have to solve them, by installing the required libraries. -

- - - - RPM package -

- Install vlc just as you would install any RPM package : - - rpm -i vlc-x.x.x.rpm - -

- You may have to install external libraries to meet dependencies, depending on - the package you downloaded (gnome, gtk, esd, ...). -

- - - - BeOS users -

- 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 - directory and run it from there. -

- - - - Mac OS X users -

- Double-click on the archive, and copy the vlc file to your Applications - folder. -

- - - Windows users -

- 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. -

- - - - - Get libdvdcss -

- In order to read CSSsrambled DVDs, you will need libdvdcss. - You can find binary - packages for your distribution here : -

- For Windows, BeOS and Mac OS X users, libdvdcss is statically linked in the - Windows binary, so you don't have to install it. -

- - - - Use the vlc for DVD reading -

- Launch the application simply by typing vlc in a terminal (or by - double-clicking on its icon in a graphical shell). You should see - the graphical interface appear. -

- -

- For reading a DVD (or a VCD), click on the "Disc" button. The new window - you must then enter the path to your DVD or VCD drive : - - - Linux users -

- 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. -

- It is very useful to create a symlink to this file, called /dev/dvd. - To do this, as root, type (if your dvd device is /dev/hdc for example) : - - ln -s /dev/hdc /dev/dvd - - Also make sure you have read AND write permission to the device - (otherwise dvd decryption won't work). -

- - - Windows users -

- 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. -

- - - BeOS users -

- Under BeOS, the dvd device looks like - "/dev/disk/ide/atapi/1/slave/0/raw" for example, if your dvd device is - slave on your first (not sure) ide device. -

- - - Other OS -

- To do ... -

- - - Use the vlc for network streaming -

- This is the vlc original usage. -

- -

- Launch the vlc as you would have for DVD reading. Then click on the - "Network" button. -

- - If using a VideoLAN Channel Server -

- The only thing you have to do is to check the "Channel server" box - and to enter the IP address and port - of this channel - server. Ask your administrator if you don't have it. Then click on OK. -

- You will see a new "Channel" field in the interface. You may now - enter the selected channel and click on OK. After a few seconds, - if a program is being sent in this channel, you should see the program - start. -

- 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 occurred (if you launched vlc from - a terminal, you should see "Network error: no answer from vlcs"). -

- - - Without VideoLAN Channel Server -

- Simply clicking on the network button, then on ok should be - sufficient in most cases. -

- After clicking on OK, and if a program is being sent, you should see - a window open with your program. -

- - - - - The graphical interface -

- Please note that the gnome, gtk and win32 interfaces are currently the most - advanced. The following descriptions refer to them. -

- - Opening a stream -

- For opening streams through the graphical interface, click on either - "File" for opening a file stored on your hard drive, "Disc" for - opening a DVD or a VCD, "Network" for reading a stream from a vls - or through http input, or "Satellite" for reading directly - from a satellite card. -

- - Basic stream control -

- You have at your disposal all the classical control of a video player. - For example when playing local streams, you can do pauses, speed up or - slow down the stream ... Just use the corresponding buttons. -

- - DVD and VCD navigation -

- When reading a DVD or a VCD, you can change chapter and title either - by using the - right-click menu or by using the dedicated bar that appears when reading - from a disc. -

- - - - Programs, audio and subtitles -

- When reading a multiprogram stream, you can change the current program - by selecting it in the "View/Programs" submenu, or using the "right click" - menu from the video output window. -

- In DVDs, if different angles are availables, they will be treated as - different programs. -

- At any time you can change the audio/subtitles channel using either the - "setting" menu from the interface or using the "right click" menu from - the video output window. -

- - Preferences window -

- By choosing "Preferences" in the "Settings" menu, you will open - the preferences window. This window is generated dynamically according - to the modules that were compiled. -

- In every tab, you may click on "Save" to store your settings in your - ~/.videolan/vlcrc file. -

- - Interface tab -

- In that tab, you can select which interface you would like to use on next - start. Click on the choosen interface, click on "Select" then on "Save". -

- - - Audio tab -

- In this tab, you can select the audio output you would like to use on - next start. You may also specify some other settings such as the output - level, the audio frequency, ... -

- - - Video tab -

- In this tab, you can select which video output will be used on next start, - and add a video filter module. You may also specify some video settings, - such as the window size or if you would like fullscreen display. -

- - - Input tab -

- In this tab, you can enter the input method with options (for example - udp:@239.255.255.42) that will be used on next start. You can - also add some settings, such as the channel server address ... -

- - - Decoders tab -

- In this tab, you can select which decoder you want to use for MPEG audio - and AC3 streams. -

- - - CPU tab -

- In this tab, you may disable the use of some CPU extensions such as - MMX or SSE. -

- - - Playlist tab -

- In this tab, you can select some playlist options, such as looping the - playlist. -

- - - Miscellanous tab -

- In this tab, you can select which memcpy version you want to use. Some - of them uses MMX 3Dnow! extensions. -

- - - - - Command line options -

- Many options are only available through command line. They are detailed here. -

- - Opening streams -

- The following commands start vlc and add a first element to the playlist. -

- - Opening a file -

- Simply start vlc with vlc my_file.mpg. -

- You may tell vlc what input to use, for example add --input ts - when playing a ts MPEG, although vlc should be able to recognize the type - of MPEG. -

- - - Opening a DVD or VCD -

- Simply start vlc with vlc dvd:DVDDRIVE or vlc vcd:CDROMDRIVE -, where DVDDRIVE/CDROMDRIVE is the complete - path to your dvd/cdrom drive. -

- You may add -t X -T Y to start directly from the Xth chapter, Yth - title. -

- - - Start a network stream -

- To receive an UDP stream (being sent from a VLS), start vlc with - vlc udpstream:[@<bind address>[:<server port>]] . -

- Please note that bind address refers to the destination address, for - example your broadcast address. If the stream is being broadcasted, - vlc udpstream: should be sufficient. If the stream - is multicasted, you must specify the multicast address, for example - vlc udpstream:@239.255.255.42 -

- To receive a http stream, start vlc with vlc <your URL>. - - -

- - - - - Modules selection -

- The vlc tries to select the most appropriate interface, input and output - modules, among the ones available on the system, according to - the stream he is given to read. However, you may wish to force - the use of a specific module with the following options: - -

--intf <interface module> - allows you to select the interface module

- -

--vout <video output module> - allows you to select the video output.

- -

--aout <audio output module> - allows you to select the audio output.

- -

--filter <video filter module> - allows you to add a video filter module.

- -

--mpeg-adec <MPEG audio decoder module> - allows you to select the audio MPEG decoder.

- -

--ac3-adec <AC3 audio decoder module> - allows you to select the audio AC3 decoder.

- - - - Other options - - Help options: - -

--help - gives you all the available options.

--longhelp - gives you a more detailled version of the available options.

--version - gives you information about the current version.

--list - gives you the list of all available plugins.

-vvvv (X times) - set the level of warning messages.

--stats - gives statistic outputs.

- - - - Audio options: - - -

--noaudio - disables the audio output

--mono - forces the vlc to treat the stream in mono audio.

--volume <integer> - set the level of audio output.

--rate <integer> - set the audio output frequency (Hz)

--desync <integer> - compensates desynchronization of audio (ms)

- - - - Video options: - -

--novideo - disables the video output

--width <integer> - --height <integer> - set the video window dimensions.

--grayscale - turns video output into grayscale mode.

--fullscreen - set fullscreen video.

--nooverlay - disables hardware acceleration for the video output

--spumargin <integer> - force subtitles position.

- - - - Input options: - - -

--network-channel - Start with channel server enabled.

--channel-server <string> - Specify the channel server address.

--channel-port <integer> - Specify the channel server port.

--iface <string> - Select the network interface to use.

--input-program <integer> - Select the program to use (for streams with - several programs, as those coming from satellite).

--audio-type <integer> - Select the audio channel to use.

--subtitle-channel <integer> - Select the subtitle.

--audio_channel <integer> - Select the channel number.

--dvd <string> - Specify the default dvd device.

--vcd <string> - Specify the default vcd device.

-4, --ipv4 - Force IPv4.

-6, --ipv6 - Force IPv6.

- - - - CPU options -

--nommx - disable the use of mmx CPU extensions.

--no3dn - disable the use of 3D Now! CPU extensions.

--nommxext - disable the use of mmx ext CPU extensions.

--noaltivec - disable the use of AltiVec CPU extensions.

- - - - - - - - - - - Building the vlc from sources -

- You can choose either to take the latest release, or a CVS source. Note that - CVS snapshots may be broken, although we do our best to prevent this from - happening. -

- From here, you have to be a little experienced, even more if you want to use - the cvs. -

- - Getting an archive -

- You have guessed it, the first thing to do is to get the source. - Until there, everyone should understand :) -

- - Web site -

- Source packages can be found in the "tarballs" section of the download page : - . -

- CVS snapshots are available from the address : - . -

- Then untar the archive : - - tar xzf vlc-x-x-x.tar.gz - -

- - - Directly from CVS -

- First log in as user anonymous with an empty password : - - cvs -d :pserver:anonymous@anoncvs.videolan.org:/var/cvs/videolan login - - Then retrieve the repository : - - cvs -d :pserver:anonymous@anoncvs.videolan.org:/var/cvs/videolan -z3 checkout vlc - -

- - - libdvdcss -

- To compile vlc with dvd support, you need to get and install libdvdcss. -

- It is available for download here : - - - Decompress the tarball in a directory of your choice and build it : - - tar -xvzf libdvdcss-x.x.x.tar.gz - cd libdvdcss-x.x.x - ./configure - make - [as root] make install - - - You can also find binaries packages for many distributions. - - - - Building the program -

- Go into the vlc directory and run the configure script : - - ./configure - - If you want to enable options, you may add "--enable-option" - to the previous line. - For example, to build with the xvideo extension, and alsa support, - you should type : - - ./configure --enable-xvideo --enable-alsa - - To get the list of the available options, and know if they are - enabled by default, - you can try : - - ./configure --help - -

- Also have a look on the . -

- A very typical installation, on a XFree 4.1 system, recent video card, with - gnome, is : - - ./configure --enable-esd --enable-gnome - -

- - - Plugins, builtins ... -

- The configure script should create a Makefile.opts file, which you can edit and modify. - Indeed you can chose to have features (as esd support, for example) built as plugins - or inside the program. -

- If you build a feature as a plugin, it can lead to a little loss of performance. - It you build it inside the code, it'll enlarge a bit the size of the executable. -

- When you're done with Makefile.opts (which also works if you leave it - untouched), just - type: - - make - - It should compile without any error. If there are, please check you - have the required libraries - installed on your system, as the configure script can't check them all. -

- When you're done with it, as root, type : - - make install - - if you wish to have vlc fully installed on your system. If you prefer - to keep in in the - current directory, you may skip the "make install". You'll then have - to cd into the vlc - directory and type "./vlc" instead of just typing vlc. -

- - - - - Modules description -

- - Here is a description of nearly all the available modules for the - vlc. If you wish to compile one which is stated disabled by default, - you have to launch the configure script with - ./configure --enable-module_name . See . - - Video outputs - - x11 -

default :enabled

- This is the basic x11 video output. It only requires a - working X11 server. You will need xlibs headers to compile it - (xlibs-dev package on Debian systems). -

- - - - xvideo -

default : enabled

- It requires an xvideo compliant graphic card (it is the case for - nearly all the modern card). It uses hardware acceleration for - yuv transformation and for rescaling. -

- - - - sdl -

default : enabled

- This video output uses sdl libraries. You need at least version 1.1.6 of - this libraries. -

- You may indicate the path to the sdl-config program with the - --with-sdl-config-path=PATH option given to the - configure script. -

- - - - directx -

default: enabled on win32

- This video output uses Microsoft Direct X libraries. It is recommended - for the win32 port. -

- You may indicate the path to directx libraries and headers with - the --with-directx=PATH option. - - - - fb -

default: enabled on Linux

- This is the frame buffer video output. It requires that your kernel - was compiled with frame buffer support. -

- - - - glide -

default: disabled

- This video output uses Glide libraries (hardware acceleration for - 3Dfx cards). -

- You may indicate the path to the library with the - --with-glide=PATH compilation option. -

- - - - mga -

default: disabled

- It provides hardware acceleration for Matrox cards on Linux. -

- - - - ggi -

default: disabled

- - - - aa -

default: disabled

- This video output uses the aalib library to display video - through ASCII art. It requires aalib headers (aalib1-dev under Debian) - to compile. -

- - - - Video filters modules - - deinterlace -

default: enabled

- This filter deinterlaces video. It is useful with streams coming - from a satellite broadcast. -

- - - - wall -

default: enabled

- This filter allows you to have the video cut in pieces in several - windows, which you can order as you wish. It can be used to generate - image walls with several sources. Start it with - --filter wall:XxY in order to have the video cut in X rows - and Y columns -

- - - distort -

default: enable

- This filter adds a distortion effect to the video. Who said it - was useless ;-) ? -

- - - - transform -

default: enable

- This filter rotates the video window of 90 degrees. -

- - - - invert -

default: enabled

- This filter inverses colors. -

- - - - Sound outputs - - dsp -

default: enabled on Linux

- This is the Linux /dev/dsp output. It requires that your kernel - was compiled with support for your sound card. -

- - - - alsa -

default: disabled

- This is the sound output for Advanced Linux Sound Architecture. - It requires that you installed the alsa drivers and libraries. -

- - - - esd -

default: disabled

- This sound output has Enlightened Sound Daemon support - (usually used with Gnome). - You must have the daemon and its libraries installed. -

- - - arts -

default: disabled

- This sound output has aRts (KDE's sound server) support. - You must have the daemon and its libraries installed. -

- - - - waveout -

default: enabled on win32

- This is the Wave output, which is used by the win32 port. -

- - - - - Input modules - - dvd -

default: enabled

- This is the DVD input module. It will need libdvdcss, which can - be found . -

- - - - dvdread -

default: disabled

- This is an alternative to the previous one, it uses libdvdread - (which also needs libdvdcss). -

- - - vcd -

default: enabled

- This is the VideoCD input. -

- - - http -

default: enabled

- This is the http input. You can use it for Video On Demand. -

- - - satellite -

default: disabled

- This is an input module that allows to read directly from a - Hauppauge WinTV Nova card under Linux. It requires drivers 0.9.4 - available from - . -

- - - avi -

default: enabled

- This input module allows to read .avi files. -

- - - - - - Interface modules - - gtk -

default: enabled

- This is the GTK+ interface. It needs gtk libraries (libgtk1.2 package - on Debian) and headers files if you are compiling it (libgtk1.2-dev - package on Debian). Note that it can be used under Windows. -

- - - gnome -

default: disabled

- This is the Gnome interface. It needs gnome libraries (libgnome32 under - Debian) and headers (libgnome-dev) if you wish to compile it. -

- - - intfwin -

default: enabled on win32

- This is the Windows native interface. It requires Borland C++ builder - to compile. You may use --with-bc-builder=PATH option - to specify the path to this application. -

- - - - qt -

default: disabled

- This is the QT libraries interface module. You will need the libraries - (libqt2 package on Debian) and headers (libqt-dev) if you wish to - compile it. -

- - - kde -

default: disabled

- This is the KDE interface module. You will need the libraries - (kdelib package on Debian) and headers (kde-devel) if you wish to - compile it. -

- - - - rc -

default: enable

- This is the Remote Control interface module. With this one, vlc - is controled by sending him commands, such as play, stop, ... so - that you may control vlc through a script. -

- - - - ncurses -

default: disabled

- This is a text interface, using ncurses library. You will need - ncurses headers if you want to compile it (libncurses5-dev on Debian). -

- - - lirc -

default: disabled

- This interface module allows you to control vlc through a remote. - A lircrc example is provided to help you configure it to your remote - (see doc/lirc/example.lircrc). -

- - - - Codec modules -

The following modules add codec support.

- - a52 -

default: disabled

- This is a better AC3/A52 decoder than the built-in one, based on - liba52 : - . -

- - - ffmpeg -

default: disabled

- This is a free MPEG-4/DivX/OpenDivX codec : - . -

- - - - - OS support modules -

The following modules add support or different OSs.

- - macosx -

default: enabled on MacOS X

- This is the MacOS X support module, including a native interface. -

- - - - qnx -

default: enabled on qnx

- This is the QNX RTOS support module. -

- - - - - Specific use of the vlc - - Use the vlc as a viever and decoder for the Hauppauge WinTV - Nova card - - What is required ? -

- At the present time, the satellite input only works under Linux. - It requires that drivers version 0.9.4 of the card, drivers - that are being developped by the . -

- - - Building the vlc with satellite support -

- Get the sources, either from our last .tar.gz release, - or best from the cvs (see ). -

- Move to the vlc directory, then launch - - ./configure --enable-satellite - - You may add other compilation options, see . - Then launch the compilation with - - make - - You may install it with (as root) - - make install - - or run it from the current directory. -

- - - Running it from the command line -

- Run the vlc with - - vlc satellite:<frequency(Hz)>,<polarization(0 for V, - 1 for H)<, - >FEC (1 for 1/2, 2 for 2/3 ...)>,<symbol rate (kbytes/sec)> - - You then have to select your program, either with the command line option - - --input_program - - or by choosing it in the view/programs menu. - - - Running it from the GTK/Gnome interface -

- Click on the "Sat" icon. In the opening box, you may enter - your transponder settings, then click on "Ok". -

- After a few seconds, the word satellite should appear under the command - buttons. You may now choose your program from the View/Programs menu. -

- - - - Use the vlc to create image walls. -

- The idea is to use several video sources, each one displaying a part - of the whole image, to get a bigger result. -

- Vlc and the VideoLAN solution can provide a good way to create - such displays : a vls broadcasts a stream in several vlc each - display a part of image. -

- For this, you should use the wall filter : start vlc with - - vlc udp: --filter wall:<number of rows>x<number of columns> - :<number of the part to diplay> - -

- - - - - Get more help -

- First of all, it something seems to go wrong, read and try to - understand the error messages. You can have detailed messages by - choosing messages in the view menu, in GTK, Gnome and Win32 interfaces. -

- There is a FAQ page on our website : - . - If you think one question should be in the FAQ, please contact - -

- Finally, there's a users mailing list (English-speaking). To subscribe, send a mail to - containing - "subscribe vlc" as message body. -

- -

How to set up VLC for web streaming (X11 only)

Abstract

Installing and configuring XSwallow for plain MPEG files

Tricks for live web streaming using VLMS

Configuring the Web server

Configuring XSwallow

Acknowledgements