In this guide we'll set up our Raspberry Pi so that we can stream live video to YouTube to either a public, unlisted or private stream.
Using a pre-built Docker image means we know exactly what we're getting and instead of having to go through lots of manual steps we can type in a handful of commands and get started immediately.
The YouTube live dashboard show my Raspberry Pi cluster and Pimoroni LED blinkt! boards.
Acknowledgements: thanks to Richard Gee for giving me the idea to live stream with a Raspberry Pi.
The old way of doing things
Normally this would have involved typing in many manual CLI commands and waiting up to 9 hours for some video encoding software (ffmpeg) to compile itself. If you got anything wrong you'd have to add on another 9 hours of compilation time (on a PiZero). In fact while compiling this tutorial I left my Pi running over night and it ran out of disk space meaning I had to start all over again.
08-05-2018 Update for Raspbian Stretch
The original Docker image was compiled for Raspbian Jessie. This is an update for Raspbian Stretch. Please use the following Docker image instead:
alexellis2/streaming:07-05-2018
The guide
You'll need a Raspberry Pi, I've used a Pi Zero here and the accompanying camera cable. Once you've setup the camera according to the official guide you're going to be good to go.
Also enable SSH via raspi-config and login remotely so you can save yourself some typing.
This guide work with Raspbian Jessie Lite as well as the full Pixel desktop.
Step 1. Install Docker
Installing Docker on the Pi is a one-line script:
$ curl -sSL https://get.docker.com | sh
$ sudo usermod pi -aG docker
$ reboot
Step 2. Test the camera
To make sure your camera is plugged in properly fire off a test shot. This will also help us gauge whether the orientation is correct:
$ sudo raspistill -o tester.jpg
You can then use scp or sftp to copy the file back to your Mac, Linux or Windows machine.
As a Windows user you may want to install Git bash which provides all the common UNIX-like utilities used with a Linux system.
Step 3. Pull the image down
The Docker image I produced took almost 9 hours to build, so you have two options now - either rebuild it yourself (over 9 hours) or pull it down from the Docker Hub. It's a 640MB download which will expand to 1.3GB in disk space:
$ docker pull alexellis2/streaming:17-5-2017
Step 4. Get your secret streaming key
Now head over to your Youtube live streaming dashboard. Make sure you've filled in all the details and click Reveal to see your key:
Now copy and paste your key (i.e. xxxx-xxxx-xxxx-xxxx( into the Raspberry Pi's terminal like this:
$ docker run --privileged --name cam -ti alexellis2/streaming:17-5-2017 xxxx-xxxx-xxxx-xxxx
You'll now be streaming live to the Internet, so pick wisely whether you want to keep that stream private, unlisted or public.
To cancel the stream just hit Control + C or shutdown the Pi.
This is me doing some late night testing for the blog.
Share your URL!
You can now share your URL with your audience and check out your statistics in real-time. There may be a delay of a few seconds - this is entirely normal and you can tweak lots of settings on the dashboard.
Step 5. Tweaks
Running in the background
To run in the background just swap out the -ti flag for -d:
$ docker run --privileged --name cam -d alexellis2/streaming:17-5-2017 xxxx-xxxx-xxxx-xxxx
Managing your container
If you type in docker run --name cam ... a second time you will get an error saying that a container with that name already exists. You can do two things now:
- Start the container again if it's stopped
$ docker start cam
- Stop and remove the container
$ docker stop cam
$ docker rm cam
Or in short-hand: docker rm -f cam
For a reference of Docker commands checkout my Docker and Raspberry Pi workshop.
Run on boot-up
To automatically stream every time you power up, then just add the flag --restart=always to the docker run command line.
Altering/extending the Docker image
Head over to this Gist for instructions on how to hack on the Dockerfile or entry.sh shell-script which contains all the parameters for streaming.
Add effects to the video
This is a more advanced step, but you can add effects to change the colour or rotate the picture by editing the entry.sh file in the provided Github repository.
Audio
By default the command-line we used won't be transmitting audio, for that we'd have to recompile ffmpeg using the Dockerfile and some additional options.
In our entry.sh script we set an empty audio channel since YouTube requires us to stream some audio, even if it's empty.
Positioning your camera
If you'd like to set your camera up on a window then there are two products I'd recommend which come with mini suction cups.
At the budget end you have the ZeroView from ThePiHut and at the premium end you have the cute Octocam kit from Pimoroni which contains all the hardware necessary for the project.
Now I want to learn Docker!
If you'd like to learn more about Docker on the Raspberry Pi then head over to my free tutorial series as featured in Docker Weekly.
There you'll be able to Build a Timelapse Rig with your Raspberry Pi, Create an Environmental Monitoring Dashboard, get started right at the beginning with a video and much more!
Other Q&A
Can I tweak the settings of the Dockerfile?
This short Gist gives instructions for editing the Dockerfile and entry script.
Can I use a USB camera?
This tutorial is geared up to use the Raspberry Pi camera module. Live-streaming with USB cameras is possible but there are more variables involved depending on the camera. If you'd like to write your own tutorial using a Dockerfile for a USB camera I'll link to it.
Isn't this faster to build on an RPi3?
Yes it is (around 45-60 minutes including adding libraries) - but there is something brilliant about being able to use the tiny form-factor of the ZeroW which has WiFi built-in.
Can't I cross-compile on another machine?
Cross-compiling is where you build code for one type of computer from a different one. I.e. code for a Pi Zero from a laptop or desktop machine. In theory you can do this but there a few drawbacks:
- You need a correctly configured Linux desktop or cloud VM.
- You have to be an expert with the command-line
- It's hard to reproduce exactly the same result every time.
Building on the device and shipping an image means the process is as simple as possible.
Shouldn't there be a
debfor this?
There are several ways of packaging software including Debian package files, Docker images, binaries and source tarballs (tgz). The deb package would assume the target OS is Raspbian (only) - the Docker image we've built should technically run on non-Debian based distributions too such as ArchLinux. Debian packages also need a certain amount of vetting and community involvement to get into the official repositories. The Dockerfile is a quick and easy way to get a repeatable result.