A user guide written by a newbie user.
Editor: Kenneth Lavrsen
Original
URL for this document. http://www.lavrsen.dk/sources/webcam/motion_guide.htm
Version:
1.27 (for motion 3.0.5 and 3.1.5), 2003 Jan 12, 16:27
From version 3.0.1 of motion this
guide is now part of the distribution. The jpg files however are not included.
Go to the URL above if you want to see the guide with pictures.
1.5 Added a detailed
description about using the video4linux loopback device with Motion.
1.6
Corrected some details about module loading order in the video loopback section
that was added in 1.5.
1.7 Added fix for filename bug in the mpeg_encode
feature. Added note that ffmpeg sources are currently no longer available at
the ffmpeg site.
1.8 Added a reference to the URL of the original document
in case someone gets a copy in a package or paper copy and wants to see the
latest online.
1.9 Updated for rev 3.0.1. Removed the bugfixes that are now
all fixed in 3.0.1. Added a section describing the new make file options.
1.10
Added method for downloading ffmpeg from the CVS
1.11 Corrected the feature
description of ffmpeg.
1.12 Added a fix for using ffmpeg version 0.4.5. Also
added a link to locations of the ffmpeg-0.4.5.tar.gz file (no guarantee that
it will always be valid). Updated version of motion to 3.0.2. This version does
not yet cover the experimental 3.1.0 version.
1.13 Added even more ffmpeg
0.4.5 download URLs. One of them must work.
1.14 Added note about ffmpeg
and processor type in the ffmpeg section.
1.15 Updated to version 3.0.3.
ffmpeg now fixed. Added the new 3 usertext options and a section to describe
these.
1.16 Updated so that examples shows 3.0.3.
1.17 Clarified that
the timelaps function of ffmpeg generated mpegs is fixed to one shot per minute.
1.18
Updated to version 3.0.4. No changes in this guide except the version.
1.19
Added the new options for experimental version 3.1.2. Added new section with
sub-sections at the end of the document describing the 3.1.2 experimental version.
1.20
Minor cosmetics and removal of two dead ffmpeg links.
1.21 Updated for version
3.1.3.. The following options descriptions were added or improved: debug_parameter,
ffmpeg_cap_motion, ffmpeg_timelaps, mpeg_encode, netcam_url, netcam_userpass,
onmpeg, realconfig (removed), thread, track_speed, track_stepsize, -U, -A (removed).
The following special sections have been improved: ffmpeg, mask file, webcam
server, and experimental version 3.1.2 has become 3.1.3 with many changes and
important bug fix notes. Options in tables have been better alphabetized. Misc
typos corrected.
1.22 Minor clarification of the install commands (/path/to)
based on user feedback.
1.23 Added information in the config file options
section about parameters that are not allowed in the config file without having
the matching software installed (cURL, MySQL, PostgreSQL and ffmpeg).
1.24
Updated the guide for versions 3.0.5 (no changes) and 3.1.4 (less errors to
correct when installing - also NEW errors). ffmpeg section updated.
1.25.
Modified ffmpeg section to only refer to the latest cvs version (which now works
great with Motion). Changed the yes|no to on|off for all boolean type config
parameters to match the autogerated motion.conf files that motion 3.1.4 can
create using xml-rpc commands. Yes|no are still valid values. So are 1 and 0.
Corrected some errors in the drawtext parameter description.
1.26. Updated
for motion 3.1.5. Workarounds and code tweaking is no longer needed to install
3.1.5. xml-rpc section for 3.1.5 is improved. New 'motion-control action quit'
command added. Commands are now placed in a nice table.
1.27 Corrected mistake
in the mask file section (missing important '-' in djpeg command line)
1.28
Clarified the licensing description so that it is clear that Motion is a Generel
Public License project.
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:
Motion is an open source type of project. It does not cost anything. Motion is published under the GNU GENEREL 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 dutys 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 subjust available the of the Free Software Foundation pages about the Philosophy of the GNU Project.
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.
The latest stable versions is 3.0.5.
There is an experimental version
3.1.5 which is actually quite stabil also but with some new features that are
not fully refined.
See more description at the Motion Homepage.
You can find more information and links at the Motion Homepage.
Motion is distributed as source files that you must compile yourself. There
are an old RPM file but it is completely out of date.
I recommend compiling.
It is not very difficult.
You may run into some small problems when compiling
with either MySQL or PostgreSQL support. No worries. See the speciel sections
about the two later in this document.
For the experimental versions 3.1.5... read the speciel section about that at the end of this document as a supplement to this.
The short story is:
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. The configure script used is based on another configure scripts and contains some not very interesting switches.
|
Option |
Description |
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 |
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-version |
|
--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. |
|
--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.
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-libavcodec=DIR |
Specify the path for libavcodec (part of ffmpeg) |
DIR is the location of the libavcodec directory
in the FFmpeg package. |
|
--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 |
|
--without-mysql |
Do not compile with MySQL support |
Use this if you do not want to include MySQL support
in the package. |
|
--with-pgsql=DIR |
Include PostgreSQL support. DIR is the PostgreSQL
base install directory, defaults to /usr/local/pgsql. |
Default is that make searches in the normal installation
directories of most distributions. |
|
--without-pgsql |
Do not compile with PostgresSQL support |
Use this if you do not want to include PostgresSQL
support in the package. |
|
Environment values. |
||
|
CC |
C compiler command |
Normally you should not have to worry about any of these. |
|
CFLAGS |
C compiler flags |
|
|
LDFLAGS |
linker flags, e.g. -L<lib dir> if you have libraries in a nonstandard directory <lib dir> |
|
|
CPPFLAGS |
C/C++ preprocessor flags, e.g. -I<include dir> if you have headers in a nonstandard directory <include dir> |
|
|
CPP |
C preprocessor |
|
Not much to say about this. 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.
If you have run make before, you should run a "make clean" before
running make again. This cleans out all the output files that were generated
the previous time you ran make. On other words:
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" simply copies all the nice files that were generated
during the compilation/linking that make did.
In version 3.0.5 the following
is done by make install.
Makes the directories (if they do not already exist): /usr/local/bin, usr/local/man/man1, /usr/local/etc, /usr/local/doc/motion-3.0.5, /usr/local/doc/motion-3.0.5, and /usr/local/examples/motion-3.0.5.
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)
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"
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.
The make command can be run with severel 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.
make distclean
deletes the files: config.status, config.log, config.cache, Makefile, and motion.spec.
make
updateguide fetches a frech 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.
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.
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 a camera with a built in web server that can be connected directory to you network.
Motion is invoked from the command line. It has no GUI.
A few important definitions.
SYNOPSIS
motion [ -BCDhlmNpQw] [ -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. |
|
-B |
Encode all jpg images to mpeg after a event using mpeg_encode |
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 make motion (using mpeg_encode) to merge the individual jpg images into a small mpeg "film" showing the event. |
|
-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! |
|
-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. |
|
-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. |
|
-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. |
|
-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. |
|
-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. Valid range: depends on video capture card, default: not set |
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 can ignore this. |
|
-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 |
Don't output normal images |
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. This option turns the feature OFF. |
|
-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 |
|
-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 se 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|IP_addr |
Webcam path |
URL for a net camera. |
|
-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 |
Activate light switch filter. With this option on motion will not classify sudden light differences as a motion (not 100% fail proof!) |
Default (switch not set) is off. |
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 may only be used if Motion is built on a system that has the matching software installed (cURL, MySQL, PostgreSQL and FFMPEG). If you do not have this software installed you should not have the matching parameters in the config file. Either remove the config option or comment it out with a leading "#".
These are the software packages and the matching config options to watch out for.
cURL (libcurl)
netcam_url, netcam_userpass
MySQL
mysql_db, mysql_host, mysql_user, mysql_password
PostgreSQL
pgsql_db, pgsql_host, pgsql_user, pgsql_password, pgsql_port
FFMPEG
ffmpeg_cap_new, ffmpeg_cap_motion, ffmpeg_timelaps, ffmpeg_bps
|
Option |
Description |
Editors comment |
|
adjust_rate on|off |
Try to make the frame rate of the created mpegs as normal as possible. Normal means round 25 frames per second. Allowed values: on, off. Default: off |
Adjust the number of frames for an mpeg movie to get almost 25 frames per second. |
|
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! |
|
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. |
|
daemon on|off |
Start motion in daemon mode and release terminal. Default: off |
(Important! In version 2.6.3 and earlier this
option was misspelled deamon). Wonder about the word and its spelling.
Look here! |
|
drawtext_changes on|off |
Turns the changed pixels osd on/off. Default: off |
By setting this option to 'on' the number of pixels that changed compared to the reference frame is displayed over the date/time stamp in the lower right of the pictures. This is good for calibration and test. Maybe not so interesting for a greater public. Set it to your personal taste. |
|
drawtext_shots on|off |
Turns the last two digits (counting each individual frame) after the timestamp osd on/off. Default: off |
Setting the option 'drawtext_shots' to on adds the frame number as '- two digits' after the time stamp. If you save pictures faster than once per second or you generate mpegs with ffmpeg - it can be quite nice to identify each picture frame by a unique time stamp. Set it to your personal taste |
|
drawtext_user TEXT |
User defined text overlayed on each frame. Use A-Z, 0-9 - : and '_' as space. 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 - UPPERCASE letters only, the digits 0-9 and the characters "-" and ":". Use the underscore "_" as a space. |
|
execute command |
External command to be executed when detecting motion. Default: none |
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_cap_new on|off |
Use ffmpegs libavcodec to encode mpeg movies in
realtime. Default =
off. |
To use this feature you need to install the FFmpeg
Streaming Multimedia System |
|
ffmpeg_cap_motion on|off |
Use ffmpegs libavcodec to encode motion type mpeg movies in
realtime. Default =
off. |
To use this feature you need to install the FFmpeg
Streaming Multimedia System |
|
ffmpeg_timelaps on|off |
Use ffmpegs libavcodec to encode a timelaps movie.
Default = off. |
The ffmpeg_timelaps function takes pictures at a fixed rate of one per minute. This cannot be configured. To use this feature you need to install the FFmpeg Streaming Multimedia System. See ffmpeg section later in this document. NOTE: In version 3.1.3 and forward this parameter
is changed from a boolean (on/off) to an integer value that defines
the timelap interval in seconds. Setting it to 0 disables it. |
|
ffmpeg_bps bps |
Bitrate of mpegs produced by ffmpeg. Default:
400000 (400Kbps). |
Experiment to get the desired quality. The better
quality the bigger files. See ffmpeg section later in this document. |
|
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. |
|
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. |
|
input number |
Select the input of the video device. 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. |
|
jpg_cleanup on|off |
Remove all jpeg images after making a mpeg movie of them. Default: off |
When this option is set to on jpg images will be deleted after creation of an mpeg movie. If you want to see the individual jpg images you should choose off. Otherwise set it to on and keep your disk space more under control. |
|
lightswitch on|off |
Activate light switch filter. With this option on motion will not classify sudden light differences as a motion (not 100% fail proof!). Default: off |
Editors recommendation. Experiment to see what works best for your application. |
|
locate on|off |
Locate and draw a box around the moving object. Default: on |
|
|
low_cpu on|off |
When this option is enabled motion will grab only one frame per second while not detecting motion. Default: off |
This is smart for running a server that also does other tasks such as running Apache, MySQL etc. Motion grabs one frame per seconds 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: none |
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 set. |
Full path of the PGM (portable gray map) mask
file (binary format). |
|
max_mpeg_time seconds |
The maximum length of an mpeg movie. Default: 3600 seconds (one hour). Set this to zero for unlimited length. |
|
|
mpeg_encode on|off |
Use the Berkeley mpeg encoder 'mpeg_encode' to make movies of the events Default: off |
For more information here is a link to the Berkeley
mpeg encoder. |
|
mpeg_encode_bin path |
Specify the path to the mpeg_encoder. Default is /usr/local/bin/mpeg_encode |
This option is not included in the default motion.conf file. It specifies the path to the Berkely mpeg_encode executable binary file. The default value is /usr/local/bin/mpeg_encode. This is normally where the encoder gets installed if you build from source. But if you install a binary RPM the encoder will most likely end up in /usr/bin/mpeg_encode. In this case set this option. |
|
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. |
|
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.
(Please confirm). 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. |
|
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. |
Example of URL: http://www.gate.com/pe1rxq/jeroen.jpg. |
|
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 |
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 to 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: on |
Editors recommends to experiment for best result as this depends heavily on the camera and light conditions. |
|
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. |
|
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. |
|
oldlayout on|off |
If this option is set to on motion will use
the old style filenames for saving images: 'No-YYYYMMDDHHMMSS-Fm'
No is the event number, Fm the frame number for that second. As
default motion will create directories for years, months, days and
so on. |
Editors notes. If you do not choose this option motion will generate a deep directory structure of year/month/day/hour/minute. This is nice for a simple web interface but it becomes a little more complicated to write an automatic script that keeps the last 100 pictures available and deletes the rest. If you want to delete any picture older than 2 days this is easier with the new layout. Choose the one that fits your need best. |
|
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. |
|
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. |
|
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 have an "m" at the end of the
filename. E.g. for the old directory layout the name can be 01-20020424232936-00m.jpg. |
|
output_normal on|off |
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. |
|
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. |
|
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 |
|
|
realmotion on|off |
With this option set to on motion images will contain the actual difference in the frames. Normally these pictures will show the moving parts of the newest frame. Default: off |
This is another useful tuning option. This option
only works in combination with the "output_motion" option. |
|
roundrobing_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 |
Roundrobing feature is described in a section later in this document. |
|
roundrobing_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 |
Roundrobing feature is described in a section later in this document |
|
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 se the sms_client home page. |
|
snapshots seconds |
Make automated snapshots every N seconds. Valid range: 0 to thousands, default: 0 (No snapshots) |
The snapshots are stored in the target directory with the "-snapshot" appended to the body of the filename. E.g for the oldlayout the filename can be 01-20020425003030-snapshot.jpg |
|
snapshot_overwrite on|off |
All snapshots are named 'lastsnap.[jpg|ppm]' instead of time coded names. Thus every new snapshot overwrites any existing ones. Default: off |
Note that the default motion.conf file says that the filename is snapshot.[jpg/ppm]. This is wrong. The filename is lastsnap.[jpg/ppm] when using 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 roundrobing_skip to 1 without generating much false detection. Default: 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. Use an absolute directory path (not relative) if you want to use mpeg_encode. |
|
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.
From version 2.9.x this replaces the realconfig option. Important note for version 3.1.5. The way the threads and thread files are made have changed to a more logical configuration. See the section about 3.1.5 below. |
|
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. |
|
videodevice device_name |
The videodevice to be used for capturing. Default: /dev/video0 |
This is the video4linux device name. |
|
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. |
|
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 only send images with motion over the webcam connection, else send 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. |
|
MySQL CONFIG FILE OPTIONS |
||
|
mysql_db |
|
Name of the MySQL database |
|
mysql_host |
|
IP address or domain name for the MySQL server. Use "localhost" if motion and MySQL runs on the same server. |
|
mysql_user |
|
The MySQL user name. |
|
mysql_password |
|
The MySQL password. |
|
PostgreSQL CONFIG FILE OPTIONS |
||
|
pgsql_db |
|
Name of the PostgresSQL database |
|
pgsql_host |
|
IP address or domain name for the PostgresSQL server. Use "localhost" if motion and PostgresSQL runs on the same server. |
|
pgsql_user |
|
The PostgresSQL user name |
|
pgsql_password |
|
The PostgresSQL password |
|
pgsql_port |
Default is 5432 |
The PostgresSQL server port number |
|
TRACKING CONFIG FILE OPTIONS |
||
|
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: -1 (Use the stepper motor interface) |
|
|
track_maxx |
The maximum position for servo x. |
|
|
track_motorx |
The motor number that is used for controlling the x-axis. |
|
|
track_port |
This is the serial port to which the stepper motor interface is connected. |
|
|
track_speed |
Speed to set the motor to |
|
|
track_stepsize |
Number of steps to make |
|
|
NEW OPTIONS FOR EXPERIMENTAL VERSION 3.1.5 |
||
|
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 priviledges. Port 8080 is a fine choice of port to use for the purpose. |
|
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. |
|
ffmpeg_timelaps seconds |
Use ffmpegs libavcodec to encode a timelaps movie. saving a picture frame at the interval in seconds set by this parameter. Default = not defined. Set it to 0 if not used. |
This parameter is already defined earlier in this table but repeated here because the parameter is redefined from boolean to an interger adding the feature of a user defined interval in seconds. |
|
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. |
|
predict_description filename.desc |
Load prediction description file. This option can be repeated for each additional files that needs to be loaded. |
When the predict_enable feature is enabled, Motion saves a file ending with .desc in the target directory. These files can merged into prediction description files that contains a number of detected motions put into number codes. Using the predict_description option a multiple number of times Motion will load in these description files and will now be able report the name of the prediction motion to the console. The idea is that later features will be added that can take specific actions when it recognise speciel motion patterns. This feature is still very new and very experimental. Consider it fun and games for now. Report any interesting experience on the Motion mailing list. |
|
predict_enable on|off |
Enable the new experimental prediction feature. Default: off. |
The prediction feature is very new and very experimental. It is a way for Motion to recognise motions patterns stored in prediction files and take actions accordingly. At the moment all Motion can do is report recognition as a "Best Guess: Prediction_name value" on the console. Ie. it cannot do anything in Daemon mode. |
|
predict_threshold value |
Set threshold for reporting motion as predicted on the console. Default: 90 |
This parameter is only used to decide when to report a "Best guess" on the console. |
|
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. |
|
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. |
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. (If you use a version of motion 2.6.3 or earlier, you
must kill each individual process and start motion again).
Motion responds to the following signals:
|
Signal |
Description |
Editors comment |
|
SIGALRM |
Motion will generate a snapshot. |
|
|
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. |
|
To use this feature you need to install the Berkeley
mpeg_encode program.
The program is pretty old (1995) and there has been
some problems with compiling the source code. There is a guy doing an exciting
project called AMIDE.
This project includes the mpeg_encode program and it seems that the author of
AMIDE has polished the old mpeg_encode a little bit calling it 1.5b.2. The author
has placed 2 versions. A binary only RPM for the Intel 386 platform and two
RPMs with full source. I installed just the binary RPM from the AMIDE site and
it worked fine. The binary RPM contains only two files: mpeg_encode itself which
it installs in /usr/bin and a manual page. Motion looks for the mpeg_encode
in the directory /usr/local/bin. So either move the binary to this place, or
place a link to it OR use the "secret" config file option mpeg_encode_bin.
Ie. to enable the feature you need the following entries in the motion.conf
file.
# Use the Berkeley mpeg encoder 'mpeg_encode'
# Default: off
mpeg_encode
on
mpeg_encode_bin /usr/bin/mpeg_encode
The last line is not included in the default config file. The default value is '/usr/local/bin/mpeg_encode' so if this is where your mpeg_encode is, you do not need to add it to your config file.
Important! Your target_dir option should be an absolute path (starting with /) when using mpeg_encode.
The feature itself works like this:
Everytime motion detects motion a jpg picture is stored. This happens at the framerate you have specified with the 'framerate' option (or at the interval set by the 'minimum_gap' option if different from zero). When the event is over (time defined by the 'gap' option) motion generates a small mpg film using mpeg_encode. This is important to notice when you test the feature the first time. You will have to wait the period defined by 'gap' before you see the mpg file on your disk. If you have used a small framerate or used the minimum_gap option the film is going to be over in a split second. For this feature to be useful you should let motion store pictures almost real time. To generate better films you can play with options like 'post_capture' which will take extra picture after a motion is detected to create better floating films and 'adjust_rate' which will try to generate a 25 fps film. To avoid your harddisk from getting full because a bird is hopping around on the lawn, there are two parameters you can use. 'jpg_cleanup' will delete all the jpg files once the mpeg has been generated. 'max_mpeg_time' limits the duration of an mpeg film to the number of seconds you specify.
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. With
the Berkeley mpeg_encode feature the film is generated based on the saved jpg
pictures. With ffmpeg the film is generated directly by motion. Note that when you build motion with ffmpeg
(configure using --with-libavcodec=DIR) DIR must be the path to the directory
containing libavcodec.a. If you install ffmpeg in /usr/local/ffmpeg then the
directory is /usr/local/ffmpeg/libavcodec.
Some people on the Motion maling
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.
The ffmpeg_cap_new option 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.
The ffmpeg_cap_motion works like ffmpeg_cap_new but outputs motion pictures instead.
The
ffmpeg_timelaps generates a picture at a constant framerate of 1 frame
per minute. Gives
your viewer the chance to watch the day pass by. Nice effect to film flowers
etc closeup during the day. Note that this rate cannot be configured. Options
like frame_rate, snapshot, gap etc has no impact on the ffmpeg timelaps function.
NOTE:
In version 3.1.3 and forward this parameter is changed from a boolean (on/off)
to an integer value that defines the timelap interval in seconds. Setting it
to 0 disables it.
There is an option ffmpeg_bps. This 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.
If you want to use this feature you can read about the FFmpeg Streaming Multimedia System
Since Motion versions 4.0.5 and 4.1.4, Motion now works with the current CVS version of ffmpeg (0.4.6 alpha versions) which is the only version available at the ffmpeg website. Earlier you had to use an older version 0.4.5 of ffmpeg together with Motion but this is no longer the case.
The latest CVS version of ffmpeg should now work with Motion.
The
latest CVS build is now easy to download and install.
From the ffmpeg homepage you find a link called Current CVS snapshot: ffmpeg-cvs.tar.gz.
Just 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
./configure
make
make install
This creates the libavcodec library under /usr/local/ffmpeg/libavcodec and this is really all we need for Motion.
In versions up to 2.6.3 the mask file must be in the ppm format (portable
pixel map). Note that you must choose the BINARY format.
From version 2.9.9 the feature is changed
to use a pgm format mask 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.
Mask file (converted to png format so it can be shown by your web browser)
You can use the MySQL database to register each file that is stored by motion. What is stored is the
filename (full path), and the time.
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:
You can create the table using the following SQL statement.
CREATE TABLE security (filename char(60) not null, minute int, hour int, day int, month int, year int, type int);
Remember to update grant table to give access to the mysql username you choose
for motion.
Note that motion does not store the seconds so you have have
many files saved with the same time stamp. To get the exact time you will need
to extract that from the file name.
If you are having trouble when installing motion with MySQL support you may have the same problem as the editor of this document had on his first Linux machine.
Versions from 2.9.9 works with no problems when mysql installed as a Red Hat RPM where
mysql is installed in the standard directories
Data files in /var/lib/mysql
Binary
program files in /usr/bin
Libraries in /usr/lib/mysql
Daemon in /usr/sbin
Misc
shared stuff in /usr/share/mysql
Headers in /usr/include/mysql
Manual
pages in /usr/man/man1
When installing the generic binary from www.mysql.com the directory structure
is different.
MySQL recommends not compiling MySQL with gcc version 2.96.
And this is what Red Hat ships with. I assume that MySQL similar to Apache can
be configured to different layouts. The generic i386 binary that they have on
their site has been made with everything under one directory. This makes sense
when you download and untar one package without compiling.
The structure of mysql is then (assuming installing undet /usr/local).
Base
dir is /usr/local/mysql
Data files in /usr/local/mysql/data
Binary program
files in /usr/local/mysql/bin/
Libraries in /usr/local/mysql/lib
Daemon
in /usr/local/mysql/bin/
Misc shared stuff in /usr/local/mysql/share
Headers
in /usr/local/mysql/include
Manual pages in /usr/local/mysql/man (though
I believe the install script does copy them to a standard location)
The workaround for 3.0.5 is:
If you have an RPM based distro I would recommend using the RPM from mysql if you want to replace the mysql that came with your distribution to the latest and greatest. This way you do not have to worry about the work-around above. See also next section about PostgreSQL
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.
Same/similar as for MySQL above.
There are the same potential installation as for MySQL. The workaround is
the same.
Motion is looking for a header file called xxx/postgresql/libpq-fe.h
where xxx is the path that gcc is searching for headers. Often PostgreSQL header
files are installed either in a directory called pgsql or directly in /usr/include.
You
can either change the motion source or create a symbolic link. Editor recommends
the link method because then you do not have to think about it when you try
new versions of Motion.
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.
These are the special
webcam parameters.
The webserver generates a stream in "multipart jpeg" format. You cannot watch the stream with most browsers. Editor has tried Internet Explorer 6, Netscape 6.2 (windows) and Konquerer. 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.
Replade 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 with these config lines.
############################################################
# Webcam:
############################################################
# Supply a live stream using multipart jpegs with a mini
# http deamon.
# Default: not set
webcam_port 8081
webcam_quality 30
webcam_motion off
webcam_maxrate 4
Naturally adjust the settings to your preference. Maxrate and quality are important to limit the load on your server and link. Don't set them too high.
Motion supports capture cards with more than more input. The inputs are controlled
through the Video4Linux interface and are simply numbered. To find out which
number means what you can experiment with a program such as Camstream. Here
you can see which input has which number easily.
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.
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 roundrobing options:
-
If multiple threads use the same video device, they each can capture roundrobbing_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
round_robing_skip number of frames are skipped to allow the device to
settle.
TV tuner cards are used the same way as video capture cards except one of the inputs have one extra parameter which is the "frequency" for the TV tuner. The value is the value that the bttv driver sends to the capture card. Use a program such as Camstream or xawtv to experiment with the values.
This is still at the experimental stage. Read more about it motion tracking page.
Drawtext is a new feature added to motion version 3.0.3. It enables you to taylor the on-screen display (OSD) to your taste and to add your own user defined text.
Motion has the following on screen display.
|
USERTEXT is a user defined text defined by the 'drawtext_user' option. If
the option is not defined no text is displayed at this position.
CHANGES
is the number of pixels that changed compared to the reference frame. Good for
calibration and test. Maybe not so interesting for a greater public. The feature
can be turned on or off by setting the 'drawtext_changes' option to on or off.
YYYY-MM-DD
is the date in international date format - year four digits - month two digits
- date. This cannot be changed.
HH:MM:SS is the time - hour : minute : second.
This cannot be changed either.
FM is the frame number. If you save pictures
faster than once per second or you generate mpegs with ffmpeg - it can be quite
nice to identify each picture frame by a unique time stamp. Setting the option
'drawtext_shots' to on or off adds the frame number as '- two digits' after
the time stamp.
The 3 options 'drawtext_user', 'drawtext_changes' and 'drawtext_shots' can be entered both in the motion.conf file and in each thread.conf file. E.g. you can set the 'drawtext_changes' and 'drawtext_shots' only in motion.conf setting the format of the display the same way for all cameras and then add unique 'drawtext_user" options in each thread.conf file. This way you can display "FRONT DOOR", "BACK DOOR" and "GARAGE" on 3 different cameras.
The user defined text can be the english alphabet - UPPERCASE letters only, the digits 0-9 and the characters "-" and ":". Use the underscore "_" as a space.
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 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.
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>
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
Special tuning options
Normal picture frame
Motion type picture frame with realmotion set to 'off'
Motion type picture frame with realmotion set to 'on'
Note the dark area
in the upper left corner which is the area masked off by the mask_file option.
In version 3.1.5 there are two new options 'noise_tune' and 'threshold_tune'. See special section below on version 3.1.5.
The version 3.1 series are experimental version that are used to introduce and test new features. The 3.1 releases will not be as stable as the 3.0 series but this where the exciting new stuff is happening. This guide will try and keep up with these releases but sometimes the Author needs to learn about the new feature himself first before they can be described. The author of Motion is Jeroen and the author of this guide is Kenneth Lavrsen and I am always a bit behind.
Known problems.
None. You will get a small compiler warning about an unused
variable. Just ignore this.
The Makefile now has a new feature. The normal make and make install works as in version 3.0. There is now a new option make motion-control. This build the extra motion-control application that can control motion while it runs using the xml-rpc protocol.
To install and use motion-control and to be able to use xml-rpc you will need to install xmlrpc-c first. This is a library containing the xmlrpc functions to be used in C programs.
First, the xmlrpc stuff we need to install is located here: http://xmlrpc-c.sourceforge.net/downloading.php
Current version is 0.9.9-1. If you use a distribution using RPM like Red Hat and many other all you need is to download and installed the RPMs.
After installation of xmlrpc-c you need to re-install motion going throught all the steps configure, make and make install
Additionally you need to build the motion-control application by simply running make motion-control
And then manually copy it to your /usr/local/bin directory or where ever you want the binary executable.
Version 3.1.5 changes the concept of how thread files are read to something
new and easier to use.
In version 3.0 the main thread controlled by motion.conf
was always running the first camera.
For version 3.1.5 this has changed changed. Now
the motion.conf file is still a global settings file which defines all options
that are common to all cameras. If you only have one camera you can still just
have the motion.conf file OR you can place the camera specific options in a
thread config file. If you have more than one camera ALL cameras must now each
their own thread config file.
The motion.conf file will still contain setting
that are global to all cameras, but the minute you add 'thread' options to your
motion.conf file you will need one thread file per camera.
The Motion Guide author has only very little experience with the feature. At the moment all Motion can do is report recognition as a "Best Guess: Prediction_name value" on the console. Ie. it cannot do anything in Daemon mode. Prediction is controlled by the new 'predict_enable', predict_description' and 'predict_threshold' config file options. This is really experimental code that needs some further work. Once the prediction is working there are many funny features it can be used for where motion can take actions/run scripts/save pictures depending on the kind of motion detected.
These are Jeroen own words for the feature.
prediction is a little experiment I have been doing over the past days...
Using
'description files' that describe a movement. Motion tries to predict what it
was that triggered it. At the moment motion can distinguish between me sitting
at the computer, me walking out of the room and me walking into the room.
A
description is outputted for each event (.desc files). Motion will load files
mentioned with 'predict_description' in the config file. These files have three
lines: a line with the title, a line with the minimum values and a line with
the maximum values. The current version is very rude..... try it, but don't
expect to much
HOWTO make a description file:
The combine program that Jeroen talks about is included in the Motion 3.1.5 distribution both as a Intel-386 binary and as source. To build this little application from source simply run this command.
gcc -o combine combine.c
This creates the combine binary in the Motion directory.
Motion version 3.1.5 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 be built and which can be used to control all the new control features of Motion. The installation of xml-rpc and the motion-control program is described above in the 'Installation of version 3.1.5 section'.
The motion-control program is easy to use. Run it without any parameters and it displays the help.
The command 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 from jpegs using the mpeg_encode tool 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. |
The 'conf set [threadnr] [parameter] [value]' feature is very smart for trying tuning setting and for changing the user defined on screen display.
In motion.conf there is now a new option called 'control_localhost'. By setting this to "on" or "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.
Version 3.1.3 introduces two new features. Automatic threshold tuning and
automatic noise tuning. These can be activated or deactivated by the config
file options 'threshold_tune' and 'noise_tune'.
Both algorithms are new and
may not yet be optimal. Try them and if they do not work, use the good old manual
setting. We on the Motion mailing list are always interested in hearing your
experience and especially any improvement you may have made to the source.
A new option called 'webcam_localhost' has been introduced in 3.1.3. This 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.