HomeSeer HS4 Streaming Camera Plugin Instructions

HomeSeer logoStreaming Camera plugin for
HS4 (Stream Cam)

HS4 Streaming Camera Plugin

Go to https://forums.homeseer.com/forum/hs4-products/hs4-plugins/camera-plugins-aa/dcor for on-line forum support!
Please read the help  file and take traces before you  post questions on-line!

Introduction

Welcome to the HS4 compatible version of the Streaming-Camera plugin.
If you run into an issue or have a question, when you post on the forum, what is required is:

  1. Recreate the issue with debug logging on, typically the log level set to “Errors and Events” is sufficient.
  2. Log to disk! It is easy and makes sure that all info is present as using the HS log to cut/paste loses HTML tag information.
  3. When asked, make a “Capture” file, it contains all the ONVIF discovery info and most of the plugin’s HS settings.
  4. Post screen shots of your configuration, i.e.. HS device page.
  5. Detail what exactly you are doing and what exactly is not working.

READ THIS FIRST!!

  • The Plugin does NOT start automatically upon initial activation. Users must acknowledge the UELA by navigating to Plugins->Stream Cam->Accept and reviewing the information prior to acceptance.
  • For Windows users, if prompted for network access approval by the PI, please grant permission.
  • Note that the plugin author has no affiliation with any camera vendor, and vendors may alter their SW at any time, potentially rendering the plugin ineffective. Users should consider and accept this risk before purchasing, as refunds will not be issued under such circumstances.
  • The camera’s API could reveal proprietary information. When posting logs, ensure they do not contain sensitive data. If uncertain, send a personal message with debug log details to the author via the message board.
  • For camera issues, users can “capture” ONVIF information published by the respective devices by going to settings->Debug, selecting the “Capture” button, and sending the log file along with a description to the author.
    The PI supports live views, but compatibility varies across different browsers and platforms. Ensure the necessary codecs are installed.
  • For 2-way audio during live view, browsers only permit this over HTTPS (or localhost). HS does not natively support HTTPS access; options include localhost access, installing certificates for HTTPS use, or using MyHS.
  • ONVIF is a great protocol, but unfortunately device manufacturers tend to have poor and proper implementation of the protocol. Initial experience learns that vendors tend to publish services that are actually not really supported by their SW.
    As a consequence, the plugin may create features that are not working. There are settings in the plugin to disable those non-working features.

A bit about this plugin.

This plugin was created to discover and manage devices that support the ONVIF protocol.
Do make sure that your device has the ONVIF protocol enabled. Through the ONVIF protocol, the plugin will discover the supported services, such as snapshots, streaming video, events, pan/tilt/zoom, preset and preset tours. When a service is discovered, a feature will be created.
For cameras that do not support ONVIF, you can manually add devices and enter the snapshot and video information.
The plugin makes use of 3rd party open-source software, allowing it to source video/audio in a great variety of different encoding schemes and stream it directly to a browser embedded video player, using WebRTC, a very efficient and low latency protocol. It can
do transcoding’s if needed and record the livestream.
It will support audio when the camera has a microphone and can support bi-directional audio in case the camera has support for it. This bi-directional audio, due to browser protection, must be established through a LOCALHOST or HTTPS connection. Unfortunately, this means you will have to pull up the HS4 webpages through My HS.
You can use the created live view features to create dashboards or use on your HS Touch clients. If the camera supports pan/tilt or zoom, you can use the overlaid controls (or use mouse/fingers to drag) to steer the camera.

