Configuration

Basic Setup

Motion is able to process images from many different types of cameras. The following is brief overview of the process to set up the Motion software.
• Determine the type of camera
  • v4l2 devices which are most webcams
  • Composite capture cards
  • Network or IP cameras
  • The PI camera
  • Static movie files.
• Specify the camera in the configuration files.
• Start Motion from a terminal via the command line
• Review the messages to ensure camera was found and press cntrl-c to exit
• Specify a target_dir in the configuration file.
• Enable the web stream in the configuration file
• Specify a stream_port
• Optionally turn off stream_localhost if you want to view the stream from a different computer
• Optionally adjust the number of persistent connections of your browser. By default many browsers limit the number of simultaneous connections (usually to something like 5). Since Motion uses connections for each camera, it is possible that only the first 5 cameras are displayed on the all cameras home pages. To get around this, some browsers allow the user to specify a different(higher) number of simultaneous streams. For some browsers, this is specified via the network.http.max-persistent-connections-per-server option. For other browsers, users are not permitted to customize the settings. For these browsers, users will need to specify a different port for each camera stream. The connection limit is based upon the server:port combination therefore specifying a different port for each camera avoids the limitation.
• Enable the web control in the configuration file
• Specify a webcontrol_port
• Optionally turn off webcontrol_localhost if you want to view the webcontrol from a different computer
• Specify which parameters to show on the webcontrol via webcontrol_parms
• Optionally specify a stream_preview_method
The above should allow users to get Motion running and being able to view images via the stream. The next steps refine and finish a basic setup.
• Refine how the image is captured with the image processing parameters
• Specify the motion detection parameters
• Execute scripts, Save pictures or movies.
The most difficult step in the above process will be the motion detection settings and specifying them to minimize the false positives. To assist this process, Motion provides the stream_preview_method option 3 which allows users to see side by side images of where the motion is occurring next to the regular image.
• Specify stream_preview_method 3
• Specify webcontrol_parms 2
• Start Motion and in a web browser navigate to the webcontrol port
• Try adjusting the threshold, noise_level, despeckle_filter and smart_mask_speed
• Make sure to write configuration to file in order to save any changes.
Motion also includes a setup_mode which provides more values reported on the motion images and in the log to assist the setup.
The following are some additional topics which may be of interest during the initial setup.
• Run automatically at start (Run as service)
• Remove deprecated parameters warnings (Remove deprecated)
• List/include all possible configuration parameters (All parameters)
Video4linux devices must be installed per the requirements of the camera. It is out of the scope of this document to tell you how to do this and it depends on which type of camera. Once the camera is installed it will have the device name(s) of /dev/video0, /dev/video1, /dev/video2...
FreeBSD has a different naming scheme for pci devices that use the bktr subsystem. The bktr subsystem will report devices using a naming scheme of /dev/bktr0, /dev/bktr1, etc. These device may also need to use the other special device for the tuner. The tuner will need to be specified with the tunerdevice option as /dev/tuner0.
USB cameras take a lot of bandwidth. A USB camera connected to a USB2 port or hub consumes virtually all the bandwidth that the port can handle. Even with a small framesize and low framerate you should not expect to have more than one camera per USB controller. If you need more than one USB camera it is possible to add extra USB PCI cards to your computer. It is also possible that your computer has more than one controller for different USB slots. For example, if the computer has six USB ports, the three on the left may be on controller A versus the three on the right may be on controller B. In this situation, connecting two cameras to ports only on the left would not work due to excessive bandwidth. However connecting one camera to port on the right and the other to the port on the left may work since they are on different controllers.
Motion permits the use of video cards that have discreet input channels. Since USB cameras do not have input channels, the option input must be set to the value -1 for USB cameras.
Network cameras are set up via the netcam_url parameter. The latest versions of Motion support rtsp format which many cameras now stream. Some users have requested a list of the network cameras that will work with Motion. Since Motion can now process RTSP streams, almost all cameras are supported. Simply review the specifications of the camera and validate that RTSP or RTMP is listed. The cameras that will not work are those specifically sold to be integrated into proprietary software monitoring systems. When determining cameras, consider carefully before selecting a wireless camera. Cameras require a solid consistent signal and use a lot of bandwidth. Inconsistencies in the wireless signal can result in a poor user experience so the use of a hardwired camera is recommended.
The URL connection string to enter is specific to the camera and is usually provided by the manufacturer. The connection string is the same as what would be used by other video playing software such as VLC. If the camera does not stream via RTSP and instead uses a MJPEG, then Motion can also view that format. See the option netcam_url for additional options.
The raspberry Pi camera is set up via an application called libcamera. libcamera provides access to the camera as a v4l2 device but this interface is only available when using a special application. Users must run Motion using the command libcamerify motion and then specify the /dev/videoX device in the Motion configuration file.
With just one camera connected to the Pi, the device name should normally be /dev/video0. With multiple cameras connected, e.g. a regular USB web and the Pi camera, you will need to determine the device associated with the Pi camera and the USB camera. The list of devices can be seen using the command (v4l2-ctl --list-devices).
Composite video cards are normally made with a chip called BT878 (older cards have a BT848). They all use the Linux driver called 'bttv'.
There are cards with more then one video input but still only one BT878 chip. They have a video multiplexer which input is selected with the config option input. Input channel numbers start at 0 (which is why the value -1 and not 0 disables input selection). There are video capture cards available with 4 or 8 inputs but only one chip. They present themselves as one single video device and you select input using the 'input' option. If you define e.g. 4 camera config files with the same video device name but different input numbers Motion automatically goes into round robin mode.
Many TV tuner cards have the input channels: TV Tuner = 0, Standard composite video = 1, S-VHS = 3. Others have TV=0, composite video 1= 1, composite video = 2, S-VHS = 3. For video capture cards input 1 is normally the composite video input.
Some capture cards are specially made for surveillance with for example 4 inputs. Others have a TV tuner, a composite input and perhaps also a S-Video input. For all these cards the inputs are numbered. The numbering varies from card to card so the easiest is to experiment with a program such as VLC that can show the video stream.
If you use the TV tuner input you also need to set the frequency of the TV channel using the option frequency. Otherwise set frequency to 0.
Finally you need to set the TV norm. Values: 0 (PAL), 1 (NTSC), 2 (SECAM), 3 (PAL NC no colour). Default is 0 (PAL). If your camera is a PAL black and white you may get a better result with norm=3 (PAL no colour).
Static files can also be processed by Motion in one of two ways. The first method is by using the netcam_url option and using a prefix of file:\\. With this method, Motion will process the file at the speed specified by framerate. This allows the user to either speed up or slow down the video processing to suit the particular need.
The second option for processing a static file requires a bit of additional setup and uses a v4l2loopback device. To set this up, first install the loopback software as described in the Output - Pipe Options section of this guide to create a /dev/videoX device and then use software such as ffmpeg to stream the static file into the v4l2 device. e.g. ffmpeg -re -i mymovie.mp4 -f v4l2 /dev/video0 Then in a separate terminal, start Motion with it set to use the /dev/video0 device as input. This method can can also be used to reformat the content to a different format. The following outputs the original movie into a gray pixel format. ffmpeg -re -i mymovie.mp4 -f v4l2 -pix_fmt gray /dev/video0 This can be helpful as a interim process where ffmpeg supports a particular input but that format is not yet supported by Motion.
Run as Service
The following instructions are only applicable to Debian and Ubuntu based systems. For other distributions, users should consult their distribution documentation and provide pull requests to the Motion developers so that this section can be updated with their distribution.
Motion can be set up to run as a service which means that it will start automatically whenever the computer is started. When setting up Motion to run as a service, it should be done only after all the other configuration has been completed. It is much easier to edit and revise the parameters when Motion is just running in a terminal rather than as a service. Motion now uses the systemctl and when running as a service, the option daemon must be set as off
The following commands control the Motion service.
• Start the Motion servicesudo systemctl start motion
• Stop the Motion servicesudo systemctl stop motion
When running as a service, Motion runs as the user motion and this user is automatically added to the user group of video. By only be included in this user group, when Motion is run, it will only have limited permissions. It is NOT recommended that this user get added to the sudo group. Instead, only add this user to groups that are specifically required.

