Running Motion

Important Definitions

Motion is invoked from the command line. It has no GUI. Everything is controlled from config files. From version 3.2 the command line is only used to define location of config file and a few special runtime modes (setup and non-daemon).

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. Motion is shown in greytones. If labelling is enabled the largest area is marked as blue. Smart mask is shown in red.
• A "normal" image is the real image taken by the camera with text overlayed.

The Config Files

If Motion was invoked with command line option -c pathname Motion will expect the config file to be as specified. When you specify the config file on the command line with -c you can call it anything.

If you do not specify -c or the filename you give Motion does not exist, Motion 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 file 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 thread 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.

It is often seen that people copy the entire motion.conf into the thread config files and change a few options. This works but it not recommended because it is more difficult to maintain and overview. Keep all the common options in motion.conf and the few unique only in the thread config files

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.

To make it clear, the thread files format and syntax is the same as motion.conf. An example of what you might want in a thread file as follows: assume you have two cameras, attached to one system. Create files thread0.conf and thread1.conf. At the end of motion.conf, uncomment out the lines that refer to them. The full contents of the thread files can be as simple as

thread0.conf:
videodevice /dev/video0
stream_port 8081

thread1.conf:
videodevice /dev/video1
stream_port 8082

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.

Nearly all config options can be unique for a specific camera and placed in a thread config file. There are a few options that must be in motion.conf and cannot be in a thread config file: control_authentication, control_html_output, control_localhost, control_port, daemon, and thread.

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 http control command http://host:port/0/config/writeyes, 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.