= Live Video Streaming = 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. See also: [wiki:StreamDesktop how to stream your desktop]. = 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. For a simple script that will use your local webcam and microphone see the [http://publish.mayfirst.org/icecast/ Mobi Script] == 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) * dvsink GPLv2 you can install those programs by running the following command as root on Debian Whezzy (some packages are not available for 'jessie' yet): {{{ aptitude install dvswitch oggfwd ffmpeg ffmpeg2theora dvsource dvsink libav-tools pulseaudio-utils }}} or this one on Ubuntu: {{{ sudo apt-get install dvswitch oggfwd ffmpeg ffmpeg2theora dvsource dvsink libav-tools pulseaudio-utils }}} == 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. * One ore more DV cameras with firewire. 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. Take note that most FW cameras have optical and digital zoom and some other functions, while most usb cameras dont' * One or more usb cameras. * 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.] <-- this is not needed if the presenter's computer is running debian as (s)he can streams his desktop directly to dvswitch. 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. You would need two parameters: the port and the host. As for port you can use whatever you want but 2000 is recomended and >1024 is mandatory. As for the host, if you want to use cameras connected to other computers, you would need to use the ip of the computer running dvswitch, which you can get running this command and looking for a number different to 127.0.0.1, which would likely start with 192. {{{ /sbin/ifconfig|grep inet }}} outpt exmple: {{{ ~$ /sbin/ifconfig |grep inet inet addr:127.0.0.1 Mask:255.0.0.0 inet6 addr: ::1/128 Scope:Host inet addr:192.168.1.73 Bcast:192.168.1.255 Mask:255.255.255.0 inet6 addr: fe80::aabb:cfff:fe18:349e/64 Scope:Link }}} If you are not planning to send video streams from other computers, you can use 'localhost' insted of the ip address. From now on you should use 'localhost' or the ip number, depending of what you have choosen, instead of DVSWITCHHOST. So run this command to start dvswitch: {{{ dvswitch -h DVSWITCHHOST -p 2000 }}} * '''NOTE:''' You have to start DVswitch before starting the source or the sink. == On the machine connected to the camera == === if using a firewire cam === * 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. === if using an USB cam === * Connect the usb cam to the computer if you want to use a wired cam insted of the built in most laptops come with. * look for the video input device you are going to use with this command {{{ ls /dev/video* }}} it should return someting like this: {{{ /dev/videoX }}} being X a number depending of the number of cameras connected to the computer. This would show up if you have 2 usb cameras connected to the computer: {{{ ls /dev/video* /dev/video0 /dev/video1 }}} * Run the next command to grab the video comming from the usb cam and pipe it to the dvsource-file command to send it to dvswitch. {{{ avconv -f video4linux2 -i /dev/videoX -target ntsc-dv - | dvsource-file /dev/stdin -p 2000 -h DVSWITCHHOST }}} Notice using the number of the cam insted of the X in the command line above. Also note you are sending an ntsc-dv video format but it could be pal-dv. This matters if you are using more than 1 camera, as the first video stream sent to dvswitch will set the 'default' format and the other sources would need to stick with it. Finally, note you can run this command on different computers at the same time to feed dvswitch with several video streams if you used the ip of the computer running dvswitch instead of using 'localhost' === if you want to stream you desktop === First off you would need to get the size of your screen. You can use this command to get it and store it in a variable called 'PANTALLA' {{{ export PANTALLA=$(xdpyinfo | awk '/dimensions:/ { print $2; exit }') }}} and verify the size of the screen by echoing that variable with the following command: {{{ echo $PANTALLA }}} Now you can stream you desktop to dvswitch running this: {{{ avconv -f x11grab -s $PANTALLA -r 29 -i :0.0 -target ntsc-dv -y - | dvsource-file /dev/stdin -p 2000 -h DVSWITCHHOST }}} Note that you would create and infinite (funny) loop if you run this command on the same computer running dvswitch but it won't harm. =) == On the DVsink machine == * Make sure that you have the "ffmpeg2theora" and "oggfwd" packages installed. * Run: {{{ dvsink-command -h DVSWITCHHOST -p 2000 tee /dev/null | 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 -h DVSWITCHHOST -p 2000 tee out.dv | ffmpeg2theora - -f dv -F 25:5 --speedlevel 0 -v 4 -a 1 -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 1 -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. == Recording your stream == You can record your stream on two different ways and qualities. === Higher stream quality === The first way would get the highest quality avaliable from the video sources, and would save it as a .dv file. This might be awesome but it also might consume a huge ammount of disk space. If you have enough room to store yout recording, you can run this command to start recording directly from dvsiwtch: {{{ dvsink-files -h DVSWITCHHOST -p 2000 FILENAME-OF-THE-RECORDING }}} Now press the 'record' button at the dvswitch interface to start/stop recording, and the 'cut' one to create a new file with the same name but a highet number === Lower stream quality === You can also record the stream locally at the same quality you are streaming through the ffmpg2theora command we used above to send the stream to the Icecast2 server. In this case you would only need to add {{{-o recording-file-name.ogv -}}} to the same command you used before. Like this: {{{ dvsink-command -h DVSWITCHHOST -p 2000 tee out.dv | ffmpeg2theora - -f dv -F 25:5 --speedlevel 0 -v 4 -a 1 -c 1 -H 9600 -o recording-file-name.ogv -o - | oggfwd ICECASTHOST ICECASTPORT ICECASTPASS /mountpoint.ogg }}} Please note that you would overwrite the first recording if you run that command twice, as you are using the same filename. You could is a $date variable to prevent this from happening. Like this: {{{ dvsink-command -h DVSWITCHHOST -p 2000 tee out.dv | ffmpeg2theora - -f dv -F 25:5 --speedlevel 0 -v 4 -a 1 -c 1 -H 9600 -o recording-file-name-$(date +"%T_%d-%m-%Y").ogv -o - | oggfwd ICECASTHOST ICECASTPORT ICECASTPASS /mountpoint.ogg }}}