Differences

This shows you the differences between two versions of the page.

--- video:api:amcrest_hd [2023/05/08 17:03] – added info on human detection as well as the motion info event. James Sentman
+++ video:api:amcrest_hd [2023/05/31 14:20] (current) – added showCapabilities command James Sentman
@@ Line 1: / Line 1: @@
 =====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.
+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:=====
@@ Line 33: / Line 33: @@
   * 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.**
@@ Line 55: / Line 57: @@
-====Log Events:===
+====Show Events:===
-takes no parameters, writes the currently configured events to the XTension log for debugging or to know what is currently setup.
+takes no parameters, opens a window with a list of currently enabled events, if any.
 <code>
-tell xInterface “Amcrest Cam” to logEvents()
+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)
@@ Line 81: / Line 86: @@
 </code>
-====Log Motion Regions:====
+====Show 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.
+Takes no parameters. Opens a text window listing the currently enabled motion regions for the camera.
 <code>
-tell xInterface “Amcrest Cam” to logMotionRegions()
+tell xInterface “Amcrest Cam” to showMotionRegions()
 </code>
@@ Line 208: / Line 213: @@
 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:====
@@ Line 219: / Line 240: @@
 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:====
@@ Line 228: / Line 286: @@
 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:====