Motion - External Commands

External Commands

Motion can execute external commands based on the motion detection and related events. They are all described in this section. The option quiet is also included in this section.

A redesign of the external commands was due. They were not very easy to understand, not all were flexible enough and some were missing. So a new external command feature set was made for 3.2.1 and on.

This is how the new script commands look like:

Function Old Option New Option Argument Appended
Start of event (first motion) execute on_event_start None
End of event (no motion for gap seconds) New! on_event_end None
Picture saved (jpg or ppm) onsave on_picture_save Filename of picture
Movie starts (mpeg file opened) onmpeg on_movie_start Filename of movie
Movie ends (mpeg file closed) onffmpegclose on_movie_end Filename of movie
Motion detected (each single frame with Motion detected) New! on_motion_detected None
Mail and sms has been removed because they were not configurable. If you want to send event-based mails or sms, just use one of those commands above and send the mail from that script. See What happened to mail and sms?

ALERT! Security Warning! Note that this feature also means you have to pay attention to the following.
  • Anyone with access to the remote control port (http) can execute any command on your computer with the same privileges as the user running Motion. Anyone can access your control port if you have not either limited access to localhost or limited access using firewalls in the server. You should always have a router between a machine running Motion with remote control enabled and the Internet and make sure the Motion control port is not accessible from the outside.
  • If you limit control port to localhost you still need to take care of any user logging into the server with any kind of GUI or terminal session. All it takes is a browser or single command line execution to change settings in Motion.
  • It is a good idea to run Motion as a harmless user. Not as root!!

These are the options

on_area_detected

  • Type: String
  • Range / Valid values: Max 4095 characters
  • Default: Not defined
  • Option Topic

Command to be executed when motion in a predefined area is detected. Check option area_detect.

on_camera_lost

  • Type: String
  • Range / Valid values: Max 4095 characters
  • Default: Not defined
  • Option Topic

Command to be executed when a camera can't be opened or if it is lost. You can use Conversion Specifiers and spaces as part of the command. Use %f for passing filename (with full path) to the command. (new in 3.2.10)

NOTE: There is situations when motion don't detect a lost camera!
It depends on the driver, some drivers dosn't detect a lost camera at all
Some hangs the motion thread. Some even hangs the PC!

on_event_end

  • Type: String
  • Range / Valid values: Max 4095 characters
  • Default: Not defined
  • Option Topic

Command to be executed when an event ends after a period of no motion. The period of no motion is defined by option gap. You can use Conversion Specifiers and spaces as part of the command.

Full path name of the program/script.

