May First/People Link is committed to [https://support.mayfirst.org/wiki/live-video-streaming-support supporting video streaming], as well as free software. These two goals have have challenged us to use tools that allow for high quality video streams using entirely free software. In addition to this description, we've also started some experimentation with [ticket:5862 stream-m], which has the advantage of using webm/vp8, the container/codec that Google recently aquired and then released under a BSD license. I originally went down that page when I got the impression that webm/vp8 would not be supported by Icecast, however, a [http://lists.xiph.org/pipermail/icecast/2012-February/012150.html thread from early in 2012] suggests that I may be wrong. = Video streaming with free software = The method and tool set that we are now using and recommending was first developed for streaming the annual [http://debconf.org/ Debian Developers Conference], and has since been used to stream other events and conferences such as FOSDEM and Linux Conf Australia. These tools should work on all GNU/Linux distributions. Many of the notes, and background information come from steady reference to the [http://dvswitch.alioth.debian.org/wiki/ DVswitch Wiki], particularly the [http://dvswitch.alioth.debian.org/wiki/component_interaction/ component interaction], as well as other resources supplied by the developers. == Basic Software Components == * [http://dvswitch.alioth.debian.org/wiki/ dvswitch] (GPLv2) * dvsource (ships with dvswitch but can be installed independently, and is packaged independently in some GNU/Linux distros) * dvsink (ships with dvswitch but can be installed independently, and is packaged independently in some GNU/Linux distros) * [http://v2v.cc/~j/ffmpeg2theora/ ffmpeg2theora] (GPLv3) * [http://v2v.cc/~j/oggfwd/ oggfwd] (GPLv2) * [http://www.icecast.org/ icecast2] (GPLv2) == Hardware == Depending on the hardware, bandwidth, LAN, and other physical constraints, there can be some flexibility in how much hardware this requires. There are some general things that will make your life easier. * A DV camera with firewire (or USB). Firewire transfers data at a higher rate, however many newer cameras do not have Firewire. In this case you may be better off with a slightly older camera. DV cams are preferable to other USB cams, like cheap webcams; these can be made to work, but are not well supported. * A computer with appropriate ports for the camera, and a working NIC (runs dvsource). * A computer with good graphics support, reasonable processor, at least 2G of RAM and a working NIC (runs dvswitch). * A computer with a good processor a working NIC with an connection to the Internet * A computer with running icecast2 with a high speed NIC and good bandwidth (more on that later). * Ideally a gigabyte switch, with gigabyte NICs on all of the computers should be used on the LAN to cut down on latency, but it should work on a 10/100 LAN just fine. There are additional pieces of hardware that can be obtained to increase the quality of your stream. * A USB audio device that can take inputs. This is helpful as most laptops expect microphone input and so do odd things with gain, reducing audio quality. There are many mixers and other simpler devices available. As long as it works on your version of GNU/Linux with ALSA, it can be used as a source. Thinking about the sound is important, as poor sound quality is more distracting than poor video quality. * A VGA converter, such as the TwinPact100 (a model recommended by the DVswitch developers that runs ~$500USD). This will allow you to turn a presenter's computer into a video source for the stream. The three computers running dvsource, dvswitch and dvsink is an ideal setup. In a pinch all three pieces can be run on fewer machines. We have successfully run all three on an x61 Thinkpad, but the machine ran '''hot'''. Dvsource is very lightweight, and can be run on an old machine with little RAM. DVswitch can be moderately CPU intensive and depending on how many dvsources you are using that scales up. DVsink is processor intensive, mainly because ffmpeg has to convert the dv stream to ogg. If using two machines, it is best to split the sink from the switch. == Networking and Bandwidth == There are multiple layers of bandwidth and networking in this setup. On site you will need two things, a functional LAN (preferably wired), and at least one connection to the Internet that can be used for forwarding the stream to a server. This connection does not need to be astonishingly fast to achieve a quality stream. It is more important to attempt establishing a stable route to the server than a high bandwidth one. Depending on your expected audience size, the bandwidth needs of your Icecast server may vary. In our limited testing, the Icecast software can handle several thousand streams at once, without a huge impact on the hardware, so it is likely that you will hit bandwidth limits before you hit a hardware bottleneck. For MFPL's streams, we have Icecast running from data center connections. If you are anticipating a large audience of stream viewers from within your LAN, it may be worthwhile to set up and Icecast server locally to conserve onsite bandwidth (particularly if you need that space to publish the stream to other servers). == Formats and Protocols == Provided you are using devices that generate DV, there is only one main conversion; from DV to ogg/theora. DVsource and DVswitch pass their video in DV, DVsink allows you to pipe the DV to other software. Using ffmpeg2theora we convert the DV stream directly to theora, and then forward the ogg stream using oggfwd. == Embedding streams onto web sites == Once you have an ogg stream running, it is important to make it easy to find and view. Embedding it into the browser is the common choice. There has been a significant growth of support for the HTML5 video tag as well as in browser support for ogg/theora. Firefox/Iceweasel, Chrome/Chromium, Opera will all embed a video player with just a video tag pointing to a functional stream. However, there is still the looming problem of proprietary browsers refusing to support ogg/theora. This problem has been addressed by [http://www.theora.org/cortado/ cortado], which uses a Java applet to supply oggs to browsers that don't support HTML5 video tags and/or ogg/theora. [http://current.workingdirectory.net/pages/jxiph/ jxiph] is a simple javascript library that attempts to auto-detect whether a browser should be served the cortado java app or html 5. == A Basic Example == Here is a simple set up, with some commands to illustrate how the flow of stream works; there are of course different ways to do this. Again we are assuming that there is a functional LAN and functional connection to the Internet, and all machines are running functional versions of GNU/Linux with appropriate software installed. All of which are out of scope for this example. === On the Icecast server === * Double check Icecast is running and make sure you know the port it is listening on, and the password. * ('''TODO: Add a link to some good information about installing and configuring Icecast''') === On the DVswitch machine === * Make sure it is connected to the LAN * Launch "dvswitch" either from a terminal or a window manager launcher. {{{ dvswitch -h localhost -p 2000 }}} * '''NOTE:''' You have to start DVswitch before starting the source or the sink. === On the machine connected to the camera === * Connect a DV cam via Firewire to the machine * Double check your LAN connection. * In a terminal run: {{{ dvsource-firewire -h DVSWITCHHOST -p 2000 }}} Where DVSWITCHHOST is either the domain, IPV4 or IPV6 address of the machine running DVswitch. The "-p" flag specifies the port on which the DVswitch is listening. === On the DVsink machine === * Make sure that you have the "ffmpeg2theora" and "oggfwd" packages installed. * Run: {{{ dvsink-command -- ffmpeg2theora - -f dv -F 25:5 --speedlevel 0 -v 4 -a 0 -c 1 -H 9600 -o - | oggfwd ICECASTHOST ICECASTPORT ICECASTPASS /mountpoint.ogg }}} Consult the ffmpeg2theora man pages for different conversion values. ICECASTHOST is the hostname or IP of the icecast server. ICECASTPORT is the port on which Icecast is listening. The default is 8000. ICECASTPASS is the password for the Icecast server. mountpoint.ogg is the mountpoint of your stream name. Here's an alternative that will save a raw dv file with the output ''and'' stream to an icecast server (beware - this will create a file that consumes a lot of disk space). {{{ dvsink-command -- tee out.dv | ffmpeg2theora - -f dv -F 25:5 --speedlevel 0 -v 4 -a 0 -c 1 -H 9600 -o - | oggfwd ICECASTHOST ICECASTPORT ICECASTPASS /mountpoint.ogg }}} And here's an alternative that is useful if you are streaming using a limited bandwidth upstream connection, you can replace the part starting with ffmpeg2theora with the following. It reduces the size of output to 360x240 (from twice that size) and it limits from 25 frames per second to just 5 frames per second. {{{ ffmpeg2theora - -f dv -F 5 --speedlevel 0 --width 360 --height 240 -v 4 -a 0 -c 1 -H 9600 -o - }}} === Testing the Stream === You're now ready to test the stream. In a browser that supports ogg/theora, or a standalone player (like VLC), and open: {{{ http://ICECASTHOST/mountpoint.ogg }}}. If you see a video you have a working single camera stream. More source machines can be added. DVswitch allows you to switch sources, as well as use varied audio sources (alsa), and DV files.