Esquema da característica da transmissão da câmera de casa inteligente

action.devices.traits.CameraStream: essa característica aborda como controlar o stream da câmera de um dispositivo.

Essa característica pertence a dispositivos capazes de fazer streaming de feeds de vídeo para smart displays, dispositivos compatíveis com Chromecast ou smartphones. De modo geral, são câmeras de segurança ou câmeras infantis. No entanto, essa característica também se aplica a dispositivos mais complexos que têm uma câmera, como dispositivos de videoconferência ou um robô a vácuo com uma câmera.

ATRIBUTOS do dispositivo

Dispositivos com essa característica podem informar os atributos a seguir como parte da operação SYNC. Para saber mais sobre como gerenciar intents SYNC, consulte Fulfillment de intents.

Atributos Tipo Descrição
cameraStreamSupportedProtocols Array

Obrigatório.

Tipos de mídia compatíveis com o stream da câmera, ordenados por preferência. Normalmente, é solicitado o primeiro protocolo nesta matriz que seja compatível com a superfície de destino.

[item, ...] String

Tipo de mídia.

Os valores suportados são:

hls
Transmissão ao vivo HTTP
dash
Streaming adaptável dinâmico sobre HTTP
smooth_stream
Transmissão sem falhas
progressive_mp4
MP4 progressivo (mais usado para clipes)
webrtc
WebRTC
cameraStreamNeedAuthToken Booleano

Obrigatório.

Indica se um token de autenticação vai ser fornecido via cameraStreamAuthToken para que a superfície de destino faça streaming do feed da câmera.

Exemplos

Câmera com suporte a vários protocolos, que não exige um token de autenticação.

{
  "cameraStreamSupportedProtocols": [
    "webrtc",
    "hls",
    "dash",
    "smooth_stream",
    "progressive_mp4"
  ],
  "cameraStreamNeedAuthToken": false
}

Câmera compatível com um único protocolo, que exige um token de autenticação.

{
  "cameraStreamSupportedProtocols": [
    "hls"
  ],
  "cameraStreamNeedAuthToken": true
}

Protocolos de streaming compatíveis

Essa característica é compatível com os seguintes protocolos de streaming:

Ao fazer streaming dos protocolos hls,dash, smooth_stream e progressive_mp4 para dispositivos de transmissão (Chromecasts, smart displays e smart TVs compatíveis com Chromecast), um receptor da Web de transmissão é iniciado para processar o stream e renderizá-lo no dispositivo. É recomendável que o desenvolvedor crie um receptor da Web personalizado para permitir o acesso a ferramentas de depuração, personalizar o comportamento do player, personalizar o branding da interface e incluir análises. Para ativar o uso do receptor personalizado e desativar o uso do receptor padrão, defina o ID do app receptor gerado ao registrar seu app Cast no campo cameraStreamReceiverAppId da resposta EXECUTE.

Para saber mais sobre os apps receptores da Web personalizados, acesse o guia do site para desenvolvedores.

STATES do dispositivo

Nenhum.

COMANDOS do dispositivo

Dispositivos com essa característica podem responder aos comandos a seguir como parte da operação EXECUTE. Para saber mais sobre como gerenciar intents EXECUTE, consulte Fulfillment de intents.

action.devices.commands.GetCameraStream

Parâmetros

Parâmetros Tipo Descrição
StreamToChromecast Booleano

Obrigatório.

Indica se a transmissão será exibida em um dispositivo Chromecast.

SupportedStreamProtocols Array

Obrigatório.

Tipos/formatos de mídia aceitos pelo destino desejado.

[item, ...] String

Tipo de mídia.

Os valores suportados são:

hls
Transmissão ao vivo HTTP
dash
Streaming adaptável dinâmico sobre HTTP
smooth_stream
Transmissão sem falhas
progressive_mp4
MP4 progressivo (mais usado para clipes)
webrtc
WebRTC

Resultados

Resultados Tipo Descrição
cameraStreamAuthToken String

