Schema tratto dello stream delle videocamere per la smart home

action.devices.traits.CameraStream: questa caratteristica riguarda come controllare il flusso della videocamera di un dispositivo.

Questo tratto appartiene ai dispositivi che sono in grado di trasmettere feed video in streaming a smart display, dispositivi compatibili con Chromecast o smartphone. In generale, si tratta di videocamere di sicurezza o videocamere per bambini. Ma questa caratteristica si applica anche ai dispositivi più complessi su cui è installata una videocamera (ad esempio, dispositivi per videoconferenze o un robot aspirapolvere con una videocamera).

ATTRIBUTI dispositivo

I dispositivi con questo tratto potrebbero segnalare i seguenti attributi nell'ambito dell'operazione SYNC. Per scoprire di più sulla gestione degli intent SYNC, consulta Completamento dell'intent.

Attributi Tipo Descrizione
cameraStreamSupportedProtocols Array

Obbligatorio.

Tipi di contenuti multimediali supportati per lo stream della videocamera, ordinati in base alle preferenze. In genere, viene richiesto il primo protocollo di questo array che sia compatibile con la piattaforma di destinazione.
[item, ...] String

Tipo multimediale.

Valori supportati:

hls
Live streaming HTTP
dash
Streaming adattivo dinamico su HTTP
smooth_stream
Streaming fluido
progressive_mp4
MP4 progressivo (utilizzato principalmente per i clip)
webrtc
WebRTC
cameraStreamNeedAuthToken Valore booleano

Obbligatorio.

Indica se verrà fornito un token di autorizzazione tramite cameraStreamAuthToken per consentire alla piattaforma di destinazione di riprodurre in streaming il feed della videocamera.

Esempi

Videocamera con supporto di più protocolli, senza la necessità di un token di autenticazione.

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

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

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

Protocolli di streaming supportati

Questa trait supporta i seguenti protocolli di streaming:

Durante lo streaming dei protocolli hls,dash,smooth_stream e progressive_mp4 ai dispositivi di trasmissione (Chromecast, smart display e smart TV compatibili con Chromecast), viene avviato un web ricevitore di trasmissione per elaborare lo streaming e visualizzarlo sul dispositivo. Consigliamo allo sviluppatore di creare un ricevitore web personalizzato per abilitare l'accesso agli strumenti di debug, personalizzare il comportamento del player, personalizzare il branding dell'interfaccia utente e includere dati e analisi. Per attivare l'utilizzo del ricevitore personalizzato e disattivare il ricevitore predefinito, imposta l'ID app del destinatario generato quando registri l'app di trasmissione nel campo cameraStreamReceiverAppId della risposta EXECUTE.

Per ulteriori informazioni sulle applicazioni ricevitori web personalizzati, visita la guida al sito per gli sviluppatori.

Dispositivo STATES

Nessuna.

COMMANDS dispositivo

I dispositivi con questo tratto potrebbero rispondere ai seguenti comandi nell'ambito dell'operazione EXECUTE. Per scoprire di più sulla gestione degli intent EXECUTE, consulta Completamento dell'intent.

action.devices.commands.GetCameraStream

Parametri

Parametri Tipo Descrizione
StreamToChromecast Valore booleano

Obbligatorio.

Se lo stream verrà riprodotto su un dispositivo Chromecast.
SupportedStreamProtocols Array

Obbligatorio.

Formati/tipi di elementi multimediali supportati dalla destinazione desiderata.
[item, ...] String

Tipo multimediale.

Valori supportati:

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

Risultati

Risultati Tipo Descrizione
cameraStreamAuthToken String

Un token di autorizzazione per il destinatario specifico per autorizzare l'accesso allo stream. Se cameraStreamNeedAuthToken è true e questo valore non viene 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 comando SupportedStreamProtocols.

Valori supportati:

hls
Live streaming HTTP
dash
Streaming adattivo dinamico su HTTP
smooth_stream
Streaming fluido
progressive_mp4
MP4 progressivo (utilizzato principalmente 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 SDP (SDP) per videocamere e client. Il client deve restituire l'URL di segnalazione che utilizza cameraStreamAuthToken come token di autenticazione nell'intestazione della richiesta.
cameraStreamOffer String

Offer Session Description Protocol (SDP).
cameraStreamIceServers String

Rappresenta i server ICE (Interactive Connectivity Preparement) che utilizzano 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 Relays around NAT) sono obbligatori solo se non è possibile garantire che i candidati IP / ICE forniti siano accessibili pubblicamente (ad es. tramite un media server, un candidato ICE host pubblico, un candidato ICE per l'inoltro e così via).

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 di errori ed eccezioni.

Specifiche del protocollo WebRTC

I vantaggi dell'utilizzo di WebRTC sono bassa latenza e conversazione unidirezionale. WebRTC utilizza un metodo POST con un corpo e una risposta POST in formato JSON.

WebRTC è attualmente supportato sullo smart display Google Nest e sui dispositivi Chromecast con Google TV.

Questa sezione descrive i requisiti per l'utilizzo del protocollo di streaming 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 restituito GetCameraStream per cameraStreamAuthToken con tipo di token Bearer.
  • Content-Type (Tipo di contenuto): application/json.
Parametri della richiesta di segnalazione

La richiesta può includere i seguenti parametri:

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

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 WebRTC

  • Al momento 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.
  • Consigliamo vivamente di includere candidati ICE UDP/IPv4, TCP/IPv4, UDP/IPv6 e TCP/IPv6 per aumentare le probabilità di riuscita della connessione.

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 indicare ai browser di consentire a un'applicazione web in esecuzione su un'origine di accedere a risorse selezionate da un'origine diversa. Il server che ospita cameraStreamSignalingUrl deve 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
{}