Command Line Options

SYNOPSIS motion [ -hbnsm ] [ -c config file path ] [ -d level ] [ -k level ] [ -p pid_file ] [ -l log_file ]
• -c : Full path and filename of config file.
• -h : Show help screen
• -b : Run in daemon mode
• -n : Run in non-daemon mode
• -s : Run in setup mode. Also forces non-daemon mode.
• -d : Run with message log level 1 - 9
• -k : Run with message log type 1 - 9
• -l : Full path and file name for log file
• -p : Full path and file name for the process id file
• -m : Start in pause mode

The Configuration 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 /etc/motion)
If you have write access to /usr/local/etc/motion then the editor recommends having only one motion.conf file in the default /usr/local/etc/motion 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/motion 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 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 at the same time. The motion.conf file establishes global parameters that apply to all cameras and separate camera.conf files that specify the parameters that apply to each specific camera. The camera.conf files are specified at the bottom of the motion.conf file. If you only have one camera you only need the motion.conf file but if you have more than one camera, then you will need to have one camera config file per camera plus the motion.conf file.
If you have for example two cameras you need motion.conf and two camera config files. So a total of three config files.
An option that is common to all cameras can be placed in motion.conf. (You can also put all parameters in the camera files but that makes a lot of editing when you change a common thing).
An option that is unique to a camera must be specified in each camera file.
The first camera is defined in the first camera file called from motion.conf. The 2nd camera is defined in the 2nd camera 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 camera config file.
To make it clear, the camera files format and syntax is the same as motion.conf. An example of what you might want in a camera file as follows: assume you have two cameras, attached to one system. Create files camera0.conf and camera1.conf. At the end of motion.conf, uncomment out the lines that refer to them. The full contents of the camera files can be as simple as
camera0.conf:
video_device /dev/video0
camera1.conf:
video_device /dev/video1
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 "camera" is defined in motion.conf, the camera 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 camera config file.
4. Motion reads the command line option again overruling any previously defined options.
So always call the camera config files in the end of the motion.conf file. If you define options in motion.conf AFTER the camera file calls, the same options in the camera files will never be used. So always put the camera file call at the end of motion.conf.
Nearly all config options can be unique for a specific camera and placed in a camera config file. There are a few options that must be in motion.conf and cannot be in a camera config file: webcontrol_* , daemon, and camera.
If motion is built without specific features such as ffmpeg, mysql etc it will ignore the options that belong to those features.
Deprecated Parameters
Over the years, Motion has added many new configuration parameters and changed the name of a few of them so that there is some consistency to the parameter names. Since version 3.4.1, when a configuration parameter has a new name or additional functionality, Motion will try to interpret the value specified for the old parameter and translate it to the new parameter. These translations will be reported in the log as Motion is started. To eliminate these warnings, ensure that a webcontrol_port is specified and that the webcontrol_interface is specified as 0 (or not listed). Then start motion, open a browser and navigate to the webcontrol port. When on that page, select write configuration. This will re-write the configuration files with all the current parameters to Motion. Note that depending upon where the configuration files are located, Motion may need to be started using sudo.
Parameters in distributed configuration files
As of this writing, Motion includes over 150 parameters. With this volume of parameters, navigating the configuration file with every possible has become onerous. Starting with version 4.2, the distributed configuration files only include a limited subset of the configuration parameters. Users can add to the files as needed the parameters that are applicable to their set up. Users that wish to have every parameter listed and included in the configuration file can follow the process described immediately above in the Remove deprecated section. i.e. Use the webcontrol interface to write out the configuration file.
Extended descriptions / documentation are not included in the configuration file. This guide should be consulted for documentation of the configuration parameters.

Signals (sent with e.g. kill command)

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

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

Configuration Options-Listed Alphabetically

These are the options that can be used in the config file.
All number values are integer numbers (no decimals allowed). Boolean options can be on or off.
Some configuration options are only used if Motion is built on a system that has the matching software libraries installed (MySQL, PostgreSQL, SQLite, FFMPEG, etc).

Version 4.2	Version 4.3	Version 4.4	Current Version
area_detect	area_detect	area_detect	area_detect
auto_brightness	auto_brightness	auto_brightness	auto_brightness
camera	camera	camera	camera
camera_dir	camera_dir	camera_dir	camera_dir
camera_id	camera_id	camera_id	camera_id
camera_name	camera_name	camera_name	camera_name
daemon	daemon	daemon	daemon
database_busy_timeout	database_busy_timeout	database_busy_timeout	database_busy_timeout
database_dbname	database_dbname	database_dbname	database_dbname
database_host	database_host	database_host	database_host
database_password	database_password	database_password	database_password
database_port	database_port	database_port	database_port
database_type	database_type	database_type	database_type
database_user	database_user	database_user	database_user
despeckle_filter	despeckle_filter	despeckle_filter	despeckle_filter
emulate_motion	emulate_motion	emulate_motion	emulate_motion
event_gap	event_gap	event_gap	event_gap
flip_axis	flip_axis	flip_axis	flip_axis
framerate	framerate	framerate	framerate
height	height	height	height
lightswitch_frames	lightswitch_frames	lightswitch_frames	lightswitch_frames
lightswitch_percent	lightswitch_percent	lightswitch_percent	lightswitch_percent
locate_motion_mode	locate_motion_mode	locate_motion_mode	locate_motion_mode
locate_motion_style	locate_motion_style	locate_motion_style	locate_motion_style
log_file	log_file	log_file	log_file
log_level	log_level	log_level	log_level
log_type	log_type	log_type	log_type
mask_file	mask_file	mask_file	mask_file
mask_privacy	mask_privacy	mask_privacy	mask_privacy
minimum_frame_time	minimum_frame_time	minimum_frame_time	minimum_frame_time
minimum_motion_frames	minimum_motion_frames	minimum_motion_frames	minimum_motion_frames
movie_bps	movie_bps	movie_bps	movie_bps
movie_codec	movie_codec	movie_codec	movie_codec
ffmpeg_duplicate_frames	ffmpeg_duplicate_frames	movie_duplicate_frames	movie_duplicate_frames
movie_extpipe	movie_extpipe	movie_extpipe	movie_extpipe
movie_extpipe_use	movie_extpipe_use	movie_extpipe_use	movie_extpipe_use
movie_filename	movie_filename	movie_filename	movie_filename
movie_max_time	movie_max_time	movie_max_time	movie_max_time
movie_output	movie_output	movie_output	movie_output
movie_output_motion	movie_output_motion	movie_output_motion	movie_output_motion
movie_passthrough	movie_passthrough	movie_passthrough	movie_passthrough
movie_quality	movie_quality	movie_quality	movie_quality
native_language	native_language	native_language	native_language
		netcam_high_params	netcam_high_params
