git.sesse.net Git - vlc/blob - 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