MOTION(1)

📦
version 4.7.1 · 3 versions
, in arch rolling, debian trixie, nixos 26.05, nixpkgs unstable, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 MOTION(1) — Motion Options and Config Files 💖

okay bestie, welcome to the MOTION(1) page! it's giving Motion Options and Config Files, and we're about to vibe-check every flag, option, default, and little technical crumb. no cap. 🫶

✨ NAME ✨

motion — detect motion using a video4linux device or network camera 👀

🦋 SYNOPSIS 🦋

motion [ -hbnsm ] [ -c config file path ] [ -d level ] [ -k level ] [ -p
pid_file ][ -l log_file ]

🌸 DESCRIPTION 🌸

okay so Motion uses a video4linux device or network camera to detect motion. if motion is detected both normal and motion pictures can be taken. Motion can also take actions to notify you if needed. creation of automated snapshots is also possible. she's literally doing the most, and we're obsessed. 💅

💅 OPTIONS 💅

  • -c — full path and filename of config file. for example: /home/kurt/motion.conf the default is /usr/local/etc/motion unless specified differently when building Motion. many RPMs and Debian packages will use /etc or /etc/motion as the default. 💖
  • -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 the log file. 🗂️
  • -p — full path and filename for process id file (pid file). e.g. /var/run/motion.pid. default is not defined. pid file is only created when Motion is started in daemon mode. 👀
  • -m — start in pause mode. ⏸️

🎀 CONFIG FILE OPTIONS 🎀

okay so these are the options that can be used in the config file. they are overridden by the commandline! all number values are integer numbers (no decimals allowed). boolean options can be on or off (values "1", "yes" and "on" all means true and any other value means false). periodt. 💖

daemon 💤

  • Values: on/off
  • Default: off
  • Description: when specified as ON, Motion goes into daemon (background process) mode and releases the terminal. 👑

setup_mode 🛠️

  • Values: on/off
  • Default: off
  • Description: start in Setup-Mode, daemon disabled. ✨

pid_file 🆔

  • Values: User specified string
  • Default: Not defined
  • Description: file to store the process ID, also called pid file. 📌

log_file 📜

  • Values: User specified string
  • Default: Not Defined
  • Description: file to save logs messages, if not defined stderr and syslog is used. 🗂️

log_level 📶

  • Values: 1 to 9 (EMG, ALR, CRT, ERR, WRN, NTC, INF, DBG, ALL)
  • Default: 6 / NTC
  • Description: specify the level of verbosity in the messages sent to the log. 🔍

log_type 🏷️

  • Values: COR, STR, ENC, NET, DBL, EVT, TRK, VID, ALL
  • Default: ALL
  • Description: filter to log messages by type. 🧐

quiet 🤫

  • Values: on/off
  • Default: on
  • Description: do not sound beeps when detecting motion. 🔇

native_language 🌍

  • Values: boolean
  • Default: on
  • Description: use this option to enable native language on the webcontrol and log message. specify off to have messages provided in English. 💬

camera_name 📷

  • Values: User specified string
  • Default: Not Defined
  • Description: user specified string to describe the camera. 🏷️

camera_id 🔢

  • Values: Numeric identification number for the camera
  • Default: The order in which the camera is opened by Motion
  • Description: use this option to assign a number to each camera that is consistent every time that Motion is started. by default Motion will assign a number based upon the sequence in which it reads the configuration and this sequence may not be the same every time that Motion starts. 🎯

camera 🎥

  • Values: User specified string
  • Default: Not Defined
  • Description: this option specifies the full path and file name to individual camera files. this option can be listed multiple times. each camera file should contain the options that are unique to that camera/video device. common options are obtained from the motion.conf file and values are overwritten from each camera file. while the motion.conf includes four sample camera files, the actual limit of cameras is only dependent upon the machine capabilities. Remember: if you have more than one camera you must have one camera file for each one. For example, 2 cameras would require 3 files: The motion.conf file AND camera1.conf and camera2.conf. only put the options that are unique to each camera in the camera config files. 📸

camera_dir 📁

  • Values: User specified string
  • Default: Not Defined
  • Description: this option specifies the optional subdirectory that contains the camera config files. 🗂️

target_dir 🎯

  • Values: User specified string
  • Default: Not defined
  • Description: target base directory for pictures and films. it is recommended to use an absolute path. if this option is not defined, the current working directory is used. this option accepts the conversion specifiers included at the end of this manual. 📂

video_device 🎛️

  • Values: User specified string
  • Default: /dev/video0
  • Description: string to specify the video device to be used for capturing. the format is usually /dev/videoX where X varies depending upon the video devices connected to the computer. for FreeBSD certain devices use the bktr subsystem and they will use /dev/bktr0. 📹

video_params ⚙️

  • Values: User specified string
  • Default: None
  • Description: string to specify the parameters to pass in for a video_device. the parameters permitted are dependent upon the device. this only applies to V4L2 devices. the Motion log reports all the available options for the device. 🔧