netcam_highres	netcam_highres	netcam_high_url	netcam_high_url
	netcam_decoder	netcam_params	netcam_params
netcam_keepalive	netcam_keepalive	netcam_params	netcam_params
netcam_proxy	netcam_proxy	netcam_params	netcam_params
netcam_tolerant_check	netcam_tolerant_check	netcam_params	netcam_params
netcam_use_tcp	netcam_use_tcp	netcam_params	netcam_params
netcam_url	netcam_url	netcam_url	netcam_url
netcam_userpass	netcam_userpass	netcam_userpass	netcam_userpass
noise_level	noise_level	noise_level	noise_level
noise_tune	noise_tune	noise_tune	noise_tune
on_area_detected	on_area_detected	on_area_detected	on_area_detected
on_camera_found	on_camera_found	on_camera_found	on_camera_found
on_camera_lost	on_camera_lost	on_camera_lost	on_camera_lost
on_event_end	on_event_end	on_event_end	on_event_end
on_event_start	on_event_start	on_event_start	on_event_start
on_motion_detected	on_motion_detected	on_motion_detected	on_motion_detected
on_movie_end	on_movie_end	on_movie_end	on_movie_end
on_movie_start	on_movie_start	on_movie_start	on_movie_start
on_picture_save	on_picture_save	on_picture_save	on_picture_save
		pause	pause
picture_exif	picture_exif	picture_exif	picture_exif
picture_output	picture_output	picture_output	picture_output
picture_output_motion	picture_output_motion	picture_output_motion	picture_output_motion
picture_filename	picture_filename	picture_filename	picture_filename
picture_type	picture_type	picture_type	picture_type
picture_quality	picture_quality	picture_quality	picture_quality
pid_file	pid_file	pid_file	pid_file
post_capture	post_capture	post_capture	post_capture
pre_capture	pre_capture	pre_capture	pre_capture
quiet	quiet	quiet	quiet
rotate	rotate	rotate	rotate
roundrobin_frames	roundrobin_frames	roundrobin_frames	roundrobin_frames
roundrobin_skip	roundrobin_skip	roundrobin_skip	roundrobin_skip
roundrobin_switchfilter	roundrobin_switchfilter	roundrobin_switchfilter	roundrobin_switchfilter
setup_mode	setup_mode	setup_mode	setup_mode
smart_mask_speed	smart_mask_speed	smart_mask_speed	smart_mask_speed
snapshot_filename	snapshot_filename	snapshot_filename	snapshot_filename
snapshot_interval	snapshot_interval	snapshot_interval	snapshot_interval
sql_log_movie	sql_log_movie	sql_log_movie	sql_log_movie
sql_log_picture	sql_log_picture	sql_log_picture	sql_log_picture
sql_log_snapshot	sql_log_snapshot	sql_log_snapshot	sql_log_snapshot
sql_log_timelapse	sql_log_timelapse	sql_log_timelapse	sql_log_timelapse
sql_query	sql_query	sql_query	sql_query
sql_query_start	sql_query_start	sql_query_start	sql_query_start
sql_query_stop	sql_query_stop	sql_query_stop	sql_query_stop
stream_auth_method	stream_auth_method	stream_auth_method	stream_auth_method
stream_authentication	stream_authentication	stream_authentication	stream_authentication
stream_cors_header	stream_cors_header	stream_header_params	stream_header_params
stream_grey	stream_grey	stream_grey	stream_grey
stream_localhost	stream_localhost	stream_localhost	stream_localhost
stream_maxrate	stream_maxrate	stream_maxrate	stream_maxrate
stream_motion	stream_motion	stream_motion	stream_motion
stream_port	stream_port	stream_port	stream_port
stream_preview_method	stream_preview_method	stream_preview_method	stream_preview_method
stream_preview_newline	stream_preview_newline	stream_preview_newline	stream_preview_newline
stream_preview_scale	stream_preview_scale	stream_preview_scale	stream_preview_scale
stream_quality	stream_quality	stream_quality	stream_quality
stream_tls	stream_tls	stream_tls	stream_tls
target_dir	target_dir	target_dir	target_dir
text_changes	text_changes	text_changes	text_changes
text_event	text_event	text_event	text_event
text_left	text_left	text_left	text_left
text_right	text_right	text_right	text_right
text_scale	text_scale	text_scale	text_scale
threshold	threshold	threshold	threshold
threshold_maximum	threshold_maximum	threshold_maximum	threshold_maximum
threshold_tune	threshold_tune	threshold_tune	threshold_tune
timelapse_codec	timelapse_codec	timelapse_codec	timelapse_codec
timelapse_filename	timelapse_filename	timelapse_filename	timelapse_filename
timelapse_fps	timelapse_fps	timelapse_fps	timelapse_fps
timelapse_interval	timelapse_interval	timelapse_interval	timelapse_interval
timelapse_mode	timelapse_mode	timelapse_mode	timelapse_mode
track_auto	track_auto	track_auto	track_auto
track_generic_move	track_generic_move	track_generic_move	track_generic_move
track_iomojo_id	track_iomojo_id	track_iomojo_id	track_iomojo_id
track_maxx	track_maxx	track_maxx	track_maxx
track_maxy	track_maxy	track_maxy	track_maxy
track_motorx	track_motorx	track_motorx	track_motorx
track_motory	track_motory	track_motory	track_motory
track_move_wait	track_move_wait	track_move_wait	track_move_wait
track_port	track_port	track_port	track_port
track_speed	track_speed	track_speed	track_speed
track_step_angle_x	track_step_angle_x	track_step_angle_x	track_step_angle_x
track_step_angle_y	track_step_angle_y	track_step_angle_y	track_step_angle_y
track_stepsize	track_stepsize	track_stepsize	track_stepsize
track_type	track_type	track_type	track_type
tunerdevice	tunerdevice	tuner_device	tuner_device
frequency	frequency	video_params	video_params
input	input	video_params	video_params
norm	norm	video_params	video_params
v4l2_palette	v4l2_palette	video_params	video_params
vid_control_params	vid_control_params	video_params	video_params
videodevice	videodevice	video_device	video_device
video_pipe	video_pipe	video_pipe	video_pipe
video_pipe_motion	video_pipe_motion	video_pipe_motion	video_pipe_motion
		watchdog_tmo	watchdog_tmo
		watchdog_kill	watchdog_kill
