Mac Home Automation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
=====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. As of this writing all Amcrest cameras are supported to whatever extent they support the API. For streaming of video see the the [[video:rtsp|RTSP Video]] plugin page. Which has instructions for finding the correct URL for getting the video out of any Amcrest camera or device. There is a wide range of what is supported and how so your camera may do things slightly differently than documented here and may support only a subset of the commands. If you believe that the camera has functionality that I do not support at all please let me know and we can collect the information needed to get it working.

=====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.

====Enable Events:====
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, For doorbell cameras this is the doorbell pushed event.)
  * CrossLineDetection (someone or something has crossed over a configured line)
  * CrossRegionDetection (This seems to be the Object Detection that some cameras can do, see below on how best to use this)
  * IntelliFrame (the detector has detected some object, in some cameras this may just always be a human, but in others it may be anything else. This is a non-documented event and so may not be available on all cameras or in all situations.)
  * LeftDetection (something has been left behind by someone)
  * VideoAbnormalDetection (possibly a tampering attempt or covering of the camera or a malfunction)
  * FaceDetection
  * 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)
  * VideoMotionInfo (A much chattier version of the VideoMotion event, good if you need constant events while there is motion)
  * VideoUnFocus
  * WanderDetection
  * RioterDetection
  * ParkingDetection
  * MoveDetection (something configured has been moved)
  * StorageNotExist
  * StorageFailure (the SD card has failed)
  * StorageLowSpace
  * 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)

**Note that more events might be being added or more info added to existing ones, if you find an event that does not work properly or that is not supported at all please let me know.**


Passing the word “default” returns the setting to the list of “VideoMotion”, “AudioMutation”.

To turn off event receiption:
<code>
tell xInterface “Amcrest Cam” to enableEvents()
</code>

to set VideoMotion, sound detection and storage low space:
<code>
tell xInterface “Amcrest Cam” to enableEvents( “VideoMotion”, “AudioMutation”, “StorageLowSpace”)
</code>

====Human and other Object Detection:====

I have limited access to the fancier cameras that perform human and other object detection. It appears from my testing that there are 2 ways to get this information. The first is undocumented and has no extra information supplied and is the “IntelliFrame” event listed above. This is just an on or off that an object has been detected. Depending on the capabilities of the camera this may be a Human, or a car or anything else. This is definitely available on the AD410 doorbell camera and may be available on other devices as well.

The second is the “Cross Region Detection” event. Turning this on will enable it to send events that happen across the motion regions like the detection of a human or other object. If information is included about what kind of object has been detected then another Unit will automatically be made in XTension to receive these on and off events. In the case of a Human detection a new unit will be created with the address of “CROSSREGIONDETECTION.HUMAN” or if it is a car it would create a unit with the address of “CROSSREGIONDETECTION.CAR” and so forth. If you know what objects your camera supports you can create units ahead of time with those addresses. They cannot be created immediately upon setting up the event as there is no reliable way to discover what objects the camera supports via the API and so they will be created either by you or automatically when the camera first reports a new object type.



====Show Events:===
takes no parameters, opens a window with a list of currently enabled events, if any.
<code>
tell xInterface “Amcrest Cam” to showEvents()
</code>

====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.

If trying to gather data for newly supported events it may be helpful to change your list of enabled events to just “All” though this will result in some error messages as unsupported events are received. Collect the rest of the data and send to me to see if they can be supported in a useful way.

<code>
tell xInterface “Amcrest Cam” to debugLogEvents( True)
</code>

====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:
<code>
tell xInterface “Amcrest Cam” to enableMotionRegions()
</code>

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.

<code>
tell xInterface “Amcrest Cam” to enableMotionRegions( “side yard”, “driveway”, “main road”, “walkway”)
</code>

====Show Motion Regions:====
Takes no parameters. Opens a text window listing the currently enabled motion regions for the camera.

<code>
tell xInterface “Amcrest Cam” to showMotionRegions()
</code>

-----

=====Image Settings:=====
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.

====Set Brightness:====
<code>
tell xInterface “Amcrest Cam” to setBrightness( 50)
</code>

====Set Chroma Suppress:====
Not exactly sure what this one does. It’s in the API documentation but with no explanation.
<code>
tell xInterface “Amcrest Cam” to setChromaSuppress( 50)
</code>