auto_brightness ☀️

  • Values: 0 - 3
  • Default: 0
  • Description: the auto_brightness feature uses the device options to adjust the brightness. only recommended for cameras without auto brightness. 0-disabled, 1=Use brightness, 2=Use exposure, 3=Use absolute exposure. 💡

tuner_device 📺

  • Values: User Specified String
  • Default: /dev/tuner0
  • Description: tuner device to be used for capturing images. this is ONLY used for FreeBSD. 📡

roundrobin_frames 🔄

  • Values: 1 to unlimited
  • Default: 1
  • Description: number of frames to capture in each roundrobin step. 🎞️

roundrobin_skip ⏭️

  • Values: 1 to unlimited
  • Default: 1
  • Description: number of frames to skip before each roundrobin step. ⏩

roundrobin_switchfilter 🧹

  • Values: on/off
  • Default: off
  • Description: filter out noise generated by roundrobin. ✨

netcam_url 🌐

  • Values: User specified string
  • Default: None
  • Description: full connection URL string to use to connect to a network camera. in addition to standard camera protocols, the following prefixes are added by the Motion application.

ftp:// mjpg:// mjpeg:// file:// v4l2://

the connection string is camera specific. it is usually the same as what other video playing applications would use to connect to the camera stream. 🔗

netcam_params 🔧

  • Values: User specified string
  • Default: Not Defined
  • Description: user specified parameters for the network camera. ⚙️

netcam_high_url 📹

  • Values: User specified string
  • Default: None
  • Description: full connection URL string to use to connect to a high resolution network camera. the URL must provide a stream of images instead of only a static image. the following prefixes are recognized

rtsp:// rtmp://

the connection string is camera specific. it is usually the same as what other video playing applications would use to connect to the camera stream. Motion currently only supports basic authentication for the cameras. Digest is not currently supported. Basic authentication can be specified in the URL or via the netcam_userpass option. 🔐

netcam_high_params 🔩

  • Values: User specified string
  • Default: Not Defined
  • Description: user specified parameters for the network camera. 🛠️

netcam_userpass 🔐

  • Values: User specified string
  • Default: Not Defined
  • Description: the user id and password required to access the network camera string. only basic authentication is supported at this time. format is in user:password format when both a user name and password are required. 🔑

width ↔️

  • Values: Dependent upon video device
  • Default: 640
  • Description: image width in pixels for the video device. 📏

height ↕️

  • Values: Dependent upon video device
  • Default: 480
  • Description: image height in pixels for the video device. 📐

framerate 🎞️

  • Values: 2 - 100
  • Default: 15
  • Description: the maximum number of frames to capture in 1 second. the default of 100 will normally be limited by the capabilities of the video device. typical video devices have a maximum rate of 30. 🎬