webcontrol_auth_method	webcontrol_auth_method	webcontrol_auth_method	webcontrol_auth_method
webcontrol_authentication	webcontrol_authentication	webcontrol_authentication	webcontrol_authentication
webcontrol_cert	webcontrol_cert	webcontrol_cert	webcontrol_cert
webcontrol_cors_header	webcontrol_cors_header	webcontrol_header_params	webcontrol_header_params
webcontrol_interface	webcontrol_interface	webcontrol_interface	webcontrol_interface
webcontrol_ipv6	webcontrol_ipv6	webcontrol_ipv6	webcontrol_ipv6
webcontrol_key	webcontrol_key	webcontrol_key	webcontrol_key
webcontrol_localhost	webcontrol_localhost	webcontrol_localhost	webcontrol_localhost
		webcontrol_lock_attempts	webcontrol_lock_attempts
		webcontrol_lock_max_ips	webcontrol_lock_max_ips
		webcontrol_lock_minutes	webcontrol_lock_minutes
webcontrol_parms	webcontrol_parms	webcontrol_parms	webcontrol_parms
webcontrol_port	webcontrol_port	webcontrol_port	webcontrol_port
webcontrol_tls	webcontrol_tls	webcontrol_tls	webcontrol_tls
width	width	width	width
mmalcam_name	mmalcam_name	mmalcam_name	removed
mmalcam_control_params	mmalcam_control_params	mmalcam_params	removed

Configuration Options-Listed by Topic

These are the options that can be used in the config file.
All number values are integer numbers (no decimals allowed). Boolean options can be on or off.
Some configuration options are only used if Motion is built on a system that has the matching software libraries installed (MySQL, PostgreSQL, SQLite, FFMPEG, etc).
System Processing-General Info

daemon	setup_mode	pid_file	log_file
log_level	log_type	quiet	native_language
camera_name	camera_id	camera	camera_dir
target_dir	watchdog_tmo	watchdog_kill

Video4Linux Devices-General Info

video_device	video_params	auto_brightness	tuner_device
roundrobin_frames	roundrobin_skip	roundrobin_switchfilter

Network Cameras-General Info

netcam_url	netcam_params	netcam_high_url	netcam_high_params
netcam_userpass

Image Processing-General Info

width	height	framerate	minimum_frame_time
rotate	flip_axis	locate_motion_mode	locate_motion_style
text_left	text_right	text_changes	text_scale
text_event

Motion Detection-General Info

emulate_motion	pause	threshold	threshold_maximum
threshold_tune	noise_level	noise_tune	despeckle_filter
area_detect	mask_file	mask_privacy	smart_mask_speed
lightswitch_percent	lightswitch_frames	minimum_motion_frames	event_gap
pre_capture	post_capture

Script Execution-General Info

on_event_start	on_event_end	on_picture_save	on_motion_detected
on_area_detected	on_movie_start	on_movie_end	on_camera_lost
on_camera_found

Pictures-General Info

picture_output	picture_output_motion	picture_type	picture_quality
picture_exif	picture_filename	snapshot_interval	snapshot_filename

Movies-General Info

movie_output	movie_output_motion	movie_max_time	movie_bps
movie_quality	movie_codec	movie_duplicate_frames	movie_passthrough
movie_filename	movie_extpipe_use	movie_extpipe	timelapse_filename
timelapse_interval	timelapse_mode	timelapse_codec	timelapse_fps

Pipes-General Info

video_pipe

video_pipe_motion

Webcontrol-General Info

webcontrol_port	webcontrol_ipv6	webcontrol_localhost	webcontrol_parms
webcontrol_interface	webcontrol_auth_method	webcontrol_authentication	webcontrol_tls
webcontrol_cert	webcontrol_key	webcontrol_header_params	webcontrol_lock_attempts
webcontrol_lock_minutes	webcontrol_lock_max_ips

Live Stream-General Info

stream_port	stream_localhost	stream_auth_method	stream_authentication
stream_tls	stream_header_params	stream_preview_scale	stream_preview_newline
stream_preview_method	stream_quality	stream_grey	stream_maxrate
stream_motion

Database-General Info

database_type	database_dbname	database_host	database_port
database_user	database_password	database_busy_timeout	sql_log_picture
sql_log_snapshot	sql_log_movie	sql_log_timelapse	sql_query
sql_query_start	sql_query_stop

Tracking-General Info

track_type	track_auto	track_port	track_motorx
track_motorx_reverse	track_motory	track_motory_reverse	track_maxx
track_minx	track_maxy	track_miny	track_homex
track_homey	track_iomojo_id	track_step_angle_x	track_step_angle_y
track_move_wait	track_speed	track_stepsize	track_generic_move

Configuration Options-Detail Descriptions

The following section provides detailed descriptions of each of the configuration options.

Conversion Specifiers

%Y	year	%m	month	%d	day
%H	hour	%M	minute	%S	second
%T	HH:MM:SS	%v	event	%q	frame number
%t	camera id number	%D	changed pixels	%N	noise level
%w	width of the image	%h	height of the image	%i	width of motion area
%J	height of motion area	%K	X coordinates of motion center	%L	Y coordinates of motion center
%C	value defined by text_event	%f	filename with full path	%n	number indicating filetype
%o	threshold	%Q	Number of labels from despeckle	%{eventid}	Unique identifier for event (cam id + date/time)
%$	camera name	%{fps}	current frames per second	%{host}	name of computer running Motion
%{ver}	The version of Motion

The use of quotation marks around string is permitted. In addition to the above, the conversion specifiers include the same options as for the C function strftime (3).

System Processing

daemon

• Type: Boolean
• Range / Valid values: on, off
• Default: off
When Motion is started, immediately go to daemon mode and release the terminal. Set the option to off when running Motion as a service.

setup_mode

• Type: Boolean
• Range / Valid values: on, off
• Default: off
When this option is turned on, Motion starts in setup mode so that the parameters can be set more easily. In setup mode two things happen: With 'motion -s' Motion runs in console mode instead of daemon. It outputs a lot of useful information for each frame from the camera. Each message is prefixed by [number] where number is the camera id number. When you look at the webcam stream you see a black image with numbers. What you see is the number of changed pixels, number of labeled areas and noise setting. When something moves you see the pixels detected as Motion in black and white. The largest labeled area (assuming despeckle is enabled and with the 'l' at the end) is blue. It is only the blue areas which is counted as Motion. If smartmask is enabled you see this as red areas. Here is a suggestion how to initially setup Motion. (There are other ways to accomplish this.)
• Disable despeckle (comment it out in motion.conf).
• Disable smartmask
• Enable both the webcontrol and streams make sure to specify the webcontrol_parms. The below assumes that the webcontrol is specified as port 8080 and the stream as 8081
• Start Motion in setup mode
• Open a browser and connect to the webcontrol interface. http://localhost:8080/ . You can now control and change almost anything while Motion is running. To disable a feature enter a space.
• Start by experimenting with noise level. Do this both during daylight and during darkness. You will be surprised to see how much noise a camera makes during night. Try using the automatic noise feature. It should work for most.
• Now try the despeckle feature. Enable it using the recommended default EedDl. If this is not enough experiment. Remember that the l must be the last letter.
• Set the threshold to what you want to trigger Motion.
In normal mode you can use the same setting with two browser tabs and experiment with settings of the camera if needed. From the web interface you can ask Motion to write all your changes back to the config files (motion.conf and camera config files).

