mirror of https://github.com/tLDP/LDP
2801 lines
74 KiB
XML
2801 lines
74 KiB
XML
<?xml version="1.0" encoding="iso8859-1"?>
|
||
|
||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||
"http://docbook.org/xml/4.1.2/docbookx.dtd" []>
|
||
|
||
<book id="vls-user-guide">
|
||
|
||
<bookinfo>
|
||
|
||
<title>
|
||
VLS user guide
|
||
|
||
</title>
|
||
|
||
<authorgroup>
|
||
<author>
|
||
<firstname>Cyril</firstname>
|
||
<surname>Deguet</surname>
|
||
</author>
|
||
<author>
|
||
<firstname>Alexis</firstname>
|
||
<surname>de Lattre</surname>
|
||
</author>
|
||
</authorgroup>
|
||
|
||
<copyright>
|
||
<year>2002, 2003</year>
|
||
<holder>
|
||
the VideoLAN project
|
||
|
||
</holder>
|
||
</copyright>
|
||
|
||
<legalnotice>
|
||
|
||
<para>Permission is granted to copy, distribute and/or modify this
|
||
document under the terms of the GNU Free Documentation License, Version
|
||
1.2 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 in the appendix
|
||
<xref linkend="gfdl" endterm="tgfdl"/>.</para>
|
||
|
||
</legalnotice>
|
||
|
||
<keywordset>
|
||
<keyword>VideoLAN</keyword>
|
||
<keyword>VLS</keyword>
|
||
<keyword>stream</keyword>
|
||
<keyword>multicast</keyword>
|
||
<keyword>MPEG-1</keyword>
|
||
<keyword>MPEG-2</keyword>
|
||
<keyword>MPEG-4</keyword>
|
||
<keyword>DVD</keyword>
|
||
<keyword>DVB</keyword>
|
||
</keywordset>
|
||
|
||
<abstract>
|
||
|
||
<para>
|
||
This document is the complete user guide of VLS
|
||
|
||
.</para>
|
||
|
||
</abstract>
|
||
|
||
</bookinfo>
|
||
|
||
|
||
<toc/>
|
||
|
||
|
||
<chapter id="intro"><title id="tintro">Introduction</title>
|
||
|
||
<sect1><title>
|
||
What is the VideoLAN project ?
|
||
|
||
</title>
|
||
|
||
<sect2><title>
|
||
Overview
|
||
|
||
</title>
|
||
|
||
|
||
<para>VideoLAN is a complete software solution for video streaming, developed
|
||
by students of the <ulink url="http://www.ecp.fr">Ecole Centrale
|
||
Paris</ulink> and developers from all over the world, under the
|
||
<ulink url="http://www.gnu.org/copyleft/gpl.html">GNU General Public
|
||
License</ulink> (GPL). VideoLAN is designed to stream MPEG videos on high
|
||
bandwidth networks.</para>
|
||
|
||
<para>The VideoLAN solution includes :</para>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<itemizedlist>
|
||
|
||
|
||
<listitem><para>VLS (VideoLAN Server), which can stream MPEG-1, MPEG-2
|
||
and MPEG-4 files, DVDs, digital satellite channels, digital terrestial
|
||
television channels and live videos on the network in unicast or
|
||
multicast,</para></listitem>
|
||
|
||
|
||
|
||
|
||
|
||
<listitem><para>VLC (initially VideoLAN Client), which can be used as
|
||
a server to stream MPEG-1, MPEG-2 and MPEG-4 files, DVDs and live
|
||
videos on the network in unicast or multicast ; or used as a client
|
||
to receive, decode and display MPEG streams under multiple operating
|
||
systems.</para></listitem>
|
||
|
||
|
||
|
||
|
||
</itemizedlist>
|
||
|
||
|
||
<para>Here is an illustration of the complete VideoLAN solution :</para>
|
||
|
||
|
||
|
||
|
||
<figure float="0"><title>
|
||
Global VideoLAN solution
|
||
La solution VideoLAN globale
|
||
</title>
|
||
|
||
<mediaobject>
|
||
<imageobject>
|
||
<imagedata fileref="images/global-diagram.jpg" format="JPG" scalefit="1" scale="60"/>
|
||
</imageobject>
|
||
</mediaobject>
|
||
</figure>
|
||
|
||
|
||
<para>More details about the project can be found on the <ulink url="http://www.videolan.org/">VideoLAN Web site</ulink>.</para>
|
||
|
||
|
||
</sect2>
|
||
|
||
<sect2><title>
|
||
VideoLAN software
|
||
|
||
</title>
|
||
|
||
<simplesect><title>VLC</title>
|
||
|
||
|
||
<para>VLC works on many platforms : Linux, Windows, Mac OS X, BeOS,
|
||
*BSD, Solaris, Familiar Linux, Yopy/Linupy and QNX. It can read :</para>
|
||
|
||
|
||
|
||
|
||
<itemizedlist>
|
||
|
||
|
||
<listitem><para>MPEG-1, MPEG-2 and MPEG-4 / DivX files from a hard disk,
|
||
a CD-ROM drive, ...</para></listitem>
|
||
|
||
|
||
|
||
|
||
<listitem><para>DVDs and VCDs,</para></listitem>
|
||
|
||
|
||
|
||
|
||
<listitem><para>from a satellite card (DVB-S),</para></listitem>
|
||
|
||
|
||
|
||
|
||
<listitem><para>MPEG-1, MPEG-2 and MPEG-4 streams from the
|
||
network sent by VLS or VLC's stream output.</para></listitem>
|
||
|
||
|
||
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
VLC can also be used as a server to stream :
|
||
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
|
||
|
||
<listitem><para>MPEG-1, MPEG-2 and MPEG-4 / DivX files,</para></listitem>
|
||
|
||
|
||
|
||
|
||
<listitem><para>DVDs,</para></listitem>
|
||
|
||
|
||
|
||
|
||
<listitem><para>from an MPEG encoding card,</para></listitem>
|
||
|
||
|
||
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
to :
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
|
||
|
||
<listitem><para>one machine (i.e. to one IP address) : this is called
|
||
<emphasis>unicast</emphasis>,</para></listitem>
|
||
|
||
|
||
|
||
|
||
<listitem><para>a dynamic group of machines that the clients can
|
||
join or leave (i.e. to a multicast IP address) : this is called
|
||
<emphasis>multicast</emphasis>,</para></listitem>
|
||
|
||
|
||
|
||
</itemizedlist>
|
||
|
||
<para>in IPv4 or IPv6
|
||
.</para>
|
||
|
||
|
||
<para>To get the complete list of VLC's possibilities
|
||
on each plateform supported, see the <ulink url="http://www.videolan.org/vlc/features.html">VLC features
|
||
page</ulink>.</para>
|
||
|
||
|
||
|
||
|
||
|
||
<note><para>
|
||
VLC doesn't work on Mac OS 9, and will
|
||
probably never do.
|
||
|
||
</para></note>
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>VLS</title>
|
||
|
||
<para>
|
||
VLS can stream :
|
||
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para>
|
||
an MPEG-1, MPEG-2 or MPEG-4 files stored on a hard drive
|
||
or on a CD,
|
||
|
||
</para></listitem>
|
||
|
||
<listitem><para>
|
||
a DVD located in a local DVD drive or copied on a hard
|
||
disk,
|
||
|
||
</para></listitem>
|
||
|
||
<listitem><para>
|
||
a satellite card (DVB-S) or a digital terrestial
|
||
television card (DVB-T)
|
||
|
||
,</para></listitem>
|
||
|
||
<listitem><para>
|
||
an MPEG encoding card
|
||
|
||
;</para></listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<para>to:</para>
|
||
|
||
<itemizedlist>
|
||
|
||
|
||
<listitem><para>one machine (i.e. to one IP address) : this is called
|
||
<emphasis>unicast</emphasis>,</para></listitem>
|
||
|
||
|
||
|
||
|
||
<listitem><para>a dynamic group of machines that the clients can
|
||
join or leave (i.e. to a multicast IP address) : this is called
|
||
<emphasis>multicast</emphasis>,</para></listitem>
|
||
|
||
|
||
|
||
</itemizedlist>
|
||
|
||
<para>in IPv4 or IPv6
|
||
.</para>
|
||
|
||
|
||
<para>A Pentium 100 MHz with 32 MB of memory should be enough to send one
|
||
stream on the network. When streaming a lot of videos stored on a
|
||
hard drive, the actual limitation is not the processor but the hard
|
||
drive and the network connection.</para>
|
||
|
||
|
||
|
||
|
||
<para>VLS works under Linux and Windows. To get the complete
|
||
list of VLS's possibilities on each plateform supported, see the <ulink url="http://www.videolan.org/streaming/features.html">streaming features
|
||
page</ulink>.</para>
|
||
|
||
|
||
|
||
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>Mini-SAP-server</title>
|
||
|
||
<para>
|
||
You can add a channel information service based on the SAP/SDP
|
||
standard to the VideoLAN solution. The mini-SAP-server sends announces
|
||
about the multicast programs on the network in IPv4 or IPv6, and VLCs
|
||
receive these annouces and automatically add the programs announced to
|
||
their playlist.
|
||
|
||
</para>
|
||
|
||
<para>
|
||
The mini-SAP-server works under Linux and Mac OS X.
|
||
|
||
</para>
|
||
|
||
</simplesect>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1><title>
|
||
|
||
What is a codec ?
|
||
</title>
|
||
|
||
|
||
|
||
<para>
|
||
To fully understand the VideoLAN solution, you must
|
||
understand the difference between a <emphasis>codec</emphasis> and a
|
||
<emphasis>container format</emphasis>
|
||
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para>
|
||
A <emphasis>codec</emphasis> is a compression
|
||
algorithm, used to reduce the size of a stream. There are audio codecs
|
||
and video codecs. MPEG-1, MPEG-2, MPEG-4, Vorbis, DivX, ... are
|
||
codecs
|
||
|
||
</para></listitem>
|
||
|
||
<listitem><para>
|
||
A <emphasis>container format</emphasis> contains
|
||
one or several streams already encoded by codecs. Very often, there
|
||
is an audio stream and a video one. AVI, Ogg, MOV, ASF, ... are
|
||
container formats. The streams contained can be encoded using different
|
||
codecs. In a perfect world, you could put any codec in any container
|
||
format. Unfortunately, there are some incompatibilities. You can
|
||
find a matrix of possible codecs and container formats on the <ulink url="http://www.videolan.org/streaming/features.html">features
|
||
page</ulink>
|
||
|
||
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
To decode a stream, VLC first
|
||
<emphasis>demuxes</emphasis> it. This means that it reads the container
|
||
format and separates audio, video, and subtitles, if any. Then, each of
|
||
these are passed <emphasis>decoders</emphasis> that do the mathematical
|
||
processing to decompress the streams
|
||
|
||
.</para>
|
||
|
||
|
||
<para>
|
||
There is a particular thing about MPEG:
|
||
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para>
|
||
MPEG is a <emphasis>codec</emphasis>. There are
|
||
several versions of it, called MPEG-1, MPEG-2, MPEG-4, ...
|
||
|
||
</para></listitem>
|
||
|
||
<listitem>
|
||
|
||
<para>MPEG is also a container format, sometimes refered
|
||
to as <emphasis>MPEG System</emphasis>. There are several types of MPEG:
|
||
ES, PS, and TS</para>
|
||
<para>When you play an MPEG video from a DVD, for instance, the MPEG
|
||
stream is actually composed of several streams (called Elementary
|
||
Streams, ES): there is one stream for video, one for audio, another for
|
||
subtitles, and so on. These different streams are mixed together into a
|
||
single Program Stream (PS). So, the .VOB files you can find in a DVD are
|
||
actually MPEG-PS files. But this PS format is not adapted for streaming
|
||
video through a network or by satellite, for instance. So, another
|
||
format called Transport Stream (TS) was designed for streaming MPEG
|
||
videos through such channels.</para>
|
||
|
||
|
||
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
|
||
</sect1>
|
||
|
||
<sect1><title>
|
||
How can I use VideoLAN ?
|
||
|
||
</title>
|
||
|
||
<sect2><title>Documentation</title>
|
||
|
||
<para>
|
||
The user documentation of VideoLAN is made up of 4 documents :
|
||
|
||
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para>
|
||
the <emphasis>VideoLAN Quickstart</emphasis>. This
|
||
document will give you a quick overview of VLC, VLC's stream output,
|
||
the Video On Demand solution and the channel information service
|
||
system.
|
||
|
||
</para></listitem>
|
||
|
||
<listitem><para>
|
||
the <emphasis>VideoLAN HOWTO</emphasis>. This
|
||
document is the complete guide of the VideoLAN streaming
|
||
solution.
|
||
|
||
</para></listitem>
|
||
|
||
<listitem><para>
|
||
the <emphasis>VLC user guide</emphasis>. This document
|
||
is the complete guide for VLC.
|
||
|
||
</para></listitem>
|
||
|
||
<listitem><para>
|
||
the <emphasis>VLS user guide</emphasis>. This document
|
||
is the complete guide for VLS.
|
||
|
||
</para></listitem>
|
||
|
||
<listitem><para>
|
||
the <emphasis>VideoLAN FAQ</emphasis>.
|
||
This document contains Frequently Asked Questions about
|
||
VideoLAN.
|
||
|
||
</para></listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
|
||
The latest version of these documents can be found on the <ulink url="http://www.videolan.org/doc/">documentation page</ulink>
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
|
||
You can also have a look at the <ulink url="http://wiki.videolan.org">VideoLAN Wiki</ulink>. This is a website
|
||
that everyone can change. We use it to document everything that is not
|
||
in the "official" documentation: the tips and tricks for each O.S., the
|
||
graphical interfaces, etc...
|
||
|
||
|
||
</para>
|
||
|
||
</sect2>
|
||
|
||
<sect2><title>
|
||
User support
|
||
|
||
</title>
|
||
|
||
<para>
|
||
|
||
If you have problems using VideoLAN, and if you don't find the
|
||
answer to your problems in the documentation, please look at the <ulink url="http://www.via.ecp.fr/via/ml/videolan/index-en.html">online
|
||
archive of the mailing-lists</ulink>. There are two English-speaking
|
||
mailing-lists for the users :
|
||
|
||
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para><emphasis>vlc@videolan.org</emphasis>
|
||
for the questions on VLC
|
||
|
||
,</para></listitem>
|
||
|
||
<listitem><para><emphasis>streaming@videolan.org</emphasis>
|
||
for the questions on VLS, mini-SAP-server
|
||
and the network
|
||
|
||
.</para></listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
|
||
If you want to subscribe or unsubscribe to the mailing-lists,
|
||
please go to the <ulink url="http://www.videolan.org/support/lists.html">
|
||
mailing-list page</ulink>.
|
||
|
||
|
||
</para>
|
||
|
||
<para>
|
||
You can also talk with VideoLAN users and developers on IRC :
|
||
server <emphasis>irc.freenode.net</emphasis>, channel
|
||
<emphasis>#videolan</emphasis>
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
If you find a bug, please follow the instructions on
|
||
the <ulink url="http://www.videolan.org/support/bug-reporting.html">
|
||
bug reporting page</ulink>
|
||
|
||
.</para>
|
||
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1><title>
|
||
Command line usage
|
||
|
||
</title>
|
||
|
||
<itemizedlist>
|
||
|
||
|
||
<listitem><para>
|
||
|
||
VLC has many different graphical interfaces, that
|
||
are organized quite differently in order to be in harmony with the
|
||
guidelines of each operating system supported. Documenting the use
|
||
of each graphical interface is too long, and some features are only
|
||
available via the command line interface. Therefore we decided to
|
||
document only the command line interface, but in many cases it shoud
|
||
be easy to guess how to use the graphical interface for the same use
|
||
!
|
||
|
||
|
||
</para></listitem>
|
||
|
||
<listitem><para>
|
||
VLS has a command line and a telnet interface, but no
|
||
graphical interface !
|
||
|
||
</para></listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
|
||
All the commands that show up in this document should be typed
|
||
inside a terminal.
|
||
.</para>
|
||
|
||
<sect2><title>
|
||
Open a terminal
|
||
|
||
</title>
|
||
|
||
<simplesect><title>Windows</title>
|
||
|
||
<para>
|
||
Click on <emphasis>Start</emphasis>,
|
||
<emphasis>Run</emphasis> and type :
|
||
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para><command moreinfo="none">cmd</command> <keycap moreinfo="none">Enter</keycap>
|
||
(Windows 2000 / XP),</para></listitem>
|
||
|
||
<listitem><para><command moreinfo="none">command</command> <keycap moreinfo="none">Enter</keycap>
|
||
(Windows 95 / 98 / ME).</para></listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
The terminal appears
|
||
Le terminal apparait
|
||
</para>
|
||
|
||
<figure float="0"><title>Windows terminal</title>
|
||
<mediaobject>
|
||
<imageobject>
|
||
<imagedata fileref="images/terminal-windows.jpg" format="JPG" scalefit="1" scale="60"/>
|
||
</imageobject>
|
||
</mediaobject>
|
||
</figure>
|
||
|
||
<note><para>
|
||
Under Windows, you need to be in the directory where the
|
||
program is installed to run it.
|
||
</para></note>
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>Linux / Unix</title>
|
||
|
||
<para>
|
||
Open a terminal
|
||
|
||
:</para>
|
||
|
||
<figure float="0"><title>Linux X terminal</title>
|
||
<mediaobject>
|
||
<imageobject>
|
||
<imagedata fileref="images/terminal-linux.jpg" format="JPG" scalefit="1" scale="60"/>
|
||
</imageobject>
|
||
</mediaobject>
|
||
</figure>
|
||
|
||
<para>
|
||
In the documentation, we adopt the following
|
||
conventions for the Unix commands :
|
||
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para>
|
||
commands that should be typed as
|
||
<emphasis>root</emphasis> have a <command moreinfo="none">#</command> prompt :
|
||
|
||
</para>
|
||
|
||
<screen format="linespecific">
|
||
<prompt moreinfo="none"># </prompt><userinput moreinfo="none">command_to_be_typed_as_root</userinput>
|
||
</screen>
|
||
|
||
</listitem>
|
||
|
||
<listitem><para>
|
||
commands that should be typed as a regular user have a
|
||
<command moreinfo="none">%</command> prompt :
|
||
|
||
</para>
|
||
|
||
<screen format="linespecific">
|
||
<prompt moreinfo="none">% </prompt><userinput moreinfo="none">command_to_be_typed_as_regular_user</userinput>
|
||
</screen>
|
||
|
||
</listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>Mac OS X</title>
|
||
|
||
<para>
|
||
|
||
Go to <emphasis>Applications</emphasis>, open the
|
||
folder <emphasis>Utilities</emphasis> and double-click on
|
||
<emphasis>Terminal</emphasis>
|
||
|
||
:</para>
|
||
|
||
<figure float="0"><title>Mac OS X terminal</title>
|
||
<mediaobject>
|
||
<imageobject>
|
||
<imagedata fileref="images/terminal-macosx.jpg" format="JPG" scalefit="1" scale="60"/>
|
||
</imageobject>
|
||
</mediaobject>
|
||
</figure>
|
||
|
||
<note><para>
|
||
Under Mac OS X, you need to be in the directory where
|
||
the program is installed to run it, and start the command with
|
||
<command moreinfo="none">./</command>
|
||
|
||
.</para></note>
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>BeOS</title>
|
||
|
||
<para>
|
||
In the deskbar, go to <emphasis>Application</emphasis> and then
|
||
<emphasis>Terminal</emphasis> :
|
||
</para>
|
||
|
||
<figure float="0"><title>BeOS terminal</title>
|
||
<mediaobject>
|
||
<imageobject>
|
||
<imagedata fileref="images/terminal-beos.jpg" format="JPG" scalefit="1" scale="60"/>
|
||
</imageobject>
|
||
</mediaobject>
|
||
</figure>
|
||
|
||
<note><para>
|
||
Under BeOS, you need to be in the directory where
|
||
the program is installed to run it, and start the command with
|
||
<command moreinfo="none">./</command>
|
||
|
||
.</para></note>
|
||
|
||
</simplesect>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
</chapter>
|
||
|
||
|
||
|
||
<chapter id="install"><title id="tinstall">
|
||
Installing VLS
|
||
</title>
|
||
|
||
<sect1><title>
|
||
Installing VLS
|
||
</title>
|
||
|
||
|
||
<sect2><title>Windows</title>
|
||
|
||
<para>
|
||
Download the ZIP file from the <ulink url="http://www.videolan.org/streaming/download-vls-windows.html">VLS
|
||
Windows download page</ulink>, unzip-it and run
|
||
<filename moreinfo="none">setup.exe</filename>
|
||
|
||
.</para>
|
||
|
||
</sect2>
|
||
|
||
<sect2><title>GNULinux & Mac OS X</title>
|
||
|
||
<simplesect><title>
|
||
Install the libraries
|
||
|
||
</title>
|
||
|
||
<para>
|
||
Many libraries are needed for particular uses
|
||
|
||
</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para><emphasis>libdvbpsi</emphasis>
|
||
(always needed)
|
||
|
||
</para></listitem>
|
||
|
||
<listitem><para><emphasis>libdvdcss</emphasis>
|
||
if you want to be able to access encrypted DVDs
|
||
|
||
,</para></listitem>
|
||
|
||
<listitem><para><emphasis>libdvdread</emphasis>
|
||
if you want to be able to stream DVDs
|
||
|
||
,</para></listitem>
|
||
|
||
<listitem><para><emphasis>libdvb</emphasis>
|
||
if you want to be able to stream from a DVB card (a
|
||
satellite card or a digital terrestial TV card)
|
||
|
||
.</para></listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
Download the libraries from the <ulink url="http://www.videolan.org/streaming/download-vls-sources.html">VLS
|
||
sources download page</ulink>
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
For each library, uncompress, configure
|
||
(unless for <emphasis>libdvb</emphasis> which doesn't have a
|
||
<emphasis>./configure</emphasis>), compile and install
|
||
|
||
:</para>
|
||
|
||
<screen format="linespecific">
|
||
<prompt moreinfo="none">% </prompt><userinput moreinfo="none">tar xvzf library.tar.gz</userinput>
|
||
<prompt moreinfo="none">% </prompt><userinput moreinfo="none">cd library</userinput>
|
||
<prompt moreinfo="none">% </prompt><userinput moreinfo="none">./configure</userinput>
|
||
<prompt moreinfo="none">% </prompt><userinput moreinfo="none">make</userinput>
|
||
<prompt moreinfo="none"># </prompt><userinput moreinfo="none">make install</userinput>
|
||
</screen>
|
||
|
||
<para>
|
||
Check that the configuration file
|
||
<filename moreinfo="none">/etc/ld.so.conf</filename> contains the following line
|
||
|
||
:</para>
|
||
<programlisting format="linespecific">
|
||
/usr/local/lib
|
||
</programlisting>
|
||
|
||
<para>
|
||
If the line is not present, add-it and then run
|
||
|
||
:</para>
|
||
|
||
<screen format="linespecific">
|
||
<prompt moreinfo="none"># </prompt><userinput moreinfo="none">ldconfig</userinput>
|
||
</screen>
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>
|
||
Install VLS
|
||
|
||
</title>
|
||
|
||
<para>
|
||
Download the sources of the latest release : get
|
||
the file <filename moreinfo="none">vls-version.tar.gz</filename> from the <ulink url="http://www.videolan.org/streaming/download-vls-sources.html">VLS
|
||
sources download page</ulink>. Uncompress-it and generate
|
||
<emphasis>./configure</emphasis>
|
||
|
||
:</para>
|
||
|
||
<screen format="linespecific">
|
||
<prompt moreinfo="none">% </prompt><userinput moreinfo="none">tar xvzf vls-version.tar.gz</userinput>
|
||
<prompt moreinfo="none">% </prompt><userinput moreinfo="none">cd vls-version</userinput>
|
||
</screen>
|
||
|
||
<para>
|
||
To get the list of configuration options, do
|
||
|
||
</para>
|
||
|
||
<screen format="linespecific">
|
||
<prompt moreinfo="none">% </prompt><userinput moreinfo="none">./configure --help</userinput>
|
||
</screen>
|
||
|
||
<para>
|
||
Then configure vls
|
||
|
||
:</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para>
|
||
if you want a basic VLS without DVD support, do
|
||
|
||
:</para>
|
||
|
||
<screen format="linespecific">
|
||
<prompt moreinfo="none">% </prompt><userinput moreinfo="none">./configure --disable-dvd</userinput>
|
||
</screen>
|
||
|
||
</listitem>
|
||
|
||
<listitem><para>
|
||
if you want a VLS with DVD support, do
|
||
|
||
:</para>
|
||
|
||
<screen format="linespecific">
|
||
<prompt moreinfo="none">% </prompt><userinput moreinfo="none">./configure</userinput>
|
||
</screen>
|
||
|
||
</listitem>
|
||
|
||
<listitem><para>
|
||
if you want a VLS with DVB support, do
|
||
|
||
:</para>
|
||
|
||
<screen format="linespecific">
|
||
<prompt moreinfo="none">% </prompt><userinput moreinfo="none">./configure --enable-dvb --with-dvb=PATH_TO_DVB_DRIVERS --with-libdvb=PATH_TO_LIBDVB</userinput>
|
||
</screen>
|
||
|
||
</listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
Then, compile and install
|
||
|
||
:</para>
|
||
|
||
<screen format="linespecific">
|
||
<prompt moreinfo="none">% </prompt><userinput moreinfo="none">make</userinput>
|
||
<prompt moreinfo="none"># </prompt><userinput moreinfo="none">make install</userinput>
|
||
</screen>
|
||
|
||
<para>
|
||
You can also do a <command moreinfo="none">make uninstall</command>,
|
||
<command moreinfo="none">make clean</command> or <command moreinfo="none">make distclean</command> as
|
||
needed
|
||
|
||
.</para>
|
||
|
||
</simplesect>
|
||
|
||
</sect2>
|
||
|
||
</sect1>
|
||
|
||
<sect1><title>
|
||
Uninstalling VLS
|
||
</title>
|
||
|
||
|
||
<sect2><title>Windows</title>
|
||
|
||
<para>
|
||
Go to the <emphasis>Control Panel</emphasis>,
|
||
click on <emphasis>Add and remove programs</emphasis>, select
|
||
<emphasis>VLS</emphasis> and click on <emphasis>Modify/Remove</emphasis>
|
||
and follow the steps to uninstall the program
|
||
|
||
.</para>
|
||
|
||
</sect2>
|
||
|
||
<sect2><title>
|
||
If you compiled VLS from sources
|
||
|
||
</title>
|
||
|
||
<para>
|
||
Go to the directory containing VLS sources and run
|
||
:</para>
|
||
|
||
<screen format="linespecific">
|
||
<prompt moreinfo="none"># </prompt><userinput moreinfo="none">make uninstall</userinput>
|
||
</screen>
|
||
|
||
<para>
|
||
Then you can remove the VLS sources
|
||
|
||
.</para>
|
||
|
||
</sect2>
|
||
|
||
</sect1>
|
||
|
||
</chapter>
|
||
|
||
|
||
|
||
<chapter id="overview"><title id="toverview">
|
||
Overview and basic concepts
|
||
|
||
</title>
|
||
|
||
<sect1><title>
|
||
VLS structure
|
||
</title>
|
||
|
||
<para>
|
||
From a user's point of view, VLS can be divided into
|
||
four kinds of components
|
||
|
||
:</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para>
|
||
a <emphasis>manager</emphasis>
|
||
|
||
,</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>inputs
|
||
</emphasis>,</para></listitem>
|
||
<listitem><para><emphasis>
|
||
converters
|
||
</emphasis>,</para></listitem>
|
||
<listitem><para>
|
||
|
||
et des <emphasis>sorties</emphasis>
|
||
.</para></listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<figure float="0"><title>
|
||
VLS structure
|
||
</title>
|
||
<mediaobject>
|
||
<imageobject>
|
||
<imagedata fileref="images/archi-vls.jpg" format="JPG" scalefit="1" scale="60"/>
|
||
</imageobject>
|
||
</mediaobject>
|
||
</figure>
|
||
|
||
<simplesect><title>
|
||
Input
|
||
</title>
|
||
|
||
<para>
|
||
The role of an <emphasis>input</emphasis> is to
|
||
read MPEG streams from a given source (file, DVD, DVB card, device,
|
||
...), and feed the right <emphasis>converters</emphasis> with these
|
||
streams. An input may be able to read several streams, which are called
|
||
<emphasis>programs</emphasis>. There are several kinds of inputs
|
||
|
||
:</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para>
|
||
the <emphasis>local</emphasis> input, which can read
|
||
videos from files or DVDs
|
||
|
||
,</para></listitem>
|
||
|
||
<listitem><para>
|
||
|
||
the <emphasis>video</emphasis> input, which
|
||
can read videos from MPEG encoding cards devices
|
||
|
||
,</para></listitem>
|
||
|
||
<listitem><para>
|
||
the <emphasis>dvb</emphasis> input, which
|
||
can read videos from DVB cards,
|
||
l'entr<74>e <emphasis>dvb</emphasis>, qui peut
|
||
lire depuis des cartes DVB,</para></listitem>
|
||
|
||
<listitem><para>
|
||
the <emphasis>v4l</emphasis> input, which
|
||
can read from acquisition cards supported by the Video4Linux
|
||
drivers
|
||
|
||
.</para></listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
You can use several inputs and play several programs
|
||
at the same time
|
||
|
||
.</para>
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>
|
||
Converter
|
||
|
||
</title>
|
||
|
||
<para>
|
||
The role of a <emphasis>converter</emphasis> is to
|
||
receive a stream from an input, and convert it into the MPEG-TS format.
|
||
VLS is able to convert PS streams (from DVDs, for instance) into TS
|
||
streams (ps2ts converter). Of course, it can also read TS streams, and
|
||
fix them by handling stream discontinuities (ts2ts converter)
|
||
|
||
.</para>
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>
|
||
Channel
|
||
|
||
</title>
|
||
|
||
<para>
|
||
|
||
A <emphasis>channel</emphasis> receives a stream from a
|
||
converter, and send it to a given destination (network, file, ...).
|
||
If you want, you can call a "channel" an "output": it is the
|
||
same thing !). Currently, two kinds of channels are supported:
|
||
<emphasis>network</emphasis> and <emphasis>file</emphasis>. Note that,
|
||
at the moment, VLS can support only one output per
|
||
stream, so you cannot play a stream on the network and write it into
|
||
a file at the same time. The network output is highly configurable:
|
||
you can choose which network interface you want to use, and specify
|
||
source and destination IP addresses
|
||
|
||
|
||
|
||
.</para>
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>
|
||
Manager
|
||
|
||
</title>
|
||
|
||
<para>
|
||
The <emphasis>manager</emphasis> controls
|
||
the way streams are sent. Through an <emphasis>administration
|
||
interface</emphasis>, you can tell the manager to start, stop,
|
||
suspend, resume, forward or rewind the different programs. You
|
||
can also get a list of all programs available in the Program
|
||
Table. The manager gets this table from the VLS configuration file
|
||
(<filename moreinfo="none">vls.cfg</filename>), so it cannot be changed once VLS has
|
||
been started. At the moment, you cannot ask the manager whether a given
|
||
stream is being broadcasted, but you will get an error message if you
|
||
try to stop a stream that was not broadcasted
|
||
|
||
.</para>
|
||
|
||
</simplesect>
|
||
</sect1>
|
||
|
||
<sect1><title>
|
||
Administration interface
|
||
|
||
</title>
|
||
|
||
<para>
|
||
There are currently two ways to launch the
|
||
streaming
|
||
|
||
:</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para>
|
||
you can use the <emphasis>command line</emphasis> to
|
||
give arguments at startup;
|
||
|
||
</para></listitem>
|
||
|
||
<listitem><para>
|
||
or you can use the <emphasis>telnet
|
||
interface</emphasis> to start/stop/pause the streaming whenever you
|
||
want
|
||
|
||
.</para></listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
When using the telnet interface, you must
|
||
authenticate before typing any command, because any user may not
|
||
be allowed to execute any command (this can be configured in the
|
||
<filename moreinfo="none">vls.cfg</filename> configuration file)
|
||
|
||
.</para>
|
||
|
||
</sect1>
|
||
</chapter>
|
||
|
||
|
||
|
||
<chapter id="config"><title id="tconfig">Configuration</title>
|
||
|
||
<para>
|
||
VLS reads its configuration from the
|
||
<filename moreinfo="none">vls.cfg</filename> configuration file, which
|
||
is supposed to be located in the current directory or
|
||
in <filename moreinfo="none">SYSCONF_DIR/videolan/vls</filename> (where
|
||
<emphasis>SYSCONF_DIR</emphasis> is <filename moreinfo="none">/usr/local/etc</filename>
|
||
if you built and installed VLS by hand, or is <filename moreinfo="none">/etc</filename>
|
||
if you installed the debian binary package)
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
To write a <filename moreinfo="none">vls.cfg</filename> file, use the one supplied
|
||
with VLS as a start-point
|
||
|
||
|
||
|
||
.</para>
|
||
|
||
<sect1><title>
|
||
General structure
|
||
|
||
</title>
|
||
|
||
<para>
|
||
VLS configuration file <filename moreinfo="none">vls.cfg</filename>
|
||
is divided into sections, and each section may contain several
|
||
variables
|
||
|
||
:</para>
|
||
<programlisting format="linespecific">
|
||
|
||
BEGIN "FirstSection"
|
||
Variable1 = "value1"
|
||
Variable2 = "value2"
|
||
[...]
|
||
END
|
||
|
||
BEGIN "SecondSection"
|
||
Variable1 = "value1"
|
||
Variable3 = "value3"
|
||
[...]
|
||
END
|
||
|
||
|
||
[...]
|
||
</programlisting>
|
||
|
||
<para>
|
||
All section names, variable names and values are not
|
||
case-sensitive. There can be empty sections and subsections. Comments
|
||
must follow a <keycap moreinfo="none">#</keycap> 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
|
||
|
||
.</para>
|
||
|
||
</sect1>
|
||
|
||
<sect1><title>
|
||
Writing a <filename moreinfo="none">vls.cfg</filename>
|
||
|
||
</title>
|
||
|
||
<para>
|
||
Here is an explanation of all the sections you can
|
||
find in a <filename moreinfo="none">vls.cfg</filename>
|
||
|
||
:</para>
|
||
|
||
<sect2><title>Section "Vls"</title>
|
||
|
||
<para>
|
||
This section contains application wide settings
|
||
|
||
.</para>
|
||
|
||
<programlisting format="linespecific">
|
||
LogFile = "name"
|
||
</programlisting>
|
||
|
||
<para>
|
||
Name of VLS log file. If left empty "", then no
|
||
logging to files is done. Default is "vls.log"
|
||
|
||
.</para>
|
||
|
||
<programlisting format="linespecific">
|
||
SystemLog = "[disable|enable]"
|
||
</programlisting>
|
||
|
||
<para>
|
||
Logging to the SystemLog. Today, only the SystemLog
|
||
using syslogd is implemented: compile with <command moreinfo="none">./configure
|
||
--enable-syslog</command>
|
||
|
||
.</para>
|
||
|
||
<caution><para>
|
||
If VLS is started as <command moreinfo="none">vlsd</command>, then
|
||
the following configuration is mandatory
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "Vls"
|
||
LogFile = ""
|
||
SystemLog = "enabled"
|
||
ScreenLog = "disabled"
|
||
END
|
||
</programlisting>
|
||
|
||
</caution>
|
||
|
||
<programlisting format="linespecific">
|
||
ScreenLog = "[disable|enable]"
|
||
</programlisting>
|
||
|
||
<para>
|
||
Logging to the console
|
||
.</para>
|
||
|
||
<para>
|
||
Example
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "Vls"
|
||
LogFile = "vls.log"
|
||
SystemLog = "disable"
|
||
ScreenLog = "enable"
|
||
END
|
||
</programlisting>
|
||
|
||
</sect2>
|
||
|
||
<sect2><title>Section "Groups"</title>
|
||
|
||
<para>
|
||
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
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
groupname = "command1|command2|..."
|
||
</programlisting>
|
||
|
||
<para>
|
||
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, forward,
|
||
rewind, stop, shutdown, logout
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
Example
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "Groups"
|
||
monitor = "help|browse|logout"
|
||
master = "help|browse|start|resume|suspend|forward|rewind|stop|shutdown|logout"
|
||
END
|
||
</programlisting>
|
||
|
||
</sect2>
|
||
|
||
<sect2><title>Section "Users"</title>
|
||
|
||
<para>
|
||
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
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
username = "password:groupname"
|
||
</programlisting>
|
||
|
||
<para>
|
||
This adds a user "username", who belongs to the
|
||
group "groupname" (defined in the "Groups" section) and can log in with
|
||
the password "password"
|
||
|
||
.</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para>
|
||
Under Unix/Linux, the password must be encrypted,
|
||
with a tool such as <command moreinfo="none">mkpasswd</command>, or with the UNIX
|
||
function "crypt"
|
||
|
||
.</para></listitem>
|
||
|
||
<listitem><para>
|
||
Under Windows, the password must be in clear text
|
||
|
||
.</para></listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
Example for Unix/Linux
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "Users"
|
||
monitor = "3BcKWoiQn0vi6:monitor" # password is 'monitor'
|
||
admin = "42BKiCguFAL/c:master" # password is 'Vir4Gv5S'
|
||
END
|
||
</programlisting>
|
||
|
||
</sect2>
|
||
|
||
<sect2><title>Section "Telnet"</title>
|
||
|
||
<para>
|
||
In this section, you can configure the telnet
|
||
administration interface
|
||
|
||
.</para>
|
||
|
||
<programlisting format="linespecific">
|
||
LocalPort = "port"
|
||
</programlisting>
|
||
|
||
<para>
|
||
Defines which port will be used for the telnet
|
||
server. Default port is "9999"
|
||
|
||
.</para>
|
||
|
||
<programlisting format="linespecific">
|
||
Domain = "domain"
|
||
</programlisting>
|
||
|
||
<para>
|
||
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"
|
||
|
||
.</para>
|
||
|
||
<programlisting format="linespecific">
|
||
LocalAddress = "IP address"
|
||
</programlisting>
|
||
|
||
<para>
|
||
Defines on which IP address the telnet server will
|
||
listen for requests. Default address is "0.0.0.0" (or "0::0" with
|
||
IPv6)
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
Example
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "Telnet"
|
||
LocalPort = "9999"
|
||
END
|
||
</programlisting>
|
||
</sect2>
|
||
|
||
<sect2><title>Section "NativeAdmin"</title>
|
||
|
||
<para>
|
||
Same syntax as "Telnet". Not used yet
|
||
|
||
.</para>
|
||
|
||
</sect2>
|
||
|
||
<sect2><title>Section "Inputs"</title>
|
||
|
||
<para>
|
||
In this section, you can define which inputs you
|
||
want to use. For each input you need, add a line in the following
|
||
format
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
InputName = "Type"
|
||
</programlisting>
|
||
|
||
<para>
|
||
This adds a input named "InputName", the type
|
||
of which is "Type". As explained before, there are several types of
|
||
input
|
||
|
||
:</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para>
|
||
|
||
"local" to play a stream from a file or a DVD
|
||
|
||
,</para></listitem>
|
||
|
||
<listitem><para>
|
||
"video" to play a stream from an MPEG encoding
|
||
card
|
||
|
||
,</para></listitem>
|
||
|
||
<listitem><para>
|
||
"dvb" to play a stream from a DVB card
|
||
|
||
,</para></listitem>
|
||
|
||
<listitem><para>
|
||
"v4l" to play a stream from a Video4Linux device
|
||
|
||
.</para></listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
Each input must be configured in its own section
|
||
(see next paragraph)
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
Example
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "Inputs"
|
||
local1 = "local"
|
||
pvr = "video"
|
||
dvb1 = "dvb"
|
||
tuner = "v4l"
|
||
END
|
||
</programlisting>
|
||
</sect2>
|
||
|
||
<sect2><title>
|
||
Inputs configuration
|
||
|
||
</title>
|
||
|
||
<para>
|
||
For each input declared in the "Inputs" section,
|
||
excepted "local" inputs, you must add a section with the same name as
|
||
the corresponding input. For instance, if you declared an input "pvr",
|
||
there should be one section named "pvr" too. The syntax of such sections
|
||
depends on the type of the corresponding input
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
To configure a local input, you don't have to do
|
||
anything. Except when another trickplay strategy must be used
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "Local1"
|
||
ProgramCount = "1"
|
||
TrickPlay = "normal"
|
||
END
|
||
</programlisting>
|
||
|
||
<para>
|
||
"Local1" is the name of the local input you want to
|
||
configure. "ProgramCount" is the number of programs assigned to this
|
||
input. "TrickPlay" is the trickplay strategy that is used by this input
|
||
(default is "normal")
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
To configure a video input, add a section in the
|
||
following format
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "VideoInputName"
|
||
Device = "device"
|
||
Type = "type"
|
||
END
|
||
</programlisting>
|
||
|
||
<para>
|
||
"VideoInputName" is the name of the video input you
|
||
want to configure. "Device" is the path of the MPEG encoding card 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")
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
Example for a Hauppauge WinTV-PVR-250 card
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "pvr"
|
||
Device = "/dev/video0"
|
||
Type = "Mpeg2-PS"
|
||
END
|
||
</programlisting>
|
||
|
||
<para>
|
||
To configure a dvb input, add a section in the
|
||
following format
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "DvbInputName"
|
||
DeviceNumber = "devicenumber"
|
||
SendMethod = "0"
|
||
END
|
||
</programlisting>
|
||
|
||
<para>
|
||
"DvbInputName" is the name of the dvb input you
|
||
want to configure. Set "SendMethod" to "0" if you to stream the
|
||
complete DVB stream and set it to "1" if you only want to stream
|
||
the MPEG audio and video streams (default is "0"). "DeviceNumber"
|
||
is the number of the DVB device you want to read from (read
|
||
from <filename moreinfo="none">/dev/ost/dvr<devicenumber></filename>,
|
||
default is ""). The dvb configuration file is defined by the
|
||
driver. You can find it in <filename moreinfo="none">$HOME/.dvbrc</filename> for
|
||
/dev/dvb/adapter0 or in <filename moreinfo="none">$HOME/.dvbrc.X</filename> for
|
||
<filename moreinfo="none">/dev/dvb/adapterX</filename>
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
Example
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "dvb1"
|
||
DeviceNumber = "0"
|
||
TrickPlay = "normal"
|
||
END
|
||
</programlisting>
|
||
|
||
</sect2>
|
||
|
||
<sect2><title>Section "Channels"</title>
|
||
|
||
<para>
|
||
In this section, you can define the channels
|
||
(outputs) you want to use. For each channel, write a line in the
|
||
following format
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
ChannelName = "Type"
|
||
</programlisting>
|
||
|
||
<para>
|
||
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
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
Example
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "Channels"
|
||
localhost = "network"
|
||
client1 = "network"
|
||
client2 = "network"
|
||
multicast1 = "network"
|
||
multicast2 = "network"
|
||
localfile = "file"
|
||
END
|
||
</programlisting>
|
||
|
||
</sect2>
|
||
|
||
<sect2><title>
|
||
Channels configuration
|
||
|
||
</title>
|
||
|
||
<para>
|
||
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
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
To configure a network channel, add a section in the
|
||
following format
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "NetChannelName"
|
||
Domain = "Domain"
|
||
Type = "Type"
|
||
SrcHost = "SourceHost"
|
||
SrcPort = "SourcePort"
|
||
DstHost = "DestHost"
|
||
DstPort = "DestPort"
|
||
TTL = "ttl"
|
||
Interface = "Interface"
|
||
END
|
||
</programlisting>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para>
|
||
"NetChannelName" is the name of the network channel
|
||
you want to configure
|
||
|
||
.</para></listitem>
|
||
|
||
<listitem><para>
|
||
"Domain" is either "inet4" if you use IPv4
|
||
addresses, or "inet6" if you use IPv6 (default is "inet4")
|
||
|
||
.</para></listitem>
|
||
|
||
<listitem><para>
|
||
"Type" is either "unicast", "broadcast" or
|
||
"multicast" (default is "unicast"), depending on what you want to do
|
||
(and on your "DstHost" address)
|
||
|
||
.</para></listitem>
|
||
|
||
<listitem><para>
|
||
"SourceHost" is the IP address (or DNS name) from
|
||
which VLS will send the stream
|
||
|
||
.</para></listitem>
|
||
|
||
<listitem><para>
|
||
"SourcePort" is the UDP port from which the stream
|
||
will be sent
|
||
|
||
.</para></listitem>
|
||
|
||
<listitem><para>
|
||
"DestHost" is the IP address (or DNS name) to which
|
||
the stream will be sent
|
||
|
||
.</para></listitem>
|
||
|
||
<listitem><para>
|
||
"DestPort" is the UDP port to which the stream will
|
||
be sent (default is "1234")
|
||
|
||
.</para></listitem>
|
||
|
||
<listitem><para>
|
||
"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
|
||
|
||
.</para></listitem>
|
||
|
||
<listitem><para>
|
||
"Interface" is an option only supported under
|
||
GNU/Linux, to force the stream to be sent through a given network
|
||
interface, "eth1" for instance" (to use this option, you must have
|
||
super-user permissions)
|
||
|
||
.</para></listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<note><para>
|
||
"SrcHost" and "SrcPort" are optional (if you don't
|
||
set them, VLS will not 'bind' the socket)
|
||
|
||
.</para></note>
|
||
|
||
<para>
|
||
To configure a file channel, add a section in the
|
||
following format
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "FileChannelName"
|
||
FileName = "file"
|
||
Append = "append"
|
||
END
|
||
</programlisting>
|
||
|
||
<para>
|
||
"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
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
Example
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
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 in IPv6
|
||
Domain = "inet6"
|
||
DstHost = "3ffe:ffff::2:12:42"
|
||
DstPort = "1234"
|
||
END
|
||
|
||
BEGIN "multicast1" # multicast streaming
|
||
Type = "multicast"
|
||
DstHost = "239.2.12.42"
|
||
DstPort = "1234"
|
||
TTL = "2"
|
||
END
|
||
|
||
BEGIN "multicast2" # multicast streaming in IPv6
|
||
Domain = "inet6"
|
||
Type = "multicast"
|
||
DstHost = "ff08::1"
|
||
DstPort = "1234"
|
||
TTL = "12"
|
||
END
|
||
|
||
BEGIN "localfile" # file output
|
||
FileName = "stream.ts"
|
||
Append = "no"
|
||
END
|
||
</programlisting>
|
||
|
||
<caution><para>
|
||
If you use Windows, you should specify the "SrcHost"
|
||
and "SrcPort" fields. For example
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "client1" # The client is on the same host as the server
|
||
SrcHost = "192.168.1.1" # IP of VLS
|
||
SrcPort = "1242" # Source port : the value is not important
|
||
DstHost = "192.168.1.2" # IP of the client
|
||
DstPort = "1234"
|
||
END
|
||
</programlisting>
|
||
|
||
</caution>
|
||
|
||
</sect2>
|
||
|
||
<sect2><title>
|
||
Programs Configuration
|
||
|
||
</title>
|
||
|
||
<para>
|
||
As explained before, you must define the programs.
|
||
Each one is a MPEG stream (a file, for example). To do this, you must
|
||
add an "Input" section in your <filename moreinfo="none">vls.cfg</filename> file. Each
|
||
"Input" section must have the following syntax
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "Input"
|
||
FilesPath = "path"
|
||
ProgramCount = "count"
|
||
END
|
||
</programlisting>
|
||
|
||
<para>
|
||
"path" is the path where your MPEG files are located
|
||
(by default it is the current directory). "count" is the number of
|
||
programs defined ("0" by default)
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
For each program you want to define, you must add a
|
||
section with the following format
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
BEGIN "number"
|
||
Name = "name"
|
||
Type = "type"
|
||
FileName = "file"
|
||
Device = "device"
|
||
END
|
||
</programlisting>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para>
|
||
"number" is the program number: the first program
|
||
has number 1, the second number 2, and so on
|
||
|
||
.</para></listitem>
|
||
|
||
<listitem><para>
|
||
"name" is the program name, by which you will tell
|
||
VLS to start this program (see next chapter "Running VLS")
|
||
|
||
.</para></listitem>
|
||
|
||
<listitem><para>
|
||
"type" can be "Mpeg1-PS", "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
|
||
|
||
.</para></listitem>
|
||
|
||
<listitem><para>
|
||
if "type" is set to "Mpeg1-PS", "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)
|
||
|
||
.</para></listitem>
|
||
|
||
<listitem><para>
|
||
if "type" is "DVD", the variable "Device" will be
|
||
used instead of "FileName" (the variable "FilesPath" is not prepended
|
||
to the device name !). The variable "Device" is the device of your DVD
|
||
drive ("/dev/hdc" or "/dev/cdrom" for instance). You can also play a DVD
|
||
copied on a hard disk: then "device" is the directory where the .vob
|
||
files are stored ("/mnt/data/VIDEO_TS" for instance)
|
||
|
||
.</para></listitem>
|
||
</itemizedlist>
|
||
|
||
<note>
|
||
|
||
|
||
<para>
|
||
VLS can stream MPEG files that meet two critera
|
||
:</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para>
|
||
the file must be MPEG <emphasis>PS</emphasis>
|
||
(Program Stream) or MPEG <emphasis>TS</emphasis> (Transport Stream),
|
||
that contain video and audio multiplexed. VLS cannot stream MPEG
|
||
<emphasis>ES</emphasis> (Elementary Stream), i.e. a file with only audio
|
||
or video
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
In order to know if an MPEG file is MPEG
|
||
<emphasis>PS</emphasis>, MPEG <emphasis>TS</emphasis> or MPEG
|
||
<emphasis>ES</emphasis>, read the file with VLC and look at the messages
|
||
(select in the menu <emphasis>View / Messages</emphasis>, or use the
|
||
command line <command moreinfo="none">vlc -vvv</command>)
|
||
|
||
.</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem><para>
|
||
If you see a line
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
[00000107] main module debug: using demux module "ts_dvbpsi"
|
||
</programlisting>
|
||
|
||
<para>
|
||
it means the file is MPEG TS
|
||
|
||
.</para></listitem>
|
||
|
||
|
||
<listitem><para>
|
||
If you see a line
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
[00000109] main module debug: using demux module "ps"
|
||
</programlisting>
|
||
|
||
<para>
|
||
it means the file is MPEG PS
|
||
|
||
.</para></listitem>
|
||
|
||
<listitem><para>
|
||
If you see a line
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
[00000109] main module debug: using demux module "es"
|
||
</programlisting>
|
||
|
||
<para>
|
||
it means the file is MPEG ES, VLS can't stream it.
|
||
|
||
.</para></listitem>
|
||
|
||
|
||
</itemizedlist>
|
||
|
||
</listitem>
|
||
|
||
<listitem><para>
|
||
the sequence header of the video must repeat itself
|
||
regularly, which is often the case with MPEG-2, but very rare with
|
||
MPEG-1. There is no easy way to know if the sequence header is repeated
|
||
regularly. Files with a <emphasis>.vob</emphasis> extension are
|
||
normally MPEG-2 files and files with <emphasis>.mpg</emphasis> or
|
||
<emphasis>.mpeg</emphasis> extension or usually MPEG-1 files
|
||
|
||
.</para>
|
||
|
||
</listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
You can download this
|
||
streamable MPEG-2 PS file for your tests : <ulink url="ftp://ftp.videolan.org/pub/videolan/streams/presentation/presentation_short.vob">presentation_short.vob</ulink>
|
||
|
||
.</para>
|
||
|
||
</note>
|
||
|
||
<note><para>
|
||
In order to play DVDs, you need to compile VLS with
|
||
DVD support, which uses libdvdread and libdvdcss. You will need
|
||
read <emphasis>and</emphasis> write access rights to the DVD
|
||
device
|
||
|
||
.</para></note>
|
||
|
||
|
||
<para>
|
||
Full example
|
||
|
||
:</para>
|
||
|
||
<programlisting format="linespecific">
|
||
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
|
||
</programlisting>
|
||
|
||
</sect2>
|
||
</sect1>
|
||
</chapter>
|
||
|
||
|
||
|
||
<chapter id="run"><title id="trun">
|
||
Running VLS
|
||
|
||
</title>
|
||
|
||
<sect1><title>
|
||
Launching VLS
|
||
|
||
</title>
|
||
|
||
<para>
|
||
If you want to use the telnet interface, running
|
||
VLS is very easy: just type <command moreinfo="none">vls</command> in a shell
|
||
console, and that's all. Running <command moreinfo="none">vlsd</command> will
|
||
start VLS as a daemon and will detach itself from the launching
|
||
shell. Remember that VLS will try to load its configuration file
|
||
(<filename moreinfo="none">vls.cfg</filename>) from the current directory, and if
|
||
there is no <filename moreinfo="none">vls.cfg</filename> there, it will try to load it
|
||
from <filename moreinfo="none">SYSCONF_DIR/etc/videolan</filename> (see section <xref linkend="config" endterm="tconfig"/>)
|
||
|
||
.</para>
|
||
|
||
<caution><para>
|
||
If your log file is <filename moreinfo="none">vls.log</filename> as
|
||
in the example, VLS will need write access in the current directory, or
|
||
you will see something like
|
||
|
||
:</para>
|
||
|
||
<screen format="linespecific"><computeroutput moreinfo="none">
|
||
*** 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
|
||
</computeroutput></screen>
|
||
|
||
<para>
|
||
Remember also that you must be root when using the
|
||
"Interface" option in <filename moreinfo="none">vls.cfg</filename>
|
||
|
||
.</para>
|
||
|
||
</caution>
|
||
|
||
<para>
|
||
|
||
If everything is right, you will see something like
|
||
:</para>
|
||
|
||
<screen format="linespecific"><computeroutput moreinfo="none">
|
||
VideoLAN Server v 0.5.3 (Jun 6 2003) - (c)1999-2003 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
|
||
[...]
|
||
</computeroutput></screen>
|
||
|
||
<para>
|
||
What you can see on the screen (stderr) is exactly
|
||
what goes in the log file <filename moreinfo="none">vls.log</filename>
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
When VLS has been successfully started, it doesn't
|
||
take any command from its standard input, so you can put it into
|
||
background (you can use the <emphasis>screen</emphasis> utility to do
|
||
that)
|
||
|
||
.</para>
|
||
|
||
<para>
|
||
On the other hand, if you want to
|
||
use the command line interface, please see the <ulink url="http://www.videolan.org/doc/">VideoLAN HOWTO</ulink>
|
||
|
||
.</para>
|
||
|
||
</sect1>
|
||
|
||
<sect1><title>
|
||
Using the telnet interface
|
||
|
||
</title>
|
||
|
||
<para>
|
||
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
|
||
|
||
:</para>
|
||
|
||
<screen format="linespecific">
|
||
<prompt moreinfo="none">% </prompt><userinput moreinfo="none">telnet localhost 9999</userinput>
|
||
</screen>
|
||
|
||
<para>
|
||
You should see something like
|
||
|
||
:</para>
|
||
|
||
<screen format="linespecific"><computeroutput moreinfo="none">
|
||
Trying 127.0.0.1...
|
||
Connected to vls.
|
||
Escape character is '^]'.
|
||
|
||
Videolan Server Administration System
|
||
|
||
Login:
|
||
</computeroutput></screen>
|
||
|
||
<para>
|
||
Then you must authenticate with a login/password
|
||
pair defined in <filename moreinfo="none">vls.cfg</filename>. When you have been
|
||
successfully authenticated, you should see a prompt like
|
||
|
||
:</para>
|
||
|
||
|
||
<screen format="linespecific"><computeroutput moreinfo="none">
|
||
admin@vls>
|
||
</computeroutput>></screen>
|
||
|
||
<para>
|
||
Then you can type some commands, which are explained
|
||
in the next paragraph. To log out, type <command moreinfo="none">logout</command> after
|
||
the telnet prompt
|
||
|
||
.</para>
|
||
|
||
</sect1>
|
||
|
||
<sect1><title>
|
||
Interface commands
|
||
</title>
|
||
|
||
<simplesect><title>help</title>
|
||
|
||
<para>
|
||
Usage: help [command]
|
||
.</para>
|
||
|
||
<para>
|
||
Called with no argument, "help" gives the list of
|
||
all the commands (available or not). Called with one argument it gives
|
||
details about how to use the specified command
|
||
|
||
.</para>
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>browse</title>
|
||
|
||
<para>
|
||
Usage: browse [input]
|
||
.</para>
|
||
|
||
<para>
|
||
Called without argument, "browse" gives all programs
|
||
of inputs. Called with one argument it only gives the programs of the
|
||
specified input. Each program is given with its status
|
||
|
||
.</para>
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>start</title>
|
||
|
||
<para>
|
||
|
||
Usage: start <program> <channel> <input> [--loop] [--rtp]
|
||
|
||
</para>
|
||
|
||
<para>
|
||
"start" launches the specified program of the
|
||
specified input and broadcasts it through the specified channel. The
|
||
option "--loop" makes the program being repeated indefinitely. The
|
||
option "--rtp" makes the TS packet to be send through the RTP protocol,
|
||
as defined in RFC 1889 and RFC 2250
|
||
|
||
.</para>
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>stop</title>
|
||
<para>
|
||
Usage: stop <channel>
|
||
|
||
</para>
|
||
<para>
|
||
"stop" ends the broadcast of the specified channel
|
||
|
||
.</para>
|
||
</simplesect>
|
||
|
||
<simplesect><title>forward</title>
|
||
|
||
<para>
|
||
Usage: forward <channel> <speed>
|
||
</para>
|
||
|
||
<para>
|
||
"forward" forwards the channel with the given speed.
|
||
This does not work when reading directly from a device such as an MPEG
|
||
encoding card, a DVB card or an acquisition card
|
||
|
||
.</para>
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>rewind</title>
|
||
|
||
<para>
|
||
Usage: rewind <channel> <speed>
|
||
</para>
|
||
<para> "rewind" rewinds the channel with the given
|
||
speed. This does not work when reading directly from a device such as an
|
||
MPEG encoding card, a DVB card or an acquisition card
|
||
.</para>
|
||
</simplesect>
|
||
|
||
<simplesect><title>suspend</title>
|
||
|
||
<para>
|
||
Usage: suspend <channel>
|
||
|
||
</para>
|
||
<para>
|
||
"suspend" suspends the streaming of the specified
|
||
channel
|
||
|
||
.</para>
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>resume</title>
|
||
|
||
<para>
|
||
Usage: resume <channel>
|
||
|
||
</para>
|
||
|
||
<para>
|
||
"resume" resumes the streaming of the specified
|
||
channel
|
||
|
||
.</para>
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>logout</title>
|
||
|
||
<para>
|
||
Usage: logout
|
||
</para>
|
||
|
||
<para>
|
||
"logout" closes the current administration session
|
||
and the remote connection
|
||
|
||
.</para>
|
||
|
||
</simplesect>
|
||
|
||
<simplesect><title>shutdown</title>
|
||
|
||
<para>
|
||
Usage: shutdown
|
||
</para>
|
||
|
||
<para>
|
||
"shutdown" stops all the programs and shutdowns VLS
|
||
.</para>
|
||
|
||
</simplesect>
|
||
|
||
</sect1>
|
||
</chapter>
|
||
|
||
<appendix id="gfdl">
|
||
<title id="tgfdl">GNU Free Documentation License</title>
|
||
<subtitle>Version 1.2, November 2002</subtitle>
|
||
|
||
<blockquote id="fsf-copyright">
|
||
<para>Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
|
||
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
||
Everyone is permitted to copy and distribute verbatim copies
|
||
of this license document, but changing it is not allowed.</para>
|
||
</blockquote>
|
||
|
||
<sect1 id="gfdl-0"><title>PREAMBLE</title>
|
||
|
||
<para>The purpose of this License is to make a manual, textbook, or
|
||
other functional and useful document "free" in the sense of freedom: to
|
||
assure everyone the effective freedom to copy and redistribute it, with
|
||
or without modifying it, either commercially or noncommercially.
|
||
Secondarily, this License preserves for the author and publisher a way
|
||
to get credit for their work, while not being considered responsible for
|
||
modifications made by others.</para>
|
||
|
||
<para>This License is a kind of "copyleft", which means that derivative
|
||
works of the document must themselves be free in the same sense. It
|
||
complements the GNU General Public License, which is a copyleft license
|
||
designed for free software.</para>
|
||
|
||
<para>We have designed this License in order to use it for manuals for
|
||
free software, because free software needs free documentation: a free
|
||
program should come with manuals providing the same freedoms that the
|
||
software does. But this License is not limited to software manuals; it
|
||
can be used for any textual work, regardless of subject matter or
|
||
whether it is published as a printed book. We recommend this License
|
||
principally for works whose purpose is instruction or reference.</para>
|
||
</sect1>
|
||
|
||
<sect1 id="gfdl-1"><title>APPLICABILITY AND DEFINITIONS</title>
|
||
|
||
<para id="gfdl-doc">This License applies to any manual or other work, in
|
||
any medium, that contains a notice placed by the copyright holder saying
|
||
it can be distributed under the terms of this License. Such a notice
|
||
grants a world-wide, royalty-free license, unlimited in duration, to use
|
||
that work under the conditions stated herein. The "Document", below,
|
||
refers to any such manual or work. Any member of the public is a
|
||
licensee, and is addressed as "you". You accept the license if you
|
||
copy, modify or distribute the work in a way requiring permission under
|
||
copyright law.</para>
|
||
|
||
<para id="gfdl-mod-ver">A "Modified Version" of the Document means any
|
||
work containing the Document or a portion of it, either copied verbatim,
|
||
or with modifications and/or translated into another language.</para>
|
||
|
||
<para id="gfdl-secnd-sect">A "Secondary Section" is a named appendix or
|
||
a front-matter section of the Document that deals exclusively with the
|
||
relationship of the publishers or authors of the Document to the
|
||
Document's overall subject (or to related matters) and contains nothing
|
||
that could fall directly within that overall subject. (Thus, if the
|
||
Document is in part a textbook of mathematics, a Secondary Section may
|
||
not explain any mathematics.) The relationship could be a matter of
|
||
historical connection with the subject or with related matters, or of
|
||
legal, commercial, philosophical, ethical or political position
|
||
regarding them.</para>
|
||
|
||
<para id="gfdl-inv-sect">The "Invariant Sections" are certain Secondary
|
||
Sections whose titles are designated, as being those of Invariant
|
||
Sections, in the notice that says that the Document is released under
|
||
this License. If a section does not fit the above definition of
|
||
Secondary then it is not allowed to be designated as Invariant. The
|
||
Document may contain zero Invariant Sections. If the Document does not
|
||
identify any Invariant Sections then there are none.</para>
|
||
|
||
<para id="gfdl-cov-text">The "Cover Texts" are certain short passages of
|
||
text that are listed, as Front-Cover Texts or Back-Cover Texts, in the
|
||
notice that says that the Document is released under this License. A
|
||
Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at
|
||
most 25 words.</para>
|
||
|
||
<para id="gfdl-transparent">A "Transparent" copy of the Document means a
|
||
machine-readable copy, represented in a format whose specification is
|
||
available to the general public, that is suitable for revising the
|
||
document straightforwardly with generic text editors or (for images
|
||
composed of pixels) generic paint programs or (for drawings) some widely
|
||
available drawing editor, and that is suitable for input to text
|
||
formatters or for automatic translation to a variety of formats suitable
|
||
for input to text formatters. A copy made in an otherwise Transparent
|
||
file format whose markup, or absence of markup, has been arranged to
|
||
thwart or discourage subsequent modification by readers is not
|
||
Transparent. An image format is not Transparent if used for any
|
||
substantial amount of text. A copy that is not "Transparent" is called
|
||
"Opaque".</para>
|
||
|
||
<para>Examples of suitable formats for Transparent copies include plain
|
||
ASCII without markup, Texinfo input format, LaTeX input format, SGML or
|
||
XML using a publicly available DTD, and standard-conforming simple HTML,
|
||
PostScript or PDF designed for human modification. Examples of
|
||
transparent image formats include PNG, XCF and JPG. Opaque formats
|
||
include proprietary formats that can be read and edited only by
|
||
proprietary word processors, SGML or XML for which the DTD and/or
|
||
processing tools are not generally available, and the machine-generated
|
||
HTML, PostScript or PDF produced by some word processors for output
|
||
purposes only.</para>
|
||
|
||
<para id="gfdl-title-page">The "Title Page" means, for a printed book,
|
||
the title page itself, plus such following pages as are needed to hold,
|
||
legibly, the material this License requires to appear in the title page.
|
||
For works in formats which do not have any title page as such, "Title
|
||
Page" means the text near the most prominent appearance of the work's
|
||
title, preceding the beginning of the body of the text.</para>
|
||
|
||
<para id="gfdl-entitled">A section "Entitled XYZ" means a named subunit
|
||
of the Document whose title either is precisely XYZ or contains XYZ in
|
||
parentheses following text that translates XYZ in another language.
|
||
(Here XYZ stands for a specific section name mentioned below, such as
|
||
"Acknowledgements", "Dedications", "Endorsements", or "History".) To
|
||
"Preserve the Title" of such a section when you modify the Document
|
||
means that it remains a section "Entitled XYZ" according to this
|
||
definition.</para>
|
||
|
||
<para>The Document may include Warranty Disclaimers next to the notice
|
||
which states that this License applies to the Document. These Warranty
|
||
Disclaimers are considered to be included by reference in this License,
|
||
but only as regards disclaiming warranties: any other implication that
|
||
these Warranty Disclaimers may have is void and has no effect on the
|
||
meaning of this License.</para>
|
||
</sect1>
|
||
|
||
<sect1 id="gfdl-2"><title>VERBATIM COPYING</title>
|
||
|
||
<para>You may copy and distribute the Document in any medium, either
|
||
commercially or noncommercially, provided that this License, the
|
||
copyright notices, and the license notice saying this License applies to
|
||
the Document are reproduced in all copies, and that you add no other
|
||
conditions whatsoever to those of this License. You may not use
|
||
technical measures to obstruct or control the reading or further copying
|
||
of the copies you make or distribute. However, you may accept
|
||
compensation in exchange for copies. If you distribute a large enough
|
||
number of copies you must also follow the conditions in section 3.
|
||
</para>
|
||
|
||
<para>You may also lend copies, under the same conditions stated above,
|
||
and you may publicly display copies.</para>
|
||
</sect1>
|
||
|
||
<sect1 id="gfdl-3"><title>COPYING IN QUANTITY</title>
|
||
|
||
<para>If you publish printed copies (or copies in media that commonly
|
||
have printed covers) of the Document, numbering more than 100, and the
|
||
Document's license notice requires Cover Texts, you must enclose the
|
||
copies in covers that carry, clearly and legibly, all these Cover Texts:
|
||
Front-Cover Texts on the front cover, and Back-Cover Texts on the back
|
||
cover. Both covers must also clearly and legibly identify you as the
|
||
publisher of these copies. The front cover must present the full title
|
||
with all words of the title equally prominent and visible. You may add
|
||
other material on the covers in addition. Copying with changes limited
|
||
to the covers, as long as they preserve the title of the Document and
|
||
satisfy these conditions, can be treated as verbatim copying in other
|
||
respects.</para>
|
||
|
||
<para>If the required texts for either cover are too voluminous to fit
|
||
legibly, you should put the first ones listed (as many as fit
|
||
reasonably) on the actual cover, and continue the rest onto adjacent
|
||
pages.</para>
|
||
|
||
<para>If you publish or distribute Opaque copies of the Document
|
||
numbering more than 100, you must either include a machine-readable
|
||
Transparent copy along with each Opaque copy, or state in or with each
|
||
Opaque copy a computer-network location from which the general
|
||
network-using public has access to download using public-standard
|
||
network protocols a complete Transparent copy of the Document, free of
|
||
added material. If you use the latter option, you must take reasonably
|
||
prudent steps, when you begin distribution of Opaque copies in quantity,
|
||
to ensure that this Transparent copy will remain thus accessible at the
|
||
stated location until at least one year after the last time you
|
||
distribute an Opaque copy (directly or through your agents or retailers)
|
||
of that edition to the public.</para>
|
||
|
||
<para>It is requested, but not required, that you contact the authors of
|
||
the Document well before redistributing any large number of copies, to
|
||
give them a chance to provide you with an updated version of the
|
||
Document.</para>
|
||
</sect1>
|
||
|
||
<sect1 id="gfdl-4"><title>MODIFICATIONS</title>
|
||
|
||
<para>You may copy and distribute a Modified Version of the Document
|
||
under the conditions of sections 2 and 3 above, provided that you
|
||
release the Modified Version under precisely this License, with the
|
||
Modified Version filling the role of the Document, thus licensing
|
||
distribution and modification of the Modified Version to whoever
|
||
possesses a copy of it. In addition, you must do these things in the
|
||
Modified Version:</para>
|
||
|
||
<orderedlist continuation="restarts" inheritnum="ignore" id="gfdl-modif-cond" numeration="upperalpha">
|
||
<listitem><simpara>Use in the Title Page (and on the covers, if any) a
|
||
title distinct from that of the Document, and from those of previous
|
||
versions (which should, if there were any, be listed in the History
|
||
section of the Document). You may use the same title as a previous
|
||
version if the original publisher of that version gives permission.
|
||
</simpara></listitem>
|
||
<listitem><simpara>List on the Title Page, as authors, one or more
|
||
persons or entities responsible for authorship of the modifications in
|
||
the Modified Version, together with at least five of the principal
|
||
authors of the Document (all of its principal authors, if it has fewer
|
||
than five), unless they release you from this requirement.
|
||
</simpara></listitem>
|
||
<listitem><simpara>State on the Title page the name of the publisher of
|
||
the Modified Version, as the publisher.</simpara></listitem>
|
||
<listitem><simpara>Preserve all the copyright notices of the Document.
|
||
</simpara></listitem>
|
||
<listitem><simpara>Add an appropriate copyright notice for your
|
||
modifications adjacent to the other copyright notices.
|
||
</simpara></listitem>
|
||
<listitem><simpara>Include, immediately after the copyright notices, a
|
||
license notice giving the public permission to use the Modified
|
||
Version under the terms of this License, in the form shown in the
|
||
<link linkend="gfdl-addendum">Addendum</link> below.
|
||
</simpara></listitem>
|
||
<listitem><simpara>Preserve in that license notice the full lists of
|
||
Invariant Sections and required Cover Texts given in the Document's
|
||
license notice.</simpara></listitem>
|
||
<listitem><simpara>Include an unaltered copy of this License.
|
||
</simpara></listitem>
|
||
<listitem><simpara>Preserve the section Entitled "History", Preserve its
|
||
Title, and add to it an item stating at least the title, year, new
|
||
authors, and publisher of the Modified Version as given on the Title
|
||
Page. If there is no section Entitled "History" in the Document,
|
||
create one stating the title, year, authors, and publisher of the
|
||
Document as given on its Title Page, then add an item describing the
|
||
Modified Version as stated in the previous sentence.
|
||
</simpara></listitem>
|
||
<listitem><simpara>Preserve the network location, if any, given in the
|
||
Document for public access to a Transparent copy of the Document, and
|
||
likewise the network locations given in the Document for previous
|
||
versions it was based on. These may be placed in the "History"
|
||
section. You may omit a network location for a work that was
|
||
published at least four years before the Document itself, or if the
|
||
original publisher of the version it refers to gives permission.
|
||
</simpara></listitem>
|
||
<listitem><simpara>For any section Entitled "Acknowledgements" or
|
||
"Dedications", Preserve the Title of the section, and preserve in the
|
||
section all the substance and tone of each of the contributor
|
||
acknowledgements and/or dedications given therein.
|
||
</simpara></listitem>
|
||
<listitem><simpara>Preserve all the Invariant Sections of the Document,
|
||
unaltered in their text and in their titles. Section numbers or the
|
||
equivalent are not considered part of the section titles.
|
||
</simpara></listitem>
|
||
<listitem><simpara>Delete any section Entitled "Endorsements".
|
||
Such a section may not be included in the Modified Version.
|
||
</simpara></listitem>
|
||
<listitem><simpara>Do not retitle any existing section to be Entitled
|
||
"Endorsements" or to conflict in title with any Invariant Section.
|
||
</simpara></listitem>
|
||
<listitem><simpara>Preserve any Warranty Disclaimers.
|
||
</simpara></listitem>
|
||
</orderedlist>
|
||
|
||
<para>If the Modified Version includes new front-matter sections or
|
||
appendices that qualify as Secondary Sections and contain no material
|
||
copied from the Document, you may at your option designate some or all
|
||
of these sections as invariant. To do this, add their titles to the
|
||
list of Invariant Sections in the Modified Version's license notice.
|
||
These titles must be distinct from any other section titles.</para>
|
||
|
||
<para>You may add a section Entitled "Endorsements", provided it
|
||
contains nothing but endorsements of your Modified Version by various
|
||
parties--for example, statements of peer review or that the text has
|
||
been approved by an organization as the authoritative definition of a
|
||
standard.</para>
|
||
|
||
<para>You may add a passage of up to five words as a Front-Cover Text,
|
||
and a passage of up to 25 words as a Back-Cover Text, to the end of the
|
||
list of Cover Texts in the Modified Version. Only one passage of
|
||
Front-Cover Text and one of Back-Cover Text may be added by (or through
|
||
arrangements made by) any one entity. If the Document already includes
|
||
a cover text for the same cover, previously added by you or by
|
||
arrangement made by the same entity you are acting on behalf of, you may
|
||
not add another; but you may replace the old one, on explicit permission
|
||
from the previous publisher that added the old one.</para>
|
||
|
||
<para>The author(s) and publisher(s) of the Document do not by this
|
||
License give permission to use their names for publicity for or to
|
||
assert or imply endorsement of any Modified Version.</para>
|
||
</sect1>
|
||
|
||
<sect1 id="gfdl-5"><title>COMBINING DOCUMENTS</title>
|
||
|
||
<para>You may combine the Document with other documents released under
|
||
this License, under the terms defined in <link linkend="gfdl-4">section
|
||
4</link> above for modified versions, provided that you include in the
|
||
combination all of the Invariant Sections of all of the original
|
||
documents, unmodified, and list them all as Invariant Sections of your
|
||
combined work in its license notice, and that you preserve all their
|
||
Warranty Disclaimers.</para>
|
||
|
||
<para>The combined work need only contain one copy of this License, and
|
||
multiple identical Invariant Sections may be replaced with a single
|
||
copy. If there are multiple Invariant Sections with the same name but
|
||
different contents, make the title of each such section unique by adding
|
||
at the end of it, in parentheses, the name of the original author or
|
||
publisher of that section if known, or else a unique number. Make the
|
||
same adjustment to the section titles in the list of Invariant Sections
|
||
in the license notice of the combined work.</para>
|
||
|
||
<para>In the combination, you must combine any sections Entitled
|
||
"History" in the various original documents, forming one section
|
||
Entitled "History"; likewise combine any sections Entitled
|
||
"Acknowledgements", and any sections Entitled "Dedications". You must
|
||
delete all sections Entitled "Endorsements".</para>
|
||
</sect1>
|
||
|
||
<sect1 id="gfdl-6"><title>COLLECTIONS OF DOCUMENTS</title>
|
||
|
||
<para>You may make a collection consisting of the Document and other
|
||
documents released under this License, and replace the individual copies
|
||
of this License in the various documents with a single copy that is
|
||
included in the collection, provided that you follow the rules of this
|
||
License for verbatim copying of each of the documents in all other
|
||
respects.</para>
|
||
|
||
<para>You may extract a single document from such a collection, and
|
||
distribute it individually under this License, provided you insert a
|
||
copy of this License into the extracted document, and follow this
|
||
License in all other respects regarding verbatim copying of that
|
||
document.</para>
|
||
</sect1>
|
||
|
||
<sect1 id="gfdl-7"><title>AGGREGATION WITH INDEPENDENT WORKS</title>
|
||
|
||
<para>A compilation of the Document or its derivatives with other
|
||
separate and independent documents or works, in or on a volume of a
|
||
storage or distribution medium, is called an "aggregate" if the
|
||
copyright resulting from the compilation is not used to limit the legal
|
||
rights of the compilation's users beyond what the individual works
|
||
permit. When the Document is included an aggregate, this License does
|
||
not apply to the other works in the aggregate which are not themselves
|
||
derivative works of the Document.</para>
|
||
|
||
<para>If the Cover Text requirement of section 3 is applicable to these
|
||
copies of the Document, then if the Document is less than one half of
|
||
the entire aggregate, the Document's Cover Texts may be placed on covers
|
||
that bracket the Document within the aggregate, or the electronic
|
||
equivalent of covers if the Document is in electronic form. Otherwise
|
||
they must appear on printed covers that bracket the whole
|
||
aggregate.</para>
|
||
</sect1>
|
||
|
||
<sect1 id="gfdl-8"><title>TRANSLATION</title>
|
||
|
||
<para>Translation is considered a kind of modification, so you may
|
||
distribute translations of the Document under the terms of section 4.
|
||
Replacing Invariant Sections with translations requires special
|
||
permission from their copyright holders, but you may include
|
||
translations of some or all Invariant Sections in addition to the
|
||
original versions of these Invariant Sections. You may include a
|
||
translation of this License, and all the license notices in the
|
||
Document, and any Warrany Disclaimers, provided that you also include
|
||
the original English version of this License and the original versions
|
||
of those notices and disclaimers. In case of a disagreement between the
|
||
translation and the original version of this License or a notice or
|
||
disclaimer, the original version will prevail.</para>
|
||
|
||
<para>If a section in the Document is Entitled "Acknowledgements",
|
||
"Dedications", or "History", the requirement (section 4) to Preserve its
|
||
Title (section 1) will typically require changing the actual
|
||
title.</para>
|
||
</sect1>
|
||
|
||
<sect1 id="gfdl-9"><title>TERMINATION</title>
|
||
|
||
<para>You may not copy, modify, sublicense, or distribute the Document
|
||
except as expressly provided for under this License. Any other attempt
|
||
to copy, modify, sublicense or distribute the Document is void, and will
|
||
automatically terminate your rights under this License. However,
|
||
parties who have received copies, or rights, from you under this License
|
||
will not have their licenses terminated so long as such parties remain
|
||
in full compliance.</para>
|
||
</sect1>
|
||
|
||
<sect1 id="gfdl-10"><title>FUTURE REVISIONS OF THIS LICENSE</title>
|
||
|
||
<para>The Free Software Foundation may publish new, revised versions of
|
||
the GNU Free Documentation License from time to time. Such new versions
|
||
will be similar in spirit to the present version, but may differ in
|
||
detail to address new problems or concerns. See
|
||
http://www.gnu.org/copyleft/.</para>
|
||
|
||
<para>Each version of the License is given a distinguishing version
|
||
number. If the Document specifies that a particular numbered version of
|
||
this License "or any later version" applies to it, you have the option
|
||
of following the terms and conditions either of that specified version
|
||
or of any later version that has been published (not as a draft) by the
|
||
Free Software Foundation. If the Document does not specify a version
|
||
number of this License, you may choose any version ever published (not
|
||
as a draft) by the Free Software Foundation.</para>
|
||
</sect1>
|
||
|
||
<sect1 id="gfdl-addendum"><title>ADDENDUM: How to use this License for
|
||
your documents</title>
|
||
|
||
<para>To use this License in a document you have written, include a copy
|
||
of the License in the document and put the following copyright and
|
||
license notices just after the title page:</para>
|
||
|
||
<blockquote id="copyright-sample"><para>
|
||
Copyright (c) YEAR YOUR NAME.
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.2
|
||
or any later version published by the Free Software Foundation;
|
||
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
|
||
A copy of the license is included in the section entitled "GNU
|
||
Free Documentation License".
|
||
</para></blockquote>
|
||
|
||
<para>If you have Invariant Sections, Front-Cover Texts and Back-Cover
|
||
Texts, replace the "with...Texts." line with this:</para>
|
||
|
||
<blockquote id="inv-cover-sample"><para>
|
||
with the Invariant Sections being LIST THEIR TITLES, with the
|
||
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
|
||
</para></blockquote>
|
||
|
||
<para>If you have Invariant Sections without Cover Texts, or some other
|
||
combination of the three, merge those two alternatives to suit the
|
||
situation.</para>
|
||
|
||
<para>If your document contains nontrivial examples of program code, we
|
||
recommend releasing these examples in parallel under your choice of free
|
||
software license, such as the GNU General Public License, to permit
|
||
their use in free software.</para>
|
||
</sect1>
|
||
</appendix>
|
||
|
||
|
||
</book>
|