minimum_frame_time ⏱️

  • Values: 0 to unlimited
  • Default: 0
  • Description: the minimum time in seconds between capturing picture frames from the camera. the default of 0 disables this option and relies upon the capture rate of the camera. this option is used when you want to capture images at a rate lower than 2 per second. ⏳
  • rotate — spin your whole image around by this many degrees, bestie 💫
    • Values: 0, 90, 180, 270
    • Default: 0
    • This rotation hits all your saved images and your movies. Everything. No escape. 🌀
  • flip_axis — flip the images vertically or horizontally ✨
    • Values: none, v, h
    • Default: none
    • Same energy as rotate: it affects all saved images as well as movies. 🦋
  • locate_motion_mode — find the moving thing and draw a lil box around it 🎯
    • Values: on/off/preview
    • Default: off
    • Set it to 'on' and it locates the moving object and draws a box around it. Set it to 'preview' and it only draws that box in preview_shot pictures. Sneaky, lowkey. 🙈
  • locate_motion_style — okay but how do we mark it tho 👀
    • Values:
      • box : draw a traditional box around the part of the image generating the motion
      • redbox : draw a red box around the part of the image generating the motion
      • cross : draw a cross on the part of the image generating the motion
      • redcross : draw a red cross on the part of the image generating the motion
    • Default: box
    • When locate_motion_mode is enable, this option specifies how the motion will be indicated on the image. 💅
  • text_left — text for the lower left corner 🎀
    • Values: User specified string
    • Default: Not defined
    • Text to place in lower left corner of image. Format specifiers follow C function strftime(3). ⏰
  • text_right — text for the lower right corner 🫶
    • Values: User specified string
    • Default: %Y-%m-%d\n%T
    • Text to place in lower right corner of image. Format specifiers follow C function strftime(3). ⏰
  • text_changes — show off how much stuff moved 📊
    • Values: on/off
    • Default: off
    • When specified, draw the number of changed pixed on the images. This option will normally be set to off except when you setup and adjust the motion settings. The text is placed in upper right corner of the image. 🧚
  • text_scale — how big we drawing that text 🔍
    • Values: 1 to 10
    • Default: 1
    • The scale at which to draw text over the image. ⭐
  • text_event — the special event name-maker 🎉
    • Values: User specified string
    • Default: %Y%m%d%H%M%S
    • Define the value of the special event conversion specifier %C. The user 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. The %C can be used filenames and text_left/right for creating a unique identifier for each event. 🔥
  • emulate_motion — fake it till you make it, motion edition 😭
    • Values: on/off
    • Default: off
    • Always save images even if there was no motion. fr fr, zero motion, still saving. 💀
  • pause — hold up, pause the detection ⏸️
    • Values: on/off
    • Default: off
    • When Motion is started, pause the motion detection.
  • threshold — how much has to change before we call it motion 🚨
    • Values: 1 to unlimited
    • Default: 1500
    • Threshold for number of changed pixels in an image that triggers motion detection.
  • threshold_maximum — and a ceiling for that 🧱
    • Values: 0, 1 to unlimited
    • Default: 0
    • Maximum of changed pixels in an image that triggers motion detection. A value of zero disables this option.
  • threshold_tune — auto-tune that threshold 🎚️
    • Values: on/off
    • Default: off
    • Automatically tune the threshold down if possible.
  • noise_level — background noise? not today 🌫️
    • Values: 1 to unlimited
    • Default: 32
    • Noise threshold for the motion detection.
  • noise_tune — auto-tune the noise 🌊
    • Values: on/off
    • Default: on
    • Automatically tune the noise threshold.
  • despeckle_filter — clean up the messy lil speckles 🧼
    • Values:
      • e/E : erode
      • d/D : dilate
      • l : label
    • Default: Not defined
    • Despeckle motion image using (e)rode or (d)ilate or (l)abel. The 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. 👑
  • area_detect — trigger scripts from specific zones 📍
    • Values: 1 to 9
    • Default: Not Defined
    • When motion is detected in the predefined areas indicated below, trigger the script indicated by the on_area_detected. The trigger is only activated once during an event. one or more areas can be specified with this option. Note that this option is only used to trigger the indicated script. It does not limit all motion detection events to only the area indicated.
       Image Areas
       123
       456
       789
  • mask_file — a PGM mask telling motion where to look 👀
    • Values: User specified string
    • Default: Not defined
    • When particular area should be ignored for motion, it can be accomplished using a PGM mask file. The PGM mask file is a specially constructed mask file that allows the user to indicate the areas for which motion should be monitored. This option specifies the full path and name for the mask file.
  • mask_privacy — a PGM mask that hides stuff from every image 🙈
    • Values: User specified string
    • Default: Not defined
    • The PGM mask file is a specially constructed mask file that allows the user to indicate the areas to remove from all images. This option specifies the full path and name for the privacy mask file.
  • smart_mask_speed — how fast the dynamic mask changes 🏃‍♀️
    • Values: 0 to 10
    • Default: 0 (off)
    • Speed of mask changes when creating a dynamic mask file.
  • lightswitch_percent — ignore the lights getting flipped on 💡
    • Values: 0 to 100
    • Default: 0
    • Ignore sudden massive light intensity changes. Triggers when the percentage of the picture area that changed intensity is greater than this value.
  • lightswitch_frames — how many frames we sit out after that 💤
    • Values: 1 to 1000
    • Default: 5
    • Number of frames to ignore when lightswitch has been triggered.
  • minimum_motion_frames — how many frames in a row before we commit 🎬
    • Values: 1 to unlimited
    • Default: 1
    • The minimum number of picture frames in a row that must contain motion before a event is triggered. The default of 1 means that all motion is detected. The recommended range is 1 to 5.
  • event_gap — how long a silence ends an event ⏳
    • Values: -1 to unlimited
    • Default: 60
    • The number of seconds of no motion that triggers the end of an event. An event is defined as a series of motion images taken within a short timeframe. The recommended value is 60 seconds. The value -1 is allowed and disables events causing all Motion to be written to one single movie file and no pre_capture. If set to 0, motion is running in gapless mode. Movies don't have gaps anymore. An event ends right after no more motion is detected and post_capture is over.
  • pre_capture — the buffered pics from before the motion 👻
    • Values: 0 to unlimited
    • Default: 0
    • The number of pre-captured (buffered) pictures from before motion was detected that will be output upon motion detection. The recommended range is 0 to 5. It is not recommended to use large values since it will cause Motion to skip frames. To smooth movies use larger values of post_capture instead.
  • post_capture — and the pics after the motion 🎞️
    • Values: 0 to unlimited
    • Default: 0
    • Number of frames to capture after motion is no longer detected.