pid_file

• Type: String
• Range / Valid values: Max 4095 characters
• Default: Not defined
Specify the full path and file name in order to store the pid for processing.

log_file

• Type: String
• Range / Valid values: Max 4095 characters
• Default: Not defined
Use this option to specify the full path and filename to use for logging of the messages generated from Motion. If this option is not defined, the stderr and syslog is used. Note that Motion can generate a LOT of messages and as a result, this option should be considered if the log_level is at any of the higher levels.

log_level

• Type: Integer
• Range / Valid values: 1 - 9
• Default: 6
This option specifies the level of verbosity of the messages sent from Motion. At a level of 8(DBG), there are a LOT of messages. At a level of 1(EMR) virtually no messages will be output.
The various levels are [1..9] (EMR, ALR, CRT, ERR, WRN, NTC, INF, DBG, ALL).
When reporting any issues or errors associated with the Motion application, use the INF level.

log_type

• Type: Discreet Strings
• Range / Valid values: See Below
• Default: ALL
The different components of Motion use different log types. This option allows the user to only show the messages from particular components. The choices for this option are: COR, STR, ENC, NET, DBL, EVT, TRK, VID, ALL

quiet

• Type: Boolean
• Range / Valid values: on, off
• Default: on
Be quiet, don't output beeps when detecting motion. Only works in non-daemon mode.

native_language

• Type: Boolean
• Range / Valid values: on, off
• Default: on
Enable native language for Motion webcontrol and log messages.
Motion will use the locale variable LANGUAGE for determining the webcontrol and log messages. If messages or the webcontrol still display in English, then the messages / words have not yet been translated.
Please consider helping the developers by submitting pull requests to add new translations and correcting any inaccurate translations.
When this option is specified as 'off', the webcontrol and log messages will be provided in English.

camera_name

• Type: String
• Range / Valid values: Max 4095 characters
• Default: Not defined
This option specifies a camera name to be used in the format specifiers as well as on the web interface.

camera_id

• Type: Integer
• Range / Valid values: 1 - 32000
• Default: The sequence that the camera file is read
This option is useful for situations where there are multiple cameras being used by Motion. This option allows for the assignment of a numeric id number that can be used in database queries, format specifiers as well as for the web interface and streams.
If this option is not specified, the thread number as determined by Motion is used. The number assigned to each camera must be unique.
When using multiple cameras, the default for the main thread is 0 (zero) but this can be overridden as needed by specifying a camera_id in the motion.conf file even though there are not any cameras running on this thread.

camera

• Type: String
• Range / Valid values: Max 4095 characters
• Default: Not defined
The full path and file name for the camera file. Motion allows for this line to be listed in the motion.conf file multiple times. These specifications should be the LAST lines in the motion.conf file. See the Configuration Files section within this guide for a complete discussion of what to put into the camera0.conf, camera1.conf, cameraX.conf files that would be specified in this option.

camera_dir

• Type: String
• Range / Valid values: Max 4095 characters
• Default: Not defined
This option specifies a directory to contain the individual camera configuration files. Any files ending in '.conf' in this directory will be read as a camera config file.
Users can disable a camera (config file) by renaming it so it does not end with '.conf'.

target_dir

• Type: String
• Range / Valid values: Max 4095 characters
• Default: Not defined = current directory
The full path for the target directory for picture and movie files to be saved. The default is the current directory. This is the target directory for all snapshots, picture files and movie files. You will normally always want to specify this parameter as an absolute path.
Note that the file name options are all saved relative to this target_dir This means in principle that you can specify target_dir as '/' and be 100% flexible. But this is NOT recommended. It is recommended that this directory be specified as deep as possible.

watchdog_tmo

• Type: int
• Range / Valid values: Integer
• Default: 30
The number of seconds a camera can be non-responsive before Motion attempts to stop the camera gracefully.

watchdog_kill

• Type: int
• Range / Valid values: Integer
• Default: 30
The number of seconds after the timeout has expired until Motion forcefully kills the camera that is unresponsive.

Video4Linux Device

Please refer to the Basic Setup section of this guide for an additional discussion of Video4Linux devices and how to test and specify them correctly for Motion.

video_device

• Type: String
• Range / Valid values: Max 4095 characters
• Default: /dev/video0
The video device to be used for capturing. Default is /dev/video0. See the Basic Setup section of this guide for an additional discussion of this option.
This option is the usual method to specify the video4linux device name. If the camera does not work when specifying it with this option, it is also possible to specify the device in the netcam_url with the v4l2 prefix option. The netcam_url option uses an alternative method to open and operate the device which may work with this option fails. If the netcam_url is used for either this alternative method or for a normal network camera, the video_device option is ignored.
Since the exact device number is set by the kernel upon boot, when there is more than one video device it is possible that the particular cameras that were assigned to /dev/video0 and /dev/video1 may switch. In order to set up Motion so that a particular camera is always assigned the same way, users can set up a symbolic link using udev rules. To do this a unique attribute must be identified for each camera. The camera attributes can be viewed by using the command udevadm info -a -p $(udevadm info -q path -n /dev/video0) while the camera is attached. Usually a serial number can be used. ("Usually" because some cameras have been observed to have the same serial number for different cameras)
Once a unique attribute has been identified for each camera, edit or create the file /etc/udev/rules.d/99-local.rules.
Assuming that the unique attribute for the camera was name and was ATTR{name}=="Philips SPC 900NC webcam" you would add the following line to the 99-local.rules file: KERNEL=="video[0-9]*", ATTR{name}=="Philips\ SPC\ 900NC*", SYMLINK+="video-webcam0"
Once the change has been made and saved, reboot the computer and there should now be a "sticky" device called /dev/video-webcam0

video_params

