CameraLiveStream Schema

Nest Cam Indoor Nest Cam (outdoor or indoor, battery) Nest Hub Max Nest Doorbell (wired) Nest Doorbell (battery) 

sdm.devices.traits.CameraLiveStream

This trait belongs to any device that supports live streaming.

Fields

Field Description Data Type
maxVideoResolution Maximum resolution of the video live stream. VideoResolution
videoCodecs Video codecs supported for the live stream. array(string)
Value: ["H264"]
audioCodecs Audio codecs supported for the live stream. array(string)
Value: ["AAC"]
supportedProtocols Streaming protocols supported by the device. The value of this field indicates which commands are supported for the device. For example, if this field contains WEB_RTC, only WEB_RTC commands are supported. array(string)
Value: ["RTSP", "WEB_RTC"]

VideoResolution

Field Description Data Type
width Maximum image resolution width. May also be used as a query parameter in the download URL. int32
Example: 640
height Maximum image resolution height. May also be used as a query parameter in the download URL. int32
Example: 480

Sample GET request and response

Request

GET /enterprises/project-id/devices/device-id

Response

{
  "name" : "enterprises/project-id/devices/device-id",
  "traits" : {
    "sdm.devices.traits.CameraLiveStream" : {
      "maxVideoResolution" : {
        "width" : 640,
        "height" : 480
      },
      "videoCodecs" : ["H264"],
      "audioCodecs" : ["AAC"],
      "supportedProtocols" : ["WEB_RTC"]
    }
  }
}

Commands

GenerateRtspStream

Nest Cam Indoor Nest Hub Max Nest Doorbell (wired) 

Request a token to access an RTSP live stream URL.

RTSP live stream URLs cannot be shared between clients. A stream URL can only be used by one client at a time. If multiple clients want to stream from the same camera at the same time, RTSP commands must be sent for each individual client, and each individual client must use its own stream URL.

GenerateRtspStream request and response

Request

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.CameraLiveStream.GenerateRtspStream",
  "params" : {}
}

Response

{
  "results" : {
    "streamUrls" : {
      "rtspUrl" : "rtsps://someurl.com/CjY5Y3VKaTZwR3o4Y19YbTVfMF...?auth=g.0.streamingToken"
    },
    "streamExtensionToken" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
    "streamToken" : "g.0.streamingToken",
    "expiresAt" : "2018-01-04T18:30:00.000Z"
  }
}

GenerateRtspStream response fields

Field Description Data Type
streamUrls Map of RTSP live stream URLs. object
streamExtensionToken Token to use to extend the streamToken for an RTSP live stream. string
Example: "CjY5Y3VKaTZwR3o4Y19YbTVfMF..."
streamToken Token to use to access an RTSP live stream. string
Example: "g.0.streamingToken"
expiresAt Time at which both streamExtensionToken and streamToken expire, in RFC 3339 format. string
Example: "2018-01-04T18:30:00.000Z"

ExtendRtspStream

Nest Cam Indoor Nest Hub Max Nest Doorbell (wired) 

Request a new RTSP live stream URL access token to replace a valid RTSP access token before it expires. This is also used to replace a valid RTSP token from a previous ExtendRtspStream command request.

Camera live stream sessions are only valid for 5 minutes. If you need to extend the lifetime of a live stream, use the appropriate ExtendFormatStream command of the CameraLiveStream trait for the stream format you generated.

ExtendRtspStream request and response

Request

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.CameraLiveStream.ExtendRtspStream",
  "params" : {
    "streamExtensionToken" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF..."
  }
}

Response

{
  "results" : {
    "streamExtensionToken" : "dGNUlTU2CjY5Y3VKaTZwR3o4Y1...",
    "streamToken" : "g.0.newStreamingToken",
    "expiresAt" : "2018-01-04T18:30:00.000Z"
  }
}

ExtendRtspStream request fields

Field Description Data Type
streamExtensionToken Token to use to request an extension to the RTSP streaming token. string
Example: "CjY5Y3VKaTZwR3o4Y19YbTVfMF..."

ExtendRtspStream response fields

Field Description Data Type
streamExtensionToken Token to use to view an existing RTSP live stream and to request an extension to the streaming token. string
Example: "dGNUlTU2CjY5Y3VKaTZwR3o4Y1..."
streamToken New token to use to access an existing RTSP live stream. string
Example: "g.0.newStreamingToken"
expiresAt Time at which both streamExtensionToken and streamToken expire, in RFC 3339 format. string
Example: "2018-01-04T18:30:00.000Z"

StopRtspStream

Nest Cam Indoor Nest Hub Max Nest Doorbell (wired) 

