Skip to main content
Version: 1.0

Streamer

The Streamer component manages the WebRTC sessions over which the camera delivers live audio and video. The camera can act as either the offerer or the answerer, depending on which method the client calls. This protocol operates in a non-trickle mode. All ICE candidates are gathered before the SDP is sent and are embedded directly within the SDP string.

note

As a standards-based alternative to this JSON-RPC signaling, the camera also exposes a WHEP HTTP endpoint for establishing a WebRTC session, which is directly compatible with WHEP-capable clients.

Methods​

Streamer.Offer​

The client requests the Shelly device to generate a WebRTC SDP offer. The device will gather all necessary ICE candidates and include them in the returned SDP.

Request​

Parameters:

PropertyTypeDescription

ice_servers

array of strings

List of ICE servers to be used by the device for candidate gathering. Each entry must match the format: [("stun"|"turn"|"turns") (":"|"://")][username ":" password "@"]hostname[":" port]["?transport=" ("udp"|"tcp"|"tls")]

stream_id

number

The ID of the stream to offer (e.g. 0 or 1). The available stream IDs can be found in the Camera.GetConfig configuration. Optional

Response​

Attributes in the result:

PropertyTypeDescription

session_id

string

Unique identifier for the created session.

sdp

string

The SDP offer string containing all gathered ICE candidates.

end_of_candidates

boolean

Always true (indicates non-trickle mode).

candidates

array

Always empty (candidates are in the SDP).

Streamer.Answer​

The client sends its SDP answer to the device to finalize the connection. The client must have gathered its own candidates and included them in the SDP before calling this method.

Request​

Parameters:

PropertyTypeDescription

session_id

string

The session ID obtained from Streamer.Offer.

sdp

string

The Client's SDP answer string containing all gathered ICE candidates.

end_of_candidates

boolean

Must be true.

candidates

array

Must be [] (empty array).

Response​

The result from this method is null.

Streamer.GetAnswer​

The client generates the SDP offer and the device replies with its SDP answer, completing the handshake in a single call. This is the reverse of the Streamer.Offer / Streamer.Answer exchange, in which the device is the offerer. The client must have gathered its own candidates and included them in the offer SDP before calling this method.

Request​

Parameters:

PropertyTypeDescription

sdp

string

The client's SDP offer string containing all gathered ICE candidates.

ice_servers

array of strings

List of ICE servers to be used by the device for candidate gathering, in the same format as in Streamer.Offer. Pass an empty array to have the device gather host candidates only.

stream_id

number

The ID of the stream to receive (e.g. 0 or 1). The available stream IDs can be found in the Camera.GetConfig configuration. Optional

session_id

string

Identifier of the session. If not provided, the device generates one and returns it in the result. Optional

Response​

Attributes in the result:

PropertyTypeDescription

session_id

string

Identifier of the session, to be used with Streamer.SetStreamSource and Streamer.StopStream.

sdp

string

The device's SDP answer string containing all gathered ICE candidates.

Streamer.SetStreamSource​

Dynamically changes the active stream source (resolution/quality) for an ongoing session. The available stream IDs can be found in the Camera.GetConfig configuration (e.g., 0, 1, 2).

Request​

Parameters:

PropertyTypeDescription

session_id

string

The session ID obtained from Streamer.Offer.

stream_id

number

The ID of the stream to switch to (e.g., 1).

Response​

The result from this method is null.

Streamer.StopStream​

Terminates an active streaming session.

Request​

Parameters:

PropertyTypeDescription

session_id

string

The session ID to terminate.

Response​

The result from this method is null.

Examples​

Streamer.Offer example​

http://192.168.33.1/rpc/Streamer.Offer?ice_servers=["stun:stun.shelly.cloud:3478"]

Response

{
  "candidates": [],
  "end_of_candidates": true,
  "sdp": "v=0\r\no=rtc 1897771158 0 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\n...a=candidate:1 1 UDP 2122317823 192.168.1.222 58192 typ host\r\na=end-of-candidates\r\n...",
  "session_id": "J1ARS8Xn"
}

Streamer.Answer example​

http://192.168.33.1/rpc/Streamer.Answer?session_id="J1ARS8Xn"&sdp="v=0\r\no=mozilla...THIS_IS_SDPARTA-99.0 9213127519493443522 0 IN IP4 0.0.0.0\r\ns=-\r\nt=0 0\r\n...a=candidate:0 1 UDP 2122252543 b5d80035.local 48472 typ host\r\na=end-of-candidates\r\n..."&candidates=[]&end_of_candidates=true

Response

null

Streamer.GetAnswer example​

http://192.168.33.1/rpc/Streamer.GetAnswer?sdp="v=0\r\no=- 1702035895763188295 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE 0 1\r\n...\r\nm=video 34945 UDP/TLS/RTP/SAVPF 96 97 98 99 100 101 ...\r\na=candidate:2612771362 1 udp 2113937151 0d7b0b05-f816-46bb-8b71-daf8cbfb6535.local 34945 typ host generation 0 network-cost 999\r\na=candidate:2618165947 1 udp 1677729535 203.0.113.10 34945 typ srflx raddr 0.0.0.0 rport 0 generation 0 network-cost 999\r\n..."&ice_servers=["stun:stun.shelly.cloud:3478"]&stream_id=0

Response

{
  "sdp": "v=0\r\no=rtc 1066947812 0 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE 0 1\r\n...\r\nm=video 9 UDP/TLS/RTP/SAVPF 119\r\n...\r\na=candidate:1 1 UDP 2114977791 192.168.0.219 58198 typ host\r\na=candidate:4 1 UDP 1678769407 203.0.113.10 58198 typ srflx raddr 0.0.0.0 rport 0\r\na=end-of-candidates\r\n...",
  "session_id": "nJPOBUtY"
}

Streamer.SetStreamSource example​

http://192.168.33.1/rpc/Streamer.SetStreamSource?session_id="J1ARS8Xn"&stream_id=1

Response

null

Streamer.StopStream example​

http://192.168.33.1/rpc/Streamer.StopStream?session_id="J1ARS8Xn"

Response

null