🎬 Script Options 💖

  • 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
    • Values: User defined string
    • Default: Not defined
    • Specify the full path and file name for the script to execute when the indicated event occurs. When a file name is required for the script, append a %f to the script string. 🫶
  • picture_output — when do we save pics 📸
    • Values: on, off, first, best, center
    • Default: off
    • Output pictures when motion is detected. 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'. Picture with motion nearest center of picture is saved when set to 'center'. Can be used as preview shot for the corresponding movie. 🌈
  • picture_output_motion — ghost images only, iconic tbh 👻
    • Values: on/off
    • Default: off
    • Output pictures with only the pixels moving object (ghost images).
  • picture_type — pick your format 🖼️
    • Values: jpeg/ppm/webp/grey
    • Default: jpeg
    • The file type of output images.
  • picture_quality — how crispy 💎
    • Values: 1 to 100
    • Default: 75
    • The quality (in percent) to be used by the jpeg and webp compression.
  • picture_exif — a lil note in the EXIF 💌
    • Values: User specified string
    • Default: Not defined
    • Text to include in a JPEG EXIF comment.
  • picture_filename — bestie, this is the file path for your motion triggered images (jpeg, ppm or webp), relative to target_dir. 💖
    • Values: User specified string
    • Default: %v-%Y%m%d%H%M%S-%q
    • The file extension .jpg, .ppm or .webp gets added automatically, so do not include it yourself, okay? 🫶
    • Set it to 'preview' and team it up with the best-preview feature and you unlock a special naming convention for preview shots. ✨
    • This option accepts the conversion specifiers included at the end of this manual.
  • snapshot_interval — how often we're out here snatching snapshots. 📸
    • Values: 0 to unlimited
    • Default: 0
    • When it's 0, the snapshot feature is straight up disabled, periodt. When you give it a value, that value is the number of seconds between snapshots.
  • snapshot_filename — the file path for snapshots, relative to target_dir. 🎀
    • Values: User specified string
    • Default: %v-%Y%m%d%H%M%S-snapshot
    • The file extension .jpg, .ppm or .webp is automatically added so do not include this.
    • A symbolic link called lastsnap.jpg created in the target_dir will always point to the latest snapshot — unless snapshot_filename is exactly 'lastsnap'. 👀
    • This option accepts the conversion specifiers included at the end of this manual.
  • movie_output — use ffmpeg to encode movies of the motion. cinema, but make it yours. 🎬
    • Values: on/off
    • Default: on
  • movie_output_motion — use ffmpeg to encode movies with only the pixels of the moving object. ghost images, lowkey iconic. 👻
    • Values: on/off
    • Default: off
  • movie_max_time — the maximum length in seconds of a movie. ⏱️
    • Values: 0 to unlimited
    • Default: 120
    • When the value is exceeded, a new movie file gets created. A value of 0 means there is no limit at all, go off.
  • movie_bps — the bitrate to be used by the ffmpeg encoder. 💅
    • Values: 0 to unlimited
    • Default: 400000
    • This option is ignored if movie_quality is not 0.
  • movie_quality — enable and define the variable bitrate for the ffmpeg encoder. 🌈
    • Values: 0 to 100
    • Default: 60
    • movie_bps is ignored if variable bitrate is enabled.
    • When specified as 0, use the fixed bitrate defined by movie_bps.
    • When defined as 1 - 100, it varies the quality of the movie. A value of 1 is worst quality versus a value of 100 is best quality. slay.
  • movie_codec — for regular motion videos, the container/codec must be available in the ffmpeg installed on the computer. no cap, check your install first. 🔍
    • Values:
      • Motion videos:
        • mpeg4 - Creates .avi file
        • msmpeg4 - Creates .avi file
        • swf - Flash film with extension .swf
        • flv - Flash video with extension .flv
        • ffv1 - FF video codec 1 for Lossless Encoding
        • mov - QuickTime
        • mp4 - MPEG-4 Part 14 H264 encoding
        • mkv - Matroska H264 encoding
        • hevc - H.265 / HEVC (High Efficiency Video Coding)
    • Default: mkv
  • movie_duplicate_frames — when creating videos, should frames be duplicated in order to keep up with the requested frames per second? 🌀
    • Values: on/off
    • Default: off
  • movie_passthrough — when using a rtsp camera, make movies without decoding the stream. efficiency queen. 👑
    • Values: on/off
    • Default: off
  • movie_filename — file path for motion triggered ffmpeg films (movies), relative to target_dir. 🍓
    • Values: User specified string
    • Default: %v-%Y%m%d%H%M%S
    • The extensions (.swf, .avi, etc) are automatically added so do not include them.
    • This option accepts the conversion specifiers included at the end of this manual.
  • movie_extpipe_use — use the external pipe in order to encode videos. 🔥
    • Values: on/off
    • Default: off
    • This is a replacement option for the FFMPEG builtin encoder for movie_output only.
    • The options movie_filename and timelapse_filename are also used from the ffmpeg feature.
  • movie_extpipe — command line string to receive and process a pipe of images to encode. 🫶
    • Values: User specified string
    • Default: Not defined
    • Generally, use '-' for STDIN.
  • timelapse_interval — number of seconds between frame captures for a timelapse movie. ⏳
    • Values: 0 to unlimited
    • Default: 0
    • Specify 0 to disable the timelapse.
  • timelapse_mode — file rollover mode for the timelapse video. 🎞️
    • Values:
      • hourly
      • daily
      • weekly-sunday
      • weekly-monday
      • monthly
      • manual
    • Default: daily
  • timelapse_fps — frames per second used for playback of the timelapse video. 🌸
    • Values: 0 to unlimited
    • Default: 30
  • timelapse_codec — for mpg timelapse videos, if motion is shutdown and restarted, new pics will be appended to any previously created file with the name indicated for timelapse. For mpeg4 timelapse videos, if motion is shutdown and restarted, new pics will create a new file with the name indicated for timelapse. different vibes, both valid. 💫
    • Values:
      • mpg - Creates mpg file with mpeg-2 encoding.
      • mpeg4 - Creates avi file with the default encoding.
    • Default: mpg
  • timelapse_filename — file path for timelapse movies relative to target_dir. 🎀
    • Values: User specified string
    • Default: %Y%m%d-timelapse
    • The file extensions (.mpg .avi) are automatically added so do not include them.
    • This option accepts the conversion specifiers included at the end of this manual.
  • video_pipe — output images to a video4linux loopback device. 🦋
    • Values: User specified string
    • Default: Not Defined
  • video_pipe_motion — output motion images to a video4linux loopback device. ✨
    • Values: User specified string
    • Default: Not Defined
  • webcontrol_port — port number for the web control / preview page. 🌐
    • Values: 0 to maximum port number
    • Default: 0
  • webcontrol_ipv6 — listen to IPv6 localhost instead of IPv4. 👑
    • Values: on/off
    • Default: off
    • This option is also applicable for all streams.
  • webcontrol_localhost — restrict control connections to localhost only. safety first, bestie. 🔒
    • Values: on/off
    • Default: on
  • webcontrol_parms — the type of parameters that are able to be modified via the web interface. 🛠️
    • Values:
      • 0 = No parameters available to change on web control
      • 1 = Limited list of parameters available to change
      • 2 = Advanced list of parameters (usually requires restart to become effective)
      • 3 = Restricted list of parameters (User IDs, passwords, commands to execute, etc)
    • Default: 0
    • > This parameter can never be modified via the web interface and must be specified directly in the configuration file. no shortcuts, babes. 💀
  • webcontrol_interface — specifies the web control interface type. 🎨
    • Values: 0-2
    • Default: 0
    • 0=css, 1=text, 2=legacy
  • webcontrol_auth_method — the authentication method to use for the webcontrol. 🔐
    • Values:
      • 0 = disabled
      • 1 = Basic authentication
      • 2 = MD5 digest (the safer authentication)
    • Default: 0
  • webcontrol_authentication — the username and password to use for authentication of the webcontrol. 🙈
    • Values: User specified string
    • Default: Not defined
    • The format is Username:Password
  • webcontrol_tls — when specified as on, use SSL/TLS for the webcontrol. 🔒✨
    • Values: on/off
    • Default: off
  • webcontrol_cert — the full path to the SSL certification file for webcontrol. 📜
    • Values: User specified string
    • Default: Not defined
  • webcontrol_key — the full path to the SSL key file for webcontrol. 🗝️
    • Values: User specified string
    • Default: Not defined
  • webcontrol_header_params — the comma separated header=value pairs to use for the webcontrol responses. 💌
    • Values: User specified string
    • Default: Not defined
  • webcontrol_lock_attempts — the number of failed authentication attempts before IP is locked out. 🚫
    • Values: integer
    • Default: 5
  • webcontrol_lock_minutes — the number of minutes a failed authentication IP is locked out. ⏲️
    • Values: integer
    • Default: 5
  • webcontrol_lock_max_ips — the maximum number of concurrent IPs that can be locked out. 🌈
    • Values: integer
    • Default: 5
  • stream_port — this option is the port number that the mini-http server listens on for streams of the pictures. 📺
    • Values: 0 to port number limit
    • Default: 0
  • stream_localhost — restricts stream connections to localhost only 💖
    • Values: on/off
    • Default: on
    • Description: Restrict stream connections to localhost only
  • stream_auth_method — the authentication method to use for viewing the stream 🔐
    • Values:
      • 0 = disabled
      • 1 = Basic authentication
      • 2 = MD5 digest (the safer authentication)
    • Default: 0
    • Description: The authentication method to use for viewing the stream.
  • stream_authentication — the username and password for stream auth 🫶
    • Values: User specified string
    • Default: Not defined
    • Description: The username and password to use for authentication of the stream. The format is Username:Password
  • stream_tls — turn on SSL/TLS for the stream port ✨
    • Values: on/off
    • Default: off
    • Description: When specified as on, use SSL/TLS for the stream port.
  • stream_header_params — extra header pairs for stream responses 🎀
    • Values: User specified string
    • Default: Not defined
    • Description: The comma separated header=value pairs to send for the stream responses.
  • stream_preview_scale — how much to scale preview images 🦋
    • Values: 1 to 100
    • Default: 25
    • Description: This defines what percentage the stream image should be scaled to for the preview page
  • stream_preview_newline — stack preview images or keep them side by side 🌸
    • Values: on/off
    • Default: off
    • Description: When the image is put on the preview page, should the image start on a new line. This option allows the user to specify whether the preview images should be side by side or stacked on the page.
  • stream_preview_method — how images show up on the webcontrol page 💅
    • Values: 0 to 2
    • Default: 0
    • Description: Method to display images on webcontrol page. 0=Full, 1=Substream, 2=Static
  • stream_quality — jpg quality percent for the stream 🔥
    • Values: 1 to 100
    • Default: 50
    • Description: The quality in percent for the jpg images streamed.
  • stream_grey — send the live stream in black and white 🖤
    • Values: on/off
    • Default: off
    • Description: Send the live stream of the camera in grey (black and white) instead of color.
  • stream_maxrate — maximum frame rate for the stream 🏃‍♀️
    • Values: 1 to unlimited
    • Default: 1
    • Description: Maximum frame rate to send to stream
  • stream_motion — drop to 1 fps when nothing is moving 👀
    • Values: on,off
    • Default: off
    • Description: Limit stream to 1 fps when no motion is being detected.
  • database_type — which database bestie are we using 🗄️
    • Values: mysql, mariadb, postgresql, sqlite3
    • Default: Not defined
    • Description: The type of database being used.
  • database_dbname — the database name (or SQLite3 path) 📁
    • Values: User defined string
    • Default: Not defined
    • Description: The name of the database being used (dbname). For SQLite3, the full path to the database.
  • database_host — where the database lives 🌐
    • Values: User defined string
    • Default: localhost
    • Description: The hostname, DNS name, or IP address at which the database is running. Optionally for PostgreSQL, full path of the local directory containing its Unix domain pipe. For SQLite3, ignored.
  • database_port — TCP port for database access 🔌
    • Values: 0 to maximum port number
    • Default: Not defined
    • Description: TCP port number used for database access. For SQLite3, ignored. Default ports used by DBMSs: MySQL & MariaDB, 3306; PostgreSQL, 5432.
  • database_user — username to access the database 🙋‍♀️
    • Values: User defined string
    • Default: Not Defined
    • Description: The username to access the database. For SQLite3, ignored.
  • database_password — password for that database user 🔑
    • Values: User defined string
    • Default: Not Defined
    • Description: The database password for the user to access the database. For SQLite3, ignored.
  • database_busy_timeout — SQLite3 wait time for locked database ⏳
    • Values: 0 to unlimited
    • Default: 0
    • Description: SQLite3 only: database wait time in milliseconds for locked database to be unlocked before returning database locked error
  • sql_log_picture — log when a motion-triggered picture is created 📸
    • Values: on/off
    • Default: off
    • Description: Log to the database when creating motion triggered picture file
  • sql_log_snapshot — log when a snapshot image file is created 🖼️
    • Values: on/off
    • Default: off
    • Description: Log to the database when creating a snapshot image file
  • sql_log_movie — log when a motion-triggered movie file is created 🎬
    • Values: on/off
    • Default: off
    • Description: Log to the database when creating motion triggered movie file
  • sql_log_timelapse — log when timelapse movie files are created ⏱️
    • Values: on/off
    • Default: off
    • Description: Log to the database when creating timelapse movies file
  • sql_query — the SQL that runs when Motion saves an image or starts recording 🧾
    • Values: User defined string
    • Default: Not defined
    • Description: SQL statement to execute when Motion saves an image file or begins recording a movie and the corresponding file type's sql_log_* configuration option is set on. Use same conversion specifiers as for text features. Additional special conversion specifiers are:
      • %n = the number representing the file_type
      • %f = filename with full path
    • Sample table set up (not sql_query):
