The Master Example Motion Config File

The config file requirements

• Format is plain text. Options are loaded with "option value". One option per line.
  • Leading and trailing whitespace on any line is ignored.
  • White space between option name and value can be spaces and or tabs in any number
  • Text type option values can be placed in " " or ' ' marks to allow leading and trailing spaces to be accepted.
  • Options may not span more that one line.
• The config file will have a global section labelled [global] with all the possible options including all the default plugins that ship with Motion. All have comments like we know them today.
  • Camera sections will not be called thread anymore. They will be called camera. [camera name 1], [camera name 2] etc. Spaces are allowed in the value after camera. This name will be assigned to the conversion specifier %c.
  • Camera sections are by default in the motion.conf file. If we make the include option people can have them in seperate files like today.
• Comment lines are any line where the first non white space character is either # or ;
• Help comments have # and options that are default off are commented out with ;
• Options in camera sections will not have comments.
• Blank lines are allowed and ignored. They are used in both the default config file and when saving a config file. They are typically used to separate sections and enhance overview and readability.
• Motion must still be able to save a config file.
  • Saving config files saves all options in the global section in a predictable way, with options nicely grouped with group help text like today
  • Saving config files will preserve options within camera sections intact, even if the value is the same as the common/global value (unlike today)
  • Include files??? Will they be merged into the motion.conf or remain as they are.
  • User added comments disappear when you load and save. I cannot see how we can clean up a config file when saving, while at the same time preserving user comments.
  • Motion only saves config files when the user initiates it from http control.
  • Saving a config file adds options that were not in the original config file and with default values (disabled with ';' if this is the default).
• Nesting sections looks too complicated and it is not needed. The code should be able to do well without. Plugins do not need sections.
• Prefix syntax is the most user friendly way of having plugin unique options.
• Options are always lowercase and underscore is used for prefixing and separating words. This rule is to prevent people from misspelling options because they mix up upper and lower case, or using a wrong separator there are a mix of dashes, dots, underscores etc. It it easier to get the option right when you know options are always lowercase with underscores.
• Common core options can exist that will only be used in plugins. An example is movie_filename which is defined in the core code but not used within the core code. It is, however, used by movie_plugins like ffmpeg and xvid.
• Plugins will have access to all options, including options from the global scope. Plugins ADD additional options. Prefix syntax is a naming convention only. The core and plugin code will not contain special code that enforces the prefixes. It is a naming convention that has two purposes. 1. it prevents name clashes, and 2. it helps users know what belongs to what.
• There is a wish for an include option that includes a config file and that is probably a good idea. This can also be used to activate and deactivate a camera with one simple character. But if we do we need to agree how motion saves the config files then and how Motion saves the included files.

Default Config File

# /usr/local/etc/motion.conf 
#
# This config file was generated by motion 4.X

[global]

############################################################
# Daemon
############################################################

# Start in daemon (background) mode and release terminal (default: off)
daemon on

############################################################
# Basic Setup Mode
############################################################

# Start in Setup-Mode, daemon disabled. (default: off)
setup_mode off

############################################################
# Load Plugins
# Load plugins that are to be used in Motion
############################################################
plugin v4l    /usr/local/motion/plugin/v4l.so
plugin netcam /usr/local/motion/plugin/netcam.so
plugin ffmpeg /usr/local/motion/plugin/motion-ffmpeg.so

############################################################
# Default Plugins
# Plugins used if not specified in camera section
############################################################
input_plugin v4l
movie_plugin ffmpeg

############################################################
# Generic Input Options
############################################################

# 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

###########################################################
# V4L Plugin Options
# These options are used only if the v4l plugin is used
############################################################

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

# The video input to be used (default: 8)
# Should normally be set to 1 for video/TV cards, and 8 for USB cameras
v4l_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)
v4l_norm 0

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

# Let motion regulate the brightness of a video device (default: off).
# The auto_brightness feature uses the brightness option as its target value.
# If brightness is zero auto_brightness will adjust to average brightness value 128.
# Only recommended for cameras without auto brightness
v4l_auto_brightness off

# Set the initial brightness of a video device.
# If auto_brightness is enabled, this value defines the average brightness level
# which Motion will try and adjust to.
# Valid range 0-255, default 0 = disabled
v4l_brightness 0

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

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

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

# Number of frames to capture in each roundrobin step (default: 1)
# Round Robin related option (multiple inputs on same video device name)
v4l_roundrobin_frames 1

# Number of frames to skip before each roundrobin step (default: 1)
# Round Robin related option (multiple inputs on same video device name)
v4l_roundrobin_skip 1

###########################################################
# Netcam options
# These options are used only if the netcam plugin is used
############################################################
# 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