Another word of warning: depending on browser, its SW version, your HW, the supported Codecs for audio and video will vary widely. If everyone involved plays nice, the plugin will attempt to match source with browser, however experience has shown that browsers will publish capabilities it can’t handle. You may have to experiment a little to find the correct video sub stream that works for that particular browser on that particular piece of HW. The plugin has plenty of config support for that.
ONVIF supports two mechanisms to report events. One is through periodic polling by the plugins (pull notifications) while the other is through subscribing to events which will be reported by the device to the plugin through pushbacks. The latter mechanism is obviously more efficient for the plugin. Again, experience has shown that not all ONVIF devices support it and worse, some report they do support it but don’t. If you have an ONVIF device that supports events and the plugin is not creating any event features, go to the device’s feature settings and enable “Prefer Polling”.
Many thanks to Alex X (https://github.com/alexxit) for his go2rtc open source project. It is a critical component for the functionality of this project. Also thanks to the creators and contributors of the FFMPEG/FFPROBE project.

Starting for the first time.

If you start the plugin for the first time you will have to accept the conditions for use. You do this by clicking on the Plugins button -> StreamCam -> Accept. Once accepted, you will not have to repeat this step unless you have deleted the StreamCam.ini file for some reason.
Once accepted the plugin will automatically send out ONVIF discovery messages to all attached interfaces. If you are using virtual machines, containers or VLANs, do note that the discovery only works for devices in the same subnet. So if your PC has, for example, a virtual bridge with NAT, the plugin will not discover the ONVIF devices. The plugin and devices must be in the same subnet.
This plugin makes use of open-source 3rd party SW that at start-up will be downloaded from my GitHub account. This is done to match the correct executable with the OS/HW environment this plugin will operate in. I’ve tested this on several contemporary Windows and Linux installs but there is chance not all combinations will work, so monitor the startup log for warnings or errors. Once downloaded,  only the version  will be checked during each future start-up of the plugin. The plugin supports a Health feature
that would indicate faults in case the 3rd pty SW fails to download or fails to run.HomeSeer HS4 Streaming Camera Plugin - StartingAll ONVIF devices discovered will be stored internally by the plugin and can be displayed on the plugin’s devices page. They will not be added to HS automatically; this is a manual process.HomeSeer HS4 Streaming Camera Plugin - fig

For ONVIF devices, clicking on the “+” icon will open a stepper window, where you will be asked to enter the password and username as the two most important items.
Adding non-ONVIF devices can be done by clicking on the “Manually Add Device”, which will open a very similar stepper window. Besides the password and username, the IP address will be another critical piece of information. You will also have to enter the
snapshot and stream URLs, so you need to look those up beforehand.
A device can have many (media) profiles, think of them as a snapshot/stream combination, which can for example represent the front camera or the back or the hi-res stream versus the low-resolution, it is up to you. You can have only one snapshot URL per media profile, but you can have many stream URLs, typically those representing different resolutions. On your dashboard you will be able to select the sub stream that works for that platform.HomeSeer HS4 Streaming Camera Plugin - platformOn the device page, you can also pull up additional information on the device or configure the device specific settings.
ONVIF Health Feature
For ONVIF devices, once added to HS, check the Onvif Health feature status to make sure that all relevant services were properly discovered. HomeSeer HS4 Streaming Camera Plugin - Health Feature

Green = OK, Orange = Not-supported, Red = an Error and the status string will show the error information.

Live Streams limitations

The plugin can show livestreams on the HS devices management page. However, when HS4, updates any feature of a device, ALL features of that device are “refreshed”. As a direct consequence, any live stream will be immediately interrupted, rendering this capability void. Therefore, this function can be only properly used when you use a dashboard card that ONLY has this live view feature on it. I will deliver example custom dashboards cards for users to use.
There is a reasonable chance that you will end up in Codec Purgatory, where the plugin either cannot match video/audio codecs in sourcing and sinking side of the stream OR worse, the browser reports Codecs unsupported and now, without error the stream will not start with a spinner showing forever. Almost all cameras have support for different resolution RTSP streams and advertise them as sub streams. The best way to find out which streams work on the HW/Browser you are using, is to go to the “Live” settings page.HomeSeer HS4 Streaming Camera Plugin - Live Streams limitationsHere you are presented with each sub stream the device has to offer. Try to play each one and see/remember which one works. If none of them work, check the log for errors and report them. If you now go back to your dashboard, you will see in the top right-hand corner a drop-down selection menu, representing each sub stream. HomeSeer HS4 Streaming Camera Plugin - substream

Pick the one that works for your HW/Browser combo. This setting is stored locally so it will respect the environment it is running in.
If the camera supports Pan/Tilt/Zoom, hovering your cursor over the object will show controls for these functions. You can also click-hold-drag to move the camera around. Again, take note that some ONVIF device will advertise these capabilities but don’t support them. Best litmus test is to take their app and see if it is supported.
Use of dashboard cards or HSTouch Clients
The best way to experience and use the liveview feature is on dashboard cards. The card does not have the limitations described in the previous paragraph, provided it doesn’t have other features on them that could trigger updates. You can create your own custom cards or use the standard “Display URL Content”.HomeSeer HS4 Streaming Camera Plugin - Clients
The value of the URL can be retrieved from the plugin’s device specific information page.
The info can be found by navigating to the plugin’s Settings->Devices page and by clicking on the “info” icon for the device you want to retrieve the liveview URL for.HomeSeer HS4 Streaming Camera Plugin - URLClicking on the info icon will open the device’s information page.HomeSeer HS4 Streaming Camera Plugin - informationEach profile will have a “Copy Live View Feature Value to Clipboard” button. If you click on it, the URL value will be copied to the clipboard. Notice you have single/specific profiles or a (combo) video source profile. The latter represents a profile that combines all the individual profiles and lets the plugin pick the sub-stream (profile) that works.
The copied value can now be pasted into the requested URL value on the “Display URL Value” dashboard card or used directly in a browser or when used on an HS Touch client, you paste the value into the textbox of an image object and set is HTML to true.
Device Specific Configuration
On the device page, for each device that was added to HS, you can change the configuration settings by clicking on the right-hand side the configuration icon.HomeSeer HS4 Streaming Camera Plugin - Device Specific Here you can change the username and password settings. Note there is no save button so hitting enter or clicking away from the input box will cause the configuration change to be  made.
Enabling Creation of Features
You can find here the settings to enable/disable the auto-creation of features. Do note that changing the checkmark on enabling features does not automatically delete the feature, you would have to do that manually, WHEN THE PLUGIN IS RUNNING. It is important that features are only deleted when the plugin is running to avoid corruption. If you deleted a feature in the past and now enabled them again, a restart of the plugin or a click on the “RETRIEVE ONVIF INFO” control on the “Onvif Health” feature for that device, will recreate the feature.
Using HTML
Some of the feature values will or can be expressed in HTML. When enabled you will see the actual snapshot, or live view object on the HS devices page or dashboards. Perhaps you are into scripting, and you are not interested in seeing this an a device page, but your script would like to have the actual URL information, if you disable “Use HTML” the feature value will be a plain string.
Image size
If you have elected to “Use HTML”, here you can manipulate the size of the image/live view object. The value is a percentage and 100% is standard.
Snapshot settings HomeSeer HS4 Streaming Camera Plugin - Snapshot settings

Most camera will have already overlaid camera and time information on their snapshots or livestreams, but if you want to add the snapshot date/time information, the plugin can do that for you and will write it in the lower right-hand corner when “Embed Timestamp” is enabled.
There are a few different ways of taking snapshots. First there is the manual or through event actions (or scripting) based issuing of a snapshot through the snapshot features control “Take Snapshot”. Secondly, you can configure Onvif devices that have events, configure which of these events will trigger a snapshot to be taken, this would be when you set Snapshot Action to “When Motion Only”. Third you can just do it on a periodic basis and when set to “Periodic” the Period you have set in seconds will cause a snapshot to be made automatically. Note this period should not be less than 15 seconds.
Now that you have set the strategy for making snapshots, you can set what you want to do with them. A snapshot taken, either manually, through motion or periodic, will update the HS Snapshot Feature value where it will overwrite the previous value. If you prefer to keep the snapshots, you can set the Snapshot Save Policy based on your preference. If set different from none, each snapshot will be copied into the <HS
root>/html/StreamCam/Snapshots/<device urn>. If you have specified a custom path (Settings->General->Custom Path Settings), the snapshots will be stored in the custom path/<device urn>/ subdirectories.
There is an auto-clean-up function that can remove files based on age or maximum number of files, see the section on “General Settings” for more information. Do not make your own subdirectories in the /snapshots or /videos subdirectories as the clean-up function, only looks at “last modified” date to decide to delete and will delete any file that matches the criteria.
Recording Settings HomeSeer HS4 Streaming Camera Plugin - Recording Settings

Onvif specific Settings

HomeSeer HS4 Streaming Camera Plugin - Onvif specific Settings
If you don’t need specific features, here is where you can disable them. You do need to delete them manually if they were created WHILE THE PLUGIN IS RUNNING.
Onvif devices, supporting events, can either notify the plugin through unsolicited pushbacks or the devices can be periodically polled (pull notifications). The abilities are published by the device and discovered by the plugin. Subscribing to unsolicited events through pushbacks is the preferred mechanism BUT I’ve come across devices that advertise they can do Postbank but don’t do any. In that case you should enable “Polling Preferred”. A strong hint is usually when your device has no event features when added.
For each event that the device can generate, you can configure whether you want the plugin to trigger a snapshot or recording. This default information comes from the topics.csv file, you can read about this further in this document.
Network Settings HomeSeer HS4 Streaming Camera Plugin - Network Settings

Here you can set how aggressive (or not) you want the plugin to declare a device to be online of off-line.
Every 10 seconds a ping is sent to a device, any device, so ONVIF or Manually added. I recommend a lower missed ping number to allow a ping or so to go missing in your network but fast enough to detect a device from being off-line. However, I would recommend not to set too aggressive a “successful ping” value because experience has shown that ONVIF device tend to respond to pings many seconds before their ONVIF functions are properly working. If set too aggressive, you will get error when a device is
detected back on-line and when the ONVIF information retrieval fails because the device is not ready yet.

General Settings

HomeSeer HS4 Streaming Camera Plugin - General SettingsCustom Path Setting
If you want to store snapshots or recording in a different directory, then the standard directory (<HS Root>/html/StreamCam/snapshots or ../videos) you can do it here. Perhaps you want to store the files on a NAS, it can be done here but keep in mind that the HS4 embedded webserver, for your security allows only content to be retrieved if it resides in a subdirectory of the WebServer’s root directory ie <HS Root>/html. The plugin will always leave the latest file in an accessible folder so your dashboards or HSTouch clients will be able to retrieve that content, but the long-term stored objects will be inaccessible.
Auto Delete Settings
The plugin will, at start-up, and each day thereafter, run a clean-up cycle. You can specify whether you never want to delete snapshots or recordings, or perhaps you want to keep just a maximum amount of the latest objects, or perhaps only files that are younger than a specific age. These settings only apply if you have selected to store snapshot and/or recordings and only delete files in the respective subdirectories. Do not make your own subdirectories in the /snapshots or /videos subdirectories as the clean-up function, only looks at “last modified” date to decide to delete.
Network Setting
The “Allow Outside Subnet” setting tells the plugin whether devices that respond to an ONVIF discovery (probe) with an IP-Address that is outside the subnet assigned to the interface it was received on, whether to accept it or drop it. In a normal scenario, there will never be responses from out-of-subnet devices (standard broadcast behavior) but perhaps you have installed some proxy or shortcuts, so you have the option to accept those responses. Word of caution, I added this because I had ONVIF devices that responded with bogus IP-Addresses that they use for their own apps to discover devices (168.xx.xx.xx)
Debug Settings HomeSeer HS4 Streaming Camera Plugin - Debug Settings

The plugin has very extensive logging capabilities and is centered around three main objects:

  1. Logging of plugin function: this is info about the working of the plugin. For typical debugging session, “Errors and Events” is plenty. Unless I ask for “Verbose” or “Tracing”, stick to “Errors and Events”
  2.  If we have issues with livestreams not working in a specific browser or on a specific platform, the plugin has the capability to extract logging information of what happens on the browser, through the plugin. You can set the logging here and refresh your browser to have it take effect.
  3.  Also related to livestreams, we may have to trace what is happening in the go2rtc 3rd pity component, you can set an elevated logging level here as well. No need to refresh anything after changing the debug level but do note that the plugin will automatically reset go2rtc to have the log level changes take effect which will impact active streams.

To make it easier to extract only the log related to the plugin, you can enable here to log all plugin log info directly to disk. The filename is shown, and you can make use of the download function to download the file directly to your PC. The enable/disable checkmark works as a toggle and a reset. If you enable it, it will open a new log file, disabling will close the file and flush all caching to disk. Best to do that before downloading. Be careful, if you enable again, the log is gone.
There is also a capability to capture all the ONVIF and HS related settings in a single file. This is a very important function, and you will be asked many times to click that “CAPTURE” button. Don’t post the file on the forum, it will have proprietary information in it, only PM it to me and feel free to delete sensitive information but let me know.
Recordings
To be implemented
History
To be implemented
Useful debug links
Check your Chrome browser WebRTC connections: Chrome://webrtc-internals
Check your Chrome GPU settings: Chrome://gpu
Check your browser codec capabilities: https://refined-github-html-preview.kidonng.workers.dev/AlexxIT/go2rtc/raw/refs/heads/master/www/codecs.html
Acknowledgements
It would have been much harder to develop this plugin without the great work done by others. Many thanks to Alex X (https://github.com/alexxit) for his go2rtc open source project. It is a critical component for the functionality of this project. Also thanks to the
creators and contributors of the FFMPEG/FFPROBE project. HomeSeer logo

Documents / Resources

PDF thumbnailHS4 Streaming Camera Plugin
Instructions · HS4 Streaming Camera Plugin, HS4, Streaming Camera Plugin, Streaming, Camera Plugin

References

Ask a Question

Use this section to ask about setup, compatibility, troubleshooting, or anything missing from this manual.

Ask a Question

Ask about setup, compatibility, troubleshooting, or anything missing from this manual. Name and email are optional.