Schema del tratto CameraStream di Smart Home

action.devices.traits.CameraStream: questa caratteristica spiega come controllare lo streaming della videocamera di un dispositivo.

Questo tratto appartiene ai dispositivi in grado di trasmettere in streaming i feed video a smart display, dispositivi compatibili con Chromecast o smartphone. In genere si tratta di videocamere di sicurezza o videocamere per bambini. Questo tratto vale anche per i dispositivi più complessi dotati di una videocamera, ad esempio i dispositivi per videoconferenze o un robot aspirapolvere con la videocamera inserita.

ATTRIBUTE dispositivo

I dispositivi con questo trattino potrebbero segnalare i seguenti attributi come parte dell'operazione SYNC. Per saperne di più sulla gestione degli intent SYNC, consulta la sezione fulfillment di intent.

Attributi Tipo Descrizione
cameraStreamSupportedProtocols Array

Obbligatorio.

Tipi di contenuti multimediali supportati per lo stream della videocamera, ordinati in base alle preferenze. In genere, è richiesto il primo protocollo in questo array compatibile con la superficie di destinazione.

[item, ...] String

Tipo di elemento multimediale.

Valori supportati:

hls
Live streaming HTTP
dash
Streaming adattivo dinamico tramite HTTP
smooth_stream
Streaming fluido
progressive_mp4
MP4 progressivo (utilizzato soprattutto per i clip)
webrtc
WebRTC
cameraStreamNeedAuthToken Booleano

Obbligatorio.

Indica se verrà fornito un token di autenticazione tramite cameraStreamAuthToken per la piattaforma di destinazione per lo streaming del feed della videocamera.

Esempi

La fotocamera con più protocolli supporta, senza richiedere un token di autenticazione.

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

La fotocamera supporta un singolo protocollo, che richiede un token di autenticazione.

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

Protocolli di streaming supportati

Questa caratteristica supporta i seguenti protocolli di streaming:

STATO dispositivo

Nessuna.

COMANDI dispositivo

I dispositivi con questo trattino potrebbero rispondere ai seguenti comandi nell'ambito dell'operazione EXECUTE. Per saperne di più sulla gestione degli intent EXECUTE, consulta la sezione fulfillment di intent.

action.devices.commands.GetCameraStream

Parametri

Parametri Tipo Descrizione
StreamToChromecast Booleano

Obbligatorio.

Indica se lo stream verrà riprodotto su un dispositivo Chromecast.

SupportedStreamProtocols Array

Obbligatorio.

Tipi/formati multimediali supportati dalla destinazione desiderata.

[item, ...] String

Tipo di elemento multimediale.

Valori supportati:

hls
Live streaming HTTP
dash
Streaming adattivo dinamico tramite HTTP
smooth_stream
Streaming fluido
progressive_mp4
MP4 progressivo (utilizzato soprattutto per i clip)
webrtc
WebRTC

Risultati

Risultati Tipo Descrizione
cameraStreamAuthToken String

Un token di autenticazione per il destinatario specifico per autorizzare l'accesso allo stream. Se cameraStreamNeedAuthToken è true e questo valore non è fornito, le credenziali OAuth dell'utente verranno utilizzate come token di autenticazione.

cameraStreamProtocol String

Obbligatorio.

Il formato multimediale a cui rimanda l'URL dello stream. Deve essere uno dei protocolli elencati nel parametro di comando SupportedStreamProtocols.

Valori supportati:

hls
Live streaming HTTP
dash
Streaming adattivo dinamico tramite HTTP
smooth_stream
Streaming fluido
progressive_mp4
MP4 progressivo (utilizzato soprattutto per i clip)
webrtc
WebRTC

Risultati non webRTC

Risultati Tipo Descrizione
cameraStreamAccessUrl String

Obbligatorio.

Endpoint URL per il recupero dello stream in tempo reale nel formato specificato da cameraStreamProtocol.

cameraStreamReceiverAppId String

ID ricevitore di trasmissione per elaborare lo stream della videocamera quando il parametro StreamToChromecast è true; se non viene fornito, verrà utilizzato il ricevitore predefinito.

Risultati WebRTC

Risultati Tipo Descrizione
cameraStreamSignalingUrl String

Obbligatorio.