Um token de autenticação para o receptor específico autorizar o acesso ao stream. Se cameraStreamNeedAuthToken for verdadeiro e esse valor não for fornecido, as credenciais de OAuth do usuário serão usadas como o token de autenticação.

cameraStreamProtocol String

Obrigatório.

É o formato de mídia para onde o URL do stream aponta. Ele precisa ser um dos protocolos listados no parâmetro de comando SupportedStreamProtocols.

Os valores suportados são:

hls
Transmissão ao vivo HTTP
dash
Streaming adaptável dinâmico sobre HTTP
smooth_stream
Transmissão sem falhas
progressive_mp4
MP4 progressivo (mais usado para clipes)
webrtc
WebRTC

Resultados não WebRTC

Resultados Tipo Descrição
cameraStreamAccessUrl String

Obrigatório.

Endpoint do URL para recuperar o stream em tempo real no formato especificado por cameraStreamProtocol.

cameraStreamReceiverAppId String

O ID do receptor da transmissão é usado para processar o stream da câmera quando o parâmetro StreamToChromecast for verdadeiro. O receptor padrão será usado se não for fornecido.

Resultados do WebRTC

Resultados Tipo Descrição
cameraStreamSignalingUrl String

Obrigatório.

O endpoint do URL para recuperar e trocar protocolos de descrição da sessão (SDPs) de câmeras e clientes. O cliente precisa retornar o URL de sinalização que usa o cameraStreamAuthToken como o token de autenticação no cabeçalho da solicitação.

cameraStreamOffer String

Protocolo de descrição da sessão de oferta (SDP, na sigla em inglês).

cameraStreamIceServers String

Representa os servidores de Interactive Connectivity Connectivity (ICE) usando uma string JSON codificada com a descrição de um RTCIceServer. Se você não especificar servidores STUN (Utilidades de travessia de sessão para NAT), a plataforma será padronizada para os servidores STUN públicos do Google. Os servidores de travessia usando redirecionamentos por NAT (turn, na sigla em inglês) só serão necessários se você não puder garantir que os IPs / candidatos ICE fornecidos serão acessíveis publicamente (por exemplo, por meio de um servidor de mídia, candidato a ICE de host público, candidato a ICE de redirecionamento etc).

Exemplos

Mostrar a câmera da porta da frente (receptor de transmissão padrão).

{
  "cameraStreamAccessUrl": "https://fluffysheep.com/baaaaa.mp4",
  "cameraStreamProtocol": "progressive_mp4"
}

Mostrar a câmera da porta da frente (receptor de transmissão personalizado).

{
  "cameraStreamAccessUrl": "https://fluffysheep.com/baaaaa.mp4",
  "cameraStreamReceiverAppId": "1g2f89213hg",
  "cameraStreamAuthToken": "12657342190192783",
  "cameraStreamProtocol": "progressive_mp4"
}