# URL to use for a netcam proxy server, if required, e.g. "http://myproxy".
# If a port number other than 80 is needed, use "http://myproxy:1234".
# Default: not defined
; netcam_proxy value

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

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

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

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

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

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

# 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 the 'l' must be 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 8

# 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 60

# Try to filter out noise generated by roundrobin (default: off)
switchfilter off

# 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-5
minimum_motion_frames 1

# Specifies the number of pre-captured (buffered) pictures from before motion
# was detected that will be output at motion detection.
# Recommended range: 0 to 5 (default: 0)
# Do not use large values! Large values will cause Motion to skip video frames and
# cause unsmooth mpegs. To smooth mpegs use larger values of post_capture instead.
pre_capture 0

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

# Gap is the seconds of no motion detection that triggers the end of an event
# An event is defined as a series of motion images taken within a short timeframe.
# Recommended value is 60 seconds (Default). The value 0 is allowed and disables
# events causing all Motion to be written to one single mpeg file and no pre_capture.
gap 60

# Minimum gap in seconds between the storing pictures while detecting motion.
# Default: 0 = as fast as possible (given by the camera framerate)
# Note: This option has nothing to do with the option 'gap'
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


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

# Output 'normal' pictures when motion is detected (default: on)
# Valid values: on, off, first, best
# When set to 'first', only the first picture of an event is saved.
# Picture with most motion of an event is saved when set to 'best'.
# Can be used as preview shot for the corresponding movie.
output_normal on

# Output pictures with only the pixels moving object (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


############################################################
# Snapshots (Traditional Periodic Webcam File Output)
############################################################

# Make automated snapshot every N seconds (default: 0 = disabled)
snapshot_interval 0


############################################################
# Movie (e.g. mpeg) File Output Options
# Used by movie_plugins
############################################################

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

# Use movie_plugin to make movies with only the pixels moving
# object (ghost images) (default: off)
# (formerly ffmpeg_cap_motion)
movie_motion off

# Use movie_plugin to encode a timelapse movie
# Default value 0 = off - else save frame every Nth second
# (formerly ffmpeg_timelapse)
movie_timelapse 0

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


############################################################
# ffmpeg Plugin Options
# These options are used only if the ffmpeg movie plugin is used
############################################################

# 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 2

# 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


############################################################
# 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,
# %D = changed pixels, %N = noise level,
# %i and %J = width and height of motion area,
# %K and %L = X and Y coordinates of motion center
# %C = value defined by text_event - do not use with text_event!
# You can put quotation marks around the text to allow
# leading spaces
############################################################

# Locate and draw a box around the moving object.
# Valid values: on, off and preview (default: off)
# Set to 'preview' will only draw a box in preview_shot pictures.
locate on

# 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

# 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

# This option defines the value of the speciel event conversion specifier %C
# You can use any conversion specifier in this option except %C. Date and time
# values are from the timestamp of the first image in the current event.
# Default: %Y%m%d%H%M%S
# The idea is that %C can be used filenames and text_left/right for creating
# a unique identifier for each event.
text_event %Y%m%d%H%M%S

# Draw characters at twice normal size on images. (default: off)
text_double off


############################################################
# 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
# %D = changed pixels, %N = noise level,
# %i and %J = width and height of motion area,
# %K and %L = X and Y coordinates of motion center
# %C = value defined by text_event
# Quotation marks round string are allowed.
############################################################

# Target base directory for pictures and films
# Recommended to use absolute path. (Default: current working directory)
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
# Set to 'preview' together with best-preview feature enables special naming
# convention for preview shots. See motion guide for details
jpeg_filename %v-%Y%m%d%H%M%S-%q

# File path for motion triggered movie films (mpeg) relative to target_dir
# This option is used by any movie_plugin
# Default: %v-%Y%m%d%H%M%S
# 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
movie_filename %v-%Y%m%d%H%M%S

# File path for timelapse movies relative to target_dir
# This option is used by any movie_plugin
# Default: %Y%m%d-timelapse
# For Motion 3.0 compatible mode choose: %Y/%m/%d-timelapse
# File extension .mpg is automatically added so do not include this
timelapse_filename %Y%m%d%H-timelapse


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

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

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

# Output frames at 1 fps when no motion is detected and increase to the
# rate given by webcam_maxrate when motion is detected (default: off)
webcam_motion on

# Maximum framerate for webcam streams (default: 1)
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


############################################################
# HTTP Based Control
############################################################

# TCP/IP port for the http server to listen on (default: 0 = disabled)
control_port 8080

# Restrict control connections to localhost only (default: on)
control_localhost off

# Output for http server, select off to choose raw text plain (default: on)
control_html_output on

