SOGÉÉCOM has been using Debian on all its machines for while now. This year, I was at Debconf16 in Cape Town, South Africa, for DebConf, the annual conference of the Debian project. I decided to help out with video streaming the conference and wanted to document the work we did!

The goal of this blog entry is to document the installation process of voctomix on a Debian Jessie box, with Blackmagic Decklink Capture cards. voctomix is a live video mixer written by CCC's videoteam. It's great and supports more recent video inputs than the software DebConf was using previously.

Getting the Blackmagic cards to work

Disclaimer: The blackmagic cards drivers does not seem to work with kernels more recent than 3.16.

Sadly, we will be using the proprietary drivers from Blackmagic. You can get them here. The name of the actual driver is Desktop Video. When we made the build, we used the 10.6.8 version.

When you finished downloading it, untar the file:

$ tar -xvf Blackmagic_Desktop_Video_Linux_10.6.8.tar

The driver comes with a .deb ready. You can install it with dpkg:

$ cd Blackmagic_Desktop_Video_Linux_10.6.8/deb/amd64
$ sudo dpkg -i desktopvideo_10.6.8a2_amd64.deb

You will get an error message about missing dependencies. To correct this, get apt-get to install what is missing:

$ sudo apt-get install -f

There are very good chances the software on the cards is not up to date. First, check their status:

$ sudo BlackmagicFirmwareUpdater status

If the output is not "OK", you can update them this way:

$ sudo BlackmagicFirmwareUpdater update 0:
$ sudo BlackmagicFirmwareUpdater update 1:

You should now have working drivers! The path to the video cards are /dev/blackmagic/io0 & /dev/blackmagic/io1.

Installing voctomix

There is a voctomix package on Debian Stretch an onwards, but not in Jessie. The problem is that you need more recent versions of gstreamer than what Jessie has.

To fix this, we will be using the Debian repository from the CCC VOC team to install the right versions of voctomix and gstreamer on Jessie.

First of all, add the following lines to your /etc/apt/sources.list:

deb http://www.deb-multimedia.org jessie main non-free
deb http://c3voc.de/voctomix jessie non-free

You'll then need install the GPG keys:

$ sudo apt-get update
$ sudo apt-get install deb-multimedia-keyring curl
$ sudo curl https://c3voc.de/voctomix/gpg-key.asc | apt-key add -
$ sudo apt-get update

$ sudo apt-get install gstreamer1.0-plugins-bad gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-ugly gstreamer1.0-tools libgstreamer1.0-0 python3 python3-gi gir1.2-gstreamer-1.0 gir1.2-gst-plugins-base-1.0 python3-pyinotify gstreamer1.0-libav rlwrap fbset

To get the GUI running, you'll also need these:

$ sudo apt-get install gstreamer1.0-alsa python3-gi-cairo gir1.2-gtk-3.0

Once all this is installed, it is time to clone the voctomix github repository!

$ sudo apt-get install git
$ git clone https://github.com/voc/voctomix.git

For our use, we used the latest voctomix release (0.3.1):

$ cd voctomix
$ git checkout 384a947

You should now have a working version of voctocore (the server) and voctogui (the GUI). Additionally, if you wish to call the executables without having to write the full path, you can symlink them to /usr/local/bin/:

$ sudo ln -s /home/videoteam/voctomix/voctocore/voctocore.py /usr/local/bin/voctocore
$ sudo ln -s /home/videoteam/voctomix/voctogui/voctogui.py /usr/local/bin/voctogui

Configuring voctomix

Now that voctomix has been installed, we need to configure voctocore to work with our setup!

First of all, we will need to create the main configuration file:

$ sudo mkdir /etc/voctomix
$ sudo vim /etc/voctomix/voctocore.ini

[mix]
videocaps=video/x-raw,format=I420,width=1280,height=720,framerate=25/1,pixel-aspect-ratio=1/1
audiocaps=audio/x-raw,format=S16LE,channels=2,layout=interleaved,rate=48000

; tcp-ports will be 10000,10001,10002
sources=cam1,cam2,grabber

[side-by-side-equal]
; defaults to 1% of the video width
;gutter=12
;ypos=200

[side-by-side-preview]
;asize=1024x576
;apos=12/12
;bsize=320x180
;bpos=948/528

[picture-in-picture]
;pipsize=320x180
;pippos=948/528

[previews]
; disable if ui & server run on the same computer and can exchange uncompressed video frames
enabled=false

; default to mix-videocaps, only applicable if enabled=true
; you can change the framerate and the width/height, but nothing else
videocaps=video/x-raw,width=1024,height=576,framerate=25/1

[stream-blanker]
enabled=true
sources=loop,nostream

As you can see from the first lines, this makes voctocore use 720p instead of the default 1080p. You would need quite a powerful setup (Intel i7) to run 1080p correctly.

Parsing streams to voctocore

The next step is to pass the blackmagic card output to voctocore and add a loop. You could do this 'manually' with gstreamer commands, but some nice people did a nice python script that simplifies everything.

First copy the repository:

$ git clone https://github.com/CarlFK/voctomix-outcasts
$ cd voctomix-outcasts
$ git checkout 3c99503

Once that is done, you can call ingest.py with some parameters to pass streams to voctocore for you. You will need a place to put your script and record your files:

$ cd ~
$ mkdir debconf16

We wrote a script to run all the ingest.py calls and the others scripts needed for voctomix to work correctly. This is the script you should run to start voctomix.

$ cd debconf16
$ vim debconf16/stream.sh

    #!/bin/bash -ex

    xterm -T voctocore -e sh -c 'while true; do voctocore; sleep 1; done' &

    sleep 4 # voctocore is needed for the rest. Giving it some time to start

    xterm -T voctogui -e sh -c 'while true; do voctogui; sleep 1; done' &
    xterm -T loop -e sh -c 'while true; do /home/videoteam/voctomix-outcasts/ingest.py --video-source png --video-attribs "location=/home/videoteam/debconf16/loop_720p_png/loop_720p%03d.png start-index=1 stop-index=375" --port 17000; sleep 1; done' &
    xterm -T cam1 -e sh -c 'while true; do /home/videoteam/voctomix-outcasts/ingest.py --port 10000 --video-source blackmagic --audio-source blackmagic --video-attribs "mode=17 connection=1 device-number=0"; sleep 1; done' &
    xterm -T cam2 -e sh -c 'while true; do /home/videoteam/voctomix-outcasts/ingest.py --port 10001 --video-source blackmagic --video-attribs "mode=17 connection=1 device-number=1"; sleep 1; done' &

    sleep 5 # We don't want to start recording before everything is in place

    xterm -T record -e sh -c 'while true; do /home/videoteam/voctomix-outcasts/record-timestamp.sh menzies-12; sleep 1; done' &
    xterm -T cut-list -e sh -c 'while true; do /home/videoteam/voctomix/example-scripts/control-server/generate-cut-list.py | tee --append cut-list.log; sleep 1; done' &

Making the loop work

The loop is created from a bunch of png files. In our case, they are in ~/debconf16/loop_720p_png. The png files are named according to a pattern: loop_720p_<number>.png. This means that loop_720p_001.png runs before loop_720p_002.png, and so on.

In stream.sh on the line creating the loop, you also have to specify the number of the first and the last file in the folder, after the directory and the file naming scheme. In our case, it is 1 and 375.

Congrats!

Well, this is it! You should now have a fully functional voctomix instance! Now you have to grab that stream and do whatever you need to do with it.

The mixed stream from voctomix can be displayed with this command:

$ nc <the_ip_address_voctocore> 15000 | mplayer -