Invalidates a valid RTSP access token and stops the RTSP live stream tied to that access token.

StopRtspStream request and response

Request

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.CameraLiveStream.StopRtspStream",
  "params" : {
    "streamExtensionToken" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF..."
  }
}

Response

{}

StopRtspStream request fields

Field Description Data Type
streamExtensionToken Token to use to invalidate an existing RTSP live stream. string
Example: "CjY5Y3VKaTZwR3o4Y19YbTVfMF..."

GenerateWebRtcStream

Nest Cam (outdoor or indoor, battery) Nest Doorbell (battery) 

Generate a WebRTC live stream for a device.

GenerateWebRtcStream request and response

Request

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.CameraLiveStream.GenerateWebRtcStream",
  "params" : {
    "offerSdp" : "offerSdp"
  }
}

Response

{
  "results" : {
    "answerSdp" : "answerSdp",
    "expiresAt" : "2020-01-04T18:30:00.000Z",
    "mediaSessionId" : "I4flueLguqDlCFVY58tSarb0aT..."
  }
}

GenerateWebRtcStream request fields

Field Description Data Type
offerSdp An SDP offer, specific to the local device that will display the WebRTC live stream.

Required: The audio setting in the offerSdp for this command must be set to a=recvonly (receive only).

string
Example: "offerSdp"

GenerateWebRtcStream response fields

The answerSdp must be used to generate the live stream within 30 seconds of receiving the response, otherwise it expires. If it expires, execute the GenerateWebRtcStream command again to receive a new answerSdp.

When opening WebRTC channels for the live stream, make sure to create a data channel as well as a video channel.

Field Description Data Type
answerSdp An SDP answer to be used with the local device that will display the WebRTC live stream. string
Example: "answerSdp"
expiresAt Time at which access to the WebRTC live stream expires, in RFC 3339 format. string
Example: "2020-01-04T18:30:00.000Z"
mediaSessionId Media session ID of the generated WebRTC live stream. string
Example: "I4flueLguqDlCFVY58tSarb0aT..."

ExtendWebRtcStream

Request that access to an existing WebRTC live stream be extended before it expires.

A WebRTC stream can only be extended on wire-powered cameras. A camera is considered wire-powered while plugged in for charging. If the camera is on battery power, a request to extend an active WebRTC stream will be ignored.

Camera live stream sessions are only valid for 5 minutes. If you need to extend the lifetime of a live stream, use the appropriate ExtendFormatStream command of the CameraLiveStream trait for the stream format you generated.

ExtendWebRtcStream request and response

Request

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.CameraLiveStream.ExtendWebRtcStream",
  "params" : {
    "mediaSessionId" : "I4flueLguqDlCFVY58tSarb0aT..."
  }
}

Response

{
  "results" : {
    "expiresAt" : "2018-01-04T18:30:00.000Z",
    "mediaSessionId" : "I4flueLguqDlCFVY58tSarb0aT..."
  }
}

ExtendWebRtcStream request fields

Field Description Data Type
mediaSessionId Media session ID of the WebRTC live stream to be extended. string
Example: "I4flueLguqDlCFVY58tSarb0aT..."

ExtendWebRtcStream response fields

Field Description Data Type
expiresAt The new time at which access to the WebRTC live stream expires, in RFC 3339 format. string
Example: "2018-01-04T18:30:00.000Z"
mediaSessionId Media session ID of the WebRTC live stream that was extended. string
Example: "I4flueLguqDlCFVY58tSarb0aT..."

StopWebRtcStream

Nest Cam (outdoor or indoor, battery) Nest Doorbell (battery) 

Invalidates a valid WebRTC media session and stops the WebRTC live stream tied to that session.

StopWebRtcStream request and response

Request

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.CameraLiveStream.StopWebRtcStream",
  "params" : {
    "mediaSessionId" : "I4flueLguqDlCFVY58tSarb0aT..."
  }
}

Response

{}

StopWebRtcStream request fields

Field Description Data Type
mediaSessionId Media session ID of the WebRTC live stream to stop. string
Example: "I4flueLguqDlCFVY58tSarb0aT..."

Errors

The following error code(s) may be returned in relation to this trait:

Error Message RPC Troubleshooting
Command is not supported for doorbell. FAILED_PRECONDITION A WebRTC stream cannot be extended on battery-powered doorbells. If a stream on a doorbell needs to be viewed beyond the initial session length, stop the existing stream and generate a new one.
Permission denied. PERMISSION_DENIED The user has not granted the developer the appropriate device-level permissions in Partner Connections Manager (PCM) required to execute a command.

See the API Error Code Reference for the full list of API error codes.