Video_stream

devices.capabilities.video_stream

Getting a video stream from a camera.

Common voice commands

Yasmina, show the camera in the hallway.
Yasmina, turn on video from the nursery.
Yasmina, video from the summer house.
Yasmina, camera from the hallway.

Description of capability

The structure is used in the response to the Information about user devices operation.

Capability parameters


Parameter	Type	Description	Required
type	String	Capability type.	Yes
retrievable	Boolean	Always `false`.	Yes
reportable	Boolean	Always `false`.	Yes
parameters	Object	`parameters` object.	Yes
`parameters` object
protocols	Array of Strings	It currently supports only the `HLS` streaming protocol. Supported video codecs: `H264`. Maximum video resolution: `1920 × 1080`. Supported audio codecs: `AAC`.	Yes


Parameter	Type	Description	Required
type	String	Capability type.	Yes
retrievable	Boolean	Always `false`.	Yes
reportable	Boolean	Always `false`.	Yes
parameters	Object	`parameters` object.	Yes
`parameters` object
protocols	Array of Strings	It currently supports only the `HLS` streaming protocol. Supported video codecs: `H264`. Maximum video resolution: `1920 × 1080`. Supported audio codecs: `AAC`.	Yes

Example of use

Yango Smart Home requests the details of user devices from the provider. The provider responds that the user has a camera that can output video streams in different formats.

curl -i -X GET 'https://example.com/v1.0/user/devices' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...'
Copied to clipboard

HTTP/1.1 200 OK

{
  "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "user_id": "user-001",
    "devices": [
      {
        "id": "cam-hd-01x",
        "name": "my camera",
        "description": "smart camera",
        "room": "bedroom",
        "type": "devices.types.camera",
        "capabilities": [
          {
            "type": "devices.capabilities.video_stream",
            "retrievable": false,
            "reportable": false,
            "parameters": {
              "protocols": ["hls"]
            }
          }
        ],
        "device_info": {
          "manufacturer": "Provider-01",
          "model": "hd-01x",
          "hw_version": "1.2",
          "sw_version": "5.4"
        }
      }
    ]
  }
}
Copied to clipboard

Current capability state

This capability doesn't provide a state, so you don't have to include it in the response to the Information about the states of user devices request. For devices that don't have a capability with the parameter retrievable: true, responses transmit the general status of the device (for example, online, offline, unlinked from the account).

Example of use

Response to a request for a device containing only one video_stream capability.

HTTP/1.1 200 OK

{
  "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": [
      {
        "id": "cam-hd-01x"
      }
    ]
  }
}

Response to a request for an unavailable device containing only one video_stream capability.

HTTP/1.1 200 OK

{
  "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": [
      {
        "id": "cam-hd-01x",
        "error_code": "DEVICE_UNREACHABLE",
        "error_message": "device is offline"
      }
    ]
  }
}

Change the state of the device capability

The structure is used in the request/response to the Change device state operation.

Capability parameters


Parameter	Type	Description	Required
type	String	Capability type.	Yes
state	Object	An object describing an action on the capability.	Yes
`state` object
instance	String	The function of the capability. Acceptable values: `get_stream`.	Yes
value	Object	Parameters of the video stream.	Yes
`value` object
protocols	Array of Strings	It currently supports only the `HLS` streaming protocol.	Yes


Parameter	Type	Description	Required
type	String	Capability type.	Yes
state	Object	An object describing an action on the capability.	Yes
`state` object
instance	String	The function of the capability. Acceptable values: `get_stream`.	Yes
value	Object	Parameters of the video stream.	Yes
`value` object
protocols	Array of Strings	It currently supports only the `HLS` streaming protocol.	Yes


Parameter	Type	Description	Required
type	String	Capability type.	Yes
state	Object	An object that describes the result of changing the state of the capability.	Yes
`state` object
instance	String	The function of the capability. Acceptable values: `get_stream`.	Yes
value	Object	An object describing the video stream. If `status:"DONE"`, the parameter is required.	No
action_result	Object	An object that describes the stream.	Yes
`value` object
stream_url	String	The URL of the stream with the parameters specified in the request. In response to the stream request by this link, the following headers must be returned: `Content-type: application/vnd.apple.mpegurl` `Access-Control-Allow-Origin: https://yastatic.net`	Yes
protocol	String	A streaming protocol.	Yes
`action_result` object
status	String	Status of the device capability state change. Acceptable values: `DONE`: The state of the device capability state changed. `ERROR`: An error occurred when changing the state of the device capability.	Yes
error_code	String	An error code from the list of errors. If `status:"ERROR"`, the parameter is required.	No
error_message	String	Extended human-readable description of a possible error. It is displayed only in the Testing section of the developer console.	No


Parameter	Type	Description	Required
type	String	Capability type.	Yes
state	Object	An object that describes the result of changing the state of the capability.	Yes
`state` object
instance	String	The function of the capability. Acceptable values: `get_stream`.	Yes
value	Object	An object describing the video stream. If `status:"DONE"`, the parameter is required.	No
action_result	Object	An object that describes the stream.	Yes
`value` object
stream_url	String	The URL of the stream with the parameters specified in the request. In response to the stream request by this link, the following headers must be returned: `Content-type: application/vnd.apple.mpegurl` `Access-Control-Allow-Origin: https://yastatic.net`	Yes
protocol	String	A streaming protocol.	Yes
`action_result` object
status	String	Status of the device capability state change. Acceptable values: `DONE`: The state of the device capability state changed. `ERROR`: An error occurred when changing the state of the device capability.	Yes
error_code	String	An error code from the list of errors. If `status:"ERROR"`, the parameter is required.	No
error_message	String	Extended human-readable description of a possible error. It is displayed only in the Testing section of the developer console.	No

Example of use

Yango Smart Home requests the provider to change the state of the user's devices. The provider responds with the result of user device state change.

Note.

The provider must respond to the request within 4 seconds. Otherwise, the video won't open.

curl -i -X POST 'https://example.com/v1.0/user/devices/action' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...' \
-H 'Content-Type: application/json' \
-d '{
      "payload": {
        "devices":
        [
          {
            "id": "cam-hd-01x",
            "custom_data": {
              "api_location": "rus"
            },
            "capabilities": [
              {
                "type": "devices.capabilities.video_stream",
                "state": {
                  "instance": "get_stream",
                  "value": {
                    "protocols": [
                      "hls"
                    ]
                  }
                }
              }
            ]
          }
        ]
      }
    }'
Copied to clipboard

HTTP/1.1 200 OK

{
  "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": [
      {
        "id": "cam-hd-01x",
        "capabilities": [
          {
            "type": "devices.capabilities.video_stream",
            "state": {
              "instance": "get_stream",
              "value": {
                "stream_url": "https://host/path/to/playlist.m3u8?token=123456789abcdef",
                "protocol": "hls"
              },
              "action_result": {
                "status": "DONE"
              }
            }
          }
        ]
      }
    ]
  }
}
Copied to clipboard