* ./modules/video_filter/adjust.c: properly fixed margin handling (partially
[vlc.git] / doc / web-streaming.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 <html> <head>
3   <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
4   <meta name="Description" content="Web streaming">
5   <meta name="Keywords" content="MPEG, Web, streaming, VideoLAN">
6   <meta name="Author"
7         content="Christophe Massiot, massiot@via.ecp.fr">
8   <link rev="made" href="mailto:massiot@via.ecp.fr">
9   <title>How to setup VLC for web streaming (X11 only)</title>
10   <style type="text/css">
11     <!--
12     body, table, td, p, blockquote, th, td, tr, caption, dir
13           {font-family: Verdana, Arial, Helvetica, Lucida, sans-serif;
14            text-decoration: none; font-weight: 100; margin-left: 25px;}
15     ul, li {font-family: Verdana, Arial, Helvetica, Lucida, sans-serif;
16             text-decoration: none; font-weight: 100;}
17     code {font-family: "Letter Gothic", "Courier New", Courier, monospace;
18           font-weight: bold}
19     pre {font-family: "Letter Gothic", "Courier New", Courier, monospace;}
20     a {text-decoration: none}
21     b, strong {font-weight: bold}
22     h1 {font-family: Verdana, Arial, Helvetica, Lucida, sans-serif;
23         font-weight: bold; text-align: center}
24     h2 {font-family: Verdana, Arial, Helvetica, Lucida, sans-serif;
25         font-weight: bold; margin-left: -20px;}
26     h3 {font-family: Verdana, Arial, Helvetica, Lucida, sans-serif;
27         font-weight: bold; text-decoration: underline}
28     .lettrine {font-size: 18pt;}
29     -->
30   </style>
31 </head>
32
33 <body bgcolor="#E8E8E8">
34
35   <h1> How to set up VLC for web streaming (X11 only) </h1>
36
37   <h2> Abstract </h2>
38
39 VLC is a separate application which can either read a plain file or a TS
40 network stream. Using XSwallow, it is possible to incorporate VLC video
41 output window right into the window of a browser. With additional
42 tricks, it is also possible to launch a VLMS (VideoLAN MiniServer) on the
43 server-side, and have the client read a live network stream. This document,
44 intended for expert users only, describes the ways to do it.
45
46
47   <h2> Installing and configuring XSwallow for plain MPEG files </h2>
48
49 XSwallow is a software which allows any X11 window to be "swallowed"
50 (technically, just reparented, so that it has no effet on performance
51 anyhow) into the window of a netscape-compatible browser (Navigator,
52 Mozilla, Konqueror, Galeon, Opera...). This is indeed a trick in the X11
53 windowing model, and don't even expect to port this behaviour to any
54 non-X11-based operating system, even supported by VLC (MS Windows,
55 MacOS X, BeOS, QNX, ...). <p>
56
57 Download it here : <a href="http://www.csn.ul.ie/~caolan/docs/XSwallow.html">
58 http://www.csn.ul.ie/~caolan/docs/XSwallow.html</a>. Compilation is really
59 straightforward, it basically boils down to some :
60 <pre> make -f makefile.linux </pre> <p>
61
62 Place the resulting xswallow.so in a directory scanned by your browser
63 for plug-ins (for instance, /usr/lib/netscape/plugins, this scan path
64 can with some browsers be read in $NPX_PLUGIN_PATH) and xswallow.conf
65 in the directory indicated by the environment variable $MOZILLA_HOME. If
66 it is currently unset, <b>set it</b> with for instance :
67 <pre> export MOZILLA_HOME=/etc </pre> <p>
68
69 Of course your mileage may vary. The last step is to customize xswallow.conf
70 so that it launches VLC to handle MPEG files. Comment out all lines you
71 don't need, and add :
72 <pre>
73 video/mpeg; mpeg,mpg,vob;   vlc -I dummy -V xvideo %s; VideoLAN Client 0.2.83 (XVideo output); VideoLAN
74 </pre> <p>
75
76 Notes :
77 <ul>
78   <li> This assumes vlc is in your $PATH, if it is not the case, adapt it.
79   <li> If nothing shows up, it might be because VLC cannot find its plug-ins.
80        Please check that they are in an appropriate place (such as
81        /usr/lib/videolan/vlc). You can try to add -vvvvv to the arguments to
82        see where it fails.
83   <li> The third field on the line is the actual name of the window to
84        swallow. This is currently annoying, you will have to guess the
85        name of the video output window, ie. changing the version number
86        and the output plug-in (to SDL for instance if you use SDL). At
87        present there is no way to force VLC to use a definite name, but
88        it will be added by 0.2.90.
89   <li> When the window is first spawned, it will appear on screen and
90        then be quicky reparented, making some flickering. The usual
91        workaround is to make the window appear at offset +10000+10000
92        using the --geometry switch, but it is not currently supported
93        by VLC. The will be addressed by 0.2.90 too.
94   <li> If your window manager isn't configured for automatic placement
95        of new windows, it may ask you to manually place the window before
96        XSwallow can swallow it. This is annoying, too. The only workaround
97        is to disable the functionality (for instance with twm, add
98        RandomPlacement in .twmrc). It will be addressed at the same time
99        with --geometry.
100   <li> XSwallow will first download the file, and then launch VLC. There
101        is no way to begin reading the stream before it is complete, à la
102        QuickTime plug-in. This will be addressed in a future version of
103        VLC (0.4). If you want to do live streaming, proceed to the next
104        chapter.
105 </ul> <p>
106
107 From now on, if you have your browser reload its plug-in list, it will
108 display VideoLAN as application handler for video/mpeg. You should now
109 try and see what it yields.
110
111
112   <h2> Tricks for live web streaming using VLMS </h2>
113
114 With a little trick, it is possible to stream a video using VLC and VLMS,
115 and make it appear in a Web browser (without having a local copy of the
116 file). This will only work if there is no firewall (nor masquerading)
117 between the server and the client. It requires to have a CGI support
118 built into the Web server. <p>
119
120 Here is the sketch :
121 <ul>
122   <li> The client requests a specific page, say video.html. This page
123        contains an image tag to a file vlc.ts, AND launches a VLMS
124        through a CGI script.
125   <li> The client receives the vlc.ts file which contains the address
126        of the VLMS server, and through a special mime-type in XSwallow
127        spawns a VLC.
128   <li> As soon as VLC begins to receive the stream, it is swallowed by
129        XSwallow and appears in the browser's window.
130 </ul>
131
132   <h3> Configuring the Web server </h3>
133
134 In this section I will only give configuration directives for Apache.
135 You need to add a new MIME type for TS stream in httpd.conf :
136 <pre> AddType video/x-mpeg-ts .ts </pre> <p>
137
138 And relaunch your Web server (apachectl reload). Next, create the vlc.html
139 page. You need two specific lines, one to load vlc.ts, the other to start
140 the VLMS server ; for instance in PHP (adapt it for Perl, Java, or whatever) :
141 <pre>
142 &lt;img src="vlc.ts"&gt;
143 &lt;?php system("/var/www/cgi-bin/stream.sh $REMOTE_ADDR mystream.mpg &gt; /dev/null 2&gt;&amp;1 &amp;"); ?&gt;
144 </pre> <p>
145
146 Where stream.sh is a simple shell script :
147 <pre>
148 #!/bin/sh
149 vlms -d $1 -a mpeg $2
150 </pre> <p>
151
152 VLMS starts streaming mystream.mpg to $REMOTE_ADDR (the IP address fetched
153 by the server, this is why you cannot do it through firewalls) on port 1234.
154
155 Notes :
156 <ul>
157   <li> The -a mpeg option may surprise you ; the VLMS doesn't preparse the
158        stream and thus cannot know which audio channel to send. If you had
159        an AC3 audio track, you could have put -a ac3. You can also
160        activate subtitles with -s.
161   <li> VLMS only reads MPEG-1 files from version 0.2 on. If you have an
162        older version, you may want to upgrade.
163   <li> It is possible that, due to the client latency, the client misses
164        the first frames of the stream. I have no ideal workaround for this.
165   <li> Some streams (especially MPEG-1) only have one sequence header at the
166        beginning of the stream. Since the client risks missing it, it may
167        be completely unable to decode the stream _at all_. If you only get
168        a blank screen, please try with another stream, such as one test
169        stream on <a href="ftp://ftp.videolan.org/pub/videolan/streams">
170        ftp://ftp.videolan.org/pub/videolan/streams</a> before issuing
171        a bug report.
172   <li> You should be careful that the stream.sh script is indeed launched
173        in the background. If your CGI program waits for it, it doesn't
174        hang up the connection until it finishes, and Web browsers wait
175        for the connection to be closed before launching plug-ins. In
176        that case you have nothing on screen, not even a <em> Click to
177        abort swallow </em> message.
178 </ul> <p>
179
180 Finally, create the vlc.ts file. It just contains the address of the server,
181 so that VLC can bind on it (you can't retrieve that from XSwallow). For
182 instance :
183 <pre> streaming.idealx.com </pre> <p>
184
185   <h3> Configuring XSwallow </h3>
186
187 You need to add an entry video/x-mpeg-ts in you xswallow.conf :
188 <pre> video/x-mpeg-ts; ts; video-streaming.sh %s; VideoLAN Client 0.2.83 (XVideo output); VideoLAN </pre> <p>
189
190 The same provisions as before apply here. The video-streaming.sh file is a
191 simple shell script which retrieves the server's name and spawns VLC :
192 <pre>
193 #!/bin/sh
194 SERVER=$( cat $@ )
195 vlc -I dummy -V xvideo ts://$SERVER
196 </pre> <p>
197
198 Here you go. This is quite a hack, but it will hold until the next major
199 release of VLC.
200
201
202   <h2> Acknowledgements </h2>
203
204 This page has been written by <a href="mailto:massiot@via.ecp.fr">
205 Christophe Massiot</a> for <a href="http://www.idealx.com/"> IDEALX
206 S.A.S</a>. <br>
207 <em> $Id: web-streaming.html,v 1.1 2001/08/22 18:47:52 massiot Exp $ </em>
208
209 </body>
210
211 </html>
212