Mysql:  CREATE TABLE security (camera INTEGER NOT NULL, filename CHAR(80) NOT NULL, frame INTEGER, file_type INTEGER NOT NULL, time_stamp DATETIME NOT NULL, text_event CHAR(255));
Postgresql: CREATE TABLE security (camera INTEGER NOT NULL, filename VARCHAR NOT NULL, frame INTEGER, file_type INTEGER NOT NULL, time_stamp TIMESTAMP NOT NULL, text_event VARCHAR);
  • Sample sql_query
INSERT INTO security(camera, filename, frame, file_type, time_stamp, text_event) VALUES(%t, '%f', %q, %n, '%Y-%m-%d %T', '%C')
  • sql_query_start — SQL that runs at the start of a motion event 🚦
    • Values: User defined string
    • Default: Not defined
    • Description: SQL statement to execute at the start of a motion event. When the related table schema (and, for PostgreSQL, a RETURNING clause included in this statement) provide for it, the database generates a table-unique event ID that is returned and substituted for the %{dbeventid} conversion specifier. When no valid value is returned, %{dbeventid} is replaced by zero.
  • sql_query_stop — SQL that runs when a motion event movie or timelapse movie closes 🛑
    • Values: User defined string
    • Default: Not defined
    • Description: SQL statement to execute upon closure of a motion event movie or timelapse movie file, provided the corresponding file type's sql_log_* configuration option is set on.
  • track_type — what kind of tracker are we working with 🎯
    • Values:
      • 0 = none
      • 1 = stepper
      • 2 = iomojo
      • 3 = pwc
      • 4 = generic
      • 5 = uvcvideo
      • 6 = servo
    • Default: 0
    • Description: This option specifies the type of tracker. The generic type enables the definition of motion center and motion size to be used with the conversion specifiers for options like on_motion_detected
  • track_auto — automatic tracking on or off 🤖
    • Values: on/off
    • Default: off
    • Description: Enables/disables the automatic tracking.
  • track_port — serial port of the motor 🔌
    • Values: User specified string
    • Default: Not defined
    • Description: The serial port of the motor. For example /dev/ttyS0
  • 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 — the tracking parameter squad 👑
    • Values: device dependent
    • Default: 0
    • Description: These options specify the parameters for cameras with tracking capabilities.
  • track_generic_move — script to run for generic tracking movement 📜
    • Values: User specified string
    • Default: Not defined
    • Description: Full path and file name for the script to execute to move a camera in generic tracking mode.