• Type: String
• Range / Valid values: Max 4095 characters
• Default: Not defined
For most devices the configuration options are automatically assigned but devices also usually allow the user to change certain settings to suit their needs. The options that the camera manufacturer permits the user to change are called "controls". The video_params option allows users to specify values for these controls when Motion runs.
The video_params option also allows users to specify some Motion specific parameters that are used to open the camera. In previous versions of Motion, these options were the frequency, input, norm and v4l2_palette options. These options have now been embedded into the video_params option to provide consistency.
The following is the list of previous Motion options that have now been replaced by the video_params option.
• brightness
• contrast
• hue
• power_line_frequency
• saturation
• frequency
• input
• norm
• v4l2_palette
While it always recommended that users remove older configuration options and only use the new options, if users have within the configuration file any of the deprecated options list above, Motion will continue to read those values and upgrade them into the new video_params option. The resulting pictures from the device may however may not be comparable due to different interpretations of the values.
It is therefore highly recommended that users remove the old configuration values and calibrate their devices only using this new configuration option.
To use this parameter, users will need to first identify the name or ID description of the particular control. Next, simply specify the control/id followed by an equal sign and then the desired value. The specification of multiple controls can be specified by separating them with a comma.
Since the name of some controls can include a comma or spaces, names can also be specified by enclosing them in double quotes. To help users know which controls are available for their device, the Motion log will report the available controls, associated IDs and minimum/maximum values permitted when the log_level is specified as INF or higher.
e.g. Change the log_level to INF, start up Motion with the device attached and specified, let it report items to the log and then shut Motion down. Within the Motion log, it will list which controls the device has that can be adjusted.
The following is a sample output from the log and examples of how to specify the parameters
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ---------Controls---------
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: V4L2 ID Name and Range
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID09963776 Brightness, 0 to 127
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID09963777 Contrast, 0 to 63
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID09963778 Saturation, -100 to 100
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID09963788 White Balance, Automatic, 0 to 4
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: menu item: Value 0 Indoor (Incandescant Lighting)
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: menu item: Value 1 Outdoor (Sunlight) Mode
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: menu item: Value 2 Indoor (Fluorescent Lighting) M
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: menu item: Value 3 Manual Mode
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: menu item: Value 4 Auto Mode
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID09963790 Red Balance, 0 to 255
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID09963791 Blue Balance, 0 to 255
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID09963792 Gamma, 0 to 31
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID09963793 Exposure, 0 to 255
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID09963794 Gain, Automatic, 0 to 1
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID09963795 Gain, 0 to 63
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID09963804 Backlight Compensation, 0 to 1
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID09963807 Color Effects, 0 to 1
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: menu item: Value 0 None
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: menu item: Value 1 Black & White
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID09963809 Band-Stop Filter, 0 to 1
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID10025216 Auto contour, 0 to 1
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID10025217 Contour, 0 to 63
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID10025218 Dynamic Noise Reduction, 0 to 3
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID10025219 Auto White Balance Speed, 1 to 32
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID10025220 Auto White Balance Delay, 0 to 63
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID10025221 Save User Settings, 0 to 0
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID10025222 Restore User Settings, 0 to 0
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: ID10025223 Restore Factory Settings, 0 to 0
• [1:ml1:c1] [INF] [VID] v4l2_ctrls_list: --------------------------
Example 1: Set the gain to manual, then the gain to 50 and the brightness to 30
video_params "Gain, Automatic"=1,ID09963795=50, brightness=30
a equally valid alternative method for specifying this example would be
video_params ID09963794=1,ID09963795=50, ID09963776=30
or another way of specifying it could be
video_params ID09963794=1,"Gain"=50, "brightness"=30
Example 2: Set the saturation to 50 and the contrast to 100
video_params saturation=50,contrast=100
As can be seen in these examples, the specification can use either the control ID or the name of the control. If the control name has embedded blanks or commas, then it must be enclosed in quotes. Special care should be taken when using the name. As shown above, there is a comma that separates the name of the control versus the valid range of values. That comma is NOT part of the control name and only delimits the end of the name for the Motion log.

palette

• Type: Integer
• Range / Valid values: 0 - 20
• Default: 17
The palette option is specified in the video_params option and allows the user to specify the preferred palette for Motion to use. If the video device does not support this preferred format, Motion will loop through the available palettes to try to find one that is supported by both Motion and the device.
Motion will report the supported palettes of the device when Motion starts when the log_level is specified as NTC or higher.
The default of 17 is highly preferred over all other formats since this the native format that Motion uses internally.
The following are each of the palette options. For the Motion configuration, specify the numeric value as the Motion option.

V4l2 Option	FOURCC	v4l2_palette option
V4L2_PIX_FMT_SN9C10X	S910	0
V4L2_PIX_FMT_SBGGR16	BYR2	1
V4L2_PIX_FMT_SBGGR8	BA81	2
V4L2_PIX_FMT_SPCA561	S561	3
V4L2_PIX_FMT_SGBRG8	GBRG	4
V4L2_PIX_FMT_SGRBG8	GRBG	5
V4L2_PIX_FMT_PAC207	P207	6
V4L2_PIX_FMT_PJPG	PJPG	7
V4L2_PIX_FMT_MJPEG	MJPG	8
V4L2_PIX_FMT_JPEG	JPEG	9
V4L2_PIX_FMT_RGB24	RGB3	10
V4L2_PIX_FMT_SPCA501	S501	11
V4L2_PIX_FMT_SPCA505	S505	12
V4L2_PIX_FMT_SPCA508	S508	13
V4L2_PIX_FMT_UYVY	UYVY	14
V4L2_PIX_FMT_YUYV	YUYV	15
V4L2_PIX_FMT_YUV422P	422P	16
V4L2_PIX_FMT_YUV420	YU12	17
V4L2_PIX_FMT_Y10	Y10	18
V4L2_PIX_FMT_Y12	Y12	19
V4L2_PIX_FMT_GREY	GREY	20

It is possible that after looping through all of the palette options for the camera, Motion will not find a palette that is acceptable for processing. In this situation, it may be possible to be the camera to work using the netcam_url option with the v4l2 prefix.

input

• Type: Integer
• Range / Valid values: -1, 0 - ?
• Default: -1
The input option is specified in the video_params option and allows the user to specify the input channel to use for the device.
For USB cameras, the input option should specify -1.
For other devices such as capture cards, the input option is device dependent but usually starts with zero. Using an external application such as VLC can allow for easier specification of the input associated with the camera.

norm

• Type: Integer
• Range / Valid values: 0 (PAL), 1 (NTSC), 2 (SECAM), 3 (PAL NC no colour)
• Default: 0 (PAL)
The norm option is specified in the video_params option and allows the user to specify the television norm to use for the device.

frequency

• Type: Integer
• Range / Valid values: 0 - 999999
• Default: 0 (Not set)
The frequency option is specified in the video_params option and allows the user to specify the frequency to use for the device.
The default is 0 meaning it is not set. This option is only relevant if the device is a TV tuner card where the frequency can be set.

auto_brightness

• Type: Integer
• Range / Valid values: 0 - 3
• Default: 0
Let motion regulate the brightness of a video device. Only recommended for cameras without auto brightness Motion will try to adjust the brightness of the video device if the images captured are too dark or too light. This option will be most useful for video devices which sometimes don't have such an option in hardware. The auto_brightness feature will adjust the brightness of the device up or down until the value is close to a target value.
By default, the target value is the midpoint between the minimum and maximum value permitted for the control being adjusted. (See methods available below)
Users can specify a different target value by specifying a value for the control in the video_params option.
Motion allows for three possible methods for adjusting the brightness.
• 1: Use the brightness control to regulate the brightness (equivalent to specifying on/yes)
• 2: Use the exposure control to regulate the brightness
• 3: Use the exposure absolute control to regulate the brightness

tuner_device

• Type: String
• Range / Valid values: Max 4095 characters
• Default: /dev/tuner0
The tuner device used for controlling the tuner in a tuner card. This option is only used when Motion is compiled for FreeBSD with the bktr option. See the Basic Setup section of this guide for a additional discussion of this option.

roundrobin_frames

