diff --git a/Makefile b/Makefile index e26747ddae064a394bb432df2f49502af3127ad4..fd107d0633cee8ef2b66ee06f07dfdec024b20aa 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ # vls (VideoLAN Server) main Makefile #------------------------------------------------------------------------------- # (c)1999-2001 VideoLAN -# $Id: Makefile,v 1.83 2001/12/12 15:37:02 bozo Exp $ +# $Id: Makefile,v 1.84 2002/03/11 21:44:39 asmax Exp $ ################################################################################ @@ -162,7 +162,7 @@ dep: Makefile.opts $(DEP) vls: Makefile.opts $(OBJ) $(BUILTINS) @echo "Linking $@..." @test -d bin || mkdir -p bin - $(CXX) $(LCFLAGS) -o bin/$@ $(OBJ) $(BUILTINS:%=obj/%.a) $(VLS_LIB) + $(CXX) $(LCFLAGS) -o bin/$@ $(OBJ) $(BUILTINS:%=obj/%.a) $(VLS_LIB) -pg chmod 755 bin/$@ dep/server/vls.d: src/server/vls_builtins.cpp diff --git a/doc/vls-guide.sgml b/doc/vls-guide.sgml new file mode 100644 index 0000000000000000000000000000000000000000..2c974da200c0132938584df60f4d45b53cbfa902 --- /dev/null +++ b/doc/vls-guide.sgml @@ -0,0 +1,778 @@ + + +
+ +VideoLAN Server User's Guide +written by Cyril Deguet + +$Id: vls-guide.sgml,v 1.1 2002/03/11 21:44:39 asmax Exp $ + + +This document describes how to install, configure, and run the VideoLAN Server +(vls). + + + + +Introduction + +What is the VideoLAN project ? +

+VideoLAN is a complete software solution for video streaming, developed by +students at the Ecole Centrale Paris, under the General Public License (GPL). +It has been designed for broadcasting MPEG2 videos on local area networks +(LAN), but it can be extended to metropolitan or wide area networks, thanks to +the multicast technology. The VideoLAN solution includes a server, which can +broadcast video streams from various sources (DVD, satellite, camera, ...), +a client, which can receive, decode and display MPEG2 streams and, if +necessary, a channel server which makes the client receive the right stream. + + + DVD --->- Unicast/Broadcast/Multicast + \ --- + File --->-- -------- / \ -------- + |->-| Server |=====>====| LAN |---->-----| Client | + Satellite ->-- | (VLS) | \ / | (VLC) | + / -------- --- -------- + MPEG2 -->- ^ + encoder | + v + ---------------- + | Channel Server | + | (VLCS) | + ---------------- + +More details about the whole project can be found at +. + + +What is the VideoLAN server (vls) ? +

+The VideoLAN Server (vls) was designed to read MPEG videos from various sources +(DVDs for instance) and broadcast them on a network, in MPEG2-TS format. +Depending on the network capabilities, the VideoLAN Server can send the streams +in unicast, broadcast, or multicast mode. + + +Requirements + +Operating System +

+The VideoLAN Server is supposed to work under any Unix-like operating system. +A Windows port may be written one day or another ;) + + +Software requirements +

+You will need if you want to stream DVDs with vls, and + for reading +encrypted DVDs. + + +Hardware requirements +

+Vls is a very light software and needs few ressources. A Pentium 100 MHz +with 32 MB of memory should be enough for broadcasting one stream (then it +takes about 50% of CPU time). On my Pentium III 800 MHz, I can broadcast +more than 5 streams and vls eats less than 1% of CPU ! When broadcasting a +lot of streams stored on a hard disk, the actual limitation is not the +processor but the disk (especially when using IDE disks). + + + +Contact us +

+If you have any questions about the VideoLAN Server, you can contact us +at our mailing-list + + + + +Installation + +Getting vls +

