Commit 42788088 authored by Clément Stenac's avatar Clément Stenac

Hum, really make the streaming howto where it must be.

parent 720f5224
# Makefile for the VideoLAN Documentation in DocBook XML
# Written by Alexis de Lattre <alexis@videolan.org>
# To build another language than the default one, do 'make LANG=foo'
# Document name
DOC := streaming-howto
# XML declaration
XML_DECL1 = /usr/lib/sgml/declaration/xml.decl
XML_DECL2 = /usr/share/sgml/declaration/xml.decl
XML_DECL = `test -f $(XML_DECL1) && echo $(XML_DECL1) || echo $(XML_DECL2)`
# Default language (English)
LANG = en
XSL= ../common/videolan-doc.xsl
# All available languages (used in 'make clean')
ALL_LANG = en
# Build HTML, PDF, RTF and TXT outputs (for the web site)
all: $(LANG)/$(DOC)-$(LANG).html $(LANG)/$(DOC)-$(LANG).pdf $(LANG)/$(DOC)-$(LANG).rtf $(LANG)/$(DOC)-$(LANG).txt
init-$(LANG):
mkdir -p $(LANG)
ln -sf ../../../images/documentation $(LANG)/images
cp ../common/screen.css $(LANG)
cp ../common/htaccess $(LANG)/.htaccess
# HTML output
$(LANG)/$(DOC)-$(LANG).html: init-$(LANG)
xsltproc $(XSL) src/$(LANG)/$(DOC).xml > $(LANG)/$(DOC)-$(LANG).html
mv *.html $(LANG)
cd $(LANG) && cp index.html $(DOC)-$(LANG).html && cd ..
rm -f $(LANG)/$(DOC)-$(LANG)-html.zip
cd $(LANG) && zip $(DOC)-$(LANG)-html.zip *.html images/*.gif
# PDF output
$(LANG)/$(DOC)-$(LANG).pdf: init-$(LANG)
jade -t tex -d ../common/stylesheet-print-noicones.dsl -o $(LANG)/$(DOC)-$(LANG).tex $(XML_DECL) src/$(LANG)/$(DOC).xml
cd $(LANG) && pdfjadetex $(DOC)-$(LANG).tex
cd $(LANG) && pdfjadetex $(DOC)-$(LANG).tex
cd $(LANG) && pdfjadetex $(DOC)-$(LANG).tex
cd $(LANG) && rm -f *.tex *.out *.aux *.log
cd $(LANG) && zip $(DOC)-$(LANG)-pdf.zip $(DOC)-$(LANG).pdf
# RTF output
$(LANG)/$(DOC)-$(LANG).rtf:init-$(LANG)
cd $(LANG) && jade -t rtf -d ../../common/stylesheet-print-noicones.dsl -o $(DOC)-$(LANG).rtf $(XML_DECL) ../src/$(LANG)/$(DOC).xml
rm -f $(LANG)/$(DOC)-$(LANG)-rtf.zip
cd $(LANG) && zip $(DOC)-$(LANG)-rtf.zip $(DOC)-$(LANG).rtf
# TXT output
$(LANG)/$(DOC)-$(LANG).txt:init-$(LANG)
jade -t sgml -d ../common/stylesheet-txt.dsl -V nochunks $(XML_DECL) src/$(LANG)/$(DOC).xml > $(LANG)/dumpfortxt.html
lynx -force_html -dump $(LANG)/dumpfortxt.html > $(LANG)/$(DOC)-$(LANG).txt
rm -f $(LANG)/dumpfortxt.html
# Delete all outputs
clean:
rm -rf $(ALL_LANG)
# All languages
all-lang:
for l in $(ALL_LANG); do $(MAKE) LANG=$$l || exit 1; done
#! /bin/sh
# $Id$
# Build script for VideoLAN documentation
# Written by Clment Stenac <zorglub@via.ecp.fr>
DOC="streaming-howto"
ALL_LANG="en"
DEFAULT_LANG="en"
if test "$1" = help
then
echo "./build TARGET [LANG]"
echo "LANG can be: $ALL_LANG. Default is $DEFAULT_LANG"
echo "TARGET can be one of: html, pdf, rtf, txt, clean"
exit 0
fi
echo "+ Finding for which langage we are building"
if test -n "$2"
then
if test "$2" = all
then
for lang in `echo $ALL_LANG`
do
echo "+ Recursive call for $lang"
$0 $1 $lang
done
exit 0
fi
build_lang=""
for lang in `echo $ALL_LANG`
do
if test $2 = $lang
then
build_lang=$lang
fi
done
if [ $build_lang = "" ]
then
echo "- Lang $2 not found"
build_lang=$DEFAULT_LANG
fi
else
echo "- No lang. Using default"
build_lang=$DEFAULT_LANG
fi
echo "+ Building for $build_lang"
echo -n "+ Building the target: "
case $1 in
html)
TARGET="$build_lang/$DOC-$build_lang.html";;
pdf)
TARGET="$build_lang/$DOC-$build_lang.pdf";;
rtf)
TARGET="$build_lang/$DOC-$build_lang.rtf";;
txt)
TARGET="$build_lang/$DOC-$build_lang.rtf";;
clean)
TARGET="clean";;
all)
TARGET="all";;
*)
echo ""
echo -n "- Error: unknown target. Building "
TARGET="all";;
esac
echo $TARGET
export ALL_LANG=$ALL_LANG
COMMAND="make -f ../common/Makefile $TARGET DOC=$DOC LANG=$build_lang"
echo "+ Executing $COMMAND"
$COMMAND
<?xml version="1.0" encoding="iso8859-1"?>
<chapter id="gui"><title id="gui">
Announce</title>
<!-- TODO :
Write :)
-->
<sect1><title>Intro</title></sect1>
</chapter>
<?xml version="1.0" encoding="iso8859-1"?>
<chapter id="cmdline"><title id="tcmdline">
Advanced streaming using the command line</title>
<!-- TODO :
Update all this
Improve texts
-->
<sect1><title>Structure of stream output</title>
<para>
the stream output has a powerful architecture
that uses modules. Each module has capabilities, and you
can <emphasis>chain</emphasis> the modules to enhance the
possibilities.
</para>
<para>
Here is the list of the modules currently available:
</para>
<itemizedlist>
<listitem><para><emphasis>standard</emphasis>
"sends" the stream via an <emphasis>access
output</emphasis> module: for example, UDP, file, HTTP, ... You will
probably want to use this module at the end of your chains.
</para></listitem>
<listitem><para><emphasis>transcode</emphasis>
allows you to transcode the audio and the video
of the input stream "on the fly" (if your computer is powerful enough).
</para></listitem>
<listitem><para><emphasis>duplicate</emphasis>
allows you to create a second chain, where the
stream will be handled in an independant way.
</para></listitem>
<listitem><para><emphasis>display</emphasis>
allows you to display the input stream, as VLC
would normally do. Used with the <emphasis>duplicate</emphasis>
module, this allows you to view the stream as you send it.
</para></listitem>
<listitem><para><emphasis>rtp</emphasis>
streams over RTP (one UDP port for each elementary stream).
</para></listitem>
<listitem><para><emphasis>es</emphasis>
allows you to make separate Elementary Streams (ES)
out of an input stream.
</para></listitem>
</itemizedlist>
<para>
Each of these modules may take options. Here is the
syntax that you must use:
</para>
<screen>
<prompt>% </prompt><userinput>vlc input_stream --sout '#module1{option1=...,option2=...}:#module2{option1=...,option2=...}:...'</userinput>
</screen>
<para>
You may also use the following syntax :
</para>
<screen>
<prompt>% </prompt><userinput>vlc input_stream --sout-module1-option1=... --sout-module1-option2=... --sout-module2-option1=... --sout-module2-option2=... ...</userinput>
</screen>
<para>
For example, to transcode a stream and send it, use:
</para>
<screen>
<prompt>% </prompt><userinput>vlc input_stream --sout '#transcode{options}:#standard{options}'</userinput>
</screen>
</sect1>
<sect1><title>Description of the modules</title>
<sect2><title>standard (alias std)</title>
<para>
Sends a stream.
</para>
<para>
Options:
</para>
<itemizedlist>
<listitem><para><emphasis>access</emphasis>:
how to send:
<emphasis>file</emphasis>, <emphasis>udp</emphasis>,
<emphasis>rtp</emphasis>, <emphasis>http</emphasis>.
</para></listitem>
<listitem><para><emphasis>mux</emphasis>:
which muxer (ie, which format) will be used. It can
be one of
<emphasis>avi</emphasis>
(for AVI format)
<emphasis>ogg</emphasis>
(for OGG format)
<emphasis>ps</emphasis>
(for MPEG2-PS format)
<emphasis>ts</emphasis>
(for MPEG2-TS format).
</para></listitem>
<listitem><para><emphasis>url</emphasis>:
if you use the
<emphasis>file</emphasis> access, it will be the location where to
store the stream; if you use another access, it will be the unicast or
multicast IP address where you want to stream.
</para></listitem>
<listitem><para><emphasis>sap</emphasis>:
if you use the <emphasis>udp</emphasis> or
<emphasis>rtp</emphasis> accesses, use this option to announce your
stream, using SAP/SDP.
</para></listitem>
<listitem><para><emphasis>name</emphasis>!
This option contains the name under which you want to announce the
program.
</para></listitem>
<listitem><para><emphasis>slp</emphasis>:
like sap, but use the SLP protocol. You need
to have libslp on your system.
</para></listitem>
<listitem><para><emphasis>sap_ipv</emphasis>:
if you use the <emphasis>sap</emphasis> option,
use this option to specify if you want to send the SAP announces in
IPv4 or IPv6. The value of this option is <emphasis>4</emphasis> or
<emphasis>6</emphasis>.
</para></listitem>
</itemizedlist>
<note><para>
If you are streaming in multicast, you may want to
use the global option <command>--ttl 12</command> to set the TTL to a
value superior to 1.
</para></note>
</sect2>
<sect2><title>display</title>
<para>
Displays the stream.
</para>
<para>
Options:
</para>
<itemizedlist>
<listitem><para><emphasis>noaudio</emphasis>:
Ignore audio.
</para></listitem>
<listitem><para><emphasis>novideo</emphasis>:
Ignore video.
</para></listitem>
</itemizedlist>
</sect2>
<sect2><title>duplicate</title>
<para>
Duplicates the stream to a new stream output chain.
</para>
<para>
Options:
</para>
<itemizedlist>
<listitem><para><emphasis>dst</emphasis>:
A new stream output chain of modules, as described
earlier.
</para></listitem>
<listitem><para><emphasis>select</emphasis>:
This option allows you to specify which programs or es you wish to
stream for the previous dst, if the input stream has several ones.</para>
<para>
Format is "program=<emphasis>program_id</emphasis>" or es="<emphasis>es_id</emphasis>".
You can also use ranges, like "program=<emphasis>start_program-end_program</emphasis>".
You can select only es of a given type, with :</para>
<itemizedlist>
<listitem><para>no-audio, noaudio, audio</para></listitem>
<listitem><para>no-video, novideo, video</para></listitem>
<listitem><para>no-spu, nospu, spu</para></listitem>
</itemizedlist>
<para>You may use several selectors, comma-separated</para></listitem>
</itemizedlist>
</sect2>
<sect2><title>transcode</title>
<para>
Changes the codec and/or bitrates for a stream.
</para>
<para>
Options:
</para>
<itemizedlist>
<listitem><para><emphasis>acodec</emphasis>:
the new audio codec. It can be one of
<emphasis>mpga</emphasis> (MPEG audio layer 2), <emphasis>a52</emphasis>
or <emphasis>ac3</emphasis> (AC3 sound) or <emphasis>vorb</emphasis>
(Vorbis).
</para>
</listitem>
<listitem><para><emphasis>ab</emphasis>:
audio bitrate in Kbps.
</para></listitem>
<!-- UNIMPLEMENTED for the moment
<listitem><para><emphasis>samplerate</emphasis>: audio encoding rate in Hz
(44000 for a CD, for example).</para></listitem> -->
<!-- UNIMPLMENETED <listitem><para><emphasis>channels</emphasis>: number of audio
channels.</para></listitem> -->
<listitem><para><emphasis>vcodec</emphasis>:
the new video codec. It can be one of
<emphasis>mp4v</emphasis> (MPEG4), <emphasis>mpgv</emphasis>
(MPEG1), <emphasis>DIV1</emphasis>, <emphasis>DIV2</emphasis>,
<emphasis>DIV3</emphasis> (DivX 1,2,3), <emphasis>H263</emphasis>
(H263), <emphasis>I263</emphasis> (H263I), <emphasis>WMV1</emphasis>
or <emphasis>WMV2</emphasis> (Windows Media Video 1 or 2),
<emphasis>MJPG</emphasis> (MJPEG), <emphasis>MJPB</emphasis>
(MJPEGB).
</para></listitem>
<listitem><para><emphasis>width</emphasis>:
video width.
</para></listitem>
<listitem><para><emphasis>height</emphasis>:
video height.
</para></listitem>
<listitem><para><emphasis>vb</emphasis>:
video bitrate in kbps.
</para></listitem>
<listitem><para><emphasis>vt</emphasis>:
video bitrate tolerance in bps.
</para></listitem>
<listitem><para><emphasis>deinterlace</emphasis>:
deinterlace the stream.
</para></listitem>
<listitem><para><emphasis>croptop</emphasis>:
number of pixels removed from the top of the video.
</para></listitem>
<listitem><para><emphasis>cropbottom</emphasis>:
number of pixel removed from the bottom of the video.
</para></listitem>
<listitem><para><emphasis>cropleft</emphasis>:
number of pixels removed from the left of the video.
</para></listitem>
<listitem><para><emphasis>cropright</emphasis>:
number of pixels removed from the right of the video.
</para></listitem>
<listitem><para><emphasis>hq</emphasis>:
high quality transcoding (uses more CPU).
</para></listitem>
<listitem><para><emphasis>qmin</emphasis>:
minimum video quantiser scale (VBR)
</para></listitem>
<listitem><para><emphasis>qmax</emphasis>:
maximum video quantiser scale (VBR).
</para></listitem>
</itemizedlist>
</sect2>
<sect2><title>rtp</title>
<para>
Sends a stream over RTP
</para>
<para>
Options:
</para>
<itemizedlist>
<listitem><para><emphasis>dst</emphasis>:
destination IP address (unicast or multicast).
</para></listitem>
<listitem><para><emphasis>port</emphasis>:
destination UDP port.
</para></listitem>
<listitem><para><emphasis>sdp</emphasis>:
how to send the sdp file: <emphasis>http://server_ip:server_port/path</emphasis> for http, or <emphasis>rtsp://server_ip:server_port/path</emphasis> for rtsp, where <emphasis>server_ip</emphasis> is the address of one of the server's interface, and <emphasis>path</emphasis> where the sdp file will be accessible on the server. You can also use <emphasis>sap://</emphasis> to announce your stream by SAP.
</para></listitem>
</itemizedlist>
<note><para>
When using <emphasis>sdp=rtsp</emphasis>, it is possible not to give any destination address. VLC will then send the stream to any client that connects to it.
</para></note>
</sect2>
<sect2><title>es</title>
<para>
Make separate Elementary Streams.
</para>
<para>Options:</para>
<itemizedlist>
<listitem><para><emphasis>access_audio</emphasis>:
how to send the audio track:
<emphasis>file</emphasis>, <emphasis>udp</emphasis>,
<emphasis>rtp</emphasis> or <emphasis>http</emphasis>.
</para></listitem>
<listitem><para><emphasis>access_video</emphasis>:
how to send the vido track:
<emphasis>file</emphasis>, <emphasis>udp</emphasis>,
<emphasis>rtp</emphasis> or <emphasis>http</emphasis>.
</para></listitem>
<listitem><para><emphasis>access</emphasis>:
if you want the audio and the video tracks to use
the same access, use this option instead of the two above.
</para></listitem>
<listitem><para><emphasis>mux_audio</emphasis>:
which muxer (ie, which format) will be used for the
audio track. It can be one of <emphasis>avi</emphasis> (for AVI format),
<emphasis>ogg</emphasis> (for OGG format), <emphasis>ps</emphasis> (for
MPEG2-PS format), <emphasis>ts</emphasis> (for MPEG2-TS format).
</para></listitem>
<listitem><para><emphasis>mux_video</emphasis>:
which muxer (ie, which format) will be used for the
video track. It can be one of <emphasis>avi</emphasis> (for AVI format),
<emphasis>ogg</emphasis> (for OGG format), <emphasis>ps</emphasis> (for
MPEG2-PS format), <emphasis>ts</emphasis> (for MPEG2-TS format).
</para></listitem>
<listitem><para><emphasis>mux</emphasis>:
if you want the audio and the video tracks to use
the same muxer, use this option instead of the two above.
</para></listitem>
<listitem><para><emphasis>url_audio</emphasis>:
if you use the <emphasis>file</emphasis> access, it
will be the location where to store the audio track; if you use another
access, it will be the unicast or multicast IP address where you want to
stream.
</para></listitem>
<listitem><para><emphasis>url_video</emphasis>:
if you use the <emphasis>file</emphasis> access, it
will be the location where to store the vido track; if you use another
access, it will be the unicast or multicast IP address where you want to
stream.
</para></listitem>
<listitem><para><emphasis>url</emphasis>:
if you want the audio and the video tracks to use
the same url, use this option instead of the two above.
</para></listitem>
</itemizedlist>
<note><para>
In the <emphasis>url</emphasis> options, if you use
the <emphasis>file</emphasis> access, you can use the following macros
in the filename:</para>
<itemizedlist>
<listitem><para><emphasis>%n</emphasis> =
stream number</para></listitem>
<listitem><para><emphasis>%c</emphasis> = FOURCC ;</para></listitem>
<listitem><para><emphasis>%m</emphasis> =
muxer
;</para></listitem>
<listitem><para><emphasis>%a</emphasis> = access.</para></listitem>
</itemizedlist>
</note>
</sect2>
<sect2><title>
Miscellaneous
</title>
<para>
Here are a few additional global options
</para>
<itemizedlist>
<listitem><para><emphasis>--sout-all, --no-sout-all</emphasis>
Enable streaming of all ES (default disabled). By defaut VLC will only stream one audio ES and one video ES (the first ones). If you enable sout-all, all ES (audio, video and SPU) will be streamed.</para>
</listitem>
<listitem><para><emphasis> --sout-keep, --no-sout-keep</emphasis>
Keep sout open (default disabled) : use the same sout instance accross the various playlist items, if possible.</para>
</listitem>
<listitem><para><emphasis>--no-sout-audio</emphasis>
disables audio stream output.
</para></listitem>
<listitem><para><emphasis>--no-sout-video</emphasis>
disables video stream output.
</para></listitem>
</itemizedlist>
<para>
The stream output also offers a simplified syntax,
with which you can only you use the <emphasis>standard</emphasis> module
main options:
</para>
<screen>
<prompt>% </prompt><userinput>vlc input_stream --sout access/mux:url</userinput>
</screen>
<para>
where <emphasis>access</emphasis>,
<emphasis>mux</emphasis> and <emphasis>url</emphasis> are as defined in
the options of the standard module.
</para>
</sect2>
</sect1>
<sect1><title>
Examples
</title>
<para>
To understand fully the complex syntax of VLC's
stream output, please look at the examples in the nexte section.
</para>
</sect1>
</chapter>
<?xml version="1.0" encoding="iso8859-1"?>
<chapter id="dvb"><title id="tdvb">
Stream a DVB channel (satellite or digital
terrestial TV)
</title>
<!-- FIXME: improve, update, needs gui -->
<note><para>
This is possible under GNU/Linux only.
</para></note>
<sect1><title>
Install the DVB drivers
</title>
<para>
If you want to be able to stream from a DVB card (a
satellite card or a digital terrestial TV card), you need to install the
DVB drivers:
</para>
<itemizedlist>
<listitem><para>
if you use a Linux 2.6.x kernel, you just need to
compile the right modules;
</para></listitem>
<listitem><para>
if you are using a Linux 2.4.x
kernel, you must download the latest release of the DVB drivers from the <ulink url="http://www.linuxtv.org/download/dvb/">DVB drivers download
page</ulink> of the <ulink url="http://www.linuxtv.org/">LinuxTV</ulink>
Project.
</para></listitem>
</itemizedlist>
<para>
Uncompress the tarball and follow the instructions
written in the <filename>INSTALL</filename> file to compile and install
the drivers.
</para>
</sect1>
<sect1><title>
Stream with VLS
</title>
<para>
Put a <filename>.dvbrc</filename> file containing
the DVB channels (satellite or digital terrestial TV channels) you
want to stream in your home directory (some are provided in the
<emphasis>libdvb</emphasis> tarball for the satellite channels).
</para>
<para>
Run VLS with the following command line
:
</para>
<screen>
<prompt>% </prompt><userinput>vls -vv -d udp:192.168.0.42 dvb:"EUROSPORT" --ttl 12</userinput>
</screen>