The Live View API calls allow you to get a media stream or current snapshot in various formats for any online AccessoryAccessory - A unique device within the system. An accessory can be any of type and is represented by a unique Accessory Id. An accessory is linked to an account via an accountId. Within this API, a singular Circle camera is an Accessory.. The Circle system supports DASH, RTSP, and WebRTC for live video. It supports JPG for snapshot viewing.
WebRTC is the preferred mechanism and offers the lowest latency option as it can go peer-to-peer. RTSP is low latency, but the streams are hosted via the Circle servers. DASH is a high latency stream since DASH live view requires at least 4 seconds of delay.
WebRTC is a multi-protocol standard allowing for peer-to-peer transmission with end-to-end encryption. WebRTC is the preferred protocol for doing live view of a Circle camera.
WebRTC is comprised of an Offer-Answer model and the Circle API design provides support for using both pathways. The preferred pathway is to ask the camera for its Offer first and then your code asynchronously provides the Answer. The alternate pathway involves your client providing the Offer to the camera first, and the camera providing the Answer.
There are two mechanisms for handling the control message channel used in WebRTC. The preferred mechanism is to use a persistent WebSocket connection via Establish Live WebRTC WebSockets Channel. This pathway provides for the lowest possible latency while supporting TrickleICE for the fastest connection establishment. The WebSockets channel defines an instream JSON based protocol for passing all the Offer, Answer, ICE Candidates and hangup commands.
If your client can't support WebSockets, the following REST API calls are defined which perform the same commands. When using the REST API, TrickleICE is not supported.
- Get Live WebRTC Offer
- Provide Live WebRTC Answer Async
- Provide Live WebRTC Offer and Get Answer
- Renegotiate Live WebRTC
- Stop Live WebRTC
There are two media stack implementations of WebRTC in the Circle ecosystem: camera-side and server-side.
Camera-side WebRTC uses a native WebRTC stack running on the camera. This stack is configured to allow for peer-to-peer calls running on both UDP/TCP (STUN discovered) and TCP/TLS transports (TURN discovered). Camera-side WebRTC calls are real-time low latency. Only Circle 2 cameras running recent firmware (5.8.x series or later) support Camera-side WebRTC. Circle 1 cameras do not support it. Circle 2 cameras can only support one concurrent camera-side WebRTC call at a time. If the camera is currently engaged in a camera-side call, the call will transparently be converted to a server-side WebRTC call. Camera-side support is indicated via the
webrtcIsAvailable attribute in Get Accessory by Id. If supported, camera-side support can be disabled via the
webrtcEnabled attribute in Set Accessory Config by Id.
Server-side WebRTC uses a limited WebRTC stack running on the central Circle servers. In this mode, the video/audio stream is forked from the archival/recording stream and presented to clients as a WebRTC stream. Server-side WebRTC only supports TCP or TLS transports. Server-side WebRTC calls may have several seconds of latency due to the use of the recording stream.
All DASH calls are considered depreciated and should not be used in new developments.