WebRTC Streaming from Doorbells

BETA APIs

The following documentation is not guaranteed to work and may change.

August is experimenting with opening up video streaming to select partners. You are welcome to experiment with this API on your own development doorbells, but you must not put it into production for customer use without written agreement from August.

Media

August doorbells typically support Opus 48000 audio and H264 video over RTP. They can support audio in both directions, but do not support receiving video on the doorbell. The definitive capabilities must come from the SDP answer.

Initiate Call

Tell August that you would like to begin a WebRTC call with a doorbell. This will wake up the doorbell, begin streaming, and reply with an SDP answer to help your client connect to the doorbell.

POST /doorbells/:doorbellID/webrtcsignal

Body to post:

{
  offer: 'sdp offer string with "\r\n" newline delimeters. REQUIRED',
  clientTransactionID: 'identifier string sent by the client to trace transaction. REQUIRED',
  timeoutMs: 'milliseconds to wait for a response from doorbell, 30000 max, 5000 default. OPTIONAL',
}

The clientTransactionID must be unique to this streaming session and must be maintained by you for the duration of the call.

The August REST API becomes the signaling channel for the Service Discovery Protocol (SDP).

Response:

{
  answer: 'sdp answer string'
}

Once you have the SDP answer, the signaling is complete and your client should begin trying to connect directly to the doorbell (or to the relay server contained in the answer).

Call Begins (Proposed)

Unimplemented

This call is not yet implemented, but you should plan on making it.

This is to help August with tracking the success rate of calls.

POST /doorbells/:doorbellID/webrtcsignal/begin

Body to post:

{
  clientTransactionID: 'identifier string. REQUIRED',
  connection: 'host | srflx | relay. OPTIONAL'
}

The clientTransactionID must match the clientTransactionID used in the call initiation. The connection value should reflect the type of connection you've established, if known.

Call Ends (Proposed)

Unimplemented

This call is not yet implemented, but you should plan on making it.

This will help August shut down the video stream properly and allow the doorbell to sleep again.

POST /doorbells/:doorbellID/webrtcsignal/end

Body to post:

{
  clientTransactionID: 'identifier string. REQUIRED',
  termination: 'error | user . OPTIONAL'
}

The clientTransactionID must match the clientTransactionID used in the call initiation. The termination string should indicate the reason for ending the call.

Sample SDP Answer

One line

The following example has been transformed for readability. The actual SDP answer would appear as one long line with no actual line breaks.

"v=0\r\n
o=- 3754173828 3754173828 IN IP4 199.87.83.38\r\n
s=Mountpoint 10\r\n
t=0 0\r\n
a=group:BUNDLE audio0 video0\r\n
a=msid-semantic: WMS janus\r\n
m=audio 9 UDP/TLS/RTP/SAVPF 96\r\n
c=IN IP4 199.87.83.38\r\n
a=sendrecv\r\n
a=mid:audio0\r\n
a=rtcp-mux\r\n
a=ice-ufrag:neAt\r\n
a=ice-pwd:fKp2IopxFys5002tc4wj4z\r\n
a=ice-options:trickle\r\n
a=fingerprint:sha-256 D2:B9:31:8F:DF:24:D8:0E:ED:D2:EF:25:9E:AF:6F:B8:34:AE:53:9C:E6:F3:8F:F2:64:15:FA:E8:7F:53:2D:38\r\n
a=setup:active\r\n
a=rtpmap:96 opus/48000/2\r\n
a=fmtp:96 maxplaybackrate=48000; sprop-maxcapturerate=16000; stereo=0; sprop-stereo=0\r\n
a=ssrc:1455357831 cname:janusaudio\r\n
a=ssrc:1455357831 msid:janus janusa0\r\n
a=ssrc:1455357831 mslabel:janus\r\n
a=ssrc:1455357831 label:janusa0\r\n
a=candidate:1 1 udp 2013266431 10.0.19.194 33380 typ host\r\n
a=candidate:2 1 udp 1677722111 199.87.83.38 33380 typ srflx raddr 10.0.19.194 rport 33380\r\n
a=candidate:3 1 udp 503316991 52.53.192.70 49252 typ relay raddr 10.0.19.194 rport 33380\r\n
a=end-of-candidates\r\n
m=video 9 UDP/TLS/RTP/SAVPF 99\r\n
c=IN IP4 199.87.83.38\r\n
a=sendonly\r\n
a=mid:video0\r\n
a=rtcp-mux\r\n
a=ice-ufrag:neAt\r\n
a=ice-pwd:fKp2IopxFys5002tc4wj4z\r\n
a=ice-options:trickle\r\n
a=fingerprint:sha-256 D2:B9:31:8F:DF:24:D8:0E:ED:D2:EF:25:9E:AF:6F:B8:34:AE:53:9C:E6:F3:8F:F2:64:15:FA:E8:7F:53:2D:38\r\n
a=setup:active\r\n
a=rtpmap:99 H264/90000\r\n
a=rtcp-fb:99 ccm fir\r\n
a=rtcp-fb:99 nack\r\n
a=rtcp-fb:99 nack pli\r\n
a=rtcp-fb:99 goog-remb\r\n
a=rtcp-fb:99 transport-cc\r\n
a=fmtp:99 packetization-mode=1; profile-level-id=4D401E; sprop-parameter-sets=Z01AHppkDwKP+AtwEBAUAAAPoAADqYOhgDUwANSK7y40MAamABqRXeXCgA==,aO48gA==;\r\n
a=ssrc:4217440612 cname:janusvideo\r\n
a=ssrc:4217440612 msid:janus janusv0\r\n
a=ssrc:4217440612 mslabel:janus\r\n
a=ssrc:4217440612 label:janusv0\r\n
a=candidate:1 1 udp 2013266431 10.0.19.194 33380 typ host\r\n
a=candidate:2 1 udp 1677722111 199.87.83.38 33380 typ srflx raddr 10.0.19.194 rport 33380\r\n
a=candidate:3 1 udp 503316991 52.53.192.70 49252 typ relay raddr 10.0.19.194 rport 33380\r\n
a=end-of-candidates\r\n"