• Type: Integer
• Range / Valid values: 1 - 2147483647
• Default: 1
Specifies the number of frames to capture before switching inputs, this way also slow switching (e.g. every second) is possible. The Round Robin feature is automatically activated where multiple cameras are sharing the same video device. Each camera can then set different input or frequency options to change camera. If multiple cameras use the same video device, they each can capture roundrobin_frames number of frames before having to share the device with the other cameras.
Round Robin is not relevant for Network cameras or standard USB web cameras. It is used with video capture cards which have multiple inputs per video chip. This is not the ideal way to run multiple cameras. When the capture card changes input it takes some time before the decoder chip has synchronized to the new camera. You can improve this if you have expensive cameras with a synchronized input. Only one camera can be decoded at a time so if you have 4 cameras connected 3 of the cameras will need to wait for their turn. The fact that cameras have to take turns and the fact that you have to skip a few frames after each turn dramatically lowers the possible framerate. You can get a high framerate by viewing each camera for a long time. But then you may miss the action on one of the inactive cameras. If you can afford it avoid Round Robin and buy the more expensive type of capture cards that has one decoder chip per input. If you only need 2 or 3 cameras you can also simply put 2 or 3 cheap TV cards in the computer. Linux has no problem working with multiple TV cards. (or better yet, it multiple cheap network cameras) If multiple cameras use the same video device, they each can capture roundrobin_frames number of frames before having to share the device with the other cameras. When another camera wants to watch another input or frequency or size the first roundrobin_skip number of frames are skipped to allow the device to settle. The last option roundrobin_switchfilter is supposed to prevent the change of camera from being detected as Motion. Its function is not perfect and sometimes prevents detection of real motion. You should start with having the option disabled and then try with the option enabled to see if you can skip less frames without loosing the detection of the type of motion you normally want to detect.

roundrobin_skip

• Type: Integer
• Range / Valid values: 1 - 2147483647
• Default: 1
Specifies the number of frames to skip after a switch. (1 if you are feeling lucky, 2 if you want to be safe). The Round Robin feature is automatically activated where multiple cameras are sharing the same video device. Each camera can then set different input channels or frequencies to change camera. When another camera wants to watch another input or frequency or size the first roundrobin_ skip number of frames are skipped to allow the device to settle.

roundrobin_switchfilter

• Type: Boolean
• Range / Valid values: on, off
• Default: off
Turns the switch filter on or off. The filter can distinguish between most switching noise and real motion. With this you can even set roundrobin_skip to 1 without generating much false detection. This is a round robin related feature used when you have a capture card with multiple inputs (controlled by the 'input' option) on the same video_device.

Network Cameras

Motion can connect to certain network cameras. Please refer to the Basic Setup section of this guide for an additional discussion of network camera and how to test and specify them correctly for Motion.
Motion cannot connect to a video stream such a mpeg, mpeg4, divx to connect to streams such as these the user may review the static files portion of the Basic Setup section of this guide which illustrates some possible work arounds using ffmpeg and v4l2loopback devices.
The URL must return one single jpeg image, a mjpeg stream a RTSP stream, RTMP stream, file or ftp. When getting a still image, make sure to validate that the camera is serving up a actual raw JPG file and not a HTML page with an embedded JPG which Motion will not be able to process. When the netcam_url is defined the video4linux options above are mostly ignored.
If the connection to a network camera is lost, Motion will reuse the last good image for approx 30 seconds. After 30 seconds the image is replaced by a grey image with a text telling that the signal is lost and when the connection was lost. This text and its date format is not configurable.

netcam_url

• Type: String
• Range / Valid values: Max 4095 characters
• Default: Not defined
URL for a network camera.
The list below illustrates some of the more common protocols for network cameras but Motion does not restrict the protocols to this list. Other protocols that are available via the ffmpeg libraries can also be specified.
http://
This prefix uses the traditional http format and opens a netcam that provides a motion jpg image.
When using the rtsp format, Motion will ignore the netcam_keepalive and netcam_tolerant_check options.
rtsp://
This prefix is the standard for all modern network cameras. It is recommended that users search the web or the camera manual for the exact connection string to use for their camera.
Once a potential connection string is found, it should be validated as being functional using a external application such as ffplay or vlc.
The connection string that works for these applications is what needs to be specified for this option.
When using the rtsp format, Motion will ignore the netcam_keepalive and netcam_tolerant_check options.
rtmp://
This prefix may be available on modern network cameras. It is recommended that users search the web or the camera manual for the exact connection string to use for their camera.
Once a potential connection string is found, it should be validated as being functional using a external application such as ffplay or vlc.
The connection string that works for these applications is what needs to be specified for this option.
When using the rtmp format, Motion will ignore the netcam_keepalive and netcam_tolerant_check options.
file://
This option allows for the processing of a existing movie file. Motion will open the file and process the file at the framerate specified in the Motion configuration file. Note that since the file may have been created using a different framerate than specified in the Motion config file, the file may be processed at either a faster or slower rate than real time.
A sample format for the netcam_url would be netcam_url file:///home/user/cam1/cam1_20180817084027.mkv
This option is useful for "reprocessing" a movie created by Motion to fine tune the detection options.
At the end of the movie file, Motion will restart the movie file at the beginning so that you can continue to refine the detection parameters.
v4l2://
This option allows for an alternative method of using a v4l2 device that is not natively supported by Motion.
A sample format for the netcam_url would be v4l2:///dev/video0 Internally, this is equivalent to running the following from the command line ffplay -f v4l2 /dev/video0

mjpeg://
This is an alternative prefix for http for use when Motion is compiled without ffmpeg.

mjpg://
This option may process very old netcams with non standard mjpeg formats.
jpeg://
This option is for processing a static JPG file that is updated by processes external to Motion. It must be a local file and specified such as jpeg:///path/current.jpg
ftp://
This prefix opens the ftp site and grabs a static image. The camera will be expected to periodically replace that static image as it processes images.

netcam_params

• Type: String
• Range / Valid values: Max 4095 characters
• Default: varies by camera type
This option allows for specification of parameters to the network camera. The format for specifying parameters and values is the same as what is given in the examples for video_params. The parameters are delimited by commas and provided in the format of parameter_name = parameter_value.
For cameras that use the url prefix of mjpeg, ftp, mjpg, and jpeg the options permitted are limited to keepalive, proxy and tolerant_check. These parameters correspond to the options provided in previous versions of Motion.
For cameras that use other url prefixes, the parameters permitted are those available from the ffmpeg library plus a some that are specific to Motion as specified below. The options of keepalive, proxy, tolerant_check are not applicable to these cameras.
The following summarizes some of the options. Full descriptions of all the ffmpeg options will be contained in the documentation for ffmpeg.

keepalive

• Type: String
• Range / Valid values: Max 4095 characters
• Default: off
The keepalive option is specified in the netcam_params option.
The setting for keep-alive of network socket, should improve performance on compatible net cameras.
• off: The historical implementation using HTTP/1.0, closing the socket after each http request.
• force: Use HTTP/1.0 requests with keep alive header to reuse the same connection.
• on: Use HTTP/1.1 requests that support keep alive as default.

proxy