Endpoint URL per il recupero e lo scambio dei protocolli di descrizione della sessione (SDP) per videocamera e client. Il client dovrebbe restituire l'URL di segnalazione che utilizza cameraStreamAuthToken come token di autenticazione nell'intestazione della richiesta.

cameraStreamOffer String

Protocollo di descrizione della sessione (SDP).

cameraStreamIceServers String

Rappresenta i server ICE (Interactive Connectivity Establishment) utilizzando una stringa JSON codificata con la descrizione di un RTCIceServer. Se non specifichi i server STUN (Session Traversal Utilities for NAT), la piattaforma utilizza per impostazione predefinita i server STUN pubblici di Google. I server turn (Traversal Using Relay around NAT) sono obbligatori solo se non puoi garantire che gli IP / i candidati ICE forniti saranno pubblicamente accessibili (ad esempio tramite un server multimediale, un candidato ICE dell'host pubblico, un candidato ICE di inoltro ecc.).

Esempi

Mostra la videocamera della porta d'ingresso (ricevitore di trasmissione predefinito).

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

Mostra la videocamera della porta d'ingresso (ricevitore di trasmissione personalizzato).

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

Mostra la videocamera della porta d'ingresso (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"
}

ERRORI del dispositivo

Consulta l'elenco completo degli errori e delle eccezioni.

Specifiche del protocollo WebRTC

I vantaggi dell'utilizzo di WebRTC sono la latenza bassa e le conversazioni unidirezionali. WebRTC utilizza un metodo POST con un corpo e una risposta POST in formato JSON.

Attualmente WebRTC è supportato sugli smart display Google Nest e su Chromecast con dispositivi Google TV.

Questa sezione descrive i requisiti quando si utilizza il protocollo di stream WebRTC.

Tipo di dati Parametri/definizioni
Intestazione della richiesta di segnalazione

L'intestazione deve soddisfare i seguenti requisiti:

  • Autenticazione: l'intestazione di autenticazione deve utilizzare il token di autenticazione del valore di ritorno GetCameraStream per cameraStreamAuthToken con tipo di token Bearer.
  • Content-Type: application/json.
Parametri di richiesta di segnalazione

La richiesta può includere questi parametri:

  • action: stringa. I valori validi sono:
    • offer: offri un messaggio SDP del fornitore.
    • answer: rispondi al messaggio SDP del provider.
    • end: chiudi la sessione corrente.
  • deviceId: stringa. L'ID dispositivo riportato in una richiesta SYNC o EXECUTE.
  • sdp: stringa. Contiene il messaggio Protocol Description Protocol per la connessione peer. I contenuti si basano sul valore del parametro action. Se action è "end", questo parametro può essere vuoto.
Segnalazione dei parametri di risposta

La risposta può includere questi parametri:

  • action: stringa. Il valore della risposta deve essere di tipo answer.
  • sdp: stringa. Messaggio SDP per la risposta.

Requisiti e suggerimenti di WebRTC

  • Attualmente Google supporta la comunicazione unidirezionale (half duplex).
  • Devi supportare il raggruppamento e rtcp-mux.
  • Devi utilizzare (D)TLS 1.2 o versioni successive.
  • Trickle ICE non è supportato. Tutti i candidati ICE devono essere raccolti prima di inviare l'SDP.
  • Ti consigliamo vivamente di includere i candidati ICE UDP/IPv4, TCP/IPv4, UDP/IPv6 e TCP/IPv6 per aumentare la probabilità di una connessione riuscita.

Risoluzioni video supportate:

  • Minimo:480p
  • Massima: 1080p

Codec video supportati:

  • VP8
  • H.264

Codec audio supportati:

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

Condivisione delle risorse tra origini

La condivisione delle risorse tra origini (CORS) è un meccanismo che utilizza intestazioni HTTP aggiuntive per comunicare ai browser di consentire a un'applicazione web in esecuzione su un'origine di accedere alle risorse selezionate da un'origine diversa. Il server che ospita cameraStreamSignalingUrl dovrebbe rispondere con la seguente intestazione:

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

Esempio di richiesta e risposta di segnalazione

L'esempio seguente mostra una richiesta che Google invia al tuo servizio di segnalazione e la risposta corrispondente a Google.

Richiedi
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"
}

Risposta
// 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
{}