====Set Contrast:====
<code>
tell xInterface “Amcrest Cam” to setContrast( 50)
</code>

====Set Gamma:====
<code>
tell xInterface “Amcrest Cam” to setGamma( 50)
</code>

====Set Hue:====
<code>
tell xInterface “Amcrest Cam” to setHue( 50)
</code>

====Set Saturation:====
<code>
tell xInterface “Amcrest Cam” to setSaturation( 50)
</code>

-----

=====PTZ Control:=====

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.

====PTZ Move:====
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.

<code>
tell xInterface “Amcrest Cam” to PTZMove( 10000, -4000, 1)
</code>
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.

====Goto Preset:====
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.

<code>
tell xInterface “Amcrest Cam” to gotoPreset( 4)
</code>

====Set Preset:====
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.

<code>
tell xInterface “Amcrest Cam” to setPreset( 13)
</code>

====Clear Preset:====
Pass the preset number and optionally a channel number to clear a preset.
<code>
tell xInterface “Amcrest Cam” to clearPreset( 4)
</code>

====Start Tour:====
Pass the ID number of a previously programed tour to begin the camera moving through the Tour.
<code>
tell xInterface “Amcrest Cam” to startTour( 1)
</code>

====Stop Tour:====
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.

<code>
tell xInterface “Amcrest Cam” to stopTour( 2)
</code>

-----

=====Recording Control:=====
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.

====Manual Record:====
Begin manual recording to the internal SD card or other destination as configured in the camera.
<code>
tell xInterface “Amcrest Cam” to manualRecord()
</code>

====Auto Record:====
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.

<code>
tell xInterface “Amcrest Cam” to autoRecord()
</code>

====Stop Recording:====
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.

<code>
tell xInterface “Amcrest Cam” to stopRecording()
</code>

====Record Mode:====
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

<code>
tell xInterface “Amcrest Cam” to recordMode( 1)
</code>




-----
=====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.

While the configuration can support many options and many different overlayed text items or covers the maximum supported by your camera will vary. My amcrest doorbell cam can only support 2 overlayed items at a time. So they dont provide an interface for that as they wish to use it to display the clock and their graphic. 

====Set Font Scale:====
On the cameras I have the Font Size settings seems to have no effect, but the Font Scaling does work. There is a limited amount you can change the size of the fonts by passing a number from 0.1 to 2.0 with 1.0 being the normal default size. So to make the fonts half the size pass 0.5 and to make them double the size pass 2. Pass any floating point number in between to get any size in between. The maximum size supported on my camera is a scaling factor of 2 though other cameras may support more or less.

**setFontScale**( [**0.1..2.0**] float, (optional) **channel**)

<code>
tell xInterface “amcrest cam” to setFontScale( 1.7)
</code>



====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.

<code>
tell xInterface “Amcrest Cam” to setChannelTitle( “Kitchen: “ & (value of “Temperature Kitchen”) & “°F”)
</code>

====Set Channel Title Visible:====
You can make the channel title display appear or dissappear using the set channel title visible verb and passing true or false along with an optional channel index defaulting to 0.

<code>
tell xInterface “Amcrest Cam” to setChannelTitleVisible( true)
</code>

====Set Channel Title Location:====
The location in the view can be set with the setChannelTitleLocation verb. The channel title often defaults to the lower left hand corner but you can move it programmatically if you wish. You need pass only the left and top coordinate. The coordinates of all the screens regardless of resolution are from 0 to 8191.

<code>
tell xInterface “Amcrest Cam” to setChannelTitleLocation( 300, 7800)
</code>

Location Note. There are actually 4 parameters that are set, the rect coordinates and not just width and height. Figuring out what these should be was a pain as there is no way to know how much space a text message was going to need and so with further experimentation it seems to be good enough to set the second two values to 0 which I do internally not requiring you to manage this. If you are experiencing something odd that you think is realted to this please let me know and I can expose the values for setting if you wish to. 


====Set Channel Title Color:====
You can also set the color of the text being displayed as the color. This is maybe not as useful as it sounds as the system is just not very good at graphics for the most part and by adding color you reduce the readability, but it is here for completeness and to see if someone finds a use for this.

