Table of Contents
Amcrest HD Camera API
Commands to control the various functions of Amcrest Cameras. What commands or events are actually supported depend on your specific camera type.
Motion, Sound and other Events:
By default XTension will attempt to subscribe to Motion and Sound events. In order to work your camera must support those events and have them turned on and configured in the cameras own web pages or configuration app.
This command takes a list of available events that you wish to subscribe to. Each event will have a Unit in XTension created for it with a default name which you can change after the Unit is created. You must have the event turned on and configured in the camera first in order for these to work. Passing no parameters turns off event scanning in XTension, but does not disable any settings in the camera itself. Not all cameras support all events and will likely throw an error if you attempt to enable an event that is not supported.
Valid event entries according to the latest documentation that I was able to find are below. Please note that capitalization matters in the spelling or the camera will throw more errors.
- AlarmLocal (any local alarm or contact closure input)
- CrossLineDetection (someone or something has crossed over a configured line)
- LeftDetection (something has been left behind by someone)
- VideoAbnormalDetection (possibly a tampering attempt or covering of the camera or a malfunction)
- AudioMutation (This is a sound detection above the threshold set in the camera setup)
- AudioAnomoly (Not sure, something wrong with the sound sensing hardware?)
- VideoMotion (The “master” video motion event, see below for region support)
- MoveDetection (something configured has been moved)
- StorageFailure (the SD card has failed)
- AlarmOutput (the relay output has been turned on by some internal camera logic or config)
- HeatImagingTemper (for the thermal capable cams, an area configured is above or below the set temperature alarm)
Passing the word “default” returns the setting to the list of “VideoMotion”, “AudioMutation”.
To turn off event receiption:
tell xInterface “Amcrest Cam” to enableEvents()
to set VideoMotion, sound detection and storage low space:
tell xInterface “Amcrest Cam” to enableEvents( “VideoMotion”, “AudioMutation”, “StorageLowSpace”)
takes no parameters, writes the currently configured events to the XTension log for debugging or to know what is currently setup.
tell xInterface “Amcrest Cam” to logEvents()
Debug Log Events:
If you’re having trouble with the events system or want to help me gather data to enable newer ones you can send a True to this command and all information received from the Events server will be logged. This is potentially a lot of data so you won’t want to turn it on unless we are gathering data for some reason.
tell xInterface “Amcrest Cam” to debugLogEvents( True)
Enable Motion Regions:
The Amcrest Cams will let you configure some number of “regions” for the detection of motion. You can give these regions a name in the camera configuration and if you pass the names to this function then the plugin will create a plugin for each region that you pass and send them on and off as the regions have motion detected.
To turn off region motion support:
tell xInterface “Amcrest Cam” to enableMotionRegions()
to enable any number of regions pass all the names. Note that if you change the names of the regions in the camera you will have to also change this list.
tell xInterface “Amcrest Cam” to enableMotionRegions( “side yard”, “driveway”, “main road”, “walkway”)
Log Motion Regions:
Takes no parameters and writes the list of currently enabled motion regions to the log, just for debugging or to see what is currently configured.
tell xInterface “Amcrest Cam” to logMotionRegions()
Commands to control or manipulate the cameras image settings. Unless otherwise noted the value for all the settings is from 0 to 100. There are 2 additional optional parameters after that. The first is the “time section” which can be 0 for “normal” 1 for “Day” and 2 for “Night”, If not included this defaults to 0. The second optional parameter is the stream number. Some cameras or DVR’s can support many streams so you may have to tell it which input or camera you actually want the change to apply to. This defaults to 0.
tell xInterface “Amcrest Cam” to setBrightness( 50)
Set Chroma Suppress:
Not exactly sure what this one does. It’s in the API documentation but with no explanation.
tell xInterface “Amcrest Cam” to setChromaSuppress( 50)
tell xInterface “Amcrest Cam” to setContrast( 50)
tell xInterface “Amcrest Cam” to setGamma( 50)
tell xInterface “Amcrest Cam” to setHue( 50)
tell xInterface “Amcrest Cam” to setSaturation( 50)
All PTZ Commands unless otherwise noted will take an optional parameter at the end of the list if you need it to point to a stream other than stream 0. If you leave this out it will default to controlling stream 0.
Slightly different from other PTZ camera implementations this takes 3 values for pan, tilt and zoom. If you do not wish for one to move at all pass a zero. The numbers are relative to the current location so you can move in positive or negative directions. The values in the cameras are very large. On my camera anything below 1000 does not result in any motion at all, so do not be surprised if you need to pass something like 10000 to get the camera to go any significant distance. Optionally pass a 4th parameter for Channel if you need it to go to one other than 0.
tell xInterface “Amcrest Cam” to PTZMove( 10000, -4000, 1)
would move 10000 to the right, down by 4000 and zoom in by 1. Note that zoom changes are rather course in this and a better way to set the zoom will be coming in a future update.
Pass the preset number from 1 to 16 or more depending on the camera. Optionally pass the Channel number if it is other than 0.
tell xInterface “Amcrest Cam” to gotoPreset( 4)
Pass the preset number from 1 to 16 or more depending on the camera. Optionally pass the Channel number if it is other than 0. Saves the current camera position and zoom level as the numbered preset.
tell xInterface “Amcrest Cam” to setPreset( 13)
Pass the preset number and optionally a channel number to clear a preset.
tell xInterface “Amcrest Cam” to clearPreset( 4)
Pass the ID number of a previously programed tour to begin the camera moving through the Tour.
tell xInterface “Amcrest Cam” to startTour( 1)
This seems to require that the tour number that is running be passed as well, or perhaps this does not matter and passing any number will work to stop the currently running tour. Some experimentation may be necessary.
tell xInterface “Amcrest Cam” to stopTour( 2)
Amcrest cams allow you to tell the camera to begin recording to it’s internal SD card with these commands, This is separate from the recording in XTension via the “Record from” verb or the manual recording Unit.
Each of these commands also take the optional channel number.
Begin manual recording to the internal SD card or other destination as configured in the camera.
tell xInterface “Amcrest Cam” to manualRecord()
Returns the camera to it’s internal logic of when to record to it’s SD card. If you started a recording by setting the mode to Manual above then this command will return the control of recording to whatever settings you have set in the camera itself. Or if those are not calling for recording it will stop recording until they do.
tell xInterface “Amcrest Cam” to autoRecord()
Sets the internal camera mode to dont record. This command will disable any internal logic that might be set in the camera for when to record in response to events and also stop any manual recording that you may have started via the manualRecord command.
tell xInterface “Amcrest Cam” to stopRecording()
Allows the setting of the mode just like the above command but with a single command that takes a numerical value to set the mode. Optionally also takes a second Channel number that defaults to 0.
- 0 = Auto
- 1 = Manual
- 2 = Off
tell xInterface “Amcrest Cam” to recordMode( 1)
Status and Display:
The Channel title can be displayed over the video output and can be changed via these commands. This could be useful to overlay an event message or the temperature or anything else useful that would be more so to be dynamic.
Set Channel Title:
Takes a string parameter first which is what you would like to be displayed as the channel title and an optional second parameter for channel number if other than 0.
tell xInterface “Amcrest Cam” to setChannelTitle( “Kitchen: “ & (value of “Temperature Kitchen”) & “°F”)
Do Status Display:
If the Status on the camera is something like an indication of what event caused the recording to start it may be helpful to display a different status for only a short time. This command lets you set a temporary status and after a certain number of seconds return to some other status. First parameter is the new status, followed by the channel number “0” in most cases, followed by the status to return to after the timeout and lastly the number of seconds to keep the new status before returning.
To display that it was the porch motion that caused recording and then return to just the name after 5 seconds you could do something like:
tell xInterface “Amcrest Cam” to doStatusDisplay( “Porch: MOTION outside PIR”, 0, “Porch”, 5)
Sets the camera time to the Mac’s time.
tell xInterface “Amcrest Cam” to setTime()
I had some trouble making this work properly on my camera. It seems that a reboot is necessary to make the time actually change, but even so it may not until it next talks to a time server. Perhaps better to do this and then call the SetTime command as well.
tell xInterface “Amcrest Cam” to setDST( True)
Reboots the camera.
tell xInterface “Amcrest Cam” to reboot()