This can be any type of program or script. Remember to set the execution bit in the ACL and if it is a script type program such as perl or bash also remember the shebang line (e.g. #! /usr/bin/perl) as the first line of the script.

The command is run when an event is over. I.e. the number of seconds defined by the time 'gap' has passed since the last detection of motion and motion closes the mpeg file.

on_event_start

  • Type: String
  • Range / Valid values: Max 4095 characters
  • Default: Not defined
  • Option Topic

Command to be executed when an event starts. An event starts at first motion detected after a period of no motion defined by gap. You can use ConversionSpecifiers and spaces as part of the command.

Full path name of the program/script.

This can be any type of program or script. Remember to set the execution bit in the ACL and if it is a script type program such as perl or bash also remember the shebang line (e.g. #!/user/bin/perl) as the first line of the script.

The command is run when an event starts. I.e. the first motion is detected since the last event.

This option replaces the former options 'mail', 'sms' and 'execute'.

on_motion_detected

  • Type: String
  • Range / Valid values: Max 4095 characters
  • Default: Not defined
  • Option Topic

Command to be executed when a motion frame is detected. You can use Conversion Specifiers and spaces as part of the command.

Do not write "none" if you do not want to execute commands. Simply do not include the option in the file or comment it out by placing a "#" or ";" as the first character on the line before the execute command.

on_movie_end

  • Type: String
  • Range / Valid values: Max 4095 characters
  • Default: Not defined
  • Option Topic

Command to be executed when an ffmpeg movie is closed at the end of an event. You can use Conversion Specifiers and spaces as part of the command. Use %f for passing filename (with full path) to the command.

Full path name of the program/script.

This can be any type of program or script. Remember to set the execution bit in the ACL and if it is a script type program such as perl or bash also remember the shebang line (e.g. #!/user/bin/perl) as the first line of the script.

The command is run when an event is over. I.e. the number of seconds defined by the time 'gap' has passed since the last detection of motion and motion closes the mpeg file.

This option was previously called onffmpegclose.

Note that from Motion 3.2.4 the path name of the picture file is no longer appended to the command. Instead you can use the conversion specifier %f to insert the picture filename (full path) anywhere in the command.

Most common conversion specifiers

  • %Y = year, %m = month, %d = date
  • %H = hour, %M = minute, %S = second
  • %v = event
  • %q = frame number
  • %t = thread (camera) number
  • %D = changed pixels
  • %N = noise level
  • %i and %J = width and height of motion area
  • %K and %L = X and Y coordinates of motion center
  • %C = value defined by text_event
  • %f = filename with full path
  • %n = number indicating filetype

on_movie_start

  • Type: String
  • Range / Valid values: Max 4095 characters
  • Default: Not defined
  • Option Topic

Command to be executed when an mpeg movie is created. You can use Conversion Specifiers and spaces as part of the command. Use %f for passing filename (with full path) to the command.

Full path name of the program/script.

This can be any type of program or script. Remember to set the execution bit in the ACL and if it is a script type program such as perl or bash also remember the shebang line (e.g. #!/user/bin/perl) as the first line of the script. When you use ffmpeg the film is generated on the fly and on_movie_start then runs when the new mpeg file is created. Often you will want to use the on_movie_end option which runs when the mpeg file is closed and the event is over.

This option was previously called onmpeg.

Note that from Motion 3.2.4 the path name of the picture file is no longer appended to the command. Instead you can use the conversion specifier %f to insert the picture filename (full path) anywhere in the command.

Most common conversion specifiers

  • %Y = year, %m = month, %d = date
  • %H = hour, %M = minute, %S = second
  • %v = event
  • %q = frame number
  • %t = thread (camera) number
  • %D = changed pixels
  • %N = noise level
  • %i and %J = width and height of motion area
  • %K and %L = X and Y coordinates of motion center
  • %C = value defined by text_event
  • %f = filename with full path
  • %n = number indicating filetype

on_picture_save

  • Type: String
  • Range / Valid values: Max 4095 characters
  • Default: Not defined
  • Option Topic

Command to be executed when an image is saved. You can use Conversion Specifiers and spaces as part of the command. Use %f for passing filename (with full path) to the command.

Full path name of the program/script.

This can be any type of program or script. Remember to set the execution bit in the file access control list (chmod) and if it is a script type program such as perl or bash also remember the shebang line (e.g. #!/usr/bin/perl) as the first line of the script.

Note that from Motion 3.2.4 the path name of the picture file is no longer appended to the command. Instead you can use the conversion specifier %f to insert the picture filename (full path) anywhere in the command.

Most common conversion specifiers

  • %Y = year, %m = month, %d = date
  • %H = hour, %M = minute, %S = second
  • %v = event
  • %q = frame number
  • %t = thread (camera) number
  • %D = changed pixels
  • %N = noise level
  • %i and %J = width and height of motion area
  • %K and %L = X and Y coordinates of motion center
  • %C = value defined by text_event
  • %f = filename with full path
  • %n = number indicating filetype

quiet

  • Type: Boolean
  • Range / Valid values: on, off
  • Default: off
  • Option Topic

Be quiet, don't output beeps when detecting motion.

Only works in non-daemon mode.

What happened to mail and sms?

The 6 new on_xxxxx options replace the former execute, mail and sms options.

They are quite generic and flexible. These small bash scripts gives to the same functionality as mail and sms BUT you have all the flexibility you want to extend the messages, change the 'from' email address etc.

Sending email at start of event

_Script written by JoergWeber _
#!/bin/sh

# Motion sample script to send an e-mail at start of an event.
# Replaces the former 'mail' option.
# Just define this script as 'on_event_start'-script in motion.conf like that:
# on_event_start send_mail "%Y-%m-%d %T"

#change to suit your needs:
#location of 'mail' binary
MAIL="/usr/bin/mail"
#Destination e-mail address
TO="root@localhost"
#Subject of the e-mail
SUBJECT="Motion detected"

#Don't change anything below this line
echo -e "This is an automated message generated by motion.\n\nMotion detected: $1\n\n" | $MAIL -s "$SUBJECT" $TO

Sending SMS at start of event

_Script written by JoergWeber _

If you uncomment the line #/usr/local/bin/send_mail $1 you can combine both sending email and sms.
#!/bin/sh

# Motion sample script to send an sms at start of an event.
# Replaces the former 'sms' option.
# Just define this script as 'on_event_start'-script in motion.conf like that:
# on_event_start send_sms "%Y-%m-%d %T"
#
# If you want to send an e-mail message here as well, just uncomment the last
# line of this script.

#change to suit your needs:
#location of 'sms-client' binary
SMS_CLIENT="/usr/bin/sms_client"
#Destination sms number
TO="12345"

#Don't change anything below this line
$SMS_CLIENT $TO "Motion detected $1"

#/usr/local/bin/send_mail $1

-- KennethLavrsen - 22 Apr 2005

The bit that I wanted which wasn't obvious (to me) from the above was to have captured images (on motion) emailed to me as an attachement.

In motion.conf
on_picture_save /full/path/to/send_email

Then the contents of /full/path/to/send_email is

mutt -a $1 -- -s 'motion capture' you@example.com < '.'
Topic revision: r10 - 05 Nov 2012, ColinRussellConway
Copyright © 1999-2016 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Please do not email Kenneth for support questions (read why). Use the Support Requests page or join the Mailing List.
This website only use harmless session cookies. See Cookie Policy for details. By using this website you accept the use of these cookies.