An Introduction to Video Surveillance with 'Motion'

Videochatting and amateur pornography are all well and good, but have you ever wondered what else you can do with that webcam?
Well, thanks to the efforts of many dedicated open-source coders, any half-decent PC can be turned into a motion-detecting, snapshot-making, video-recording D.I.Y. security solution.

motion, a program designed to detect movement by analyzing streams of images, is one great way of doing this.
And while installing and configuring this piece of software used to be a royal pain in the butt, with the advent of Sarge, we now have an easy-to-install motion package right in the main repositories.

Before we go on, you should know that while motion was originally designed to interact with devices managed via Video4Linux (V4L), it is also able to interact with network cameras accessible via HTTP over TCP/IP.
In this introduction I will cover using a V4L video device (webcam, TV card, etc.) directly attached to your PC, but once you get the hang of it, using network cameras instead won't require much effort.

Initial requirements

This article assumes you have:

• a working Debian `Sarge' installation
• at least one working video device connected to your system and recognized as /dev/videoX, where 'X' is an index starting from zero (check the boot-time hardware detection messages to see)

NB: Setting up your video device is outside the scope of this article. In my case I have a cheapo Kensington USB webcam that is supported by the kernel using the se401 module, so it shows up automatically as /dev/video0 on my system.
There are many webcams out there, and Linux' hardware support varies wildly among the different models, so if you're going to buy a new webcam for your Linux box, I'd recommend that you try to make sure it's already supported -- if your camera isn't recognized by the kernel at boot time, it's likely that you'll have to find and compile a driver for it, so you can save yourself a lot of trouble by picking one that is already well-known in the Linux world.

Those who can get their hands on an old analog camera and a compatible TV capture card can use the capture card as the video device, except that it needs to be configured (set to the right channel and so on) before motion is started; there are many utilities for this, for example v4lctl.
As far as initial camera setup is concerned, the xawtv package can also be of great help if you have X installed, as it allows you to test video device output right on your monitor.

A first foray

We will begin by setting up the motion package and testing its interaction with our source video device.

For starters, get 'root' and invoke:

apt-get install motion

According to apt-get, the program itself will take up a few megs of disk space once installed.
This isn't much, but if you plan to capture and keep motion-generated video files, my advice would be to prepare a separate disk partition just for this purpose. Its size is up to you -- I'd recommend a couple GB to start -- but the number of cameras, their resolution, and your capture settings must be taken into consideration. In any case, starting with a separate partition is a good way to play around with the program without endangering the rest of your system -- should you happen to 'misunderestimate' your needs, motion will stop working once the target partition is filled up, but nothing else will get screwed up.
For the purposes of this article, we will assume that an empty disk partition has been created and mounted as /vidcap.

motion can run as a daemon or as a regular console program, according to settings read from configuration files and from the command-line.
Command-line settings override what is in the configuration file. Personally I prefer to avoid using the command-line options, so that I can tune and back up my configuration with ease.
Once you graduate to a multi-camera setup, you will need to split up your configuration into 'thread files' specific to each camera, but we don't need to worry about that now.

For the Debian package, a single configuration file is installed by default as /etc/motion/motion.conf, so that is where we will go to configure our setup.
As 'root', open /etc/motion/motion.conf with your favourite text editor.

Look for the line that says videodevice /dev/video0, and change this line so that it points to your working video device.
Immediately below, you should see width and height lines -- these need to be changed so that they match your camera's resolution in pixels. Generally you should go with the highest supported resolution unless you have good reasons (crappy CPU, low memory) not to do so; you want motion to have as many pixels to work with as possible.

If you're using a TV capture card as your video source, you'll also need a line that says input X somewhere in your config file, where 'X' is a number corresponding to the input to use from the card (normally 1). You will also need to specify a TV standard (the norm setting) matching the card's output -- normally 0 for PAL, 1 for NTSC, 2 for SECAM, and 3 for PAL NC.

motion comes with its own built-in web server, allowing it to stream 'live' video device output to [proper] web browsers, in MJPEG format. This is probably not what you're looking to do with it, but at this point it's a perfectly crumulent way of checking whether motion can grok output from our video device; another advantage of this facility is that it allows us to test our setup without a working X installation.
This is what we will do now.

Insert the following lines into /etc/motion/motion.conf:

output_all off
output_normal off
output_motion off

This disables all file output facilities.

Now look for the line that says webcam_port 0, and change the zero to a suitable port number to use for motion's mini-webserver. I go with the example 8000, which is accessible to hosts inside my LAN.

If the machine running motion can't run a graphical web browser itself, one more change is required:
look for the line that says webcam_localhost on, and change it to webcam_localhost off. This will allow HTTP clients other than the local host to access the webcam.

That's it! We're ready to roll.
Save and close /etc/motion/motion.conf.
Back at the command line, cross your fingers and punch in:

motion

If everything went well, you should see something like

Processing thread 0 - config file motion.conf
Thread0 device: /dev/video0 input: 8

This tells us motion is running.
Leave it be, and open up a graphical web browser (perhaps on another machine). Point it to http://hostname:port as appropriate -- in my case this is http://motionserver:8000. If your browser supports MJPEG as it should, you should now see 'live' output from your webcam!
NB: modern browsers should really have no problem with this. If using Firefox, you might have to refresh the page after loading it initially to get proper output. Internet Explorer users: please, give it up and get a real browser. I haven't seen a single IE setup that can deal with MJPEG, so it's t.s. for you, yet again.

Capturing motion events

OK, assuming the above instructions worked for you, we can now move on to detecting and capturing motion events, which is what motion is really for. We have two ways of storing detected events: as still image files, or as video files.
If motion is still running from before, hit Ctrl-C in its console to terminate our test run. Now return to /etc/motion/motion.conf (or wherever you chose to place the config file).
Look for the target_dir specification, and change it so that it points to the directory where you want the event data to be stored -- as per my instructions above, this would be /vidcap.

Producing motion event images

This is quite simple. In the config file, change the output_normal option from off to on.
Save the file, return to the prompt and launch motion again. While motion is running, any movement detected via your video source will result in a series of sequentially-numbered JPG files being dropped into your target directory (as defined with target_dir above).

Producing motion event videos

Let's take it one step further. Instead of capturing image sequences for each event, motion can harness the awesome power of ffmpeg to build fully-animated event video files with minimal overhead. The video files are built frame-by-frame 'on the fly', so they are finished and ready to watch almost immediately after the given 'event' is over.

Because it is considered 'non-free', ffmpeg is not available from the standard Debian repositories. To install it, you will need to add the following line to your /etc/apt/sources.list file:

deb ftp://ftp.nerim.net/debian-marillat/ sarge main

Now run

apt-get update
apt-get install ffmpeg

Once ffmpeg is installed, return to the motion config file and look for ffmpeg_cap_new off.
Changing this option to on will enable event video generation using ffmpeg.
There's one more setting you may want to add here:

ffmpeg_video_codec msmpeg4

This will force ffmpeg to use an internal video codec that is [generally] compatible with Windows Media Player without any additional codec installation, which can be pretty useful.
If omitted, this setting defaults to mpeg4, which is normally viewable anywhere true MPEG-4 is supported.

Note that there is no need to install any additional codecs (such as the popular packages from mplayerhq.hu) to get the above working. This is nice because it minimizes external dependencies, use of patent-encumbered technologies, and use of disk space.

Anyway, if you followed my instructions up to this point, save and close the config file, and launch motion again.
It's now time for a brief celebratory dance in front of your camera. When you are finished, you may browse to your storage directory, and find out just how ridiculous you look.
target_dir should begin to fill up with sequentially-numbered video event files .. and that's my cue to exit.

Onwards

The above introduction should be enough to get you started.
I'm sure you can imagine many different uses for motion.
The program supports execution of external commands at event time, so it is relatively simple to use these to hook it up to a database, or some sort of notification system (e-mail, SMS, etc.). With the right script 'glue', motion could easily be used as the core of a web-based surveillance system. Another feature I didn't really cover here is timelapse capture, which can be a lot of fun to play with (for instance, you can set up a camera to record the life of a houseplant over a few months' time).

Before we conclude, here are some caveats I should probably share with you:

• for more permanent installations, it's wiser to run motion as a special unprivileged user;
• also for security's sake, you probably shouldn't expose motion's mini-webserver to the internet -- this means running a proper firewall, or blocking external access with webcam_localhost on;
• every kind of camera and situation will require some tuning -- in the long run you'll have to adjust the settings so that 'false alarms' are minimal and image quality is acceptable;
• as far as surveillance gear is concerned, webcams are utterly sub-par, so don't expect miracles -- a production-grade system will require decent network cameras no matter what.

For the version in Debian stable (3.1.19), a detailed guide to configuring the program can be found at http://www.lavrsen.dk/twiki/bin/view/Motion/MotionGuide3x1x20.
For the purposes of this posting, you can ignore the instructions relating to compilation / installation, but the configuration tips are valid, so don't be afraid to dive in. Browsing around the same site, you will also find a selection of active mailing lists, and detailed information regarding compilation / installation / patching of newer versions, from source (NB: this is not for the faint of heart -- the program is in active development, and the bleeding-edge versions tend to be flaky).

So, that's it. You should now have a basic motion detection setup on your Debian box.

Just remember: you're not actually being paranoid if 'they' are really out to get you ;)

# Turn on timelapse feature and capture one frame every X seconds:
ffmpeg_timelapse X

# Choose a `rollover' time for timelapse videos.
# Valid choices for period are 
# "hourly", "daily", "weekly-sunday", "weekly-monday", "monthly", and "manual". 
ffmpeg_timelapse_mode period

cctv:/etc/init.d# update-rc.d motion defaults
 Adding system startup for /etc/init.d/motion ...
   /etc/rc0.d/K20motion -> ../init.d/motion
   /etc/rc1.d/K20motion -> ../init.d/motion
   /etc/rc6.d/K20motion -> ../init.d/motion
   /etc/rc2.d/S20motion -> ../init.d/motion
   /etc/rc3.d/S20motion -> ../init.d/motion
   /etc/rc4.d/S20motion -> ../init.d/motion
   /etc/rc5.d/S20motion -> ../init.d/motion

cctv:/etc/init.d# update-rc.d -f  motion remove

ffmpeg_video_code msmpeg4

ffmpeg_video_codec msmpeg4