• Type: String
• Range / Valid values: Max 4095 characters
• Default: Not defined
The proxy option is specified in the netcam_params option.
URL to use for a netcam proxy server, if required. The syntax is http://myproxy:portnumber Use this if you need to connect to a network camera through a proxy server. Example of syntax: "http://myproxy.mydomain.com:1024 If the proxy port number is 80 you can omit the port number. Then the syntax is use "http://myproxy.mydomain.com" . Leave this option undefined if you do not use a proxy server.

tolerant_check

• Type: Boolean
• Range / Valid values: on, off
• Default: off
The tolerant_check option is specified in the netcam_params option.
Use less strict jpeg checks for network cameras

decoder

• Type: String
• Range / Valid values: Max 4095 characters
• Default: Not defined
The decoder option is specified in the netcam_params option.
This option is specific to the Motion software and allows for specifying a user requested decoder for the camera. Motion will try to open the camera using the decoder specified by this parameter. If it not successful, it will fall back to the default decoder. This option may improve performance in certain situations for certain platforms and cameras.
Users can find the names of the decoders in ffmpeg on their system by going to a command prompt and typing ffmpeg -decoders and looking for the name of the decoder with a 'D' next to it and correlating this with the type of image provided from the camera. Note that although the decoder may be listed, it still may not work within Motion.
In addition to the decoders specified by ffmpeg, additional different decoder options may also be found by reviewing the Motion log. These decoders will be shown as "available" in the log when log_level is specified at the INF level or higher.
Not all decoders will work even if they are indicated as available or work using ffmpeg externally to Motion. If the camera does not open using the requested decoder, try a different decoder or leave this parameter empty to use the default.

capture_rate

• Type: int
• Range / Valid values: Integer
• Default: framerate
The capture_rate option is specified in the netcam_params option.
This option allows for the user to request a specific frame per second (FPS) capture rate for the network camera. This is needed at times so that the rate Motion is capturing images is in sync with what the camera is sending.
When this value is used, it makes a slight distinction from the usual interpretation of framerate. The capture_rate will specify how fast images are captured and decoded and the framerate will specify the rate at which they are processed for motion.
For example, if the capture_rate were set to be 10 and the framerate was set to be 20, what would happen is that each captured image would end up going through the Motion detection / processing routines twice because that loop is processing at twice the speed of the capture loop. Conversely, if the capture_rate was set to 20 and the framerate is specified as 10, then Motion will be detecting and processing every other image captured.
The reason that the capture_rate is not systematically set to the framerate within Motion has to with the camera. Each camera will provide a stream of images usually in some compression format such as H264 or H265 and provide those images at a particular FPS. If the capture and decoding FPS of Motion is set to a rate lower than the camera, decoding and disconnection errors will occur.
To avoid the decoding and disconnection errors, it is recommended that the FPS of the camera be adjusted where possible. Generally, it is preferable to have the FPS of the camera be slightly lower than the capture_rate of Motion. This allows for the decoder to perform better and reduce decoding errors. For example if the capture_rate is set at 5 and the camera is sending images at 30 FPS, the resulting images, processing latency, etc is going to be extremely "poor". But if the camera FPS is set at 4 instead, the results will "better".
Reviews of the Motion log at the INF level can assist in determining whether a higher capture_rate is required. In particular, look for the following:
• Log messages indicating what the netcam capture rate is versus the log entry for the camera FPS.
• The network camera is disconnecting and reconnecting frequently.
• A significant number of ffmpeg_avcodec_log messages

rtsp_transport

• Range / Valid values: tcp, udp, see ffmpeg documentation
• Default: tcp
The rtsp_transport option is specified in the netcam_params option. This option is from the ffmpeg libraries.
The rtsp_transport value of tcp is highly preferred because without this option the rtsp/rtmp images are frequently corrupted and result in many false positive values and images that appear to be smeared.
For some cameras, a tcp transport is not provided from the camera. Some Motion users have reported using netsed can workaround this limitation of the camera using the following method:
Instead of: netcam_url rtsp://192.168.0.51:554/onvif1
Use: netcam_url rtsp://127.0.0.1:554/onvif1
Then in a different process, start netsed to substitude AVP; with AVP/TCP;
netsed tcp 554 192.168.0.51 554 's/AVP;/AVP%2FTCP;'


input_format

• Range / Valid values: mjpeg, h264, see ffmpeg documentation
• Default: tcp
The input_format option is specified in the netcam_params option. This option is from the ffmpeg libraries. This option is used for specifying the palette format of the camera when using the v4l2 via netcam option.

netcam_high_url

• Type: String
• Range / Valid values: Max 4095 characters
• Default: Not defined
The network camera high resolution URL used in conjunction with the netcam_url parameter. Users may specify the normal resolution in the netcam_url and that will be used for the motion detection and then specify the high resolution url for this parameter.
Motion detection on the normal resolution will trigger the saving of images from the high resolution stream. Note that the ONLY overlay that will be present on the resulting high resolution pictures and movies is the privacy mask. The other overlays such as date/time, motion boxes, camera name, etc will not be included. Users wishing to see those overlays on the resulting images and movies will need to specify the high resolution url as the netcam_url and not use this option.
If the netcam_url is not specified, this option is ignored.
When this option is used with the movie_passthrough even less processing occurs. Since the movie_passthrough bypasses decoding the stream, images will be saved as provided from the camera and the privacy mask will not be applied.

netcam_high_params

• Type: String
• Range / Valid values: Max 4095 characters
• Default: varies by camera type
This option is the same as netcam_params option except this option applies the parameters to the high resolution camera.

netcam_userpass

• Type: String
• Range / Valid values: Max 4095 characters
• Default: Not defined
The username and password for the network camera. The string is specified as username:password. If the camera does not have any authentication to the stream, leave this option empty.

Image Processing

width

• Type: Integer
• Range / Valid values: Device Dependent
• Default: 640
The width in pixels of each frame. Valid range is camera dependent.
For all devices, the width must be a multiple of 8.
Motion does not scale v4l2 devices and http netcams so the value should be set to the actual size of the image provided by the device. In case of a rtsp/rtmp network camera, Motion will rescale the camera image to the requested dimensions. This rescaling comes at a very high CPU cost so it is recommended that the network camera send the image in the same dimensions as included in the configuration file.
While Motion will not rescale the image provided, it will attempt to set the size of the image coming from the video4linux device to match the values provided for height/width.
It is important to realize that certain height/width combinations are only valid at certain frame rates. The particular combinations which are valid are dependent upon 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.

height

• Type: Integer
• Range / Valid values: Device Dependent
• Default: 480
The height in pixels of each frame. Valid range is camera dependent.
For all devices, the height must be a multiple of 8.
Motion does not scale v4l2 devices and http netcams so the value should be set to the actual size of the image provided by the device. In case of a rtsp/rtmp network camera, Motion will rescale the camera image to the requested dimensions. This rescaling comes at a very high CPU cost so it is recommended that the network camera send the image in the same dimensions as included in the configuration file.
While Motion will not rescale the image provided, it will attempt to set the size of the image coming from the video4linux device to match the values provided for height/width.
It is important to realize that certain height/width combinations are only valid at certain frame rates. The particular combinations which are valid are dependent upon 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.

framerate

• Type: Integer
• Range / Valid values: 2 - 100
• Default: 1