Schéma de trait de flux de la caméra pour la maison connectée

action.devices.traits.CameraStream : cette caractéristique explique comment contrôler le flux de caméras d'un appareil.

Cette caractéristique appartient aux appareils capables de diffuser des flux vidéo sur des écrans connectés, des appareils compatibles Chromecast ou des smartphones. De manière générale, il s'agit de caméras de sécurité ou de caméras pour bébés. Mais cette caractéristique s'applique également aux appareils plus complexes équipés d'une caméra (par exemple, des appareils de visioconférence ou un aspirateur robot avec une caméra).

ATTRIBUTS DES APPAREILS

Les appareils dotés de cette caractéristique peuvent signaler les attributs suivants dans le cadre de l'opération SYNC. Pour en savoir plus sur la gestion des intents SYNC, consultez la section Traitement des intents.

Attributs Type Description
cameraStreamSupportedProtocols Array

Obligatoire.

Types de contenus multimédias compatibles avec le flux de la caméra, triés par ordre de préférence. En règle générale, le premier protocole de ce tableau compatible avec la surface cible est demandé.

[item, ...] Chaîne

Type de contenu.

Valeurs acceptées :

hls
Streaming en direct via HTTP
dash
Streaming adaptatif dynamique sur HTTP
smooth_stream
Streaming fluide
progressive_mp4
MP4 progressif (principalement utilisé pour les extraits)
webrtc
WebRTC
cameraStreamNeedAuthToken Valeur booléenne

Obligatoire.

Indique si un jeton d'authentification sera fourni via cameraStreamAuthToken pour que la surface cible diffuse le flux de la caméra.

Exemples

Caméra compatible avec plusieurs protocoles, ne nécessitant pas de jeton d'authentification.

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

Caméra compatible avec un seul protocole, nécessitant un jeton d'authentification.

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

Protocoles de streaming compatibles

Cette caractéristique est compatible avec les protocoles de streaming suivants:

Lors de la diffusion en streaming des protocoles hls, dash, smooth_stream et progressive_mp4 sur des appareils Cast (Chromecast, écrans connectés et smart TV compatibles Chromecast), un récepteur Web Cast est lancé pour traiter le flux et le diffuser sur l'appareil. Nous recommandons au développeur de créer un récepteur Web personnalisé pour autoriser l'accès aux outils de débogage, personnaliser le comportement du lecteur, personnaliser le branding de l'interface utilisateur et inclure des données analytiques. Pour activer l'utilisation du récepteur personnalisé et désactiver le récepteur par défaut, définissez l'ID de l'application du récepteur généré lorsque vous enregistrez votre application Cast dans le champ cameraStreamReceiverAppId de la réponse EXECUTE.

Pour en savoir plus sur les applications de récepteur Web personnalisé, consultez le guide du site destiné aux développeurs.

ÉTATS de l'appareil

Aucune

COMMANDES D'appareil

Les appareils dotés de cette caractéristique peuvent répondre aux commandes suivantes dans le cadre de l'opération EXECUTE. Pour en savoir plus sur la gestion des intents EXECUTE, consultez la section Traitement des intents.

action.devices.commands.GetCameraStream

Paramètres

Paramètres Type Description
StreamToChromecast Valeur booléenne

Obligatoire.

Indique si le flux sera lu sur un appareil Chromecast.

SupportedStreamProtocols Array

Obligatoire.

Types/formats de supports acceptés par la destination souhaitée.

[item, ...] Chaîne

Type de contenu.

Valeurs acceptées :

hls
Streaming en direct via HTTP
dash
Streaming adaptatif dynamique sur HTTP
smooth_stream
Streaming fluide
progressive_mp4
MP4 progressif (principalement utilisé pour les extraits)
webrtc
WebRTC

Résultats

Résultats Type Description
cameraStreamAuthToken Chaîne

Un jeton d'authentification pour le destinataire spécifique afin d'autoriser l'accès au flux. Si cameraStreamNeedAuthToken est défini sur "true" et que cette valeur n'est pas fournie, les identifiants OAuth de l'utilisateur sont utilisés comme jeton d'authentification.

cameraStreamProtocol Chaîne

Obligatoire.

Format du média vers lequel pointe l'URL du flux. Il doit correspondre à l'un des protocoles répertoriés dans le paramètre de commande SupportedStreamProtocols.

Valeurs acceptées :

hls
Streaming en direct via HTTP
dash
Streaming adaptatif dynamique sur HTTP
smooth_stream
Streaming fluide
progressive_mp4
MP4 progressif (principalement utilisé pour les extraits)
webrtc
WebRTC

Résultats non WebRTC

Résultats Type Description
cameraStreamAccessUrl Chaîne

Obligatoire.

Point de terminaison de l'URL permettant de récupérer le flux en temps réel au format spécifié par cameraStreamProtocol.

