Live View API

The Live View API calls allow you to get a media stream or current snapshot in various formats for any online 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.

JPG Snapshot

WebRTC

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.

Compliant WebRTC stacks MUST support RTP over TCP (RFC 4571) and TURN over TCP (RFC 6062). Currently Google Chrome, Opera, Firefox, Microsoft Edge and Safari work.

Various resources to learn about WebRTC can be found at https://www.w3.org/TR/webrtc/ and https://webrtc.org/

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.

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.

RTSP

DASH

All DASH calls are considered depreciated and should not be used in new developments.