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 VideoLAN Client 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

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

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

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.