cameraStreamReceiverAppId Chaîne

ID du récepteur de cast pour traiter le flux de la caméra lorsque le paramètre StreamToChromecast est défini sur "true". Le récepteur par défaut est utilisé s'il n'est pas fourni.

Résultats WebRTC

Résultats Type Description
cameraStreamSignalingUrl Chaîne

Obligatoire.

Point de terminaison de l'URL permettant de récupérer et d'échanger les protocoles de description de session (SDP) de l'appareil photo et du client. Le client doit renvoyer l'URL de signalement qui utilise cameraStreamAuthToken comme jeton d'authentification dans l'en-tête de la requête.

cameraStreamOffer Chaîne

Protocole de description de session d'offre (SDP).

cameraStreamIceServers Chaîne

Représente les serveurs ICE (Interactive Connectivity Establishment) à l'aide d'une chaîne JSON encodée avec la description d'un RTCIceServer. Si vous ne spécifiez pas de serveurs STUN (Session Traversal Utilities for NAT), la plate-forme utilise par défaut les serveurs STUN publics de Google. Les serveurs turn (Traversal using Relays rounds NAT) ne sont obligatoires que si vous ne pouvez pas garantir que les adresses IP et les candidats ICE fournis sont accessibles publiquement (par exemple, via un serveur multimédia, un candidat au réseau ICE de l'hôte public, un candidat au relais ICE, etc.).

Exemples

Affichez la caméra de la porte d'entrée (récepteur Cast par défaut).

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

Affichez la caméra de la porte d'entrée (récepteur Cast personnalisé).

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

Affichez la caméra de la porte d'entrée (flux 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"
}

ERREURS sur l'appareil

Consultez la liste complète des erreurs et exceptions.

Spécifications du protocole WebRTC

WebRTC offre plusieurs avantages : une faible latence et une communication unidirectionnelle. WebRTC utilise une méthode POST avec un corps POST et une réponse au format JSON.

WebRTC est actuellement compatible avec les écrans connectés Google Nest et Chromecast avec Google TV.

Cette section décrit les conditions requises lorsque vous utilisez le protocole de flux WebRTC.

Type de données Paramètres/Définitions
En-tête de requête de signalisation

L'en-tête doit respecter les exigences suivantes:

  • Authentification: l'en-tête d'authentification doit utiliser le jeton d'authentification de la valeur renvoyée GetCameraStream pour cameraStreamAuthToken avec le type de jeton Bearer.
  • Content-Type (Type de contenu) : application/json.
Paramètres des requêtes de signalisation

La requête peut inclure les paramètres suivants:

  • action: chaîne. Les valeurs valides sont les suivantes :
    • offer: propose un message SDP du fournisseur.
    • answer: répondre au message SDP du fournisseur.
    • end: fermer la session en cours.
  • deviceId: chaîne. ID de l'appareil indiqué dans une requête SYNC ou EXECUTE.
  • sdp: chaîne. Contient le message Session Description Protocol pour la connexion au pair. Le contenu est basé sur la valeur du paramètre action. Si action est défini sur "end", ce paramètre peut être vide.
Paramètres de réponse du signal

La réponse peut inclure les paramètres suivants:

  • action: chaîne. La valeur de la réponse doit être de type answer.
  • sdp: chaîne. Message SDP pour la réponse.

Exigences et recommandations WebRTC

  • Google prend actuellement en charge la communication unidirectionnelle (demi-duplex).
  • Vous devez accepter le regroupement et rtcp-mux.
  • Vous devez utiliser (D)TLS 1.2 ou une version ultérieure.
  • La fonctionnalité Trickle ICE n'est pas compatible. Tous les candidats ICE doivent d'abord être rassemblés avant d'envoyer le SDP.
  • Nous vous recommandons vivement d'inclure des candidats UDP/IPv4, TCP/IPv4, UDP/IPv6 et TCP/IPv6 ICE pour augmenter les chances d'établissement d'une connexion.

Résolutions vidéo compatibles:

  • Minimum:480p
  • Maximum:1080p

Codecs vidéo compatibles:

  • VP8
  • H.264

Codecs audio compatibles:

  • Opus (codec préféré)
  • G.711/PCMU
  • G.722

Partage de ressources entre origines

Le partage des ressources inter-origines (CORS, Cross-Origin Resource Sharing) est un mécanisme qui utilise des en-têtes HTTP supplémentaires pour indiquer aux navigateurs qu'ils permettent à une application Web exécutée dans une origine d'accéder à des ressources sélectionnées depuis une origine différente. Le serveur hébergeant cameraStreamSignalingUrl doit répondre avec l'en-tête suivant:

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

Exemple de requête et de réponse de signalement

L'exemple suivant montre une requête que Google envoie à votre service de signalement et la réponse correspondante à Google.

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

Réponse
// 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
{}