+You can get tarballs and binary packages for the VideoLAN Server at the vls + page. +Currently, there are binary packages only for Debian GNU/Linux, so if you +use another operating system, you will have to download the source code +(tarball) and build vls by hand (but don't worry, it is very easy ;-) + +To install the Debian package, you can type something like: + +# dpkg -i vls_0.3.1-1_i386.deb + + +If you have downloaded the source tarball, uncompress it with: + +# tar xvzf vls-0.3.1.tar.gz + + +You can also get the source code through CVS, with the following commands: + +# export CVSROOT=:pserver:anonymous@cvs.videolan.org:/cvs/videolan +# cvs login + [there is no password, just press enter] +# cvs checkout vls +# cvs logout + + + +Compiling vls +

+The VideoLAN Server uses the GNU configure and build system. It means that +you will need the standard GNU utilities, such as make, gcc, ld, and so +on... +Configuration +

+The first step is to create the +# ./configure + +You can supply several options to ./configure --help to get a list of +all options available. Here is an explanation of vls-specific options: + +--with-words=(big|little) + Specify endianness when cross-compiling. Don't use this option if + you don't know what it means ! + + + +--disable-debug + Disable debug mode (enabled by default). + + + +--enable-profiling + Generate extra code to write profile information suitable for the + analysis program gprof. + + + +--disable-dvd + Disable DVD support (enabled by default). You must supply this + option if you don't have libdvdread installed. + + + +Building +

+To compile and link vls, just type: + +# make + +Afterwards, there should be a binary called + + +Installing vls +

+To install vls files, run + +# make install + +If you haven't changed the install directories with +/usr/local/bin for binary files (/usr/local/lib/videolan/vls for plugins (/usr/local/etc/videolan/vls for configuration file +( + + +Overview and basic concepts + +Vls structure +

+From a user's point of view, the VideoLAN Server can be divided into four +kinds of components: a + + File, --------- ------------- ----------- Network, + DVD, --> | INPUT |---->| CONVERTER |---->| CHANNEL |--> File, + ... --------- ------------- ----------- ... + \ ----------- / + ----------| MANAGER |---------- + ----------- + ^ + | + Administration Interface + + +Input +

+The role of an + +Converter +

+The role of a + +Channel +

+A + +Manager +

+The + + +Administration interface +

+Once vls has been started, you must use an + + + +Configuration +

+The VideoLAN Server reads its configuration from SYSCONF_DIR/videolan/vls (where SYSCONF_DIR is /usr/local/etc +if you built and installed vls by hand, or is /etc if you installed +the debian binary package). + +To write a General structure +

+The VideoLAN Server configuration file +BEGIN "FirstSection" + Variable1 = "value1" + Variable2 = "value2" + [...] +END + +BEGIN "SecondSection" + Variable1 = "value1" + Variable3 = "value3" + [...] +END + +[...] + +All section names, variable names and values are not case-sensitive. +There can be empty sections and subsections. Comments must follow a # +character. Some variables have a default value; it means that you can ommit +to declare these variables, and then they will be given their default value. + + +Writing a +Here is an explanation of all the sections you can find in a Section "Vls" +

+This section contains application wide settings. + +LogFile = "name" + + Name of vls log file. Default is "vls.log" + + + +Example: + +BEGIN "Vls" + LogFile = "vls.log" +END + + + +Section "Groups" +

+In this section, you can define some groups of users, and which commands +these users are allowed to execute. For each group you want to define, +you must add a line in the following format: + +groupname = "command1|command2|..." + + This adds a group "groupname", the users of which are allowed to execute + command1, command2, and so on. At the moment, the available commands are: + help, browse, start, suspend, resume, stop, shutdown, logout. + + + +Example: + +BEGIN "Groups" + monitor = "help|browse|logout" + master = "help|browse|start|resume|suspend|stop|shutdown|logout" +END + + + +Section "Users" +

+This section contains a list of users allowed to control vls through an +administration interface. For each user, add a line in the following format: + +username = "password:groupname" + + This adds a user "username", who belongs to the group "groupname" (defined + in the "Groups" section) and can log in with the password "password". + BE CAREFUL: the password must be encrypted, with a tool such as + + + +Example: + +BEGIN "Users" + monitor = "3BcKWoiQn0vi6:monitor" # password is 'monitor' + admin = "42BKiCguFAL/c:master" # password is 'Vir4Gv5S' +END + + + +Section "Telnet" +

+In this section, you can configure the telnet administration interface. + +LocalPort = "port" + + Defines which port will be used for the telnet server. Default port is + "9999". + + + +Domain = "domain" + + Either "inet4" or "inet6" (default is "inet4"). If you want to use IPv4 + addresses, put "inet4", and if you want to use IPv6, put "inet6". + + + +LocalAddress = "IP address" + + Defines on which IP address the telnet server will listen for requests. + Default address is "0.0.0.0" (or "0::0" with IPv6) + + + + +Example: + +BEGIN "Telnet" + LocalPort = "9999" +END + + + +Section "NativeAdmin" +

+Same syntax as "Telnet". Not used yet. + + +Section "Inputs" +

+In this section, you can define which inputs you want to use. For each input +you need, add a line in the following format: + +InputName = "Type" + + This adds a input named "InputName", the type of which is "Type". As + explained before, there are currently two types of input: "local" and + "video". You must use the "local" input to play a stream from a file or a + DVD, and the "video" input to play a stream from a Video4Linux device. + Each input must be configured in its own section (see next paragraph). + + + +Example: + +BEGIN "Inputs" + local1 = "local" + kfir = "video" +END + + + +Inputs configuration +

+For each input declared in the "Inputs" section, you must add a section with +the same name as the corresponding input. For instance, if you declared +two inputs "local1" and "kfir", there should be two sections named "local1" +and "kfir" too. The syntax of such sections depends on the type of the +corresponding input. + +To configure a local input, add a section in the following format: + + +BEGIN "LocalInputName" + ConfigPath = "path" +END + + + "LocalInputName" is the name of the local input you want to configure. + Actually this section only tells the VideoLAN Server where to find the + configuration file for this input, called + + +To configure a video input, add a section in the following format: + + +BEGIN "VideoInputName" + Device = "device" + Type = "type" +END + + + "VideoInputName" is the name of the video input you want to configure. + "device" is the path of the Video4Linux you want to read from (default + is "/dev/video"). "type" is either "Mpeg2-PS" or "Mpeg2-TS", depending + on your device configuration (default is "Mpeg2-PS"). + + + +Example: + +BEGIN "local1" + ConfigPath = "/home/videolan/streams" + # the configuration file is /home/videolan/streams/input.cfg +END + +BEGIN "kfir" + Device = "/dev/video" + Type = "Mpeg2-PS" +END + + + +Section "Channels" +

+In this section, you can define the channels (outputs) you want to use. +For each channel you need, add a line in the following format: + +ChannelName = "Type" + + This adds a channel named "ChannelName", the type of which is "Type". + "Type" must be either "network" or "file". Like inputs, channels must be + configured in their own section. + + + +Example: + +BEGIN "Channels" + localhost = "network" + client1 = "network" + client2 = "network" + multicast = "network" + localfile = "file" +END + + + +Channels configuration +

+For each channel declared in the "Channels" section, you must add a section +with the same name as the corresponding channel. The syntax of such a section +depends on the type of the corresponding channel. + +To configure a network channel, add a section in the following format: + + +BEGIN "NetChannelName" + SrcHost = "SourceHost" + SrcPort = "SourcePort" + DstHost = "DestHost" + DstPort = "DestPort" + Type = "Type" + TTL = "ttl" + Domain = "Domain" + Interface = "Interface" +END + + + "NetChannelName" is the name of the network channel you want to configure. + "SourceHost" is the IP address (or DNS name) from which vls will send + the stream. "SourcePort" is the UDP port from which the stream will be sent. + "SrcHost" and "SrcPort" are optional (if you don't set them, vls will not + 'bind' the socket). + "DestHost" is the IP address (or DNS name) to which the stream will be sent. + "DestPort" is the UDP port to which the stream will be sent (default is + "1234"). "Type" is either "unicast", "broadcast" or "multicast" (default is + "unicast"), depending on what you want to do (and on your "DstHost" address). + "TTL" is an option useful only if "Type" is "multicast" (default value is + "0"). You can use it to increase the TTL of your multicast packets if they + have to cross several routers. + "Domain" is either "inet4" if you use IPv4 addresses, or "inet6" if you use + IPv6 (default is "inet4"). + "Interface" is an option only supported under linux, to force the stream to + be broadcasted through a given network interface, "eth1" for instance" (to + use this option, vls must have root permissions). + + + +To configure a file channel, add a section in the following format: + + +BEGIN "FileChannelName" + FileName = "file" + Append = "append" +END + + + "FileChannelName" is the name of the file channel you want to configure. + "file" is the name of the file where the stream will be stored (default + is "fileout.ts"). "append" is either "yes" or "no", and indicates whether + vls will append the stream at the end of the file, or rewrite it. + + + +Example: + +BEGIN "localhost" # The client is on the same host as the server + DstHost = "localhost" + DstPort = "1234" +END + +BEGIN "client1" # unicast towards client1 + DstHost = "192.168.1.2" + DstPort = "1234" +END + +BEGIN "client2" # unicast towards client2 + DstHost = "192.168.1.3" + DstPort = "1234" +END + +BEGIN "multicast" # multicast streaming + DstHost = "239.2.12.42" + DstPort = "1234" + Type = "multicast" +END + +BEGIN "localfile" # file output + FileName = "stream.ts" + Append = "no" +END + + + + +Writing an +As explained before, a local input must be configured in a separate file, +named + +BEGIN "Input" + FilesPath = "path" + ProgramCount = "count" +END + + + "path" is the path where your MPEG files are located (by default it is the + current directory). "count" is the number of programs defined in input.cfg + (0 by default). + + + +For each program you want to define, you must add a section with the following +format: + + + +BEGIN "number" + Name = "name" + Type = "type" + FileName = "file" + Device = "device" +END + + + "number" is the program number: the first program has number 1, the second + number 2, and so on. "name" is the program name, by which you will tell vls + to start this program (see next chapter "Running vls"). "type" can be + "Mpeg1-PS", "Mpeg1-TS", "Mpeg2-PS", "Mpeg2-TS", or "Dvd". If your stream + is stored in a MPEG file (*.mpeg, *.mpg, *.vob, and so on...), it is + probably in Mpeg1-PS or Mpeg2-PS format. If Type is set to "Mpeg1-PS", + "Mpeg1-TS", "Mpeg2-PS", or "Mpeg2-TS", vls will assume your stream is + stored in the file "file", in the directory "path" ("path" being the + variable defined in the "Input" section). If "type" is "Dvd", the variable + Device will be used instead of FileName. Note that you cannot play "Dvd" + programs unless you compiled vls with dvd support, which uses libdvdread. + With libdvdread, you can play a "real" Dvd (then "device" is the device + of your DVD drive, "/dev/hdc" or "/dev/cdrom", for instance; note that + libdvdread needs read AND write access rights to the device), but you can + also play a Dvd stored on a hard disk (then "device" is the directory + where the .vob files are stored: "/mnt/data/VIDEO_TS", for instance). + The libdvdread now supports encrypted Dvds, even stored on a hard disk. + + + +Full example: + +BEGIN "Input" + FilesPath = "/home/videolan/streams" + ProgramCount = "4" +END + +BEGIN "1" # MPEG2 stream stored in /home/videolan/streams/Dolby.vob + Name = "dolby" + FileName = "Dolby.vob" + Type = "Mpeg2-PS" +END + +BEGIN "2" # another file + Name = "canyon" + FileName = "Dolby_Canyon.vob" + Type = "Mpeg2-PS" +END + +BEGIN "3" # Dvd + Name = "dvd" + Device = "/dev/cdrom" + Type = "Dvd" +END + +BEGIN "4" # Dvd stored on a hard disk + Name = "matrix" + Device = "/mnt/data/matrix/VIDEO_TS" + Type = "Dvd" +END + + + + + + +Running vls + +Launching vls +

+Running vls is very easy: just type "vls" in a shell console, and that's all. +Be careful: if your log file is "vls.log" as in the example, vls will need +write access in the current directory , or you will see something like: + +*** Exception *** in copy constructor (0xbffffc98, copy of 0x80e30a8) +Unable to open the log file "vls.log": Error: Could not open file 'vls.log': +Permission denied + +Remember also that you must be root when using the "Interface" option in + +VideoLAN Server v 0.3.0 (Dec 22 2001) - (c)1999-2001 VideoLAN + +2002-03-09 17:24:51 [INFO/Vls] Module "channel:file" registered +2002-03-09 17:24:51 [INFO/Vls] Module "channel:network" registered +2002-03-09 17:24:51 [INFO/Vls] Module "mpegreader:file" registered +2002-03-09 17:24:51 [INFO/Vls] Module "mpegconverter:ts2ts" registered +[...] + +What you can see on the screen (stderr) is exactly what goes in the log +file + +Using the telnet interface +

+After vls has been launched, it opens a telnet server (on the port 9999 by +default). You can connect to this server with the following command: +telnet localhost 9999 +You should see something like: + +Trying 127.0.0.1... +Connected to vls. +Escape character is '^]'. + +Videolan Server Administration System + +Login: + +Then you must authenticate with a login/password pair defined in + + +admin@vls> + +Then you can type some commands, which are explained in the next paragraph. +To log out, type "logout" after the telnet prompt. + + +Interface commands +

+to be written + + + + +FAQ +

+to be written + + +