📡 SIGNALS

Motion responds to the following signals:

  • SIGHUP — The config file will be reread. 🔄
  • 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. 🎥

📝 NOTES

  • Snapshot — A snapshot is a picture taken at regular intervals independently of any movement in the picture. 📷
  • Motion image — A "motion" image/movie shows the pixels that have actually changed during the last frames. These pictures are not very useful for normal presentation to the public but they are quite useful for testing and tuning and making mask files as you can see exactly where motion sees something moving. Motion is shown in greytones. If labelling is enabled the largest area is marked as blue. Smart mask is shown in read. 👻
  • Normal image — A "normal" image is the real image taken by the camera with text overlayed. 🖼️

💾 Cameras and config files 💾

Okay bestie, this is the part where Motion figures out which config file to read and how it handles your whole camera situation, and it's giving very organized queen energy. Let's go. ✨

If Motion got invoked with the command line option -c pathname, then Motion is gonna expect the config file to be exactly the one you specified. And the slay part? When you pass the config file on the command line with -c, you can name it literally anything. No rules. Free spirit. 🦋

But if you don't pass -c, or the filename you gave Motion doesn't actually exist, Motion goes hunting for a config file called motion.conf, and it searches in this exact order:

  1. The current directory from where motion was invoked
  2. Then a directory called .motion inside the current user's home directory (shell environment variable $HOME). Like, for example, /home/goofy/.motion/motion.conf
  3. The motion/ subdirectory inside the directory defined by the --sysconfdir=DIR when you ran .configure during installation of Motion (and if that option wasn't defined, the default is /usr/local/etc/)

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. One. Singular. Not a whole collection. 💅

Motion ships with a config 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.

And here's the tea: that config file needs to be renamed from motion-dist.conf to motion.conf. Why is the original called motion-dist.conf? Because the naming means your perfectly working motion.conf does not accidentally get overwritten when you re-install or upgrade to a newer version of Motion. Protective king behavior, honestly. 👑

Now, if you have more than one camera, do not try and invoke Motion a bunch of times. Just don't. Motion is built to work with more than one camera in a very elegant way, and the way to do it is to create a number of camera config files. Motion will then spin up an extra thread of itself for each camera. So if you've only got one camera, you only need the motion.conf file. But the minute you have two or more cameras, you must have one camera config file per camera besides the motion.conf file.

So, say you've got two cameras? You need motion.conf plus two camera config files. That's 3 config files total. Math is math. 🔢

An option that's common to all cameras can live in motion.conf. (You can also put all parameters in the camera files, but that makes for a lot of editing when you change one common thing. Nobody wants that.) An option that is unique to a camera must be defined 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 gets used for all cameras, except for the cameras where that same option is defined in a camera config file.

Motion reads its configuration parameters in this sequence, and if the same parameter exists in 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 defined 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 at the end of the motion.conf file. Because if you define options in motion.conf after the camera file calls, the same options in the camera files will never be used. Never ever. So always put the camera file call at the end of motion.conf. Periodt. 🎀

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

And if you run the http control command

http://host:port/0/config/writeyes

motion will overwrite motion.conf and all the camera.conf files with autogenerated config files, neatly formatted, and only with the features included that Motion was built with. Then if you later re-build Motion with more features or upgrade to a new version, you can use your old config files, run the motion.conf.write command, and boom — you'll have new config files with the new options included, all set to their default values. This makes upgrading very easy to do. Upgrading? Easy. Iconic. 🔥

🌈 Conversion Specifiers for Advanced Filename and Text Features 🌈

The table below shows all the supported Conversion Specifiers you can use in the options text_left, text_right, snapshot_filename, jpeg_filename, ffmpeg_filename, timelapse_filename, on_event_start, on_event_end, on_picture_save, on_movie_start, on_movie_end, and on_motion_detected.

And in text_left and text_right you can additionally use '\n' for a new line. Cute, right? 💖

  • %a — The abbreviated weekday name according to the current locale.
  • %A — The full weekday name according to the current locale.
  • %b — The abbreviated month name according to the current locale.
  • %B — The full month name according to the current locale.
  • %c — The preferred date and time representation for the current locale.
  • %C — Text defined by the text_event feature.
  • %d — The day of the month as a decimal number (range 01 to 31).
  • %D — Number of pixels detected as Motion. If labelling is enabled the number is the number of pixels in the largest labelled motion area.
  • %E — Modifier: use alternative format, see below.
  • %f — File name — used in the on_picture_save, on_movie_start, on_movie_end, and sql_query features.
  • %F — Equivalent to %Y-%m-%d (the ISO 8601 date format).
  • %h — The height of the image.
  • %H — The hour as a decimal number using a 24-hour clock (range 00 to 23).
  • %i — Width of the rectangle containing the motion pixels (the rectangle that is shown on the image when locate is on).
  • %I — The hour as a decimal number using a 12-hour clock (range 01 to 12).
  • %j — The day of the year as a decimal number (range 001 to 366).
  • %J — Height of the rectangle containing the motion pixels (the rectangle that is shown on the image when locate is on).
  • %k — The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. (See also %H.)
  • %K — X coordinate in pixels of the center point of motion. Origin is upper left corner.
  • %l — The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. (See also %I.)
  • %L — Y coordinate in pixels of the center point of motion. Origin is upper left corner and number is positive moving downwards (I may change this soon).
  • %m — The month as a decimal number (range 01 to 12).
  • %M — The minute as a decimal number (range 00 to 59).
  • %n — Filetype as used in the on_picture_save, on_movie_start, on_movie_end, and sql_query features.
  • %N — Noise level.
  • %o — Threshold. The number of detected pixels required to trigger motion. When threshold_tune is 'on' this can be used to show the current tuned value of threshold.
  • %p — Either 'AM' or 'PM' according to the given time value, or the corresponding strings for the current locale. Noon is treated as pm and midnight as am.
  • %P — Like %p but in lowercase: am or pm or a corresponding string for the current locale.
  • %q — Picture frame number within current second. For jpeg filenames this should always be included in the filename if you save more then 1 picture per second, to ensure unique filenames. It is not needed in filenames for mpegs.
  • %Q — Number of detected labels found by the despeckle feature.
  • %r — The time in a.m. or p.m. notation.
  • %R — The time in 24-hour notation (%H:%M).
  • %s — The number of seconds since the Epoch, i.e., since 1970-01-01 00:00:00 UTC.
  • %S — The second as a decimal number (range 00 to 61).
  • %t — Camera ID number.
  • %T — The time in 24-hour notation (%H:%M:%S).
  • %u — The day of the week as a decimal, range 1 to 7, Monday being 1. See also %w.
  • %U — The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also %V and %W.
  • %v — Event number. An event is a series of motion detections happening with less than 'gap' seconds between them.
  • %V — The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week. See also %U and %W.
  • %w — The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u.
  • %W — The week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01.
  • %x — The preferred date representation for the current locale without the time.
  • %X — The preferred time representation for the current locale without the date.
  • %y — The year as a decimal number without a century (range 00 to 99).
  • %Y — The year as a decimal number including the century.
  • %z — The time-zone as hour offset from GMT.
  • %Z — The time zone or name or abbreviation.
  • %$ — The camera name.
  • %{host} — The computer host name.
  • %{fps} — The frame per seconds.
  • %{dbeventid} — The id number returned from mysql_insert_id.
  • %{ver} — The version number of Motion.

🔗 More information 🔗

Motion homepage: https://motion-project.github.io/

Motion Guide (user and installation guide):

And yes, bestie — the link after that colon is literally just... blank in the page. Nothing there. Not me staring at it 💀. We report, we don't invent. 🙈

👑 AUTHORS 👑

Jeroen Vreeken (pe1rxq@amsat.org), Folkert van Heusden, Kenneth Lavrsen (kenneth@lavrsen.dk), Juan Angulo Moreno <juan@apuntale.com>, the motion-project team, and many others.

And that's a wrap on MOTION(1), babe! 🫶 This page came from the Motion project and it's dated 2020-10-19 — so if you're reading this and the date feels like a lil throwback, that's why. Go point a camera at something and make it move. 🌸✨ Byeee! 💜

📦 where this page comes from