Mostrar a câmera da porta da frente (stream WebRTC.

{
  "cameraStreamIceServers": "[{\"urls\": \"stun:stun.l.partner.com:19302\"},{\"urls\":\"turn:192.158.29.39:3478?transport=udp\",\"credential\": \"JZEOEt2V3Qb0y27GRntt2u2PAYA=\",\"username\": \"28224511:1379330808\"},{\"urls\": \"turn:192.158.29.39:3478?transport=tcp\",\"credential\": \"JZEOEt2V3Qb0y27GRntt2u2PAYA=\",\"username\": \"28224511:1379330808\"}]",
  "cameraStreamSignalingUrl": "https://example.com/signaling/answer",
  "cameraStreamOffer": "o=- 4611731400430051336 2 IN IP4 127.0.0.1...",
  "cameraStreamProtocol": "webrtc"
}

ERROS DO DISPOSITIVO

Veja a lista completa de erros e exceções.

Especificações do protocolo WebRTC

Os benefícios de usar o WebRTC são baixa latência e conversa unidirecional. O WebRTC usa um método POST com corpo e resposta POST no formato JSON.

No momento, o WebRTC é compatível com os dispositivos Google Nest Smart Display e Chromecast com Google TV.

Esta seção descreve os requisitos para usar o protocolo de stream WebRTC.

Tipo de dados Parâmetros/definições
Cabeçalho da solicitação de sinalização

O cabeçalho deve atender a estes requisitos:

  • Autenticação: o cabeçalho de autenticação precisa usar o token de autenticação do valor de retorno GetCameraStream para cameraStreamAuthToken com o tipo de token Bearer.
  • Tipo de conteúdo: application/json.
Parâmetros de solicitação de sinalização

A solicitação pode incluir estes parâmetros:

  • action: string. Os valores válidos são:
    • offer: mostra a mensagem do SDP do provedor.
    • answer: responde a mensagem do SDP do provedor.
    • end: fecha a sessão atual.
  • deviceId: string. O ID do dispositivo, conforme relatado em uma solicitação SYNC ou EXECUTE.
  • sdp: string. Contém a mensagem do protocolo de descrição da sessão para a conexão de peering. O conteúdo é baseado no valor do parâmetro action. Se action for "end", esse parâmetro poderá ficar vazio.
Parâmetros de resposta da sinalização

A resposta pode incluir estes parâmetros:

  • action: string. O valor da resposta precisa ser do tipo answer.
  • sdp: string. Mensagem SDP para a resposta.

Requisitos e recomendações do WebRTC

  • Atualmente, o Google oferece suporte à comunicação unidirecional (half-duplex).
  • É preciso oferecer suporte ao agrupamento e ao rtcp-mux.
  • Use o (D)TLS 1.2 ou mais recente.
  • O Trickle ICE não é compatível. Todos os candidatos ICE precisam ser reunidos antes de enviar o SDP.
  • É altamente recomendável incluir candidatos ICE UDP/IPv4, TCP/IPv4, UDP/IPv6 e TCP/IPv6 para aumentar a probabilidade de uma conexão bem-sucedida.

Resoluções de vídeo compatíveis:

  • Mínimo:480p
  • Máximo: 1080p

Codecs de vídeo suportados:

  • VP8
  • H.264

Codecs de áudio compatíveis:

  • Opus (codec preferido)
  • G.711/PCMU
  • G.722

Compartilhamento de recursos entre origens

O compartilhamento de recursos entre origens (CORS, na sigla em inglês) é um mecanismo que usa cabeçalhos HTTP extras para informar aos navegadores que é possível permitir que um aplicativo da Web executado em uma origem acesse recursos selecionados de uma origem diferente. O servidor que hospeda cameraStreamSignalingUrl precisa responder com este cabeçalho:

Access-Control-Allow-Origin: https://www.gstatic.com

Exemplo de solicitação e resposta de sinalização

O exemplo a seguir mostra uma solicitação que o Google envia ao serviço de sinalização e a resposta correspondente ao Google.

Solicitação
Header:

Authentication: Bearer <cameraStreamAuthToken>
Content-Type: application/json

POST body:

// When camera offer SDP is provided in the execution response, Google provides an answer SDP.
{
  "action": "answer",
  "deviceId": "123",
  "sdp": "o=- 4611731400430051336 2 IN IP4 127.0.0.1..."
}

// When camera offer SDP is not provided in execution response, Google generates and provides an offer SDP.
{
  "action": "offer",
  "deviceId": "123",
  "sdp": "o=- 4611731400430051336 2 IN IP4 127.0.0.1..."
}

// Close the current stream session.
{
  "action": "end"
  "deviceId": "123"
}

Resposta
// Response to accept the answer SDP in the request.
Response Code : 200
{}

// Response to provide the answer SDP from the service provider.
Response Code : 200
{
  // When the camera offer SDP is not provided in the execution response,
  // Google provides the answer SDP via the signaling response.
  "action": "answer"
  "sdp": "o=- 4611731400430051336 2 IN IP4 127.0.0.1..."
}

// Response to close current session.
Response Code : 200
{}