Legacy Motion Guide for Motion versions 3.1.18 - 3.1.20

This is the version of the Motion Guide that matches releases from 3.1.18 till 3.1.20 of Motion.

It is a snapshot of how the Guide looked like before it was updated to fit version 3.2.1.

You cannot edit this old version of the Guide and there is not really any point in doing so.

Follow this link to the up to date MotionGuide.


Table Of Contents

Motion Overview

What is Motion?

Motion is a program that monitors the video signal from one or more cameras and is able to detect if a significant part of the picture has changed. Or in other words, it can detect motion.

The program is written in C and is made for the Linux operating system.

Motion is a command line based tool. It has absolutely no graphical user interface. Everything is setup either via the command line or via a set of configuration files (simple ASCII files that can be edited by any ASCII editor).

The output from motion can be:

  • jpg files
  • ppm format files
  • mpeg video sequences

How do I get Motion and what does it cost?

Motion is an open source type of project. It does not cost anything. Motion is published under the GNU GENERAL PUBLIC LICENSE (GPL) version 2 or later. It may be a bit difficult to understand all the details of the license text (especially if your first language is not English). It means that you can get the program, install it and use it freely. You do not have to pay anything and you do not have to register anywhere or ask the author or publisher for permission. The GPL gives you both rights and some very reasonable duties when it comes to copying, distribution and modification of the program. So in very general terms you do not have to worry about licensing as a normal hobby user. If you want to use Motion in a commercial product, if you want to distribute either modified or original versions of Motion - for free or for a fee, you should read the license carefully. For more information about free software and the GPL, I encourage you to study the very interesting documents about the subject available the of the Free Software Foundation pages about the Philosophy of the GNU Project.

Maintenance and Support

Both Motion and the Motion Guide are written by people that do all this as a hobby and without asking for any payments or donations. We have a life other than developing Motion and its documentation. This means that bugfixes and updates to this guide are done as our time and families allow it. You are however encouraged to participate and contribute in a very active mailing list. It is a list with a very "positive attitude" and with many contributors that propose features, post patches, discuss problems and patiently answer newbie questions with a very positive spirit. Expect 1-10 emails per day.

To get motion direct your browser to the Motion Homepage.

Under the download page you will find a series of stable versions and a series of development versions.

Motion was originally written by Jeroen Vreeken who still actively participates in the development of Motion and later Folkert van Heusden continued as a lead programmer with Kenneth Lavrsen responsible for Motion Guide, website and releases on Sourceforge.

From version 3.1.12 Motion is now project managed entirely by Kenneth Lavrsen, and the project now shift towards being developed by many contributers.

For support we encourage you to join the mailing list instead of writing to Jeroen, Folkert or Kenneth directly. We are all very active on the mailing list and by using the mailing list much more users will have benefit of the answers. Newbies and stupid questions are welcome on the list. Contributions in the form of patches are also very welcome on the mailing list.

Which version to download and use?

The current branch is the 3.1.X versions. There is a feature freeze on 3.1.X. Only bugfixes are made to the 3.1.X branch starting from 3.1.18. Latest 3.1.X release is the recommended release for production use.

Currently the community is starting working on the 3.2.X branch. This will completely change some features. Especially the remote control part will change from xmlrpc to a much simpler http interface.

Since 3.1.13 quite many options have been renamed to make setting up Motion easier. From 3.1.17-18 some unfinished features have been removed. The Berkeley mpeg feature is now removed because the ffmpeg feature is now mature and much better working.

Debian users can find binary packages of selected versions of motion here: http://packages.debian.org/unstable/graphics/motion

Debian releases that supports ffmpeg can be downloaded from http://sentinel.dk/debian/

What features does Motion have?

See more description at the Motion Homepage.
  • Taking snapshots of movement
  • Watch multiple video devices at the same time
  • Watch multiple inputs on one capture card at the same time
  • Live streaming webcam (using multipart/x-mixed-replace)
  • Real time creation of mpeg movies using libavcodec from ffmpeg
  • Take automated snapshots on regular intervals
  • Take automated snapshots at irregular intervals using cron
  • Sending an e-mail when detecting movement
  • Sending a SMS message when detecting movement
  • Execute external commands when detecting movement
  • Motion tracking
  • Feed events to an MySQL or PostgreSQL database.
  • Feed video back to a video4linux loopback for real time viewing
  • Web interface using Motion Related Projects such as motion.cgi, Kenneths Webcam Package, Kevins Webpage, X-Motion and many more.
  • User configurable and user defined on screen display.
  • Control via xml-rpc - small control binary to control motion while running
  • Automatic noise and threshold control
  • Ability to control the pan/tilt of a Logitech Sphere (or Orbit) camera
  • Highly configurable display of text on images.
  • High configurable definition of path and file names of the stored images and films.

You can find more information and links at the Motion Homepage.

Linux vs. FreeBSD

Motion is originally developed for Linux and it is still mainly developed and supported for this platform. From version 3.1.15 an experimental port has been made by Angel Carpintero. Not all features of Motion are supported at this time and it still needs a lot of test time on different hardware. Angel is very interested in feedback. Join the Motion Mailing List and give your feedback there. Patches for bugfixes and for enabling the missing features are very welcome. The rest of this guide is still mainly targeted for Linux users.

Documentation

You have the following sources of information:

  • This document (you are lucky to have found it).
  • The author of the program has written a description of the technology behind motion.
  • The man page. After installation simply write man motion
  • The default motion.conf file that comes with the package.
  • Misc. document that comes with the package gives a few hints. When this is written the FAQ describes the wrong information about where motion searches for the motion.conf file.

Supported Hardware

Input devices: Here we are thinking about the cameras.

Motion supports video input from two kinds of sources.

Standard video4linux devices (e.g. /dev/video0). Motion has no drivers for cameras. Installing the camera itself is outside the scope of this document. But here are some nice links. Network cameras (which are actually cameras with a built in web server that can be connected directory to your network).

Known Problems

See also the Frequently Asked Questions

Kernel 2.6 and pwc. Note that for kernel 2.6 there is a new release of the Philips WebCam (pwc and pwcx) drivers 10.0.X. It is recommended to install this (requires kernel rebuild). Hopefully it will enter the kernels soon. See Logitech Quickcam Orbit or Sphere just below this for what you must do if you have pwc 8, 9 or 10.

If you use use a Logitech Quickcam Orbit or Sphere using the driver pwc/pwcx and kernel 2.6.X you should replace the file in the Motion sources called pwc-ioctl.h with the one that comes with the your pwc version. Motion is shipped with 3 versions of pwc-ioctl.h-VERSION. Rename the one that fits your major pwc version number best to pwc-ioctl.h (after renaming the current to something else). There has been some small adjustments in the API that requires that you have the right header file.

EPIA Motherboards and maybe other i386 non-Intel CPU boards may not be detected by the configure script causing the code to be generated with assembler code that generates illegal instruction errors during runtime. The fix is to run the configure script like this:

configure --without-optimizecpu

before building Motion with make and make install

How do I install Motion?

Motion is mainly distributed as source files that you must compile yourself. There is also an RPM made on Fedora Core 2. And Debian packages are available for selected versions.