Though none of the cameras I have here support it you must pass the RGB values from 0 to 255 as well as a 4th value for the alpha channel. None of mine will render the color with anything other than 100% opacity but if you have a better or newer one it may be useful.

<code>
tell xInterface “Amcrest Cam” to setChannelTitleColor( 255, 45, 45, 0)
</code>

would change the color to bright red, The default for the text color is “255, 255, 255, 0” which would return it to it’s fully opaque white.

====Set Channel Title Back Color:====

They also allow the setting of the “background color” for the title and other text entities. This is not really the background color but just the outline color around the text. This is normally a dark grey with a default of (0, 0, 0, 128) though I can’t see if the half way opacity actually does anything other than just plain black. You can experiment with other colors but unless your camera renders these much better than mine I would stick to a light color for the text and a dark color for the outline.

<code>
tell xInterface “Amcrest Cam” to setChannelTitleBackColor( 45, 255, 45, 0)
</code>
would set the outline of the text to a bright green.

====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:
<code>
tell xInterface “Amcrest Cam” to doStatusDisplay( “Porch: MOTION outside PIR”, 0, “Porch”, 5)
</code>

-----
=====User Defined Title Displays:====

Most of the cameras, including the newer “smart home” variants will also support up to 4 User Defined Titles, These would allow you to dynamically add and control several more lines of text on the page when useful. The cameras themselves, especially the smart home variants, do not have much of a user interface and the iPhone app at least exposes only a subset of what you can do with the API that they still support.

Generally the use of these commands are the same as the Channel Title commands above but with the addition of another integer at the beginning to point to the correct user defined title object

====Set User Display Visible:====

**setUserDisplayVisible(** [**0..3**] index of the user text item, [**true|false**], (optional) **channel** defaults to 0)

<code>
tell xInterface “amcrest cam” to setUserDisplayVisible( 0, true)
</code>

====Set User Display Text:====

**setUserDisplayText(** [**0..3**] index of the display, **string** the text to be displayed, (optional) **channel** defaults to 0)

<code>
tell xInterface “amcrest cam” to setUserDisplayText( 0, “A Human Was Detected”)
</code>

====Set User Display Location:====

**setUserDisplayLocation(** [**0..3**] index of display, [**0..8191**] left, [**0..8191**] right, (optional) **channel** defaults to 0)

See the Channel Title Location command above for some discussion on the possibility of problems with the automatic setting of the right and bottom coordinates.

<code>
tell xInterface “amcrest cam” to setUserDisplayLocation( 0, 2345, 20)
</code>

====Set User Display Color:====

**setUserDisplayColor(** [**0..3**] index of display, [**0..255**] red, [**0..255**] green, [**0..255**] blue, [**0..255**] alpha opacity, (optional) **channel**)


Note that the alpha channel is required though does not actually do anything on my cameras. The default is 0 for the fore color and 128 for the background color.

<code>
tell xInterface “amcrest cam” to setUserDisplayColor( 0, 255, 20, 20, 0)
</code>

would set the text to a bright red.

====Set User Display BackColor:====

**setUserDisplayColor(** [**0..3**] index of display, [**0..255**] red, [**0..255**] green, [**0..255**] blue, [**0..255**] alpha opacity, (optional) **channel**)

Note that the alpha channel is required though does not actually do anything on my cameras. The default is 0 for the fore color and 128 for the background color.

On the cameras that I have to test with this is not actually a background, but rather the color of the outline that is drawn around the text to make it more readable regardless of the brightness or color of the background.

<code>
tell xInterface “amcrest cam” to setUserDisplayBackColor( 0, 40, 40, 40, 0)
</code>

to set the background color of display 0 to a dark grey.

-----

=====Controlling The Logo Display:=====

On the Smart Home cameras there seems to be no interface provided in the app to hide the amcrest logo or change it’s location. These verbs will let you hide the logo, move it or change it to some other custom file that might be supported by some of the cameras.

====Set Logo Visible:====

**setLogoVisible**( **true|false**, (optional) **channel**)

<code>
tell xInterface “amcrest cam” to setLogoVisible( false)
</code>
to hide the logo completely

====Set Logo Location:====

**setLogoLocation**( [**0..8191**] left, [**0..8191**] right, (optional) **channel**)