# Authentication for the http based control. Syntax username:password
# Default: not defined (Disabled)
control_authentication tutankamon:pyramidpasswd


############################################################
# Tracking (Pan/Tilt)
############################################################

# Type of tracker (0=none (default), 1=stepper, 2=iomojo, 3=pwc, 4=generic)
# The generic type enables the definition of motion center and motion size to
# be used with the convertion specifiers for options like on_motion_detected
track_type 0

# Serial port of motor (default: none)
; track_port value

# Motor number for x-axis (default: -1)
track_motorx -1

# Maximum value on x-axis (default: 0)
track_maxx 0

# ID of an iomojo camera if used (default: 0)
track_iomojo_id 0

# Speed to set the motor to (default: 255)
track_speed 255

# Number of steps to make (default: 40)
track_stepsize 0


############################################################
# External Commands, Warnings and Logging:
# You can use conversion specifiers for the on_xxxx commands
# %Y = year, %m = month, %d = date,
# %H = hour, %M = minute, %S = second,
# %v = event, %q = frame number
# %D = changed pixels, %N = noise level,
# %i and %J = width and height of motion area,
# %K and %L = X and Y coordinates of motion center
# %C = value defined by text_event
# Quotation marks round string are allowed.
############################################################

# Do not sound beeps when detecting motion (default: on)
# Note: Motion never beeps when running in daemon mode.
quiet on

# Command to be executed when an event starts. (default: none)
# An event starts at first motion detected after a period of no motion defined by gap 
; on_event_start value

# Command to be executed when an event ends after a period of no motion
# (default: none). The period of no motion is defined by option gap.
; on_event_end value

# Command to be executed when a picture (.ppm|.jpg) is saved (default: none)
# The filename of the picture is appended as an argument for the command.
on_picture_save /usr/local/motion-extras/camparse1.pl

# Command to be executed when a motion frame is detected (default: none)
; on_motion_detected value

# Command to be executed when a movie file (.mpg|.avi) is created. (default: none)
# Filename of movie is appended as an argument for the command.
; on_movie_start value

# Command to be executed when a movie file (.mpg|.avi) is closed. (default: none)
# Filename of movie is appended as an argument for the command.
; on_movie_end value


############################################################
# 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

# Log this user specified text to every record saved in the database.
# You can use all the same conversion specifiers that you can use for
# text display, filenames, and external commands (default: not defined)
; sql_user_text value


############################################################
# Database Options For MySQL
############################################################

# Mysql database to log to (default: not defined)
mysql_db motion

# The host on which the database is located (default: not defined)
mysql_host 127.0.0.1

# User account name for MySQL database (default: not defined)
mysql_user memyself

# User password for MySQL database (default: not defined)
mysql_password somesecretpasswd


############################################################
# Database Options For PostgreSQL
############################################################

# PostgreSQL database to log to (default: not defined)
; pgsql_db value

# The host on which the database is located (default: not defined)
; pgsql_host value

# User account name for PostgreSQL database (default: not defined)
; pgsql_user value

# User password for PostgreSQL database (default: not defined)
; pgsql_password value

# Port on which the PostgreSQL database is located (default: 5432)
pgsql_port 5432


############################################################
# Video Loopback Device (vloopback project)
############################################################

# Output images to a video4linux loopback device
# The value '-' means next available (default: not defined)
; video_pipe value

# Output motion images to a video4linux loopback device
# The value '-' means next available (default: not defined)
; motion_video_pipe value


##############################################################
# Camera Sections
# You need one for each camera.
# Syntax is camera and a number (should accept names and what
# would we use the name for?
# ##############################################################

[camera 1]
input_plugin netcam
movie_plugin ffmpeg
netcam_url http://192.1681.100/video.cgi
text_left %C\nCAMERA 1
ffmpeg_bps 200000

[camera 2]
input_plugin v4l
movie_plugin ffmpeg
v4l_videodevice /dev/video0
v4l_input 1
text_left CAMERA 2
target_dir /usr/local/apache2/htdocs/cam2
webcam_port 8082
on_picture_save /usr/local/motion-extras/camparse2.pl
on_movie_end /usr/local/motion-extras/mpegparse2.pl
ffmpeg_bps 600000
movie_timelapse 60

[camera 3]
input_plugin v4l
movie_plugin ffmpeg
v4l_videodevice /dev/video2
v4l_input 1
threshold 3000
text_left CAMERA 3
target_dir /usr/local/apache2/htdocs/cam3
webcam_port 8083
on_picture_save /usr/local/motion-extras/camparse3.pl
on_movie_end /usr/local/motion-extras/mpegparse3.pl
movie_motion on