The short overview of the steps to install Motion.
  • Preparation: Motion uses a number of shared libraries that must be installed on your computer before you can build Motion. The needed shared libraries depends on the features you wish to use. Features network camera, ffmpeg, MySQL and PostgreSQL needs specific shared libraries installed. See preparation section for more information.

  • Download the motion source files (distributed as tar'ed and compressed files). Place the file in a place of your own choice.

  • Untar and uncompress the file to the place you want the program installed. Editor recommends placing the motion source file directory in /usr/local. If you do not have write access to the /usr/local directory (you are under the mercy of an ignorant system administrator with a severe case of paranoia) - you can install the program in a directory in your home directory. You will then need to read the next section about how to configure before you compile the program. Below is shown the exact commands using version 3.1.X installed in /usr/local as an example (replace /path/to with the actual placement of the tar.gz file).
    cd /usr/local
    tar -xvzf /path/to/motion-3.1.X.tar.gz
    
  • You will now have created a directory called motion-3.1.X. You can rename it to motion (mv motion-3.1.X motion). I recommend creating a symbolic link to the current version. This way you can more easily experiment with different version simply by changing the link.
    ln -s motion-3.1.X motion
    
  • Now change to the new directory
    cd motion
    
  • Run configure. You can start with the defaults. If you need to modify the installation parameters you can read the next section.
    ./configure
    
  • Build the code
    make
    
  • Install the code, manual page, etc
    make install
    
  • In /etc/motion/etc you will find a file called motion-dist.conf. If it is the first time you install Motion - rename this file to motion.conf and edit as a minimum the settings: videodevice, input, norm, frequency, width, height and target_dir. That should get you going.

  • Run the program. To enable more features you must modify the config file or add command line options. You will not get too far with the defaults. The command line is nice for quick experiments. But for normal use I recommend using the config file.
    motion
    

Preparation For Install

Note: If you're using SuSE 9.2, you might want to ADDITIONALLY have a look at Compiling on SuSE 9.2. As mentioned on that page as well, you will still need to read the instructions here as well.

Before you start you may need to install a number of shared libraries that Motion uses. If they are missing the feature will simply normally not be included. Most of these libraries can be found on the CDs of your distribution. A few will have to be downloaded from the Internet. Note that when you install software using pre-compiled binaries (Redhat type RPMs, Debian debs etc) you normally only get what is needed to run the programs themselves. In order to compile other programs from source that uses these pre-compiled libraries you also need to installed the development packages. These are normally called the same name as the package suffixed by -devel or -dev. These development packages contains the header files (xxx.h) that Motion needs to build with the shared libraries. If you build a library from sources you already have these header files. It is recommended to simply install the pre-compiled binary packages and their development brothers.

This is a list of shared libraries used by Motion and the RPM packages that provides them.

Motion will always need these libraries to be built and work
Library RPM Packages Debian Packages
libm, libresolv, libdl, libpthread, libc, ld-linux, libcrypt, and libnsl glibc and glibc-devel libc6 , libc6-dev ,libglib1.2
libjpeg libjpeg and libjpeg-devel libjpeg62 and libjpeg62-dev ( optional libjpeg-mmx-dev )
libz zlib and zlib-devel zlib1g and zlib1g-dev

For generating mpeg films with ffmpeg you need this library:
(See also the section 'Generating MPEG films with ffmpeg' for how to install ffmpeg and libavcodec)
Motion must be installed with revision 0.4.8 or 0.4.9pre1 of ffmpeg.
Library RPM Packages Debian Packages
libavcodec, libavframe ffmpeg and ffmpeg-devel or install from source! ffmpeg ,libavcodec1,libavcodec1-dev (*)
(*) Debian has not provided deb packages for ffmpeg due patent issues. However this is about to change so checkout for availability of newer versions of debian ffmpeg debs. You can build yourself from source or from Christian Marillat website or apt repository.
deb ftp://ftp.nerim.net/debian-marillat/ stable main # ( woody )
deb ftp://ftp.nerim.net/debian-marillat/ testing main # ( sarge )
deb ftp://ftp.nerim.net/debian-marillat/ unstable main # ( sid )
Add the suitable line to your /etc/apt/sources.list and run this:
apt-get update ; apt-get -y install ffmpeg libavcodec1 libavcodec1-dev

For using XML-RPC remote control of Motion you need this library: (See also the section 'Controlling Motion via xml-rpc' for how to install xmlrpc-c)
Library RPM Packages Debian Packages
libxmlrpc xmlrpc-c and xmlrpc-c-devel - or install from source!
You also need w3c-libwww and w3c-libwww-devel
libxmlrpc-c0 , libxmlrpc-c0-dev , libwww-dev (for -lwwwzip )

For logging in MySQL you need this library:
Library RPM Packages Debian Packages
libmysqlclient mysql and mysql-devel libmysqlclient10 and libmysqlclient10-dev

For logging in PostgreSQL you need this library:
Library RPM Packages Debian Packages
libpq postgresql-libs and postgresql-devel postgresql-dev and libpgsql2

Configure Script

Configure is script that you run to setup the build environment for the C-compiler. It generates the "Makefile" which the program "make" uses to compile and install the software.

To run configure your current directory must be the motion directory. You type

./configure

You can add the parameter ./configure --help to get help on the different switches.

This is walk through of the options.

Option Description
Defaults for the options
are specified in brackets [ ]
Editors comment
-h, --help display this help and exit  
--help=short display options specific to this package This command shows the options special to motion. Recommended
--help=recursive display the short help of all the included packages  
-V, --version display version information and exit Gives no useful information
-q, --quiet, --silent do not print `checking...' messages Not very useful. Output to screen is only a few lines anyway.
--cache-file=FILE cache test results in FILE. [disabled] No function
-C, --config-cach alias for `--cache-file=config.cache' No function
-n, --no-create do not create output files Used for testing if other switches produce error - without writing anything to the disk
--srcdir=DIR find the sources in DIR. [configure dir or `..'] DIR is a directory path. Editor recommends having the current directory being the motion installation directory and not using this switch. Then it defaults to the same directory as where the configure script is which is the current directory.
Installation directories:    
--prefix=PREFIX install architecture-independent files in PREFIX
[/usr/local]
The default /usr/local means that the executable binary "motion" is installed in /usr/local/bin, the manual page in /usr/local/man/man1, the document files in /usr/local/docs/motion-version, configuration file in /usr/local/etc, and some examples config files in /usr/local/examples/motion-versionEditor recommends keeping this default setting.
If you are experimenting with many parallel versions it may be interesting to set the PREFIX to e.g. /usr/local/motion and then add /usr/local/motion/bin to your search path (or simply cd /usr/local/motion/bin before execution).
This way you can change version just by changing the symbolic link in /usr/local/motion as suggested earlier in this guide.
If you are installing the software on a machine where you have no access to the /usr/local but have write access to a home directory, then you should change this to point to a directory within your home tree.
Example: --prefix=$HOME
--exec-prefix=EPREFIX install architecture-dependent files in EPREFIX
[PREFIX]
If you set this it only defines an alternative installation directory for the executable binary.
Note: The executable binary will be placed in a directory "bin" below the directory specified by this option
Editor recommends leaving this as default (i.e. not setting it).
--bindir=DIR user executables [EPREFIX/bin] With this option you can control exactly in which directory the executable binary is installed. The previous option automatically adds the bin directory. Here you are in fill control.
--sbindir=DIR System admin executables [EPREFIX/sbin] Not used by motion. Ignore it.
--libexecdir=DIR program executables [EPREFIX/libexec] Not used by motion. Ignore it.
--datadir=DIR read-only architecture-independent data [PREFIX/share] Not used by motion. Ignore it.
--sysconfdir=DIR read-only single-machine data [PREFIX/etc] This is where motion both installs the default configuration file and also where it later searches for it.
Motion searches for the configuration file "motion.conf" in the following order:

    1. Current directory from where motion was invoked
    2. $HOME/.motion
    3. The sysconfig directory set by this switch. If not defined the default is /usr/local/etc/

Editor recommends leaving this at default. Be careful if you run "make install" again. This will overwrite the motion.conf file that you have edited and experimented with for hours. Make sure to keep a copy in a safe place. Alternatively, copy the working file to the motion base install directory. Then make install will simply copy the same file back again.
--sharedstatedir=DIR modifiable architecture-independent data [PREFIX/com] Not used by motion. Ignore it.
--localstatedir=DIR modifiable single-machine data [PREFIX/var] Not used by motion. Ignore it.
--libdir=DIR object code libraries [EPREFIX/lib] Not used by motion. Ignore it.
--includedir=DIR C header files [PREFIX/include] Not used by motion. Ignore it.
--oldincludedir=DIR C header files for non-gcc [/usr/include] Not used by motion. Ignore it.
--infodir=DIR info documentation [PREFIX/info] Not used by motion. Ignore it.
--mandir=DIR man documentation [PREFIX/man] Editor recommends the default.
Optional Packages:    
--with-ffmpeg=DIR Specify the path for the directory prefix in which the library and headers are installed.
If not specified configure will search in /usr/ and /usr/local/
DIR is the directory PREFIX in which the ffmpeg shared libraries and their headers are installed.
If you install ffmpeg from sources and use the default directories or if ffmpeg is installed as a binary package (RPM or deb) you do not need to specify the directory prefix. Configure will find the libraries automatically. If you installed ffmpeg from sources and specified a different --prefix when building ffmpeg you must use the same value for the DIR ( --with-ffmpeg=DIR).
For more information on FFmpeg see the FFmpeg project home page.
FFmpeg is a package that enables streamed video mpeg signal from your web camera to a browser.
Editor recommends installing ffmpeg from source and in the directory /usr/local/ffmpeg and build ffmpeg with ./configure --enable-shared.
This places libraries in /usr/local/lib and headers in /usr/local/include.
--without-ffmpeg Do not compile with ffmpeg Use this if you do not want to compile with ffmpeg. If ffmpeg is not installed you do not need to specify that Motion must build without ffmpeg.
--with-mysql=DIR normally, configure will scan all possible default installation paths for mysql. When its fail, use this command to tell configure where mysql installation root directory is. DIR is the installation directory of mysql. E.g. /usr/local/mysql
Default is that make searches in the normal installation directories of most distributions.
--without-mysql Do not compile with MySQL support Use this if you do not want to include MySQL support in the package.
This can also be useful if you get compilation errors related to MySQL and you actually do not need the feature anyway.
--with-pgsql=DIR Include PostgreSQL support. DIR is the PostgreSQL base install directory, defaults to /usr/local/pgsql.
Set DIR to "shared" to build as a dynamic library, or "shared,DIR" to build as a dynamic library and still specify DIR.
Default is that make searches in the normal installation directories of most distributions.
See section later about PostgreSQL about potential problem during compilation. There is an easy workaround for it.
--without-pgsql Do not compile with PostgreSQL support Use this if you do not want to include PostgreSQL support in the package.
This can also be useful if you get compilation errors related to PostgreSQL and you actually do not need the feature anyway.
--without-v4l Exclude using v4l (video4linux) subsystem. Makes Motion so it only supports network cameras. Can be used if you do not need V4L support and maybe lack some of the libraries for it.
--without-optimizecpu Exclude autodetecting platform and cpu type. This will disable the compilation of gcc optimizing code by platform and cpu. Use this if the optimization causes problems. Typically if you build on some non X386 compatible CPU.

Make

When you run make, all the C-source files are automatically compiled and linked. Just look out for error messages.

Make uses a file called "Makefile" which is generated by the "configure" script you just ran. If you have special needs you can manually edit this file. Next time you run configure a new Makefile will be generated and your changes are lost.

ALERT! Attention!

If you have run make before, you should run a make clean before running make again. This cleans out all the object files that were generated the previous time you ran make. If you do not run make clean first before you rebuild Motion you may not get the additional feature included. For example: If you built Motion without XMLRPC support and then add it later - and rebuild Motion without running make clean first - the XMLRPC feature does not get compiled into the Motion binary.

First time you build motion run ./configure, make, make install. If you need to build it again (to run with different configure options) run ./configure, make clean, make, make install.

Make Install

make install simply copies all the nice files that were generated during the compilation/linking that make did.

Makes the directories (if they do not already exist): /usr/local/bin, usr/local/man/man1, /usr/local/etc, /usr/local/doc/motion-3.1.X, /usr/local/doc/motion-3.1.X, and /usr/local/examples/motion-3.1.X.

Copies the following files from the base motion directory (assuming the default PREFIX /usr/local was used when running configure - otherwise adjust to the actuals you chose)
  • Executable binary "motion" to /usr/local/bin
  • Manual page "motion.1" to /usr/local/man/man1
  • Document files "CHANGELOG, COPYING, CREDITS, INSTALL, and README to /usr/local/doc/motion-3.1.X
  • Example configuration files "motion.conf*" to /usr/local/examples/motion-3.1.X
  • Configuration file "motion.conf" to /usr/local/etc
Note that the any existing files are overwritten. Pay attention to your configuration file motion.conf. You may not want this overwritten. Keep a copy in a safe place before you run "make install". Editor recommend renaming the motion.conf in the source code directory after the very first installation. This way you will not accidentally overwrite the real motion.conf file.

Un-install

From the motion base installation directory you simply run make uninstall

And delete the base installation directory in /usr/local and any link pointing to it. If you have forgotten where you installed it or someone else did it for you, simply search for the files and directories starting with motion. If the filenames and the directories match the names described in the "Make Install" section of this document, you can safely delete them.

Additional Make Options

The make command can be run with several options. make, make install and make uninstall has already been described above.

make clean
deletes all the binary files (object files) and the motion binary generated by make. It also deletes temporary files and any jpg files that motion has saved in the motion source directory. It is very important to always run make clean before you run make if you change the configuration (like adding features such as XMLRPC or ffmpeg) and rebuild motion.

make distclean
deletes the files: config.status, config.log, config.cache, Makefile, and motion.spec.

make updateguide
fetches a fresh new copy of this guide and place it in your motion source directory. Note that the pictures are not downloaded.

make dist
performs make clean, make distclean and make updateguide in one single operation.

Upgrading From Older Version

If you are upgrading from motion 3.0.X or from an older version of 3.1.X you should note that many options have been removed from version 3.1.13 and forward and many new have arrived. You still have most of the old features. The options have been changed for two reasons. New more flexible features and to simplify getting started with Motion. You should also note these major differences.
  • The use of thread files has completely changed. Read the section "The Config Files" carefully.
  • The mask file format has changed. Read the section about "Mask File"
  • Pre_capture feature introduced in 3.1.12
  • Advanced filename feature enables very flexible filename definitions (3.1.13)
  • onffmpegclose options enables running external scripts when mpeg file is closed (3.1.13)
  • despeckle feature improves motion detection and noise immunity (3.1.13)
  • Minimum_motion_frames feature prevents short noise events from being saved (3.1.14)
  • If you use the database features you need to note that from version 3.1.15 and forward the fields have been redefined. Removed are second, minute, hour, day, month and year. Instead these six have been replaced by a real timestamp field called time_stamp. The relatively new field 'type' has been renamed to 'file_type' to avoid reserved SQL words. A new field 'text_left' has been added which stores the text given by the config option text_left. And last a field called 'camera' has been added which stores the thread number.
  • From 3.1.15 the ffmpeg feature now also supports mpeg4 and msmpeg4. The build process of Motion now use ffmpeg libraries as shared libraries. The --with-libavcodec has been replaced by a --with-ffmpeg which only needed to specify if you are installing ffmpeg from sources in a non-standard location. If you have installed ffmpeg from sources already you will need to rebuild by running (from within the ffmpeg source file root) ./configure --enable-shared followed by make and make install. If you had installed ffmpeg from a binary RPM or deb you probably don't have to do anything.
  • Rotate feature was introduced in 3.1.15
  • Berkeley mpeg feature has been removed in 3.1.18 (use ffmpeg - it is much better)
  • Incomplete prediction feature was removed in 3.1.18. (lack of interest in finishing it)
  • Smart Mask feature introduced in 3.1.18
  • output_normal can now also have the value "first" which means only save first jpg from each event (3.1.18)
  • ffmpeg-0.4.9 is now supported. Motion detection mpegs can no longer be saved as mpeg1 (ffmpeg does not support non-standard framerates in 0.4.9) (3.1.18)
  • Motion now supports most (not all) mjpeg streaming cameras (3.1.18).

The table below shows the new options in the left column, and obsolete options in the right column. If the there are options on both sides in a row it means that the options in the left column replaced the options in the right column.

New Options Obsolete Options
text_left (3.1.13)
text_right (3.1.13)
text_changes (3.1.13)
drawtext_user (3.1.13)
drawtext_shots (3.1.13)
drawtext_changes (3.1.13)
jpeg_filename (3.1.13)
ffmpeg_filename (3.1.13)
snapshot_filename (3.1.13)
timelapse_filename (3.1.13)
predict_filename (3.1.13)
(predict_filename removed in 3.1.18)
oldlayout (3.1.13)
snapshots_overwrite (3.1.13)
snapshot_interval (3.1.13) snapshots (3.1.13)
  realmotion (3.1.13)
despeckle (3.1.13) -
pre_capture (3.1.12) -
onffmpegclose (3.1.13) -
ffmpeg_timelapse (v. 3.1.14) ffmpeg_timelaps (renamed v 3.1.14)
ffmpeg_timelapse_mode (3.1.14) -
sql_log_image (3.1.14)
sql_log_snapshot (3.1.14)
sql_log_mpeg (3.1.14)
sql_log_timelapse (3.1.14)
sql_log_prediction (3.1.14)
-
minimum_motion_frames (3.1.14) -
rotate (3.1.15) -
ffmpeg_variable_bitrate (3.1.15)
ffmpeg_video_codec (3.1.15)
-
  berkeley_single_directory (3.1.18)
mpeg_encode (3.1.18)
mpeg_encode_bin (3.1.18)
adjust_rate off (3.1.18)
jpg_cleanup (3.1.18)
  predict_filename (3.1.18)
predict_enable (3.1.18)
predict_threshold (3.1.18)
predict_description (3.1.18)
sql_log_prediction (3.1.18)
brightness (3.1.18)
contrast (3.1.18)
saturation (3.1.18)
hue (3.1.18)
 
smart_mask_speed (3.1.18)  
output_normal
valid values are now "on", "off", and "first"
(3.1.18)
 

Running Motion

Important Definitions

Motion is invoked from the command line. It has no GUI. Everything is controlled from the command line and from config files. The editor recommend only using the config files as this is easier in the long run and much less confusing having all options in one place. A few important definitions.
  • A snapshot is a picture taken at regular intervals independently of any movement in the picture.
  • A "motion" image/mpeg shows the pixels that have actually changed during the last frames. These pictures are not very useful for normal presentation to the public but they are quite useful for testing and tuning and making mask files as you can see exactly where motion sees something moving. Only the Y-channel is shown which make the motion images green.
  • A normal image is the entire image taken by the camera.

The Config Files

The name of the config file must be 'motion.conf'. When you invoke Motion it will search for the configuration file called 'motion.conf' in the following order:
  1. Current directory from where motion was invoked
  2. Then in a directory called '.motion' in the current users home directory (shell environment variable $HOME). E.g. /home/goofy/.motion/motion.conf
  3. The directory defined by the --sysconfdir=DIR when running .configure during installation of Motion
    (If this option was not defined the default is /usr/local/etc/)
If you have write access to /usr/local/etc then the editor recommends having only one motion.conf file in the default /usr/local/etc/ directory.

Motion has a configuration file in the distribution package called motion-dist.conf. When you run 'make install' this files gets copied to the /usr/local/etc directory.

The configuration file needs to be renamed from motion-dist.conf to motion.conf. The original file is called motion-dist.conf so that your perfectly working motion.conf file does not accidentally get overwritten when you re-install or upgrade to a newer version of Motion.

If you have more than one camera you should not try and invoke Motion more times. Motion is made to work with more than one camera in a very elegant way and the way to do it is to create a number of thread config files. Motion will then create an extra tread of itself for each camera. If you only have one camera you only need the motion.conf file. The minute you have two or more cameras you must have one thread config file per camera besides the motion.conf file.

So if you have for example two cameras you need motion.conf and two thread config files. Total of 3 config files.

An option that is common to all cameras can be placed in motion.conf. (You can also put all parameters in the thread files but that makes a lot of editing when you change a common thing).

An option that is unique to a camera must be defined in each thread file.

The first camera is defined in the first thread file called from motion.conf. The 2nd camera is defined in the 2nd thread file called from motion.conf etc.

Any option defined in motion.conf will be used for all cameras except for the cameras in which the same option is defined in a thread config file.

Motion reads its configuration parameters in the following sequence. If the same parameter exists more than one place the last one read wins.
  1. Motion reads the configuration file motion.conf from the beginning of the file going down line by line.
  2. If the option "thread" is defined in motion.conf, the thread configuration file(s) is/(are) read.
  3. Motion continues reading the rest of the motion.conf file. Any options from here will overrule the same option previously defines in a thread config file.
  4. Motion reads the command line option again overruling any previously defined options.
So always call the thread config files in the end of the motion.conf file. If you define options in motion.conf AFTER the thread file calls, the same options in the thread files will never be used. So always put the thread file call at the end of motion.conf.

If motion is built without specific features such as ffmpeg, mysql etc it will ignore the options that belongs to these features. You do not have to remove them or comment them out.

If you run the XML-RPC command motion.conf.write (motion-control conf write) motion will overwrite motion.conf and all the thread.conf files by autogenerated config files neatly formatted and only with the features included that Motion was built with. If you later re-build Motion with more features or upgrade to a new version, you can use your old config files, run the motion.conf.write command, and you will have new config files with the new options included all set to their default values. This makes upgrading very easy to do. It requires that Motion is built with the XML-RPC feature.

Command Line Options

SYNOPSIS
motion [ -CDhlmNpQw] [ -a seconds] [ -c changes] [ -d device] [ -E command]
[ -F file] [ -f nr] [ -G seconds] [ -g seconds] [ -i input] [ -L noise] [ -M address] [ -n norm]
[ -O command] [ -P device] [ -q quality] [ -S nr] [ -s widthxheight] [ -t target dir]
[ -u user:pass ] [ -U webcam_path ] [ -V device]

Option Description Editors comment
-a seconds time between two automated snapshots, valid range: 0 to thousands, default: 0 The default value of 0 means that the feature is disabled.
-C Output changes count for every frame, usable for tuning This feature writes the detected number of changed pixels (after noise filtering) to the console. Motions outputs the numbers for all threads continuously for every frame read from the video device. The output format is "changes: number_of_changes". The number is an expression of how many pixels that changed and how much. The higher a value, the more motion This feature does not work when in daemon mode!
The feature is excellent for debugging. You can use the feature to set the noise level so that motion normally shows "changes: 0". You can also use it to set the right detection threshold level.
-c changes threshold for detecting a change, Valid range: 1 to thousands, default: 1500. Use the -C switch to experiment to find the right value. If you do not get small movement detected (see the mouse on the kitchen floor) lower the value. If motion detects too many birds or moving trees, increase the number.
-D Daemonize This means that motion is started as background process(es) and you return to the command prompt right away.
Too see and kill the program while it runs in daemon mode run
ps -ef | grep motion
from the command prompt.
All you have to do now is to kill the motion with the lowest process ID "kill number". From version 2.9.x motion is started as a main thread that creates child threads. Kill the parent and you kill the children.
Note: With version 2.6.3 and earlier (before threading was introduced) you have to kill each individual process.
Also note that the equivalent option in the motion.conf file changed spelling between 2.6.3 and 2.9.x. In 2.6.3 it was deamon and in 2.9.x it was corrected to daemon.
-d device video4linux capture device, default: /dev/video0 The syntax for the value is /dev/devicename where device name in Linux is normally video0, video1, video2 etc. The actual device number is set by the device driver. See the documentation for this. If you have more than one device you need to define them in config files instead.
-E command Execute 'command' when detecting motion. The command is executed at the beginning of the event before the images are stored.
This means that you cannot use this command to process the stored files. Use -O instead for this purpose. This option is good for alarming, recording using other programs etc.
-F file pgm image to use as a mask for filtering motion. This file must have the same size as you have set for the video4linux device. Full path of the PGM (portable gray map) mask file.
If you have one or more areas of the camera image in which you do NOT want motion detected (e.g. a tree that moves in the wind or a corner of the picture where you can see cars/pedestrians passing by) you need a mask file. This file is a picture that you create in your favorite photo editing program. The areas that you want detected must be white. The error that you want ignored must be black. The ppm image must be the same size (number of pixels high and wide) as the pictures that are taken by the camera (video4linux device).
-f number Maximum number of frames per second. Valid range: 0 to limit of camera, default: none Maximum number of picture frames per second that motion takes when detecting movement. Default is none which means that it takes as many as possible.
For versions before 2.9.8 the value 0 would generate an error. Editor recommends not to define the option at all if not needed.
-G seconds Minimum gap between two shots in seconds. 0 to thousands, default: 0 It is the minimum time from an image is saved till an image is saved again.
-g seconds minimum gap between events, Valid range: 1 to thousands, default 60 An event is defined as a series of motion images taken within a short timeframe. E.g. a person walking through the room is an event that may have caused 10 single jpg images to be stored. This option defines how long a pause between detected motions that is needed to be defined as a new event.
-h Display an short text with all command line functions. Display a short 1 line help text for each command option. Motion terminates right after having shown the text. If Motion already runs it is no problem. You can invoke it with the -h option without any impact on the running processes.
-i input input channel to use expressed as an integer number starting from 0. Valid range: depends on video capture card, default: 8 If you have a video capture card you can define the channel to tune to using this option. If you are using a USB device, network camera or a capture card without tuner you should set the value to the default 8. Many TV tuner cards have the input channels: TV Tuner = 0, Standard composite video = 1, S-VHS = 3. Other have TV=0, composite video 1= 1, composite video = 2, S-VHS = 3.
-L noise Noise level, all changes smaller than this level will be considered noise. Valid range: 1 to 255, default: 32 This is different from the threshold parameter. This is changes at pixel level. The purpose is to eliminate the changes generated by electric noise in the camera. Especially in complete darkness you can see the noise as small grey dots that come randomly in the picture. This noise can create false motion detection. What this parameter means is that the intensity of a pixel must change more than +/- the noise threshold parameter to be counted.
-l Do not locate and mark motion on output pictures The mark is in the form of a rectangle on the saved images so that you can easily see what it was that was moving in the picture. It is a matter of taste if you want this.
-M address Send a mail to 'address' when detecting motion. Uses the standard UNIX 'mail' program which is part of the 'sendmail' package.
-m Output 'motion' images Motion images shows the motion content of the pictures. This is good for tuning and testing but probably not very interesting for the general public. Default is not to store motion images. Motion pictures have an m at the end of the filename.
-N Normal image is an image that is stored when motion is detected. The valid values are 'on', 'off', and 'first'. Default is 'on' Normal image is an image that is stored when motion is detected. It is the same image that was taken by the camera. I.e. not a motion image as defined above. Default is that normal images are stored. You can turn the feature off or only save the first motion detected picture per event.
-n norm norm to use (pal/pal-nc/ntsc/secam), default: pal Only relevant for capture cards. This sets the video coding standard for the card. In most of western Europe PAL is used. In France and some eastern European countries SECAM is used. In the Americas and Japan NTSC is used.
-O command Execute 'command' when an image is saved. The name of the image will be given as argument. The command can be a simple UNIX command, a bash script, a perl program, a real binary program, anything. The program is given the stored image filename as a parameter.
-P device video4linux video loopback input for normal images. If a dash '-' is given as device, motion will try to use /proc/video/vloopback/vloopbacks to find a free pipe on its own. default: not set See the video4linux loopback device web site for more information about video loopback
It is a software device driver used when you want more than one program to use the output from the same video4linux device. See also the section about video loopback device later in this document.
-p Output ppm images instead of jpeg. This will reduce CPU load but disk I/O will increase a lot.  
-Q Don't sound the warning beep when detecting motion. (This doesn't change anything in daemon mode, there never is a beep there)  
-q quality JPEG image quality, Valid range: 0-100,default: 75. 100 means hardly compressed. A small number means a much smaller file size but also a less nice quality image to look at. 50 is a good compromise for most.
-S number Send a SMS to number using sms_client when detecting motion. Not a feature that has received much attention recently. If you live in GSM land you are probably better off using the email to SMS gateway that most GSM providers have using your mail client. For more information see the sms_client home page.
-s widthxheight Picture size, Valid range: Camera dependent, default: 352x288 Motion actually set the size of the image coming from the video4linux device. The selected size must be supported by the device. For some device drivers like pwc (driver for Philips USB cameras) setting the size to a non-standard value makes the driver create an image of the nearest smaller size and create a gray band around the image to fit the size given by motion. Note that it is the driver and not motion that generates the gray band. Motion will try to detect motion in the entire image including the gray band.
-t target-dir destination for snapshots This is the target directory for all snapshots, motion images and normal images. The default is the current working directory (current working directory of the terminal from which motion was started). You will normally always want to specify this parameter either as a command line option or in the config file.
-U url or IP_addr Webcam path URL for a net camera.
Important note: To use the Netcam options you must have the cURL shared library "libcurl" installed on your system. This is normally part of Linux distributions. If it is not installed, it is most likely on your distribution CDs. As RPM the latest RedHat package for the i386 platform is called curl-7.9.5-2.i386.rpm. The official CURL homepage is at http://curl.haxx.se/. The download page on this site has both source code and many binary packages (RPM, Debian etc). Latest release as this is written is 7.9.8.
If you use the netcam_url in motion.conf or command line with -U , height and width are ignored. It actually uses jpeglib to pull the height and width from the JPEG header directly.
-u user:pass For password-protected network cameras, use this option for the HTTP 1.1 Basic authentication mechanism. default: No authentication Only relevant for network cameras.
-V device Output device name Device name that motion uses to generate output. See the video4linux loopback device web site for more information about video loopback. Note: This is not the capturing device name. To set the capturing device use the -d option.
-w Ignore sudden massive light intensity changes given as a percentage of the picture area that changed intensity.
Valid range: 0 - 100 , default: 0 = disabled
Default (switch not set) is off.

Config File Options

These are the options that can be used in the config file. They are overridden by the command line!

All number values are integer numbers (no decimals allowed). Boolean options can be on or off (values "1", "yes" and "on" all means true and any other value means false).

Some configuration options are only used if Motion is built on a system that has the matching software libraries installed (MySQL, PostgreSQL and FFMPEG).

MySQL
  • mysql_db, mysql_host, mysql_user, mysql_password

PostgreSQL
  • pgsql_db, pgsql_host, pgsql_user, pgsql_password, pgsql_port

FFMPEG (libavcodec)
  • ffmpeg_cap_new, ffmpeg_cap_motion, ffmpeg_filename, ffmpeg_timelapse, ffmpeg_timelapse_mode, ffmpeg_bps, ffmpeg_variable_bitrate, ffmpeg_video_codec

Option Description Detailed Comment
always_changes on/off Always display the differences between the captured frame and the reference frame. This can come in handy while tuning your setup. Default: off This feature writes the detected number of changed pixels (after noise filtering) to the console. Motions outputs the numbers for all threads continuously for every frame read from the video device. The output format is "changes: number_of_changes". The number is an expression of how many pixels that changed and how much. The higher a value, the more motion This feature does not work when in daemon mode!
The feature is excellent for debugging. You can use the feature to set the noise level so that motion normally shows "changes: 0". You can also use it to set the right detection threshold level.
auto_brightness on/off Motion will try to adjust the brightness of the video device if the images captured are to dark or to light. This option will be most useful for video devices like web cams, which sometimes don't have such an option in hardware. Default: off With this option enabled motion will try to regulate the brightness of a video device. If your video device already does this for you this option might cause oscillations. Editor recommends to experiment for best result.
brightness The brightness level for the video device.
Valid range:0 to 255
Default:0 (Disabled)
If this setting is used in conjunction with the auto_brightness feature then this setting is just an initial setting and then the auto_brightness feature takes over.
contrast The contrast level for the video device.
Valid range: 0 to 255
Default = 0 (Disabled)
 
control_localhost on/off Limits the xml-rpc control to the localhost. Default: on By setting this to on, the control using xml-rpc can only be accessed on the same machine on which Motion is running.
control_port port_no Sets the port number for the xml-rpc based remote control. Default: 0 (not defined) This sets the port number to be used for control of motion using xml-rpc. Port numbers below 1024 normally requires that you have root privileges. Port 8080 is a fine choice of port to use for the purpose.
daemon on/off Start motion in daemon mode and release terminal. Default: off Daemon mode is what you typically will use once you are done experimenting and have motion run permanently in the background on a server.
Wonder about the word and its spelling. Look here!
despeckle EedDl (and other combinations of E, e, d and D and optionally ending with l). Despeckle motion image using combinations of (e)rode or (d)ilate. And ending with optional (l)abeling. Default: Not defined = off. A way of tuning (by removing or enhancing) noise in the motion image. Options for the despeckle feature are any of 'e', 'E', 'd' or 'D'. This can be combined by a trailing 'l' (letter l) which enables the labeling feature. Default: Not Defined (Don't despeckle and label).
Wind blowing grass and trees around or poor light conditions can cause a lot of dots (or noise) to appear in the motion image (See the section on Tuning Motion). This feature removes (or enhances!) this noise and so improves the reliability of motion.
The 'e' option removes diamonds, 'E' removes squares and alternating eE will remove circles. Each e/E you add will shrink the noise by a pixel all the way around. So 'despeckle Ee' will remove circles of radius 2. However, this will also shrink the detection by 2 and will affect the threshold. So to remove noise and then restore the detected motion to its original size try 'despeckle EedD'.
After the despeckle feature is done you can let the labeling feature search for areas of connected pixels and "label" each area. The program will now trigger motion based on the number of changed pixels in the largest area. In other words, the largest labeled area has to be above the threshold to trigger a motion detected..
The value EedDl is a good starting point. The possible combinations are endless and it requires many experiments to find the best combination. Just remember that the labeling feature only works as intended if it runs after the despecle feature. Ie. the letter 'l' must be the last letter and only one 'l'.
If you have very few problems with false detections leave this option either blank or at EedD which will remove most of the single pixel noise.
A very detailed technical explanation of the despecle part can be found at the webpage of the author of this feature Ian McConnell's Webcam: Motion Web Page
debug_parameter integer Debug parameter does not have any function. The debug parameter is available for software debugging. If you want to test and debug the source code this parameter can be set anywhere in the code and its value read using the xml-rpc remote control interface. This way you can read the value of a variable, or identify where in the code the program get stuck. Unless you play with the source code this option has no function. In the current version the option is not assigned anywhere in the code.
execute command External command to be executed when detecting motion. Default: Not defined Do not write "none" if you do not want to execute commands. Simply do not include the option in the file or comment it out by placing a "#" as the first character on the line before the execute command.
ffmpeg_bps bps Bitrate of mpegs produced by ffmpeg. Default: 400000 (400kbps).
Must not be included in config file without having ffmpeg installed.
To use this feature you need to install the FFmpeg Streaming Multimedia System.
Experiment to get the desired quality. The better quality the bigger files. This option is ignored if ffmpeg_variable_bitrate is not 0 (disabled).
See ffmpeg section later in this document.
ffmpeg_cap_new on/off Use ffmpeg libraries to encode mpeg movies in realtime. Default = off.
Must not be included in config file without having ffmpeg installed.
To use this feature you need to install the FFmpeg Streaming Multimedia System
See ffmpeg section later in this document.
ffmpeg_cap_motion on/off Use ffmpeg libraries to encode motion type mpeg movies in realtime. Default = off.
Must not be included in config file without having ffmpeg installed.
To use this feature you need to install the FFmpeg Streaming Multimedia System
See ffmpeg section later in this document.
This feature generates the special motion type pictures where you only see the pixels that changes. The filename given is the same as the normal mpegs except they have an 'm' appended after the filename before the .mpg. E.g. 25-20040424181525m.mpg
ffmpeg_filename value File path for motion triggered ffmpeg films (mpeg) relative to target_dir. Default: %v-%Y%m%d%H%M%S Default value is equivalent to legacy 'oldlayout' option
For Motion 3.0 compatible mode (directories based on date and time) choose: %Y/%m/%d/%H%M%S
File extension .mpg is automatically added so do not include this
This option uses conversion specifiers which are codes that start by % and then a letter. The conversion specifiers used has the same function as for the C function strftime (3). The most commonly used are: %Y = year, %m = month as two digits, %d = date, %H = hour, %M = minute, %S = second. Two are unique to motion %v = event, %q = frame number. With a combination of text and conversion specifiers you have full flexibility to define your directory- and filenames. For a full list of conversion specifiers see the section 'Conversion Specifiers for Advanced Filename and Text Feature'.
If you are happy with the directory structures the way they were in earlier versions of motion use %v-%Y%m%d%H%M%S for 'oldlayout on' and %Y/%m/%d/%H%M%S for 'oldlayout off'.
ffmpeg_timelapse_mode The file rollover mode of the timelapse video.
Valid values: hourly, daily (default), weekly-sunday, weekly-monday, monthly, manual.
Note that it is important that you use the conversion specifiers in ffmpeg_filename that ensure that the new timelapse file indeed is a new file. If the filename does not change Motion will simply append the timelapse pictures to the existing file. Manual means that Motion does not automatically rollover to a new filename. You can do it manually using XML-RPC by setting the option 'ffmpeg_timelapse' to 0 and then back to your chosen value. Hourly rolls over on the full hour. Value 'daily' which is the default rolls over at midnight. There are two weekly options because depending on where you come from a week may either start on Sunday or Monday. And 'monthly' naturally rolls over on the 1st of the month.
ffmpeg_timelapse seconds Use ffmpeg libraries to encode a timelapse movie. saving a picture frame at the interval in seconds set by this parameter. Default = 0. Set it to 0 if not used. To use this feature you need to install the FFmpeg Streaming Multimedia System.
Note that the timelapse format is always mpeg1 independent of ffmpeg_video_codec. This is because mpeg1 allows the timelapse to stop and the file to be reopened and more film appended.
See ffmpeg section later in this document.
(renamed from ffmpeg_timelaps to ffmpeg_timelapse in 3.1.14)
ffmpeg_variable_bitrate value Enables and defines variable bitrate for the ffmpeg encoder. ffmpeg_bps is ignored if variable bitrate is enabled. Valid values: 0 (default) = fixed bitrate defined by ffmpeg_bps, or the range 2 - 31 where 2 means best quality and 31 is worst. Experiment for the value that gives you the desired compromise between size and quality.
ffmpeg_video_codec codec_name Codec to used by ffmpeg for the video compression. Timelapse mpegs are always made in mpeg1 format independent from this option.
Supported codec formats are: mpeg1 (ffmpeg-0.4.8 only), mpeg4 (default), and msmpeg4.
mpeg1 gives you files with extension .mpg. It is only supported by the old ffmpeg version 0.4.8. The ffmpeg team decided no longer to support non-standard framerates for mpeg1 from ffmpeg version 0.4.9pre1.
mpeg4 or msmpeg4 give you files with extension .avi
msmpeg4 is recommended for use with Windows Media Player because it requires with no installation of codec on the Windows client.
This option does not affect the timelapse feature. Timelapse is always recorded in mpeg1 format because we need to be able to append to an existing file. mpeg4 does not easily allow this.
framerate number Maximum number of frames that are saved per second. Valid range: 2-100. Default: 100 (almost no limit). Note. Motion will stop storing pictures if the framerate is set to less than 2.
Set this parameter to the maximum number of images per second that you want to store either as images or as mpeg films.
To set intervals longer than one second use the 'minimum_gap' option instead.
frequency value The frequency to set the tuner to (kHz). Valid range: per tuner spec, default: 0 (Don't set it) This option is on relevant if you have a TV tuner card where you can select the tuner frequency. Your tuner card must support this feature.
gap seconds The minimum gap between two events in seconds. Default: 60 An event is defined as a series of motion images taken within a short timeframe. E.g. a person walking through the room is an event that may have caused 10 single jpg images to be stored. This option defines how long a pause between detected motions that is needed to be defined as a new event.
height pixels The height of each frame. Valid range: Camera dependent, default: 288 The height of the image in pixels. Motion does not scale so should be set to the actual size of the v4l device. In case of a net camera motion sets the height to the height of the first image read.
Motion actually set the size of the image coming from the video4linux device. The selected size must be supported by the device. For some device drivers like pwc (driver for Philips USB cameras) setting the size to a non-standard value makes the driver create an image of the nearest smaller size and create a gray band around the image to fit the size given by motion. Note that it is the driver and not motion that generates the gray band. Motion will try to detect motion in the entire image including the gray band.
hue The hue level for the video device.
Valid range: 0 to 255
Default = 0 (Disabled)
 
input number input channel to use expressed as an integer number starting from 0. Valid range: depends on video capture card, default: 8 This parameter is really used only with video capture cards that has more than one input.
However if you set the input number to e.g. 1 for a USB camera (ov511 or pwc driver) motion writes an error message back. If you set it to 8 it does not give you any warning.
If you have a video capture card you can define the channel to tune to using this option. If you are using a USB device, network camera or a capture card without tuner you should set the value to the default 8. Many TV tuner cards have the input channels: TV Tuner = 0, Standard composite video = 1, S-VHS = 3. Other have TV=0, composite video 1= 1, composite video = 2, S-VHS = 3. Editor recommends setting the parameter to 8 for USB cameras as your first try. For video capture cards input 1 is normally the composite video input.
jpeg_filename value File path for motion triggered images (jpeg or ppm) relative to target_dir (Default: %v-%Y%m%d%H%M%S-%q) Default value is equivalent to legacy 'oldlayout' option
For Motion 3.0 compatible mode (directories based on date and time) choose: %Y/%m/%d/%H/%M/%S-%q
File extension .jpg or .ppm is automatically added so do not include this
This option uses conversion specifiers which are codes that start by % and then a letter. The conversion specifiers used has the same function as for the C function strftime (3). The most commonly used are: %Y = year, %m = month as two digits, %d = date, %H = hour, %M = minute, %S = second. Two are unique to motion %v = event, %q = frame number. With a combination of text and conversion specifiers you have full flexibility to define your directory- and filenames. For a full list of conversion specifiers see the section 'Conversion Specifiers for Advanced Filename and Text Feature'.
If you are happy with the directory structures the way they were in earlier versions of motion use %v-%Y%m%d%H%M%S-%q for 'oldlayout on' and %Y/%m/%d/%H/%M/%S-%q for 'oldlayout off'.
lightswitch percent Ignore sudden massive light intensity changes given as a percentage of the picture area that changed intensity.
Valid range: 0 - 100 , default: 0 = disabled
Editors recommendation. Experiment to see what works best for your application.
Note: From version 3.1.17 (snap release 2 and on) this option has changed from a boolean (on or off) to a number in percent between 0 and 100. Zero means the option is disabled.
The value defines the picture areas in percent that will trigger the lightswitch condition. When lightswitch is detected motion detection is disabled for 5 picture frames. This is to avoid false detection when light conditions change and when a camera changes sensitivity at low light.
locate on/off Locate and draw a box around the moving object. Default: off  
low_cpu framerate When this option is not zero motion will be in a low cpu mode while not detecting motion. In low cpu mode Motion reduces the framerate to the value given for this option. Value zero means disabled. Default: 0 (disabled). This is smart for running a server that also does other tasks such as running Apache, MySQL etc. Motion grabs this lower number of frames per second until it detects motion. Then it speeds up to normal speed and take pictures as set by the option "framerate".
mail address Address to send an e-mail to when detecting motion Default: Not defined Address in the normal form name@domain .name. An e-mail is sent for each event. Not each picture.
mask_file file PGM file to use as a sensitivity mask. This picture MUST have the same width and height as the frames being captured and be in binary format. Default: Not defined. Full path of the PGM (portable gray map) mask file (binary format).
If you have one or more areas of the camera image in which you do NOT want motion detected (e.g. a tree that moves in the wind or a corner of the picture where you can see cars/pedestrians passing by) you need a mask file. This file is a picture that you create in your favorite photo editing program. The areas that you want detected must be white. The error that you want ignored must be black. The pgm image must be the same size (number of pixels high and wide) as the pictures that are taken by the camera (video4linux device).
You can also adjust sensitivity by using gray tones. See the special section on mask file.
If you do not have a mask file disable this option by not having it in the config file or comment it out ("#" as first character in line).
If you are using the rotate option, note that the mask is applied after the rotation.
max_mpeg_time seconds The maximum length of an mpeg movie. Default: 3600 seconds (one hour). Set this to zero for unlimited length.  
minimum_gap seconds The minimum time between two shots in seconds. Valid range: 0 to thousands, default: 0 (no minimum) This is the minimum gap between the storing pictures while detecting motion. The value zero means that pictures can be stored almost at the framerate of the camera.
minimum_motion_frames number Picture frames must contain motion at least the specified number of frames in a row before they are detected as true motion. At the default of 1, all motion is detected. Valid range: 1 to thousands, recommended 1-10. Note that the picture frames are buffered by Motion and once motion is detected also the first frames containing motion are saved so you will not miss anything. The feature is used when you get many false detections when the camera changes light sensitivity or light changes. Experiment for best setting. Valid range is 0 to 1000s but for each step larger than 1 Motion reserves space in RAM for the picture frame buffer. Practical range is 1 to 10.
motion_video_pipe devicename/- The video4linux video loopback input device for motion images. If a particular pipe is to be used then use the device filename of this pipe, if a dash '-' is given motion will use /proc/video/vloopback/vloopbacks to locate a free pipe. Default: not set Using this you can view the results in real time. E.g. by using the program camstream. The difference between this option and the video-pipe option is that this option shows the motion version of the images instead of the normal images.
Disable this option by not having it in the config file (or comment it out with "#").
See also the section about video loopback device later in this document.
mysql_db Name of the MySQL database. Default: Undefined MySQL CONFIG FILE OPTION. Motion must be built with MySQL libraries to use this feature.
If you compiled motion with MySQL support you will need to set the mysql options if you want motion to log events to the database.
mysql_host IP address or domain name for the MySQL server. Use "localhost" if motion and MySQL runs on the same server. Default: Undefined. MySQL CONFIG FILE OPTION. Motion must be built with MySQL libraries to use this feature.
mysql_user The MySQL user name. Default: Undefined MySQL CONFIG FILE OPTION. Motion must be built with MySQL libraries to use this feature.
mysql_password The MySQL password. MySQL CONFIG FILE OPTION. Motion must be built with MySQL libraries to use this feature.
netcam_url URL Specify an url to a downloadable jpeg file to use as input device. Such as an AXIS 2100 network camera. Default: not set.
Must not be included in config file without having cURL (libcurl) installed.
Example of URL: http://www.gate.com/pe1rxq/jeroen.jpg.
Important note: To use the Netcam options you must have the cURL shared library "libcurl" installed on your system. This is normally part of Linux distributions. If it is not installed, it is most likely on your distribution CDs.
The official CURL homepage is at http://curl.haxx.se/. The download page on this site has both source code and many binary packages (RPM, Debian etc). If you use the netcam_url in motion.conf or command line with -U , height and width are ignored. It actually uses jpeglib to pull the height and width from the JPEG header directly.
netcam_userpass user:pass For network cameras protected by username and password, use this option for HTTP 1.1 Basic authentication. The string is specified as username:password. Default: No authentication
Must not be included in config file without having cURL (libcurl) installed.
Important note: To use the Netcam options you must have the cURL shared library "libcurl" installed on your system.
Only relevant for network cameras. See also 'netcam_url' option.
night_compensate on/off When this option is set the noise threshold will be lowered if the picture is dark. This will improve the sensitivity in dark places. However it might also increase the number of false alarms since most cameras also compensate for this with their AGC which will increase noise. Default: off Editors recommends to experiment for best result as this depends heavily on the camera and light conditions. Do not use this with 'noise_tune' on.
noise_level level The noise level is used as a threshold for distinguishing between noise and motion. Valid range: 1 to 255, default: 32 This is different from the threshold parameter. This is changes at pixel level. The purpose is to eliminate the changes generated by electric noise in the camera. Especially in complete darkness you can see the noise as small grey dots that come randomly in the picture. This noise can create false motion detection. What this parameter means is that the intensity of a pixel must change more than +/- the noise threshold parameter to be counted.
noise_tune on/off Activates the automatic tuning of noise level. Default: on. This feature makes Motion continuously adjust the noise threshold for distinguishing between noise and motion. The 'noise_level' setting is ignored when activating this feature. This is a new feature and new algorithm. It may give different results depending on camera and light conditions. Report your experience with it on the Motion mailing list. If it does not work well, deactivate the 'noise_tune' option and use the manual setting of 'noise_level' instead.
norm 0/1/2/3 Select the norm of the video device. Values: 0 (PAL), 1 (NTSC), 2 (SECAM), 3 (PAL NC no colour). Default: 0 (PAL) This value is only used for capture cards using the BTTV driver.
onffmpegclose command Execute 'command' when an ffmpeg movie is closed at the end of an event. The name of the movie will be given as argument. Default: not set. Full path name of the program/script.
This can be any type of program or script. Remember to set the execution bit in the ACL and if it is a script type program such as perl or bash also remember the shebang line (e.g. #!/user/bin&perl) as the first line of the script.
The command is run when an event is over. I.e. the number of seconds defined by the time 'gap' has passed since the last detection of motion and motion closes the mpeg file.
onmpeg command Execute 'command' when an mpeg movie is generated. The name of the movie will be given as argument. Default: not set. Full path name of the program/script.
This can be any type of program or script. Remember to set the execution bit in the ACL and if it is a script type program such as perl or bash also remember the shebang line (e.g. #!/user/bin/perl) as the first line of the script. When you use ffmpeg the film is generated on the fly and onmpeg then runs when the new mpeg file is created. Often you will want to use the onffmpegclose option which runs when the mpeg file is closed and the event is over.
onsave command Execute 'command' when an image is saved. The name of the image will be given as argument. Default: not set. Full path name of the program/script.
This can be any type of program or script. Remember to set the execution bit in the ACL and if it is a script type program such as perl or bash also remember the shebang line (e.g. #!/user/bin&perl) as the first line of the script.
output_all on/off Picture are saved continuously as if motion was detected all the time. This feature is not meant to be the normal mode of operation. Especially not if you have the output_normal or output_motion features enabled since it will keep on saving pictures on the disk and you will soon run out of disk space. So be careful with this command.. If your frame rate is 10 pictures per second motion will save 10 new picture pr second until the disk is full. All features are triggered like it was a detection of motion incl mpeg generation and running the program given by onsave. This parameter is default off.
The idea of this feature is that you can turn the feature on and off for a short period of time to test or to generate continuous mpeg films when needed. You can then use the motion-control program to turn the feature on a off.
output_motion on/off Output pictures with only the moving object. Default: off Motion images shows the motion content of the pictures. This is good for tuning and testing but probably not very interesting for the general public. Default is not to store motion images. Motion pictures are stored the same place and with the same filename as normal motion triggered pictures except they have an "m" appended at the end of the filename before the .jpg or .ppm. E.g. the name can be 01-20020424232936-00m.jpg.
See section later in this document about the different tuning modes.
output_normal on/off/first Output 'normal' pictures. Default: on Normal image is an image that is stored when motion is detected. It is the same image that was taken by the camera. I.e. not a motion image as defined above. Default is that normal images are stored. If you set the value to 'first' Motion saves only the first motion detected picture per event. This is useful if you store mpegs on a webserver and want to present a jpeg to show the content of the mpeg on a webpage.
pgsql_db Name of the PostgreSQL database. Default: undefined PostgreSQL CONFIG FILE OPTION. Motion must be built with PostgreSQL libraries to use this feature.
If you compiled motion with PostgreSQL support you will need to set the following options if you want motion to log events to the database.
pgsql_host IP address or domain name for the PostgreSQL server. Use "localhost" if motion and PostgreSQL runs on the same server. Default: undefined PostgreSQL CONFIG FILE OPTION. Motion must be built with pgsql_db libraries to use this feature.
pgsql_user The PostgreSQL user name. Default: undefined PostgreSQL CONFIG FILE OPTION. Motion must be built with PostgreSQL libraries to use this feature.
pgsql_password The PostgreSQL password. Default: undefined PostgreSQL CONFIG FILE OPTION. Motion must be built with PostgreSQL libraries to use this feature.
pgsql_port The PostgreSQL server port number. Default is 5432 PostgreSQL CONFIG FILE OPTION. Motion must be built with PostgreSQL libraries to use this feature.
post_capture number Specifies the number of frames to be captured after motion has been detected. Valid range: 0 to thousands, default=0. The purpose of this is mainly to create smooth video clips each time motion is detected. Use it to you personal taste (and disk space)..
ppm on/off Output ppm images instead of jpeg. This uses less CPU time, but causes a LOT of hard disk I/O, it is generally slower than jpeg. Default: off Editors recommendation is to always use jpg except if you have a specific need to store high quality pictures without any quality loss. For web cameras you should always choose jpg. Note that the built in webcam server requires that this parameter is set to off.
pre_capture number Specifies the number of previous frames to be outputted at motion detection. Valid range: 0 to thousands, default=0. Motion buffers the number of picture frames defined by 'pre_capture'. When motion is detected the pictures in the buffer are included in the video clip generated by ffmpeg. The effect is that it seems the program knew in advance that the event was going to take place and started the recording before it actually happened. This is a nice feature that give more complete video clips of an event. The recommended value would be approx 0.5-1 second of video so the value should be defined so it fit the framerate and the desired pre-capture time. E.g. 0.5 second at 20 frames pr second would mean a value of 10.
quality value The quality for the jpeg images. Valid range: 1-100,default: 75 100 means hardly compressed. A small number means a much smaller file size but also a less nice quality image to look at. 50 is a good compromise for most.
quiet on/off Be quiet, don't output beeps when detecting motion. Default: off Only works in non-daemon mode.
rotate degrees Rotate image the given number of degrees. The rotation affects all saved images as well as mpeg movies. Valid values: 0 (default = no rotation), 90, 180 and 270. The rotation feature is used when the camera is hanging upside down (180 degrees) or if you choose a picture format in portrait instead of the normal landscape (90 or 270 degrees).
Note that the CPU load increases when using this feature with a value other than 0. Also note that Motion automatically swaps width and height if you rotate 90 or 270 degrees, so you don't have to touch these options.
roundrobin_frames number Specifies the number of frames to capture before switching inputs, this way also slow switching (e.g. every second) is possible. Default: 1 Round robin feature is described in a section later in this document.
roundrobin_skip number Specifies the number of frames to skip after a switch. (1 of you are feeling lucky, 2 if you want to be safe). Default: 1 Round robin feature is described in a section later in this document
saturation The saturation level for the video device.
Valid range: 0 to 255. Default = 0 (Disabled)
 
smart_mask_speed Slugginess of the smart mask.
Valid range: 0 to 10.
Default is 0. 1 is slow, 10 is fast.
Smartmask is a dynamic, self-learing mask. Smartmask will disable sensitivity in areas with frequent motion (like trees in the wind). Sensitivity is turned on again after some time of no more motion in this area. The built mask is a bit larger at the borders than the actual motion was. This way smartmask works more reliable when sudden moves occur under windy conditions.
smart_mask_speed - it will tune slugginess of the mask. It accepts values from 0 (turned off) to 10 (fast). Fast means here that the mask is built quick, but it is also not staying very long with no more motion. Slow means that it takes a while until the mask is built but it also stays longer. A good start value for smart_mask_speed is 5. This setting is independent from the framerate. The attack and decay time is constant over all available framerates.
When smartmask is enabled and motion is also configured to either write motion-images or motion-mpegs, the current smartmask is copied as an overlay into the black/white motion-pictures/mpegs in red colour. That way you can easily adjust smart_mask_speed.
sms number Number to send an SMS to with sms_client. Default: none Not a feature that has received much attention recently. If you live in GSM land you are probably better off using the e-mail to SMS gateway that most GSM providers have using your mail client. For more information see the sms_client home page.
snapshot_filename value File path for snapshots (jpeg or ppm) relative to target_dir (Default: %v-%Y%m%d%H%M%S-snapshot) Default value is equivalent to legacy 'oldlayout' option
For Motion 3.0 compatible mode (directories based on date and time) choose: %Y/%m/%d/%H/%M/%S-snapshot
File extension .jpg or .ppm is automatically added so do not include this
A symbolic link called lastsnap.jpg (or lastsnap.ppm) created in the target_dir will always point to the latest snapshot, unless snapshot_filename is exactly 'lastsnap'
This option uses conversion specifiers which are codes that start by % and then a letter. The conversion specifiers used has the same function as for the C function strftime (3). The most commonly used are: %Y = year, %m = month as two digits, %d = date, %H = hour, %M = minute, %S = second. Two are unique to motion %v = event, %q = frame number. With a combination of text and conversion specifiers you have full flexibility to define your directory- and filenames. For a full list of conversion specifiers see the section 'Conversion Specifiers for Advanced Filename and Text Feature'.
If you are happy with the directory structures the way they were in earlier versions of motion use %v-%Y%m%d%H%M%S-snapshot for 'oldlayout on' and %Y/%m/%d/%H/%M/%S-snapshot for 'oldlayout off'.
For the equivalent of the now obsolete option 'snap_overwrite' use the value 'lastsnap'.
snapshot_interval seconds Make automated snapshots every N seconds. Valid range: 0 to thousands, default: 0 (No snapshots) The snapshots are stored in the target directory + the directory/filename specified by the 'snapshot_filename' option.
This is the traditional web camera feature where a picture is taken at a regular interval independently of motion in the picture.
sql_log_image on/off Log to the database when creating motion triggered image file (default: on). Configuration option common to MySQL and PostgreSQL. Motion must be built with MySQL or PostgreSQL support to use this feature.
sql_log_snapshot on/off Log to the database when creating a snapshot image file (default: on). Configuration option common to MySQL and PostgreSQL. Motion must be built with MySQL or PostgreSQL support to use this feature.
sql_log_mpeg on/off Log to the database when creating motion triggered mpeg file (default: off). Configuration option common to MySQL and PostgreSQL. Motion must be built with MySQL or PostgreSQL support to use this feature.
sql_log_timelapse on/off Log to the database when creating timelapse mpeg file (default: off). Configuration option common to MySQL and PostgreSQL. Motion must be built with MySQL or PostgreSQL support to use this feature.
switchfilter on/off Turns the switch filter on or off. The filter can distinguish between most switching noise and real motion. With this you can even set roundrobin_skip to 1 without generating much false detection. Default: off. This is a round robin related feature used when you have a capture card with multiple inputs (controlled by the 'input' option) on the same videodevice.
This option is supposed to prevent the change of camera from being detected as Motion. Unfortunately it seems that many have problems detecting motion at all when this option is enabled. We are working on improving it. You are probably better off turning this option off.
target_dir directory_path Target directory for pictures. Default: current working directory This is the target directory for all snapshots, motion images and normal images. The default is the current working directory (current working directory of the terminal from which motion was started). You will normally always want to specify this parameter either as a command line option or in the config file.
Note that the options snapshot_filename, jpeg_filename, ffmpeg_filename, and timelapse_filename all allows specifying directories. These will all be relative to 'target_dir'. This means in principle that you can specify target_dir as '/' and be 100% flexible. It also means that Motion can write files all over your harddisk if you make a mistake. It is recommended to specify the target_dir as deep or detailed as possible for this reason.
text_changes on/off Turns the text showing changed pixels on/off. Default: off By setting this option to 'on' the number of pixels that changed compared to the reference frame is displayed in the upper right corner of the pictures. This is good for calibration and test. Maybe not so interesting for a greater public. Set it to your personal taste.
text_left TEXT User defined text overlayed on each in the lower left corner. Use A-Z, a-z, 0-9, " / ( ) @ ~ # < > ¦ , . : - + _ \n and conversion specifiers (codes starting by a %). Default: none User defined text is displayed in the lower left corner of the pictures. If the option is not defined no text is displayed at this position. The user defined text can be the english alphabet and a selection of symbols: (A-Z, a-z, 0-9, " / ( ) @ ~ # < > ¦ , . : - + _ \n) and conversion specifiers. You can place the text in quotation marks to allow leading spaces. With a combination is spaces and newlines you can position the text anywhere on the picture.
A conversion specifier is a code that starts by % (except newline which is \n). The conversion specifiers used has the same function as for the C function strftime (3). The most commonly used are: %Y = year, %m = month as two digits, %d = date, %H = hour, %M = minute, %S = second, %T = HH:MM:SS. Two are unique to motion %v = event, %q = frame number. With a combination of text, spaces, new lines \n and conversion specifiers you have some very flexible text features. For a full list of conversion specifiers see the section 'Conversion Specifiers for Advanced Filename and Text Feature'.
text_right TEXT User defined text overlayed on each in the lower right corner. Use A-Z, a-z, 0-9, " / ( ) @ ~ # < > ¦ , . : - + _ \n and conversion specifiers (codes starting by a %). Default: %Y-%m-%d\n%T = date in ISO format and time in 24 hour clock User defined text is displayed in the lower right corner of the pictures. If the option is not defined no text is displayed at this position. The user defined text can be the english alphabet and a selection of symbols: (A-Z, a-z, 0-9, " / ( ) @ ~ # < > ¦ , . : - + _ \n) and conversion specifiers. You can place the text in quotation marks to allow leading spaces. With a combination is spaces and newlines you can position the text anywhere on the picture.
A conversion specifier is a code that starts by % (except newline which is \n). The conversion specifiers used has the same function as for the C function strftime (3). The most commonly used are: %Y = year, %m = month as two digits, %d = date, %H = hour, %M = minute, %S = second, %T = HH:MM:SS. Two are unique to motion %v = event, %q = frame number. With a combination of text, spaces, new lines \n and conversion specifiers you have some very flexible text features. For a full list of conversion specifiers see the section 'Conversion Specifiers for Advanced Filename and Text Feature'.
A major difference from text_left is that if this option is undefined the default is %Y-%m-%d\n%T which displays the date in ISO format YYYY-MM-DD and below the time in 24 hour clock HH:MM:SS.
thread filename Thread option. With this a separate config file can be specified to be used for a new separate thread. This is used when you have more than more camera/device.
The single camera can get all its options from the default motion.conf file. If you have two or more cameras all cameras must have their unique information in a separate thread config file. This must be at least the definition of the device or input number of a capture card.
Additionally you can add any other options such as target_dir, height/width etc. Format of the thread config files is the same as for the motion.conf.
You add one thread statement for each camera in motion.conf. Example
thread /usr/local/etc/thread1.conf
thread /usr/local/etc/thread2.conf
An option in a thread config file overrides the same option in motion.conf. This means that the options in motion.conf becomes the default value for all the cameras. The thread options must be the last options in the motion.conf file.
threshold value Threshold for declaring motion. Valid range: 1 to thousands. Default: 1500. Use the -C command line option or the always_changes config file option to experiment to find the right threshold value. If you do not get small movement detected (see the mouse on the kitchen floor) lower the value. If motion detects too many birds or moving trees, increase the number. Practical values would be from a few hundred to 2000 indoors and 1000-10000 outdoors.
threshold_tune on/off Activates the automatic tuning of threshold level. Default: on This feature makes Motion continuously adjust the threshold for declaring motion. The 'threshold' setting is ignored when activating this feature. This is a new feature and new algorithm. It may give different results depending on your camera, light conditions, indoor/outdoor, the motion to be detected etc. Report your experience with it on the Motion mailing list. If it does not work well, deactivate the 'threshold_tune' option and use the manual setting of 'threshold' instead.
timelapse_filename value File path for timelapse mpegs relative to target_dir (ffmpeg only). Default: %v-%Y%m%d-timelapse Default value is equivalent to legacy 'oldlayout' option
For Motion 3.0 compatible mode (directories based on date and time) choose: %Y/%m/%d-timelapse
File extension .mpg is automatically added so do not include this.
This option uses conversion specifiers which are codes that start by % and then a letter. The conversion specifiers used has the same function as for the C function strftime (3). The most commonly used are: %Y = year, %m = month as two digits, %d = date, %H = hour, %M = minute, %S = second. Two are unique to motion %v = event, %q = frame number. With a combination of text and conversion specifiers you have full flexibility to define your directory- and filenames. For a full list of conversion specifiers see the section 'Conversion Specifiers for Advanced Filename and Text Feature'.
If you are happy with the directory structures the way they were in earlier versions of motion use %v-%Y%m%d-timelapse for 'oldlayout on' and %Y/%m/%d-timelapse for 'oldlayout off'.
track_type number Type of tracker (0=none, 1=stepper, 2=iomojo, 3=pwc). Default: 0. Motion has special tracking options which use either a serial stepper motor controller, an iomojo smile cam or a Philips WebCam driver compatible pan/tilt camera such as the Logitech Quickcam Sphere or Orbit.
Normally this is set to 0 and the other track options are ignored.
Value 1 is for the special Motion Tracking Project using a stepper motor and a home made controller.
Value 2 is for the iomojo smilecam
Value 3 is for the a camera such a the Logitech Quickcam Sphere/Orbit which is driven by the pwc (Philips WebCam) driver. To use this camera your version of pwc must be at least 8.12.
track_iomojo_id Use this option if you have an iomojo smilecam connected to the serial port instead of a general stepper motor controller. Default: 0 Only used for iomojo camera
track_maxx The maximum position for servo x. Default: 0 Only used for stepper motor tracking.
track_motorx The motor number that is used for controlling the x-axis. Default: -1 Only used for stepper motor tracking.
track_port This is the serial port to which the stepper motor interface is connected. Default: Not defined Only used for stepper motor tracking.
track_speed Speed to set the motor to. Default: 255 Only used for stepper motor tracking.
track_stepsize Number of steps to make. Default: 40 Only used for stepper motor tracking.
tunerdevice device_name The tuner device used for controlling the tuner in a tuner card. This option is only used in FreeBSD. Default: /dev/tuner0 This option is only used in the FreeBSD version of Motion. Make sure to remove or comment out this option when running Motion under Linux.
videodevice device_name The video device to be used for capturing. Default: /dev/video0 (for FreeBSD the default is /dev/bktr0) This is the video4linux device name.
Ignore this for net cameras. For FreeBSD default is /dev/bktr0
video_pipe device_name/- The video4linux video loopback input device for normal images. If a particular pipe is to be used then use the device filename of this pipe, if a dash '-' is given motion will use /proc/video/vloopback/vloopbacks to locate a free pipe. Default: not set Using this you can view the results in real time. E.g. by using the program camstream. The difference between this option and the video-pipe option is that this option shows the normal version of the images instead of the motion images.
Disable this option by not having it in the config file (or comment it out with "#").
See also the section about video loopback device later in this document.
webcam_limit on/off Limit the number of frames to number frames. After nr frames the connection will be closed by motion. Default: 0 Number can be defined by multiplying actual webcam rate by desired number of seconds. Actual webcam rate is the smallest of the numbers framerate and webcam_maxrate.
webcam_localhost on/off Limits the access to the webcam to the localhost. Default: on By setting this to on, the webcam can only be accessed on the same machine on which Motion is running.
webcam_maxrate rate Limit the framerate of the webcam. Default is 100. Webcam feature is described in a section later in this document
webcam_motion on/off If set to 'on' Motion only sends pictures to the client when motion is detected. When 'off' Motion sends frames continuously. Default is off. Webcam feature is described in a section later in this document
webcam_port port_no TCP port on which motion will listen for incoming connects with its http server. Default is 0 which is disabled. Webcam feature is described in a section later in this document
webcam_quality level Quality setting for the jpeg files transferred over this connection (usually very low). Default is 30. Webcam feature is described in a section later in this document
width pixels The width of each frame. Valid range: Camera dependent, default: 352 Motion does not scale so should be set to the actual size of the v4l device. In case of a net camera motion sets the height to the height of the first image read.
Motion actually set the size of the image coming from the video4linux device. The selected size must be supported by the device. For some device drivers like pwc (driver for Philips USB cameras) setting the size to a non-standard value makes the driver create an image of the nearest smaller size and create a gray band around the image to fit the size given by motion. Note that it is the driver and not motion that generates the gray band. Motion will try to detect motion in the entire image including the gray band.

Signals (sent with e.g. kill command)

A signal can be sent from the command line by typing e.g. kill -s SIGHUP pid, where the last parameter is the process ID which you get by typing ps -ef ¦ grep motion. The PID is the first on the list which is the parent process for the threads. Motion responds to the following signals:

Signal Description Editors comment
SIGHUP The config file will be reread. This is a very useful signal when you experiment with settings in the config file.
SIGTERM If needed motion will create an mpeg file of the last event and exit  
SIGUSR1 Motion will create an mpeg file of the current event.  

Capture Device Options - The Basic Setup

Before you can start using motion you need to know some basics about your camera. Either you have a camera connected directly to your computer. In this case it is a video4linux type of camera. Or you connect to a network camera using a normal web URL.

video4linux (V4L) devices

You need to install your camera with the right driver. It is out of scope of this document to tell you how to do this and it depends on which type of camera. Once installed the camera(s) will have the device names /dev/video0, /dev/video1, /dev/video2...

FreeBSD has a different naming of devices. When you build Motion for FreeBSD the default device name is /dev/bktr0. Under FreeBSD a TV card has a special device for controlling the tuner (e.g. /dev/tuner0). The option tunerdevice is only valid when Motion is built and running under FreeBSD. For Linux do not include this option in the config file (remove or comment out).

Your camera or capture/TV card will not support any picture size. You must know which frame size (width and height) the camera supports. If you do not know start with width 320 and height 240 which most cameras and capture cards supports.

You also need to choose framerate. The faster you fetch pictures from the camera the more CPU load you get and the more pictures get included when Motion is detected. The value must be minimum 2.

You need to know if the camera supports auto brightness. Most cameras have auto everything. If you do not know assume that it has and do not use the Motion autobrightness feature. At least not to start with.

USB cameras take a lot of bandwidth. A USB camera connected to a USB 1.1 port or hub consumes all the bandwidth. Even with a small framesize and low framerate you should not expect to have more than one camera per USB 1.1 controller. If you need more than 1 USB camera add extra USB PCI cards to your computer. There exists cards that have 4 inputs each with their own controller and with full bandwidth. Must 4-input cards only have 1 controller. USB cameras do not have the feature of selecting input channels. _To disable the input selection the option 'input' must be set to the value 8 for USB cameras (default)_.

Composite video cards are normally made with a chip called BT878 (older cards have a BT848). They all use the Linux driver called 'bttv'.

There are cards with more then one video input but still only one BT878 chip. They have a video multiplexer which input is selected with the config option 'input'. Input channel numbers start at 0 (which is why the value 8 and not 0 disables input selection). There are video capture cards available with 4 or 8 inputs but only one chip. They present themselves as one single video device and you select input using the 'input' option. If you define e.g. 4 thread config files with the same videodevice name but different input numbers Motion automatically goes into round robin mode. See the round robin section for more information. Many TV tuner cards have the input channels: TV Tuner = 0, Standard composite video = 1, S-VHS = 3. Other have TV=0, composite video 1= 1, composite video = 2, S-VHS = 3. For video capture cards input 1 is normally the composite video input.

Some capture cards are specially made for surveillance with for example 4 inputs. Others have a TV tuner, a composite input (phono socket) and perhaps also a S-VHS input. For all these cards the inputs are numbered. The numbering varies from card to card so the easiest is to experiment for 5 minutes with a program that can show the videostream. Use a program such as Camstream or xawtv to experiment with the values.

If you use the TV tuner input you also need to set the frequency of the TV channel using the option 'frequency'. Otherwise set 'frequency' to 0.

Finally you need to set the TV norm. Values: 0 (PAL), 1 (NTSC), 2 (SECAM), 3 (PAL NC no colour). Default is 0 (PAL). If your camera is a PAL black and white you may get a better result with norm=3 (PAL no colour).

If the netcam_url option is defined all the video4linux options are ignored so make sure the netcam_url option is commented out if you do not need it.

These are the parameters used for video4linux devices.

###########################################################
# Capture device options
############################################################

#Videodevice to be used for capturing  (default /dev/video0)
#for FreeBSD default is /dev/bktr0
videodevice /dev/video0

#Tuner device to be used for capturing using tuner as source (default /dev/tuner0)
#This is ONLY used for FreeBSD. Leave it commented out for Linux
; tunerdevice /dev/tuner0

#The video input to be used (default: 8)
#Should normally be set to 1 for video/TV cards, and 8 for USB cameras
input 8

#The video norm to use (only for video capture and TV tuner cards)
#Values: 0 (PAL), 1 (NTSC), 2 (SECAM), 3 (PAL NC no colour). Default: 0 (PAL)
norm 0

#The frequency to set the tuner to (kHz) (only for TV tuner cards) (default: 0)
frequency 0

#Rotate image this number of degrees. The rotation affects all saved images as
#well as mpeg movies. Valid values: 0 (default = no rotation), 90, 180 and 270.
rotate 0

#Image width (pixels). Valid range: Camera dependent, default: 352
width 320

#Image height (pixels). Valid range: Camera dependent, default: 288
height 240

#Maximum number of frames to be captured per second.
#Valid range: 2-100. Default: 100 (almost no limit).
framerate 2

#URL to use if you are using a network camera, size will be autodetected (incl http://)
#Must be a URL that returns single jpeg pictures or a raw mjpeg stream. Default: Not defined
; netcam_url value

#Username and password for network camera (only if required). Default: not defined
#Syntax is user:password
; netcam_userpass value

#Let motion regulate the brightness of a video device (default: off)
#Only recommended for cameras without auto brightness
auto_brightness off

#Set the initial brightness of a video device.
#Valid range 0-255, default 0 = disabled
brightness 0

#Set the contrast of a video device.
#Valid range 0-255, default 0 = disabled
contrast 0

#Set the saturation of a video device.
#Valid range 0-255, default 0 = disabled
saturation 0

#Set the hue of a video device (NTSC feature).
#Valid range 0-255, default 0 = disabled
hue 0

Network Cameras

Motion can connect to a network camera through a normal TCP socket. All you need to give it is the URL. The URL given must return either one single jpeg picture or an mjpeg stream. For the time being Motion cannot connect to a video stream such a mpeg, mpeg4, divx. The URL must return one single jpeg image or an mjpeg stream!

Also watch out that you do not use a URL that create an HTML page with an embedded jpg. What must be returned is the jpg picture itself or the raw mjpeg stream.

When the netcam_url is defined all the video4linux options above are ignored!!

The support of mjpeg streaming cameras has been introduced in motion 3.1.18 and is still relatively new. This means that with some cameras the connection to the mjpeg stream ay not be fully stable. Motion tries to reconnect to the camera if the connection is lost. There is no official standard for mjpeg and we know that there are still some cameras that are not yet supported. If you run into a problem please file a Bug Report with as much information about the format as possible. A binary raw dump of the first 2-3 frames with headers and boundary strings is very useful.

#URL to use if you are using a network camera, size will be autodetected (incl http://)
#Must be a URL that returns single jpeg pictures or a raw mjpeg stream. Default: Not defined
; netcam_url value

#Username and password for network camera (only if required). Default: not defined
#Syntax is user:password
; netcam_userpass value

Round Robin feature

This feature is automatically activated where multiple threads are sharing the same video device. Each thread can then set different input channels or frequencies to change camera. These are the special Round Robin options:

  • If multiple threads use the same video device, they each can capture roundrobin_frames number of frames before having to share the device with the other threads.
  • When another thread wants to watch another input or frequency or size the first roundrobin_skip number of frames are skipped to allow the device to settle.
  • The last option switch_filter is supposed to prevent the change of camera from being detected as Motion. Unfortunately it seems that many have problems detecting motion at all when this option is enabled. We are working on improving it. You are probably better off turning this option off.

Note that in version 3.0.7 the two options are spelled roundrobing_frames and roundrobing_skip. From version 3.1.8 the spelling has been corrected to roundrobin_frames and roundrobin_skip. If you upgrade from 3.1.6 or earlier, remember to update your config files to the right spelling for these two features.

Motion Detection Settings

These are the options that controls the detection of motion. Further details follows after.

############################################################
# Motion Detection Settings:
############################################################

#Threshold for number of changed pixels in an image that
#triggers motion detection (default: 1500)
threshold 2000

#Automatically tune the threshold down if possible (default: on)
threshold_tune off

#Noise threshold for the motion detection (default: 32)
noise_level 32

#Automatically tune the noise threshold (default: on)
noise_tune off

#Enables motion to adjust its detection/noise level for very dark frames
#Don't use this with noise_tune on. (default: off)
night_compensate on

#Despeckle motion image using (e)rode or (d)ilate or (l)abel (Default: not defined)
#Recommended value is EedDl. Any combination (and number of) of E, e, d, and D is valid.
#(l)abeling must only be used once and as the last letter.
#Comment out to disable
despeckle EedDl

#PGM file to use as a sensitivity mask.
#Full path name to. (Default: not defined)
; mask_file value

#Dynamically create a mask file during operation (default: 0)
#Adjust speed of mask changes from 0 (off) to 10 (fast)
smart_mask_speed 0

#Ignore sudden massive light intensity changes given as a percentage of the picture
#area that changed intensity. Valid range: 0 - 100 , default: 0 = disabled
lightswitch 0

#Picture frames must contain motion at least the specified number of frames
#in a row before they are detected as true motion. At the default of 1, all
#motion is detected. Valid range: 1 to thousands, recommended 1-10
minimum_motion_frames 1

#Specifies the number of pre-captured (buffered) pictures from before motion
#was detected that will be output at motion detection (default: 0)
pre_capture 0

#Number of frames to capture after motion is no longer detected (default: 0)
post_capture 0

#Minimum gap between two events (seconds) (default: 60)
#An event is defined as a series of motion images taken within a short timeframe.
gap 60

#Minimum gap in seconds between the storing pictures while detecting motion.
#Default: 0 = as fast as possible (given by the camera framerate)
minimum_gap 0

#Maximum length in seconds of an mpeg movie
#When value is exceeded a new mpeg file is created. (Default: 0 = infinite)
max_mpeg_time 0

#Number of frames per second to capture when not detecting
#motion (saves CPU load) (Default: 0 = disabled)
low_cpu 0

#Always save images even if there was no motion (default: off)
output_all off

Threshold

The 'threshold' option is the most important option. When motion runs it compares the current image frame with the previous and counts the number of changed pixes (ignoring the ones that have changes intensity less then defined by 'noise_level'). If more pixels then defined by 'threshold' have changed we assume that we have detected motion. Set the threshold as low as possible so that you get the motion you want detected but large enough so that you do not get detections from noise and plants moving. Note that the larger the your frames are, the more pixels you have. So for large picture frame sizes you need a higher threshold.

Noise Level

Any camera produces noise. This can especially be seen in the dark. To avoid that noise triggers motion, each pixel must change intensity over a certain limit before it is counted. This limit is defined by the option 'noise_level'.

Automatic Threshold and Noise Tuning

Automatic threshold tuning and automatic noise tuning can be activated or deactivated by the config file options 'threshold_tune' and 'noise_tune'.

Try them and if they do not work, use the good old manual setting. The noise_tune feature has been significantly improved in Motion 3.1.18. It works so well now that we recommend turning it on as a starting point. Automatic threshold works less well and depends on light conditions and the camera. Here we recommend starting with a fixed value using the default value. We on the Motion mailing list are always interested in hearing your experience and especially any improvement you may have made to the source.

Night Compensate

The option 'night compensate' allows the noise threshold to be lowered if the picture is dark. This will improve the sensitivity in dark places. However it might also increase the number of false alarms since most cameras also compensate for this with their AGC which will increase noise. Default: off. It has normally been the advice not to use this with 'noise_tune' turned on. However the latest experience is that with the new improved noise_tune algoritm it actually works fine in combination with 'night_compensate'.

Despeckle (with labeling)

A way of tuning (by removing or enhancing) noise in the motion image. Options for the despeckle feature are any of 'e', 'E', 'd' or 'D'. This can be combined by a trailing 'l' (letter l) which enables the labeling feature. Default: Not Defined (Don't despeckle and label).

Wind blowing grass and trees around or poor light conditions can cause a lot of dots (or noise) to appear in the motion image (See the section on Tuning Motion). This feature removes (or enhances!) this noise and so improves the reliability of motion.

In general, each erode (e/E) will remove a layer of pixels from around each detection and each dilate (d/D) will add a layer of pixels to each detection

The 'e' option removes diamonds, 'E' removes squares and alternating eE will remove circles. Each e/E you add will shrink the noise by a pixel all the way around. So 'despeckle Ee' will remove circles of radius 2. However, this will also shrink the detection by 2 and will affect the threshold.

The 'd' option adds diamonds, "D" adds squares and alternating dD adds circles. Each d/D you add will add a pixel all the way around a detection area. So 'despeckle dD' will add circles of radius 2 and again affect the threshold.

So to remove noise and then restore the detected motion to its original size try 'despeckle EedD'.

After the despeckle feature is done you can let the labeling feature search for areas of connected pixels and "label" each area. The program will now trigger motion based on the number of changed pixels in the largest area. In other words, the largest labeled area has to be above the threshold to trigger a motion detected.

The value EedDl is a good starting point. The possible combinations are endless and it requires many experiments to find the best combination. Just remember that the labeling feature only works as intended if it runs after the despecle feature. Ie. the letter 'l' must be the last letter and only one 'l'.

If you have very few problems with false detections leave this option either blank or at EedD which will remove most of the single pixel noise.

A very detailed technical explanation of the despecle part can be found at the webpage of the author of this feature Ian McConnell's Webcam: Motion Web Page.

Mask File

The mask file must be a pgm format image file (portable gray map). Note that you must choose the BINARY format.

The feature is simple. Create an image of exact the same size as the ones you get from your video device (camera). Make a purely white picture and paint the areas that you want to mask out black. You can also make gray areas where you want to lower the sensitivity to motion. Normally you will stick to pure black and white.

One easy method for generating the mask file is as follows.

You can just take a motion captured picture, edit it with black and white for the mask and save it as a pgm file. If you cannot save in this format save as a grayscale jpg and then you can convert it to pgm format with

djpeg -grayscale -pnm [inputfile] > mask.pgm

(assuming you have djpeg installed - part of the jpeg lib package).

Note that the mask file option masks off the detection of motion. The entire picture is still shown on the picture. This means that you cannot use the feature to mask off an area that you do not want people to see.

Below are an example of a webcam picture and a mask file to prevent the detection cars in the street.

Normal picture. Notice the street is visible through the hedge.

normal.jpg

Mask file (converted to png format so it can be shown by your web browser)

mask1.png

Smart Mask Speed

The 'mask_file' option described above provides a static mask to turn off sensitivity in certain areas. This is very usefull to mask a street with cars passing by all day long etc...

But imagine a scenario with large bushes and big trees where all the leaves are moving in the wind also triggering motion from time to time even with despeckle turned on. Of course you can also define a static mask here, but what if the bushes are growing during spring and summer? Well, you have to adapt the mask from time to time. What if the camera position moves slightly? What if someone grows new plants in your garden? You always have to setup a new static mask.

The answer to this problem is the smart mask feature introduced in Motion 3.1.18. A dynamic, self-learing mask.

Smart mask will disable sensitivity in areas with frequent motion (like trees in the wind). Sensitivity is turned on again after some time of no more motion in this area. The built mask is a bit larger at the borders than the actual motion. This way smartmask works more reliably when sudden moves occur under windy conditions.

The smart mask feature is enabled and controlled using a single option called 'smart_mask_speed'. It tunes slugginess of the mask.

It accepts values from 0 (turned off) and 1 (slow) to 10 (fast). Fast means here that the mask is built quick, but it is also not staying very long with no more motion. Slow means that it takes a while until the mask is built but it also stays longer. A good start value for smart_mask_speed is 5.

This setting is independent from the framerate. The attack and decay time are constant over all available framerates.

When smart mask is enabled and Motion is also configured to either write motion-images or motion-mpegs, the current smartmask is copied as an overlay into the black/white motion-pictures/mpegs in red colour. That way you can easily adjust smart_mask_speed.

Lightswitch

Ignore sudden massive light intensity changes given as a percentage of the picture area that changed intensity.

The value defines the picture areas in percent that will trigger the lightswitch condition. When lightswitch is detected motion detection is disabled for 5 picture frames. This is to avoid false detection when light conditions change and when a camera changes sensitivity at low light.

Valid range: 0 - 100 , default: 0 = disabled

From version 3.1.17 (snap release 2 and on) this option has changed from a boolean (on or off) to a number in percent between 0 and 100. Zero means the option is disabled. Prior to 3.1.17 the feature did not work at all because of a bug.

Minimum Motion Frames

Picture frames must contain motion at least the specified number of frames in a row before they are detected as true motion.

At the default of 1, all motion is detected. Valid range: 1 to thousands, recommended 1-10.

Note that the picture frames are buffered by Motion and once motion is detected also the first frames containing motion are saved so you will not miss anything.

The feature is used when you get many false detections when the camera changes light sensitivity or light changes.

Experiment for best setting. Valid range is 0 to 1000s but for each step larger than 1 Motion reserves space in RAM for the picture frame buffer. Practical range is 1 to 10.

Pre-Capture

Motion buffers the number of picture frames defined by the config option 'pre_capture'. When motion is detected an ffmpeg generated film will begin with the buffered picture frames followed by the frames that were detected as motion and finally additional picture frames are added given by the config option 'post_capture'. The buffered pictures will also be saved as motion triggered images.

The result is that when you see the mpeg films generated by ffmpeg, it appears Motion was able to predict the future and start the film capturing before the event actually started.

If pre_capture is set to 0 the feature is disabled. You can have up to 1000s of pre-captured frames but naturally this makes motion leave a larger footprint in the memory of the computer. More important Motion is processing all the buffered images including saving jpegs, encoding mpegs, writing to databases and executing external programs after the first image is detected as Motion. Motion will not grab another image until this is done. This means that even moderate values for pre_capture combined with high framerates will mean that you will miss quite many frames of Motion. It is therefore recommended to use relative small values for pre_capture. Depending on your chosen framerate and depending on the features enabled values from 1-10 are sensible. If you wish to create smooth mpegs during events it is better to use a large value for post_capture.

Post-Capture

The option 'post_capture' specifies the number of frames to be captured after motion has been detected. Valid range: 0 to thousands, default=0. The purpose of this is mainly to create smooth video clips each time motion is detected. Use it to you personal taste (and disk space).

Gap

The option 'gap' is important. It defines how long a period of no motion detected it takes before we say an event is over. An event is defined as a series of motion images taken within a short timeframe. E.g. a person walking through the room is an event that may have caused 10 single jpg images to be stored. Motion detected includes post_captured frames set by the 'post_capture' option. The 'gap' option defines how long a pause between detected motions that is needed to be defined as a new event. A good starting value is 60 seconds.

The way 'gap' works in more technical terms is:
  • Gap is a timer that timeout 'gap' seconds after the last video frame with motion is detected.
  • If 'post_capture' is activated then the gap timer starts counting after the last image of the post_capture buffer has been saved.
  • The gap timer is reset and starts all over each time new motion is detected, so you will not miss any action by having a short 'gap' value. It will just create more events (e.g. more mpegs files)

The gap value impacts many functions in Motion.
  • When the gap timer runs out the event number is increased by one next time motion is detected. When you use the %v conversion specifier in filenames or text features this means that the number in filename or text increased by one.
  • The pre_capture feature only works at the beginning of an event. So if you have a very large 'gap' value pre_capture is not working very often.
  • When you make mpegs using the ffmpeg features a new mpeg file is started at the beginning of an event when the first motion is detected. When 'gap' seconds has passed without motion (and post_captured frames saved) the mpeg files is completed and closed.
  • Do not use large gap values to generate one large mpeg4 file. If Motion stops working this mpeg4 file never gets properly completed and closed and you will not be able to view it.
  • Some of the tracking features sets the camera back to the center position when an event is over.

Note that 'gap' and 'minimum_gap' have nothing to do with each other.

Minimum Gap

This option has nothing to do with the 'gap' option. This is the minimum gap between the storing pictures while detecting motion. The value zero means that pictures can be stored almost at the framerate of the camera. Normally you will set this to 0.

This feature is for people that have very limited storage space available and can live with very few pictures saved.

Max mpeg Time

The option max_mpeg_time defines the maximum length of an mpeg movie. Default: 3600 seconds (one hour). Set this to zero for unlimited length.

Low CPU (low_cpu) Mode

To save computer power on slow computers there is a 'low_cpu' option which lowers the number of frames per second that motion captures from the camera to the value defined by this option, when motion is not detected. A value of zero means that the low_cpu option is disabled.

The "output_all" Option

This new feature is not meant to be the normal mode of operation. Especially not if you have the output_normal or output_motion features enabled since it will keep on saving pictures on the disk and you will soon run out of disk space. All features are triggered like it was detecting motion all the time. It does all the normal actions that are done when motion is detected. It saves pictures on the harddisk, runs scripts, sends emails etc as fast as the frame rate of the camera. So it is probably a good idea to run with a low framerate when using this feature and to not use activate all the features that saves files on the disk. This parameter is default off.

The idea of this feature is that you can turn the feature on and off for a short period of time to test or to generate continuous mpeg films when needed. You can then use the motion-control program to turn the feature on a off.

Image File Output

The following options controls how Motion generates images when detection motion.

############################################################
# Image File Output
############################################################

#Output 'normal' pictures when motion is detected (default: on)
output_normal on

#Output pictures with only the pixels moving object (green ghost images) (default: off)
output_motion off

#The quality (in percent) to be used by the jpeg compression (default: 75)
quality 75

#Output ppm images instead of jpeg (default: off)
ppm off

The 'option_normal' option activate saving normal pictures when detecting motion.

The 'output_motion' option activate saving pictures that shows which pixels have been detected as motion. You will normally set this option to 'off'. See the 'Tuning Motion' section.

The 'quality' option sets the quality (in percent) of the saved jpeg images. The higher the number the batter quality and the larger file sizes. A good compromise is 75%.

The option 'ppm' produces non compressed pictures in the ppm format. They take a lot of diskspace. Only recommended if you need a very high picture quality.

Tuning Motion

Motion contains a number of features that helps you tune the settings of motion to the optimal. They are all described in the config file table above but this section will try to illustrate them a bit more and give some guides to how to tune.

The settings that are difficult to set are the settings that decides or influence when to detect motion. These are

threshold
number of changed image pixels that triggers motion detection

threshold_tune
automatically tune threshold down of possible

noise_level
noise threshold for detecting a pixed as changed

noise_tune
automatically tune noise_level

night_compensate
adjust threshold/noise for very dark frames (don't mix with noise tune)

despeckle
Eliminate single or few pixels of noise

mask_file
mask that disables motion detection in areas of the picture

smart_mask_speed
smart mask disables sensitivity in areas with frequent motion (like trees in the wind).

light_switch
try to filter out sudden light switches

auto_brightness
let motion regulate brightness of video device (use only with devices without built-in autobrightness)

roundrobin_frames
number of frames to capture in each roundrobin step

roundrobin_skip
number of frames to skip before each roundrobin step

switch_filter
try to filter out noise generated by roundrobin

Special tuning options

daemon off
Setting daemon to off enables you to see the debugging texts and error messages that motion creates during operation. Motion writes every time it saves a file and you can see the motion detection value. Setting "always_changes" to on gives you even further information which will help you setting the noise_level/night_compensate/threshold parameters.

always_changes
You need to run motion in non-daemon mode so that you can see the text output on the terminal. This is very useful to see how many changes motion sees AFTER the noise_level filter has been used.

locate
Locate can be used as a normal feature showing you where in the picture the motion was detected. Even if you do not want this feature e.g. on a public webcam it is still useful as a debugging/tuning tool to set the parameters such as noise_level/night_compensate/threshold/mask_file parameters

text_changes
Shows the number of pixels detected as motion as a number displayed in the upper right corner of the images and films. Again this is is very useful to see how many changes motion sees AFTER the noise_level filter has been used.

motion_video_pipe/video_pipe
These feature enables you to see live what motion sees. Being a command line only program makes motion difficult to setup but also enables the program to run in the background using very few resources and it can easily be started up automatically when booting. The motion_video_pipe shows you the motion images that are generated when motion is detected. The video_pipe shows the normal picture.

pre_capture
The feature buffers up the number of picture defined by this option and include them when motion is detected. This is a nice feature not only for testing and tuning. By enabling this feature you can see the frame just before motion was detected. This helps identifying what causes unwanted motion detections.

output_motion
This feature help you to see exactly what the motion sees as motion in the picture. What you get is a green image that shows the pixels that changed. Motion has an simple but brilliant algorithm to detect motion where the previous pictures taken are used to create a reference picture. Motion detected are differences between the latest picture and the reference picture. The reference frame is generated from the past picture frames. For each new frame the older frames gets less and less 'weight'. This is why you see motion as a bright green images and weaker ghost or shadow images.

ffmpeg_cap_motion
Same feature as output_motion except the changed pixels are captured in mpeg films.

Normal picture frame

outputnormal.jpg

Motion type picture frame without despeckle (note that from 3.1.18 these images are grayscale instead of green as shown below)

outputmotion.jpg

Motion type picture frame with despeckle set to EedD

outputmotion-EedD.jpg

-- KennethLavrsen - 29 Jan 2005

Generating MPEG films with ffmpeg

The ffmpeg option can generate mpeg films very fast and "on the fly". This means that the mpeg film is growing each time motion is detected.

Some people on the Motion mailing list have had trouble building the ffmpeg package because they did not have the NASM assembler package installed. So pay attention to this if you run into problems.

ffmpeg exists as binary packages for most distributions including RPMs and debian packages.

You can download and compile from sources as well.

Motion works with the following versions of ffmpeg:
  • ffmpeg-0.4.8. With this release Motion supports mpeg1, mpeg4 and msmpeg4.
  • ffmpeg-0.4.9pre1. Is supported starting from Motion version 3.1.18. With this release Motion supports mpeg4 and msmpeg4 but not mpeg1. The reason is that the ffmpeg team has decided no longer to support non-standard framerates in their mpeg1 encoder library.
  • ffmpeg from CVS. This may work. We cannot continuously monitor and try every time a new source file is checked into ffmpeg. You will have to try.
  • ffmpeg-0.4.9 RPMs with date code 20041110 has been confirmed to work fine with Motion.

The timelapse feature always runs mpeg1 with both ffmpeg 0.4.8 and 0.4.9. Motion simply creates the timelapse film with a standard mpeg1 framerate.

In principle Motion can be made to support many other formats. It requires additional coding in Motion. You are welcome to submit patches. All ffmpeg related code is in the source file ffmpeg.c. It is not trivial to do because the ffmpeg libraries not documented at all. All you have is a couple of code examples.

To build ffpmeg from source follow these steps: Download the ffmpeg and untar it to /usr/local/ffmpeg. Then it should be a simple matter of entering the ffmpeg directory and run the commands

cd /usr/local/ffmpeg
./configure --enable-shared
make
make install

This creates the libavcodec.so and libavformat.so libraries under /usr/local/lib and header files under /usr/local/include/ffmpeg.

You probably need to do one more step.

Make sure you have 'root' priviledges for the next steps.

Open the file /etc/ld.so.conf in your favorite text editor.

Add this line of text if it is not already there - otherwise go to the next step (ldconfig).

/usr/local/lib Run the command ldconfig.

Motion should now be able to find the shared libraries for ffmpeg (libavcodec.so and libavformat.so) in /usr/local/lib.

You can also find a pre-compiled binary package (e.g. rpm or deb) and install this. Normally an rpm will place the libavcodec.so under /usr/lib. There are various RPMs available from different repositories. Some need additional RPMs that are actually not needed by Motion but need to be installed to satisfy dependencies. The editor has tried different RPMs of ffmpeg-0.4.8 and they all seem to work.

Motion then need to be built by running ./configure, make and make install. (Note that with earlier versions of motion you had to specify the location of libavcodec. Now configure searches for the shared library in /usr/lib and /usr/local/lib by default.)

These are the config file options related to ffmpeg.

############################################################
# Film (mpeg) File Output - ffmpeg based
############################################################

#Use ffmpeg to encode mpeg movies in realtime (default: off)
ffmpeg_cap_new on

#Use ffmpeg to make movies with only the pixels moving
#object (green ghost images) (default: off)
ffmpeg_cap_motion on

#Use ffmpeg to encode a timelapse movie 
#Default value 0 = off - else save frame every Nth second
ffmpeg_timelapse 0

#The file rollover mode of the timelapse video
#Valid values: hourly, daily (default), weekly-sunday, weekly-monday, monthly, manual
ffmpeg_timelapse_mode daily

#Bitrate to be used by the ffmpeg encoder (default: 400000)
#This option is ignored if ffmpeg_variable_bitrate is not 0 (disabled)
ffmpeg_bps 500000

#Enables and defines variable bitrate for the ffmpeg encoder.
#ffmpeg_bps is ignored if variable bitrate is enabled.
#Valid values: 0 (default) = fixed bitrate defined by ffmpeg_bps,
#or the range 2 - 31 where 2 means best quality and 31 is worst.
ffmpeg_variable_bitrate 0

#Codec to used by ffmpeg for the video compression.
#Timelapse mpegs are always made in mpeg1 format independent from this option.
#Supported formats are: mpeg1 (ffmpeg-0.4.8 only), mpeg4 (default), and msmpeg4.
#mpeg1 gives you files with extension .mpg
#mpeg4 or msmpeg4 give you files with extension .avi
#msmpeg4 is recommended for use with Windows Media Player because
#it requires no installation of codec on the Windows client.
ffmpeg_video_codec mpeg4

ffmpeg_cap_new
Generates a new film at the beginning of each new 'event' and appends to the film for each motion detected within the same event. The current 'event' ends when the time defined by the 'gap' option has passed with no motion detected. At the next detection of motion a new mpeg film is started. Default: off.

ffmpeg_cap_motion
Works like ffmpeg_cap_new but outputs motion pictures instead. Default: off.

ffmpeg_timelapse
Uses ffmpegs libavcodec to encode a timelaps movie saving a picture frame at the interval in seconds set by this parameter. Setting this option to 0 disables it. The feature gives your viewer the chance to watch the day pass by. It makes a nice effect to film flowers etc closeup during the day. Options like frame_rate, snapshot, gap etc has no impact on the ffmpeg timelapse function. (note: option name ffmpeg_timelapse was renamed to correct spelling in v. 3.1.14 - adding the 'e' at the end). Also note that the timelapse format is always mpeg1 independent of ffmpeg_video_codec. This is because mpeg1 allows the timelapse to stop and the file to be reopened and more film appended.

ffmpeg_timelapse_mode
Defines the file rollover mode. Ie. when to close the current timelapse file and start a new one. Valid values: hourly, daily (default), weekly-sunday, weekly-monday, monthly, manual. it is important that you use the conversion specifiers in ffmpeg_filename that ensure that the new timelapse file indeed is a new file. If the filename does not change Motion will simply append the timelapse pictures to the existing file.

ffmpeg_bps
Sets the bits per seconds of the generated film. The higher value - the better quality - the bigger file. Experiment to get the desired quality/file sizes. Default is 400000 bps. This option is ignored if ffmpeg_variable_bitrate is not 0 (disabled)

ffmpeg_variable_bitrate
Enables and defines variable bitrate for the ffmpeg encoder. ffmpeg_bps is ignored if variable bitrate is enabled. Valid values: 0 (default) = fixed bitrate defined by ffmpeg_bps, or the range 2 - 31 where 2 means best quality and 31 is worst. Experiment for the value that gives you the desired compromise between size and quality.

ffmpeg_video_codec
Selects the codec to used by ffmpeg for the video compression. Timelapse mpegs are always made in mpeg1 format independent from this option. Supported codec formats are: mpeg1 (ffmpeg-0.4.8 only), mpeg4 (default), and msmpeg4.
'mpeg1' gives you files with extension .mpg . It is only supported by the old ffmpeg version 0.4.8. The ffmpeg team decided no longer to support non-standard framerates for mpeg1 from ffmpeg version 0.4.9pre1.
'mpeg4' or 'msmpeg4' give you files with extension .avi
msmpeg4 is recommended for use with Windows Media Player because it requires with no installation of codec on the Windows client.
Note that timelapse mpegs are always made in mpeg1 format and ignores this setting. This is because the mpeg1 encoder allows appending to an existing mpeg1 file and we need this feature for timelapse - both for when motion is stopped and re-started and during a pause.

See also the section 'Advanced Filenames' where the two additional options 'ffmpeg_filename' and 'timelapse_filename' are defined.

If you want to use this feature you can read about the FFmpeg Streaming Multimedia System

Snapshots - The Traditional Periodic Web Camera

Motion can also act like a traditional web camera.

The option 'snapshot_interval' enables the snapshots feature by being set to a value different than 0. The value gives the number of seconds between each snapshot.

See the 'snapshot_filename' option in the section 'Advanced Filenames'.

Text Features

Text features have been made highly flexible starting from version 3.1.13 of Motion. It enables you to taylor the text displayed on the images and films to your taste and to add your own user defined text. From version 3.1.13 all text related motion.conf options have been redefined and renamed.

There are 3 motion.conf options that controls the display of text.

############################################################
# Text Display
# %Y = year, %m = month, %d = date,
# %H = hour, %M = minute, %S = second, %T = HH:MM:SS
# %v = event, %q = frame number, \n = new line
# You can put quotation marks around the text to allow
# leading spaces
############################################################

#Locate and draw a box around the moving object (default: off)
locate off

#Draws the timestamp using same options as C function strftime(3)
#Default: %Y-%m-%d\n%T = date in ISO format and time in 24 hour clock
#Text is placed in lower right corner
text_right %Y-%m-%d\n%T

#Draw a user defined text on the images using same options as C function strftime(3)
#Default: Not defined = no text
#Text is placed in lower left corner
text_left CAMERA 1\nFRONT DOOR

#Draw the number of changed pixed on the images (default: off)
#Will normally be set to off except when you setup and adjust the motion settings
#Text is placed in upper right corner
text_changes off

The text_left and text_right options have the similar functions.

text_left
Places text in the lower left corner and aligns the text to the left. If the option is not defined the default is no text displayed.

text_right
Places text in the lower right corder and aligns the text to the right. If the option is not defined the default is showing date in ISO format YYYY-MM-DD and below this the time as a 24 hour clock HH:MM:SS. If you wish to have no text to the right define text_right to an empty string "".

text_changes
Is a feature meant for helping adjusting the threshold and noise_level settings. It shows the number of pixels seen as motion in the upper right corner.

This is how the text is located.

  





 

 CHANGES





 



TEXT_LEFT

TEXT_RIGHT
YYYY-MM-DD
HH:MM:SS 

Both text_left and text_right are highly flexible.

The user defined text can be the english alphabet and a selection of symbols - (A-Z, a-z, 0-9, " / ( ) @ ~ # < > | , . : - + _ \n) and conversion specifiers. Non-english characters are for the moment not supported.

A conversion specifier is a code that starts by % (except newline which is \n). The conversion specifiers used has the same function as for the C function strftime (3). The most commonly used are: %Y = year, %m = month as two digits, %d = date, %H = hour, %M = minute, %S = second, %T = HH:MM:SS. Two are unique to motion %v = event, %q = frame number. With a combination of text, spaces, new lines \n and conversion specifiers you have some very flexible text features. For a full list of conversion specifiers see the section 'Conversion Specifiers for Advanced Filename and Text Feature'.

You are allowed to put the text in quotation marks. This allows you to use leading spaces. By combining spaces and new lines '\n' you can place your text anywhere on the picture. Experiment to find your preferred look. When setting the text using motion-control to send XML-RPC commands put the text in quotation marks "" to allow for spaces and new lines.

Advanced Filenames

From version 3.1.13 the old_layout option has been replaced by new advanced options: snapshot_filename, jpeg_filename, ffmpeg_filename, and timelapse_filename.

These are the advanced filename options in motion.conf

############################################################
# Target Directories and filenames For Images And Films
# For the options snapshot_, jpeg_, mpeg_ and timelapse_filename
# you can use conversion specifiers
# %Y = year, %m = month, %d = date,
# %H = hour, %M = minute, %S = second,
# %v = event, %q = frame number
# Quotation marks round string are allowed.
############################################################

#Target base directory for pictures and films
target_dir /usr/local/apache2/htdocs/cam1

#File path for snapshots (jpeg or ppm) relative to target_dir
#Default: %v-%Y%m%d%H%M%S-snapshot
#Default value is equivalent to legacy oldlayout option
#For Motion 3.0 compatible mode choose: %Y/%m/%d/%H/%M/%S-snapshot
#File extension .jpg or .ppm is automatically added so do not include this.
#Note: A symbolic link called lastsnap.jpg created in the target_dir will always
#point to the latest snapshot, unless snapshot_filename is exactly 'lastsnap'
snapshot_filename %v-%Y%m%d%H%M%S-snapshot

#File path for motion triggered images (jpeg or ppm) relative to target_dir
#Default: %v-%Y%m%d%H%M%S-%q
#Default value is equivalent to legacy oldlayout option
#For Motion 3.0 compatible mode choose: %Y/%m/%d/%H/%M/%S-%q
#File extension .jpg or .ppm is automatically added so do not include this
jpeg_filename %v-%Y%m%d%H%M%S-%q

#File path for motion triggered ffmpeg films (mpeg) relative to target_dir
#Default: %v-%Y%m%d%H%M%S
#Default value is equivalent to legacy oldlayout option
#For Motion 3.0 compatible mode choose: %Y/%m/%d/%H%M%S
#File extension .mpg or .avi is automatically added so do not include this
ffmpeg_filename %v-%Y%m%d%H%M%S

#File path for timelapse mpegs relative to target_dir
#Default: %Y%m%d-timelapse
#Default value is near equivalent to legacy oldlayout option
#For Motion 3.0 compatible mode choose: %Y/%m/%d-timelapse
#File extension .mpg or .avi is automatically added so do not include this
timelapse_filename %Y%m%d-timelapse

The option target_dir is the target directory for all snapshots, motion images and normal images. The default is the current working directory (current working directory of the terminal from which motion was started). You will normally always want to specify this parameter either as a command line option or in the config file.

Note that the options snapshot_filename, jpeg_filename, ffmpeg_filename, and timelapse_filename all allow specifying directories. These will all be relative to target_dir. This means in principle that you can specify target_dir as '/' and be 100% flexible. It also means that Motion can write files all over your harddisk if you make a mistake. It is recommended to specify the target_dir as deep or detailed as possible for this reason.

The xxxx_filename options all support the 'Conversion Specifiers for Advanced Filename and Text Features'. This means that you can build up the filenames anyway you want using fixed text mixed with conversion specifiers for time, event and frame.

NOTE: Unless you use the minimum_gap option to limit the number of shots to less then one per second - you must use the frame modifier %q as part of the jpeg_filename. Otherwise the pictures saved within the same second will overwrite each other. The %q in jpeg_filename ensures that each jpeg (or ppm) picture saved gets a unique filename.

ALERT! Security Warning! Note that the flexibility of this feature also means you have to pay attention to the following.
  • Anyone with access to the remote control port (xmlrpc) can alter the values of these options and save files anywhere on your server with the same priviledges as the user running Motion. You do not protect anything by protecting the motion-control program. Anyone can compile and run their own copy of motion-control and access your control port if you have not either limited access to localhost or limited access using firewalls in the server. You should always have a router between a machine running Motion with remote control enabled and the Internet and make sure the Motion control port is not accessible from the outside.
  • Anyone with local access to the computer and edit rights to the motion.conf file can alter the values of these options and save files anywhere on your server with the same priviledges as the user running Motion. Make sure the motion.conf file is maximum readonly to anyone else but the user running Motion.
  • It is a good idea to run Motion as a harmless user. Not as root.

Conversion Specifiers for Advanced Filename and Text Features

The table below shows all the supported Conversion Specifiers you can use in the options text_left, text_right, snapshot_filename, jpeg_filename, ffmpeg_filename, and timelapse_filename.

In text_left and text_right you can additionally use '\n' for new line.

Conversion Specifier Description
%a The abbreviated weekday name according to the current locale.
%A The full weekday name according to the current locale.
%b The abbreviated month name according to the current locale.
%B The full month name according to the current locale.
%c The preferred date and time representation for the current locale.
%d The day of the month as a decimal number (range 01 to 31).
%D Equivalent to %m/%d/%y. (Yecch - for Americans only. Americans should note that in other countries %d/%m/%y is rather common. This means that in international context this format is ambiguous and should not be used.)
%E Modifier: use alternative format, see below.
%F Equivalent to %Y-%m-%d (the ISO 8601 date format).
%H The hour as a decimal number using a 24-hour clock (range 00 to 23).
%I The hour as a decimal number using a 12-hour clock (range 01 to 12).
%j The day of the year as a decimal number (range 001 to 366).
%k The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. (See also %H.)
%l The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. (See also %I.)
%m The month as a decimal number (range 01 to 12).
%M The minute as a decimal number (range 00 to 59).
%p Either 'AM' or 'PM' according to the given time value, or the corresponding strings for the current locale. Noon is treated as `pm' and midnight as `am'.
%P Like %p but in lowercase: `am' or `pm' or a corresponding string for the current locale.
%q Picture frame number within current second. For jpeg filenames this should always be included in the filename if you save more then 1 picture per second to ensure unique filenames. It is not needed in filenames for mpegs.
%r The time in a.m. or p.m. notation.
%R The time in 24-hour notation (%H:%M).
%s The number of seconds since the Epoch, i.e., since 1970-01-01 00:00:00 UTC.
%S The second as a decimal number (range 00 to 61).
%T The time in 24-hour notation (%H:%M:%S).
%u The day of the week as a decimal, range 1 to 7, Monday being 1. See also %w.
%U The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also %V and %W.
%v Event number. An event is a series of motion detections happening with less than 'gap' seconds between them.
%V The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week. See also %U and %W.
%w The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u.
%W The week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01.
%x The preferred date representation for the current locale without the time.
%X The preferred time representation for the current locale without the date.
%y The year as a decimal number without a century (range 00 to 99).
%Y The year as a decimal number including the century.
%z The time-zone as hour offset from GMT.
%Z The time zone or name or abbreviation.

Webcam Server

Motion has a mini (very very mini) http server built in. Each thread can have its own webserver. If you enable the webcam server (option webcam_port to a number different from 0) and you have threads you must make sure to include webcam_port to different ports or zero (disable) in each thread config file. Otherwise motion will crash because each webcam server will use the setting from the motion.conf file and try to bind to the same port.

Note: The webcam server feature requires that the option ppm is set to off. (I.e. saved images are jpeg images).

These are the special webcam parameters.

############################################################
# Live Webcam Server
############################################################

#The mimi-http server listens to this port for requests (default: 0 = disabled)
webcam_port 8081

#Quality of the jpeg images produced (default: 30)
webcam_quality 50

#Only output frames if motion is detected (default: off)
webcam_motion off

#Maximum framerate for webcam streams (default: 100)
webcam_maxrate 1

#Restrict webcam connections to localhost only (default: on)
webcam_localhost off

#Limits the number of images per connection (default: 0 = unlimited)
#Number can be defined by multiplying actual webcam rate by desired number of seconds
#Actual webcam rate is the smallest of the numbers framerate and webcam_maxrate
webcam_limit 1200

The webcam_maxrate and webcam_quality options are important to limit the load on your server and link. Don't set them too high unless you only use it on the localhost or on an internal LAN. The option webcam_quality is equivalent to the quality level for jpeg pictures.

The webcam_limit option prevents people from loading your Network connection by streaming for hours and hours. The options defines the number of picture frames sent as mjpeg Motion will allow without re-connecting (e.g. clicking refresh in the browser).

The option webcam_localhost is a security feature. When enabled you can only access the webserver on the same machine as Motion is running on. If you want to present a live webcam on your web site this feature must be disabled.

The webserver generates a stream in "multipart jpeg" format (mjpeg). You cannot watch the stream with most browsers. Editor has tried Internet Explorer 6, Netscape 6.2 (windows) and Konqueror. Only Netscape on Linux can show the stream. For public viewing this is not very useful. There exists a java applet called Cambozola. Same tool is also used in the motion.cgi program that is available from the motion homepage. To enable the feature to a broad audience you should use this applet or similar.

To use the webcam feature with Cambozola is actually very simple.

1. Create a html page in which you will want the streamed picture.

2. In the html page include this code

<applet code=com.charliemouse.cambozola.Viewer
    archive=cambozola.jar width=400 height=300>
    <param name=url value=http://www.myurl.com:8081>
</applet>

Where the width and height is the area of the applet. Adjust it to the same size or a little larger than your streamed image.

Replace www.myurl.com:8081 by the real url and port number of your choice.

3. In the same directory you place the cambozola.jar file. No need to build the java applet from source. Simply use the applet in the package. Or copy it from motion.cgi package. It is the same version.

4. Enable the feature in motion.conf.

Controlling Motion via XML-RPC

Motion version 3.1.12 has got a new exciting feature which is the ability to control Motion while it is running. Motion now has a built in http server called xmlrpc-httpd. This listens on a port specified by the new 'control_port' config file option. The control protocol is called xml-rpc. With Motion there is a small program that can be built and which can be used to control all the new control features of Motion.

Installing XMLRPC-C

First, the xmlrpc stuff we need to install is located here: http://xmlrpc-c.sourceforge.net/downloading.php

Motion has been mainly tested wuth XMLRPC-C version is 0.9.10.

Recently the XML-RPC-C project finally got a new owner after having been abandoned for years. Recently version 1.0 and 1.1 has been released.

Even though these have not been tested with Motion, it is assumed that they work. Please report on the Mailing List if you have success or failure with xmlrpc-c 1.0 or 1.1.

We have not prioritized testing the new xmlrpc versions because the next major Motion releases (3.2.X) will replace the xmlrpc interface by a much simpler and newbie friendly http based remote control interface.

At Sourceforge you find the latest files.

http://sourceforge.net/project/showfiles.php?group_id=16847

XMLRPC-C from RPMs

If you use a distribution using RPM like Red Hat and many other all you need is to download and installed RPMs.

The two RPMs you need are here

http://prdownloads.sourceforge.net/xmlrpc-c/xmlrpc-c-0.9.10-1.i386.rpm?download

http://prdownloads.sourceforge.net/xmlrpc-c/xmlrpc-c-devel-0.9.10-1.i386.rpm?download

Additionally the two RPMs above need w3c-libwww installed. The RPMs for w3c-libwww comes with RedHat but are not installed per default.

There are 2 RPMs: w3c-libwww-5.4.0-4.i386.rpm and w3c-libwww-devel-5.4.0-4.i386.rpm.

Previous versions of RedHat also have the 3 RPMs on the CDs but in earlier versions. They are probably also OK. The version should not be very critical.

XMLRPC-C from Source Files

For those that do not use distribution based on RPM, the source tar.gz is here

http://prdownloads.sourceforge.net/xmlrpc-c/xmlrpc-c-0.9.10.tar.gz?download

There is however a problem with the package above. It will not compile with gcc compiler version 3.1 and later. Kenneth Lavrsen has patched up the sources with patches found on the Sourceforge xmlrpc-c patch tracker. This patched package has been placed in the Motion Sourceforge Files area under "Related Projects" It is recommended that you download and install this instead.

http://prdownloads.sourceforge.net/motion/xmlrpc-c-0.9.10-kjl3.tar.gz?download

The Libwww can be downloaded from here

http://www.w3c.org/Library/

Follow the installation instructions from the websites of the XMLRPC-C and Libwww libraries.

After installation of xmlrpc-c you need to re-install motion going through all the steps ./configure, make and make install

Besides building motion with XML-RPC support it also build a small application called motion-control which is copied to /usr/local/bin.

motion-control

The motion-control program is easy to use. Run it without any parameters and it displays the help.

The commands are shown below. Note the following. If you choose to set configuration parameters for thread 0, all threads will be changed. The individual camera threads are numbered 1,2,3....

Configuration parameters are simply named the same as in the motion.conf file. Parameters that are global and not set in a thread config file can only be read from thread 0. Trying to read a global only value from a camera thread will give no value back (same reply as if you ask for a non-existing value). Once you set a value for a thread other than 0 you can read it again from that thread.

The detection pause feature disables the saving of pictures, snapshots etc but does not stop the webcam server. The motion-control action and detection features do not work globally. I.e. 'motion-control action snapshot 0' does not generate snapshots for all cameras. One exception is 'motion-control action quit' which simply makes motion stop running (all processes quit).

The conf write feature overwrites both the motion.conf and the thread config files in a shorter format with less comments. If you like to keep your config files make sure to save copies of them before you run this control command. If you have changed parameters using the conf set command it is the changed values that get saved to the config files. Global (thread 0) parameters to motion.conf and individual thread values to the thread config files. Files are saved at the same location as they were read from overwriting the existing files.

Command Description
motion-control info Brief information about motion version and number of threads running.
motion-control conf list List all configuration parameters/options with their type and a short help text. Not all parameters have a help text yet.
motion-control conf get [threadnr] [parameter] Get the value of a configuration parameter for a given thread. Thread 0 means the global or default value. If a parameter is not defined for a given thread then this value will be used instead as a default value.
motion-control conf set [threadnr] [parameter] [value] Set the value of a configuration parameter for a given thread. Thread 0 means the global or default value. If a parameter is not defined for a given thread then this value will be used instead as a default value.
motion-control conf write Write all motion config files. Both the motion.conf and all thread config files. Note that this overwrites the original config files. All old comments are lost.
motion-control action makemovie [threadnr] Make an mpeg movie on a given thread.
motion-control action snapshot [threadnr] Save a snapshot picture of a given thread.
motion-control action quit Make motion quit completely. Useful for stopping motion when it runs as a daemon.
motion-control detection pause [threadnr] Disables the saving of pictures, snapshots etc for a given thread but does not stop the webcam server.
motion-control detection resume [threadnr] Resume the saving of pictures, snapshots etc for a given thread.
motion-control track auto [threadnr] [value] Enable auto tracking. 0=disabled, 1=enabled. Auto tracking is always disabled when motion starts. Manual tracking is still possible when auto tracking is turned off.
motion-control track set [threadnr] [value_x] [value_y] Turn camera to a specific position. Values x and y are in degrees from center. Up and right are positive numbers, Down and left are negative numbers. If you want to move the camera in one dimension and leave the other unchanged set the value for the one to be unchanged to an out of range value such a 1000.
For a Logitech Quickcam Sphere/Orbit the range for pan (x) is -69 to 69 degrees and the range for tilt is -30 to 24 degrees.
motion-control track pan [threadnr] [value] Turn camera to a position in degrees relative to current position. Value is in degrees and positive values means turn right, negative means turn left.. This is a good command for small step sizes like 10-20 degrees. If value is out of range camera will move as far as it can.
motion-control track tilt [threadnr] [value] Tilt camera to a position in degrees relative to current position. Value is in degrees and positive values means tilt up, negative means tilt down. This is a good command for small step sizes like 5-10 degrees. If value is out of range camera will move as far as it can.

The conf set [threadnr] [parameter] [value] feature is very smart for trying tuning settings and for changing the user defined on screen display.

By setting the option control_localhost to "on" Motion can only be controlled via xml-rpc from the same machine on which Motion is running. If you need more refined access control use your firewall such as ipchains or iptables for it.

As mentioned above there is a config file option called control_port. You should normally set this to 8080. If you need to set it to another port you will also need to change the port number defined in the motion-control source file. Look for the line

#define MOTION_URL "http://localhost:8080".

Same line can be changed to a real URL so that you can control Motion from a remote machine.

ALERT! Security Warning! Note that this feature also means you have to pay attention to the following.
  • Anyone with access to the remote control port (xmlrpc) can alter the values of any options and save files anywhere on your server with the same priviledges as the user running Motion. They can execute any command on your computer with the same priviledges as the user running Motion. You do not protect anything by protecting the motion-control program. Anyone can compile and run their own copy of motion-control and access your control port if you have not either limited access to localhost or limited access using firewalls in the server. You should always have a router between a machine running Motion with remote control enabled and the Internet and make sure the Motion control port is not accessible from the outside.
  • If you limit control port to localhost you still need to take care of any user logging into the server with any kind of terminal session or any kind of access to alter PHP programs and CGI scripts. It is easy to write a PHP script or perl script that sends XMLRPC commands.
  • It is a good idea to run Motion as a harmless user. Not as root!!

Tracking Control

This is still at the experimental stage. Read more about it motion tracking page.

Tracking Feature with Logitech Quickcam Sphere/Orbit

Motion supports controlling the pan and tilt feature of a Logitech Quickcam Sphere/Orbit.

Motion can move the camera to a fixed position given in degrees pan (left-right) and tilt (down-up). Movement can be set with absolute coordinates or relative to current position. There is also an auto tracking feature for the Logitech Quickcam Sphere/Orbit but it is not very mature. It is fun to play with but not very useful yet.

Motion always starts up with auto tracking turned off.

All control is done using the XML-RPC interface. The actual XML-RPC commands are described in the xmlrpc-api.html document which is part of the distribution and also available on the motion website. The motion-control commands available are:

  • motion-control track auto thread_nr value (value: 0=disable, 1=enable)
  • motion-control track set thread_nr x-degrees y-degrees
  • motion-control track pan thread_nr x-degrees
  • motion-control track tilt thread_nr y-degrees
For a detailed description of XML-RPC see the section 'Controlling Motion via xml-rpc'.

External Commands

Motion can execute external command based on the events.

These are the options:

############################################################
# External Commands, Warnings and Logging:
############################################################

#Output less information and don't sound beeps when detecting motion (default: off)
quiet on

#Always display the difference between captured and reference frame (default: off)
always_changes off

#Email address to send a warning to when detecting motion (default: none)
; mail value

#External command to be executed when detecting motion (default: none)
; execute value

#Number to send an sms to with sms_client (default: none)
; sms value

#Command to be executed each time an image is saved (default: none)
; onsave value

#Command to be executed each time an mpeg movie is created (default: none)
; onmpeg value

#Command to be executed each time a file generated by ffmpeg is closed (default: none)
; onffmpegclose value

quiet
is only active when Motion is running in non-daemon mode. When this option is set to 'off' and Motion is running as non-daemon Motion generates a system beep when motion is detected.

always_changes
is also only working in non-daemon mode. When activated it constantly shows the number of image pixels changed. See 'Tuning Motion for more information'. Normally you set this option to 'off'

mail
when defined it sends an email when motion is detected. Argument is an email address in the normal form name@domainPLEASENOSPAM.name. An e-mail is sent for each event. Not each picture.

sms
sends an SMS when motion is detected. The argument is the number to send an SMS to with sms_client. Default: none. Not a feature that has received much attention recently. If you live in GSM land you are probably better off using the e-mail to SMS gateway that most GSM providers have using your mail client. For more information see the sms_client home page.

onsave
executes the command given when an image is saved. The name of the image will be given as argument. Default: not set. You should give the full path name of the program/script. This can be any type of program or script. Remember to set the execution bit in the ACL and if it is a script type program such as perl or bash also remember the shebang line (e.g. #!/user/bin/perl) as the first line of the script.

onmpeg
executes the command given when an mpeg movie is generated. The name of the movie will be given as argument. Default: not set. You should give the full path name of the program/script. This can be any type of program or script. Remember to set the execution bit in the ACL and if it is a script type program such as perl or bash also remember the shebang line (e.g. #!/user/bin/perl) as the first line of the script. When you use ffmpeg the film is generated on the fly and onmpeg then runs when the new mpeg file is created. Often you will want to use the onffmpegclose option which runs when the mpeg file is closed and the event is over.

onffmpegclose
executes the command given when an ffmpeg movie is closed at the end of an event. The name of the movie will be given as argument. Default: not set. You should give the full path name of the program/script. This can be any type of program or script. Remember to set the execution bit in the ACL and if it is a script type program such as perl or bash also remember the shebang line (e.g. #!/user/bin/perl) as the first line of the script. The command is run when an event is over. I.e. the number of seconds defined by the time gap has passed since the last detection of motion and motion closes the mpeg file

ALERT! Security Warning! Note that this feature also means you have to pay attention to the following.
  • Anyone with access to the remote control port (xmlrpc) can execute any command on your computer with the same priviledges as the user running Motion. You do not protect anything by protecting the motion-control program. Anyone can compile and run their own copy of motion-control and access your control port if you have not either limited access to localhost or limited access using firewalls in the server. You should always have a router between a machine running Motion with remote control enabled and the Internet and make sure the Motion control port is not accessible from the outside.
  • If you limit control port to localhost you still need to take care of any user logging into the server with any kind of terminal session or any kind of access to alter PHP programs and CGI scripts. It is easy to write a PHP script or perl script that sends XMLRPC commands.
  • It is a good idea to run Motion as a harmless user. Not as root!!

Using Databases

Motion can be compiled with both MySQL and PostgreSQL database support. When enabled Motion adds a record to a table in the database with fields for filename and time. it also write a field called type. Motion does not place any binary images in the database and it cannot remove old records.

Motion only adds records to the database when files are created. The database contains records of saved files which means to get a record in the database the feature that enables for example motion detection, timelapse, snapshots etc must be enabled. The sql_log options defines which types of files are logged in the database.

The following sql_log options are common to both MySQL and PostgreSQL.

############################################################
# Common Options For MySQL and PostgreSQL database features.
# Options require the MySQL/PostgreSQL options to be active also.
############################################################

#Log to the database when creating motion triggered image file  (default: on)
sql_log_image on

#Log to the database when creating a snapshot image file (default: on)
sql_log_snapshot on

#Log to the database when creating motion triggered mpeg file (default: off)
sql_log_mpeg on

#Log to the database when creating timelapse mpeg file (default: off)
sql_log_timelapse on

See the "MySQL" section for detailed information about the database itself.

MySQL

You can use the MySQL database to register each file that is stored by motion.

You need to generate a new database with a name of your own choice. You must enter this name in the config file (mysql_db option). Select the new database in MySQL and create a new table "security" with the following fields:

  • camera (int) - camera (thread) number
  • filename (char60) - filename (full path)
  • frame (int) - the number of the picture frame
  • file_type (int) - file type as a number - see table below..
  • text_left (char30) - The text from the text_left option
  • time_stamp (timestamp) - timestamp for the picture in native database format

Note from version 3.1.15 the fields have changed a lot. The fields 'camera', 'frame', 'time_stamp' and 'text_left' were added in version 3.1.15. 'type' was renamed to 'file_type' and the fields 'second', 'minute', 'hour', 'day', 'month', and 'year' have been removed (replaced by the much smarter 'time_stamp' field which allows much better queries using native SQL time functions).

These are the file type descriptions and the file type numbers stored in the database.

Normal image 1
Snapshot image 2
Motion image (showing only pixels defined as motion) 4
Normal mpeg image 8
Motion mpeg (showing only pixels defined as motion) 16
Timelapse mpeg 32

You can create the table using the following SQL statement.

CREATE TABLE security (camera int, filename char(60) not null, frame int, file_type int, text_left char(30), time_stamp timestamp(14));

Remember to update grant table to give access to the mysql username you choose for motion.

It would be too much to go into detail about how to setup and use MySQL. After all this is a guide about Motion. However here are some hints and links.

Setting Up a MySQL Based Website - A beginners guide from Linux Planet.

Webmonkey PHP/!MySQL tutorial - Entertaining and easy to read.

The phpMyAdmin homepage. The best and simplest tool to use MySQL (editors opinion). Requires Apache/PHP.

PostgreSQL

Same/similar as for MySQL above.

Video4Linux Loopback Device

Note: Currently the versions of the Video4Linux Loopback Device will not work on kernel 2.6.X. If you create a version that runs on 2.6.X please send it to Kenneth Lavrsen so we can put it on the Motion website.

You can use this driver for looking at motion in realtime. The video4linux driver is written by the same author as Motion. You can find the source and a brief description at the video4linux loopback device web page.

The video4linux device is a Kernel module which installs itself as a video pipe. It has an input and an output. The module simply takes anything that comes on its input and send it out at the output. The purpose of this is to create a standard video4linux type video device that other programs can then use. You may now ask: "What do I need that for?".

Only one program can access a video device at a time. When motion is using a camera - no other program can access the same camera. But motion is made to be able to feed a video signal to the video loopback device. This way an additional program such as Camstream, Xawtv, a video stream server etc can watch the signal from a camera that motion uses already. What you see is not the live camera stream but the exact same picture that motion uses for detecting motion and the same pictures that are saved/streamed. You can also choose to see the "motion" type images where you see the pixels that are changing - live. Originally the video4linux pipe was used as an interface between Motion and a Webcam server. Since version 2.9 Motion has had its own webserver so this usage is no longer very relevant.

When you install the video loopback device it will create an input - for example /dev/video5 and an output - for example /dev/video6. You can then tell motion to "pipe" the video signal to the /dev/video5 and look at the pictures live using e.g. Camstream on /dev/video6. Camstream is "fooled" to think it is looking at a real camera.

Installing

Installing the video loopback device is not difficult. At least not when you have this document available.

First you must prepare your system for more video devices. You will need two extra devices for each video pipe that you want.

For example if you have 4 cameras they will probably run at /dev/video0, /dev/video1, /dev/video2, and /dev/video3. So you will need additional 8 video devices. This is easy to do.

mknod /dev/video4 c 81 4
mknod /dev/video5 c 81 5
mknod /dev/video6 c 81 6
mknod /dev/video7 c 81 7
mknod /dev/video8 c 81 8
mknod /dev/video9 c 81 9
mknod /dev/video10 c 81 10
mknod /dev/video11 c 81 11

Note that the video device number is the same as the last parameter given on each line.

You may need to set the ownership and permissions (chown and chmod) to be the same as the video devices that were already there.

Now you need to install the video loopback device.

Download the latest video4linux loopback device (version 0.91 at the time of this document - distributed as tar'ed and compressed files). Place the file in a place of your own choice.

Untar and uncompress the file to the place you want the program installed. Editor recommends /usr/local/vloopback.

cd /usr/local

tar -xvzf /path/to/vloopback-0.91.tar.gz

You now have a directory called vloopback-0.91. You can rename it to vloopback (mv vloopback-0.91 vloopback). I recommend creating a symbolic link to the current version. This way you can more easily experiment with different versions simply by changing the link.

ln -s vloopback-0.91 vloopback

Now change to the new directory

cd vloopback

Build the code

make

There is a good chance that the make will not work and give you a long list of errors. To run make the following must be available on you machine.
  • The kernel source files must be installed.
  • The source files must be available at /usr/src/linux.
    E.g. the new Red Hat 7.3 does not have a link to the sources called linux. Instead there is a link called linux-2.4. This is easy to fix. Just create a link to the real source tree. Do not rename! Add a link using this command (replacing the kernel version number with the one you have on your machine)
    ln -s /usr/src/linux-2.4.18-4 /usr/src/linux
  • Alternatively you can change the vloopback makefile so that the "LINUXSRC=/usr/src/linux" line is changed to the actual path. I recommend the link solution since this may solve other similar problems that you can get when installing other software.

When compiling on a newer Linux distribution you may get a warning about a header file malloc.h. To remove this warning simply change the header reference as suggested by the warning.

In vloopback.c you replace the line

#include <linux/malloc.h>

with the line

#include <linux/slab.h>

Install the code you built as a Kernel module. There are two options: pipes should be set to the number of video loopbacks that you want. Probably one for each camera. The dev_offset defines which video device number will be the first. If dev_offset is not defined the vloopback module will install itself from the first available video device. If you want the cameras to be assigned to the lower video device numbers you must either load vloopback after loading the video device modules OR use the dev_offset option when loading vloopback. Vloopback then installs itself in the sequence input 0, output 0, input 1, output 1, input 2, output 2 etc. Here is shown the command for our example of 4 cameras and 4 loopback devices and the first loopback device offset to /dev/video4.

/sbin/insmod /usr/local/vloopback/vloopback.o pipes=4 dev_offset=4

When you run the command you may get a warning about tainting the Kernel. Just ignore this. You can choose to copy the vloopback.o file into a directory in the /lib/modules tree where the insmod/modprobe programs are already looking for modules. Then the command gets simpler (/sbin/insmod vloopback pipes=.....).

If you want the loopback device to load during boot, you can place the call in one of the bootup scripts such as /etc/rc.d/rc.local. Vloopback should be loaded before you start motion.

To activate the vloopback device in motion set the 'video_pipe' option in the motion.conf file. You can also view the special motion pictures where you see the changed pixels by setting the option 'motion_video_pipe' in motion.conf. When setting the video_pipe and/or motion_video_pipe options either specify the input device as e.g. /dev/video4. You can also set the parameter to '-' which means that motion will find the first vacant video loopback device input. If you have more than one camera you may want to control which loopback device each thread uses. Then you need to define the specific device name in motion.conf for the first camera and in each thread config file for the other cameras. If you set the video_pipe parameter to '-' in the motion.conf file and not setting it in the thread config files, motion automatically assign video devices in the same sequence as the threads are loaded. You can combine both video_pipe and motion_video_pipe but then naturally you will need twice as many pipes.

De-activating should be done with this command

/sbin/modprobe -r vloopback

Error Logging

Error logging has been implemented so that errors during daemon (background) mode are logged in the syslog.

The syslog is in most Linux systems the file /var/log/messages (e.g. RedHat/Fedora) or /var/log/syslog and /var/log/user.log (e.g. Debian).

-- KennethLavrsen - 03 Apr 2005
Topic revision: r3 - 26 Nov 2013, AmriAm
 
Motion - Motion Guide 3x 1x 20
Copyright 1999-2014 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Please do not email Kenneth for support questions (read why). Use the Support Requests page or join the Mailing List.
This website only use harmless session cookies. See Cookie Policy for details. By using this website you accept the use of these cookies.