see the Channel Title Location command above for more info on the possibility of problems with setting the location.

<code>
tell xInterface “amcrest cam” to setLogoLocation( 40, 40)
</code>

to place it in the upper left corner instead of the default bottom right.


====Set Logo Filename:====
Be sure you know what you’re doing before using this verb as it has the potential to confuse or otherwise mess with the camera. On my doorbell camera the default filename of “osd.bmp” it is possible that this is different for other cameras. You must know that a file is available before changing this, If you have a camera that allows you to upload different image files then this would be a way to change between them.

**setLogoFilename**( **string** name of the file, (optional) **channel**)

<code>
tell xInterface “amcrest cam” to setLogoFilename( “osd.bmp”)
</code>

-----

=====Controlling The Time Overlay:=====

In the smart home app there is no capability to control the time and date display. These commands will let you control it’s content, location, color and visibility.

====Set Time Display Visible:====

**setTimeDisplayVisible**( **true|false**, (optional) **channel**)

<code>
tell xInterface “amcrest cam" to setTimeDisplayVisible( false)
</code>

====Set Time Display Location:====

See the Channel Title Location command above for more info on the implications of this command.

**setTimeDisplayLocation**( [**0..8191**] left, [**0..8191**] right, (optional) **channel**)

<code>
tell xInterface “amcrest cam” to setTimeDisplayLocation( 10, 100)
</code>

====Set Time Display Color:====

Note that the Alpha channel value is required though does not seem to actually do anything on my cameras.

**setTimeDisplayColor**( [**0.255**] red, [**0..255**] green, [**0..255**] blue, [**0..255**] alpha)

<code>
tell xInterface “amcrest cam” to setTimeDisplayColor( 20, 20, 255, 0)
</code>

to set it to a nice bright blue. The default value on my cameras is (255, 255, 255, 0)

====Set Time Display Back Color:====

On the cameras I have this is not actually the background but the color of the outline around the display text making it easier (or harder if you choose poorly) to read the display over camera images of varying brightness and color. The default on my cameras is (0,0, 0, 128)

**setTimeDisplayBackColor**( [**0.255**] red, [**0..255**] green, [**0..255**] blue, [**0..255**] alpha)

<code>
tell xInterface “amcrest cam” to setTimeDisplayBackColor( 20, 20, 255, 0)
</code>

====Set Time Display Format:====
The cameras seem to support a subset of the standard date formatting templates. I have not tested them all but many do not actually do what is in the documentation. For example, there seems no way to get a month name, or a weekday name or an abbreviated month or weekday, or a month that is not padded with a 0. There may be other valid elements or some cameras may support different elements or properly support the elements that are there.

**setTimeFormat**( **string** the time formatting template)

<code>
tell xInterface “amcrest cam” to setTimeFormat( "yyyy-M-dd  hh:mm:ss t”)
</code>

would result in a display like: 2023-05-29 11:19:43 AM

|YY|2 digit year, without century|
|YYYY|4 digit year|
|M|Month number not padded to 2 digits 1=Jan|
|MM|Month padded to 2 digits: 01=Jan|
|MMMM| Abbreviated Month Name: Jan|
|d| Day of month, not padded to 2 digits|
|dd| Day of month padded to 2 digits|
|H| 0-23 Hour, not padded|
|HH| 01-23 Hour, padded|
|h| 12 hour, not padded|
|hh| 12 hour, padded|
|s| seconds not padded|
|ss| seconds padded|
|t| AM or PM|

See also the **Set Time** and **Set DST** commands below.


-----

=====Camera Utilities:=====


====Show Capabilities:====
Opens a window with all the camera capabilities as it reports them. Not all of this information may be sensible or useful but I am reporting it from the following sections: Video Input, Recording, Events, Storage, Encoding and Thermography.

<code>
tell xInterface “Amcrest Cam” to showCapabilities()
</code>

====Set Time:====
Sets the camera time to the Mac’s time.
<code>
tell xInterface “Amcrest Cam” to setTime()
</code>

====Set DST:====
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.
<code>
tell xInterface “Amcrest Cam” to setDST( True)
</code>

====Reboot:====
Reboots the camera.
<code>
tell xInterface “Amcrest Cam” to reboot()
</code>