Cette page a été traduite par l'API Cloud Translation.

Présentation de l'API YouTube Live Streaming

L'API YouTube Live Streaming vous permet de créer, de mettre à jour et de gérer des événements en direct sur YouTube. Vous pouvez ainsi programmer des événements (diffusions) et les associer à des flux vidéo, lesquels constituent le contenu réel de la diffusion.

L'API Live Streaming contient en fait des composants de l'API YouTube Data et de l'API YouTube Content ID. L'API Data permet aux utilisateurs YouTube de gérer leurs comptes YouTube, tandis que l'YouTube Content ID API permet d'interagir avec le système de gestion des droits de YouTube. Cependant, toutes les ressources qui composent l'API de diffusion en direct ne sont utilisées que pour créer et gérer des événements en direct.

Ce document est destiné aux développeurs qui souhaitent créer des applications facilitant la diffusion en direct sur YouTube. Il explique les concepts de base de YouTube et de l'API elle-même. Il fournit également un aperçu des différentes fonctions compatibles avec l'API.

Concepts fondamentaux

annonces: Une diffusion représente un événement pouvant être visionné en direct sur YouTube. Les diffusions peuvent également être enregistrées et enregistrées en tant que vidéos YouTube afin que les utilisateurs puissent les regarder après leur diffusion.
ruisseau: Un flux identifie le contenu audio et vidéo transmis à YouTube. Chaque diffusion est associée à un flux vidéo.
points de repère: Un point de repère représente une coupure publicitaire pouvant être insérée dans une diffusion en direct.

Cas d'utilisation de l'API

La liste ci-dessous suggère plusieurs façons d'utiliser l'API dans votre application:

Programmer des diffusions et définir les paramètres de diffusion Votre application peut permettre aux utilisateurs de prédéfinir des paramètres de diffusion, puis de sélectionner les paramètres à appliquer à une diffusion donnée.
Associez des flux vidéo et des diffusions.
Permettre aux diffuseurs de définir simultanément des informations sur une diffusion et sa vidéo (à l'aide de l'API YouTube Data)
Simplifiez les transitions entre les états de diffusion (testing, live, etc.) et permettez aux utilisateurs d'insérer des points de repère.

Avant de commencer

Vous devez disposer d'un compte Google pour accéder à Google API Console, demander une clé API et enregistrer votre application.
Enregistrez votre application auprès de Google afin qu'il puisse envoyer des demandes d'API.
Après avoir enregistré votre application, sélectionnez YouTube Data API parmi les services qu'elle utilise:
1. Accédez à API Console et sélectionnez le projet que vous venez d'enregistrer.
2. Accédez à la page API activées. Dans la liste des API, vérifiez que l'état est activé pour l'API YouTube Data version 3 et, si vous êtes un partenaire du réseau de contenu YouTube, l'API YouTube Content ID.
Familiarisez-vous avec les concepts de base du format de données JSON (JavaScript Object Notation). JSON est un format de données courant, indépendant du langage, qui fournit une représentation textuelle simple de structures de données arbitraires. Pour en savoir plus, accédez à json.org.

Autoriser les requêtes API

Comme indiqué ci-dessus, l'API de diffusion en direct utilise une fonctionnalité techniquement intégrée dans l'API YouTube Data ou l'API YouTube Content ID. L'API Content ID vous permet de fournir à YouTube des métadonnées, des informations sur la propriété et des règles pour vos éléments. (une diffusion vidéo en direct est un exemple d'asset). L'API vous permet également de revendiquer des vidéos et de définir des règles relatives aux annonces pour vos vidéos.

Cette section explique les exigences d'autorisation pour les requêtes envoyées à Content ID API, qui sont différentes de celles requises pour autoriser d'autres requêtes Live Streaming API.

Appel du Data API: La demande d'API doit être autorisée par le compte Google propriétaire de la chaîne YouTube à l'origine de la diffusion.
Appel du Content ID API: La demande d'API doit être autorisée par un compte Google associé au propriétaire du contenu qui détient la chaîne YouTube de la diffusion.

Ressources et types de ressources

Une ressource est une entité de données individuelle dotée d'un identifiant unique. Le tableau ci-dessous décrit les différents types de ressources avec lesquels vous allez interagir à l'aide de Live Streaming API. Techniquement, toutes ces ressources sont en fait définies dans YouTube Data API ou YouTube Content ID API. Toutefois, les ressources liveBroadcast, liveStream et cuepoint ne sont utilisées que pour créer et gérer des événements en direct.

Ressources
`liveBroadcast`	Contient des informations sur un événement que vous diffusez sur YouTube. Une ressource `liveBroadcast` est une extension d'une ressource vidéo YouTube et définit les métadonnées qui seraient pertinentes pour une diffusion en direct, mais pas pour d'autres vidéos YouTube. Par conséquent, une ressource `liveBroadcast` correspond exactement à une ressource vidéo YouTube. En fait, les ressources `liveBroadcast` et `video` partagent le même ID. Après avoir créé la diffusion à l'aide de l'API Live Streaming, vous pouvez utiliser l'API YouTube Data pour fournir des métadonnées supplémentaires sur la vidéo.
`liveStream`	Contient des informations sur le flux vidéo que vous transmettez à YouTube. Le flux fournit le contenu qui sera diffusé auprès des utilisateurs YouTube. Une fois créée, une ressource `liveStream` ne peut être associée qu'à une seule ressource `liveBroadcast`. De même, la ressource `liveBroadcast` ne peut être associée qu'à une seule ressource `liveStream`.
`cuepoint`	Insère un point de repère dans le flux vidéo de diffusion, ce qui peut déclencher une coupure publicitaire. Utilisez la méthode `liveBroadcasts.cuepoint` pour insérer un point de repère lors d'une diffusion.
`video`	Représente une seule vidéo YouTube. Comme indiqué ci-dessus, une ressource `liveBroadcast` est une extension d'une ressource `video`. Vous pouvez utiliser l'API YouTube Data pour modifier les métadonnées de la vidéo, telles que le lieu d'enregistrement ou les régions dans lesquelles la diffusion sera visible.
`videoAdvertisingOptions`	Définit les paramètres publicitaires d'une vidéo (ou diffusion). Utilisez YouTube Content ID API pour définir les options publicitaires.
`asset`	Représente une propriété intellectuelle, telle qu'un film ou un épisode d'une émission. Dans ce cas, la vidéo diffusée est l'élément. Vous utiliserez YouTube Content ID API pour créer et gérer des ressources `asset`.
`claim`	Associer une vidéo à un élément qui lui correspond Créez une revendication à l'aide de YouTube Content ID API pour vous identifier comme le propriétaire de la vidéo diffusée.
`policy`	Définit les règles dans lesquelles vous souhaitez que vos contenus soient visibles ou bloqués sur YouTube. Vous devez appliquer une règle à votre vidéo de diffusion et spécifier une règle que YouTube appliquera aux vidéos mises en ligne par des utilisateurs dont le contenu correspond à votre vidéo.

Opérations compatibles

Le tableau suivant présente les différentes méthodes compatibles avec l'API:

Opérations
`list`	Récupère (`GET`) une liste de zéro ou plusieurs ressources.
`insert`	Crée (`POST`) une ressource.
`update`	Modifie (`PUT`) une ressource existante pour refléter les données de votre requête.
`bind`	Lie une ressource `liveBroadcast` avec une ressource `liveStream` ou supprime une telle association.
`transition`	Modifie l'état d'une ressource `liveBroadcast` et lance tous les processus associés au nouvel état. Par exemple, lorsque vous faites passer l'état d'une diffusion à `testing`, YouTube commence à transmettre son flux vidéo au moniteur.
`delete`	Supprime (`DELETE`) une ressource spécifique.

Le tableau ci-dessous identifie les opérations compatibles avec différents types de ressources. Les opérations d'insertion, de mise à jour ou de suppression de ressources nécessitent toujours une autorisation utilisateur. Dans certains cas, les méthodes list acceptent les requêtes autorisées et non autorisées : les requêtes non autorisées ne récupèrent que les données publiques, tandis que les requêtes autorisées peuvent également récupérer des informations limitées à l'utilisateur actuellement authentifié.

Opérations acceptées
	list	insert	update	bind	transition	cuepoint	delete
livelive
diffusion en direct

Ressources partielles

L'API permet, et même nécessite, la récupération de ressources partielles pour que les applications évitent le transfert, l'analyse et le stockage de données inutiles. Cette approche garantit également que l'API utilise les ressources réseau, de processeur et de mémoire plus efficacement.

Le paramètre part est un paramètre obligatoire pour toute requête API qui récupère ou renvoie une ressource YouTube Data API. Le paramètre identifie une ou plusieurs propriétés de ressources de premier niveau (non imbriquées) à inclure dans une réponse de l'API. Par exemple, une ressource liveStream comprend les éléments suivants:

snippet
cdn
status

Toutes ces parties sont des objets contenant des propriétés imbriquées. Vous pouvez les considérer comme des groupes de champs de métadonnées que le serveur d'API peut (ou ne peut pas) récupérer. Par conséquent, le paramètre part vous demande de sélectionner les composants de ressources que votre application utilise réellement. Cette exigence remplit deux objectifs importants:

Elle réduit la latence en empêchant le serveur d'API de perdre du temps à récupérer les champs de métadonnées que votre application n'utilise pas.
Elle réduit l'utilisation de la bande passante en réduisant (ou en éliminant) la quantité de données inutiles que votre application pourrait récupérer.

Au fil du temps, à mesure que les ressources ajouteront des parties, ces avantages ne feront qu'augmenter, car votre application ne demandera plus de nouvelles propriétés qu'elle ne prend pas en charge.

Conseils et bonnes pratiques

Revendiquer votre contenu

Si vous souhaitez diffuser des annonces pendant votre diffusion, vous devez revendiquer la vidéo en question avant le début de l'événement. Pour revendiquer des contenus, vous devez être un partenaire de contenu YouTube participant au programme Content ID.

La procédure de revendication d'une vidéo diffusée en direct est différente de la procédure habituelle pour revendiquer une vidéo. Lorsque vous revendiquez une vidéo en direct, vous devez la revendiquer avant que la vidéo existe. C'est possible avec l'API, et le cycle de vie d'une diffusion décrit les appels YouTube Content ID API qui vous permettent de créer votre revendication.

Prévisualiser et tester votre contenu

À réception de votre flux vidéo entrant, YouTube peut la diffuser sur deux flux sortants:

Le flux de surveillance vous permet de prévisualiser (et de tester) votre diffusion vidéo. Vous seul y avez accès. Vous ne pouvez faire passer une diffusion à la phase testing que si le flux de surveillance de celle-ci est activé. Le flux de contrôle n'affiche pas de coupures publicitaires.
Le flux de diffusion est visible par votre audience. Vous pouvez définir l'état de confidentialité de la diffusion sur public, private ou unlisted. Une diffusion privée est visible uniquement par les utilisateurs explicitement invités à la regarder, tandis qu'une diffusion non répertoriée est visible par toute personne disposant du lien.

Vous pouvez choisir de retarder le flux de diffusion pour qu'il ne s'exécute pas simultanément avec le flux de contrôle. En retardant le flux de diffusion, vous pouvez contrôler plus précisément la durée d'insertion des points de repère dans la diffusion.

Cependant, si vous retardez la diffusion, vos présentateurs en direct auront du mal à interagir avec votre audience. En outre, si vous retardez la diffusion, vous augmentez la probabilité que les spectateurs découvrent les détails clés de l'événement depuis d'autres sources. Par exemple, si vous diffusez un événement sportif dans un délai de 60 secondes, les spectateurs peuvent découvrir des moments importants de l'événement à partir d'autres sources d'actualités en temps réel avant de les voir.

Nous vous recommandons d'activer le flux de contrôle de votre diffusion afin de pouvoir tester vos contenus. Vous devez également retarder la diffusion de votre événement en fonction de votre objectif de contrôler le moment auquel les points de repère ont lieu, plutôt que d'interagir avec votre audience ou de couvrir un événement en temps réel.

Diffuser des annonces mid-roll pendant une diffusion

Pendant une diffusion, vous pouvez insérer un point de repère pour indiquer qu'une coupure publicitaire doit commencer dans la diffusion dès que possible ou à un moment précis. La coupure publicitaire permet à YouTube de diffuser des annonces mid-roll pendant la diffusion.

Les coupures publicitaires présentent les caractéristiques suivantes:

Il possède une durée prédéfinie, que vous définissez à l'aide de la propriété durationSecs de la ressource cuepoint. Une fois la coupure publicitaire terminée, les spectateurs reviennent à la diffusion en direct.
Lorsqu'une coupure publicitaire se produit, une annonce n'est diffusée dans le lecteur vidéo que pour les spectateurs qui regardent la diffusion lorsque le point de repère est inséré. Une annonce n'est pas diffusée lorsque les internautes actualisent la page sur laquelle la diffusion est lancée, ou lorsque des visiteurs commencent à la regarder après l'insertion du point de repère.

La séquence d'étapes ci-dessous reflète la bonne pratique pour insérer une coupure publicitaire pendant votre diffusion:

Définir des décalages temporels

Lorsque vous insérez un point de repère, vous pouvez le spécifier immédiatement ou à un moment précis de la diffusion. Les options disponibles varient selon que le flux de diffusion de votre vidéo est retardé.

Si votre flux de diffusion n'est pas retardé, vous pouvez insérer le point de repère immédiatement ou utiliser la propriété walltimeMs pour que la coupure publicitaire démarre à un moment donné.
- Pour lancer la coupure publicitaire immédiatement, appelez la méthode liveBroadcasts.cuepoint. Dans le corps de la requête, définissez la valeur de la propriété insertionOffsetTimeMs sur 0 ou ne spécifiez aucune valeur pour cette propriété et ne spécifiez pas de valeur pour la propriété walltimeMs.
  
  Important:Notez que les utilisateurs ne voient pas immédiatement le contenu publicitaire. Un délai d'environ 30 secondes peut être nécessaire avant que le contenu de l'annonce soit visible par les utilisateurs. Pendant ce laps de temps, vos spectateurs pourront toujours voir votre flux, et vous devrez le regarder pour déterminer à quel moment le contenu de l'annonce s'affiche à la place du flux de contrôle.
- Pour démarrer la coupure publicitaire à un moment précis, appelez la méthode liveBroadcasts.cuepoint et utilisez la propriété walltimeMs pour spécifier l'heure souhaitée. La valeur de la propriété est un entier représentant un horodatage d'époque.
Si votre flux de diffusion est retardé, vous pouvez insérer le point de repère immédiatement comme décrit ci-dessus, spécifier une heure comme indiqué ci-dessus ou spécifier un décalage horaire pour déterminer le début de la coupure publicitaire. Le décalage horaire indique à quel moment de la diffusion l'annonce doit être diffusée.

La valeur de décalage est mesurée en millisecondes à partir du début du flux de surveillance pour votre diffusion. Notez que si votre diffusion comporte une phase de test, le flux de surveillance démarre lors du passage à l'état testing. Sinon, le flux de surveillance démarre lorsque votre diffusion passe à l'état live.

Lorsque vous insérez un point de repère, définissez la propriété insertionOffsetTimeMs de la ressource cuepoint sur le décalage souhaité.

Calculer la valeur de décalage temporel

Pour récupérer la valeur de décalage, appelez la fonction getCurrentTime de l'API Player YouTube pour le lecteur qui lit le flux du moniteur. Utilisez la valeur récupérée pour insérer le point de repère dans le flux de diffusion à ce moment-là.

Les valeurs possibles pour le décalage sont les suivantes:

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

La valeur Δ correspond à un tampon de cinq secondes au début et à la fin des décalages temporels possibles lorsque YouTube ne peut pas insérer un point de repère avec précision. Exemple :

Une diffusion comprend une phase de test de cinq minutes.
Le flux de diffusion est retardé de 60 secondes après le flux du moniteur.
Le diffuseur insère le point de repère quatre minutes après la transition à l'état live. (Trois minutes après que le flux de diffusion est visible)

Dans ce cas, la plage de décalages possible est de [(485,000), (535,000)].

Ces durées sont indiquées en millisecondes et calculées à l'aide des valeurs suivantes:

elapsed_time=540000 : le flux de surveillance a été exécuté pendant neuf minutes (540 secondes, 540 000 millisecondes) lorsque la méthode liveBroadcasts.cuepoint est appelée.
broadcast_delay=60000 : le flux de diffusion est retardé de 60 secondes, soit 60 000 millisecondes.
Δ=5000 : tampon de cinq secondes lorsque le point de repère ne peut pas être inséré de manière fiable.

Dépannage et traitement des erreurs

Les consignes suivantes expliquent comment résoudre des problèmes spécifiques. Reportez-vous également à la documentation sur les erreurs pour obtenir la liste des erreurs que chaque méthode d'API peut renvoyer.

Lorsqu'une diffusion passe d'un état à un autre, elle peut être temporairement associée à un autre état pendant que YouTube effectue les actions associées à la transition. Par exemple, si vous envoyez une demande liveBroadcasts.transition pour modifier l'état d'une diffusion de ready à testing, YouTube définira l'état de la diffusion sur testStarting, puis effectuera les actions associées à la modification de l'état. Une fois toutes ces opérations effectuées, YouTube fait passer l'état de la diffusion à testing, ce qui indique que la transition est terminée.

Si une diffusion se bloque avec l'état testStarting ou liveStarting, vous devez appeler la méthode liveBroadcasts.delete et supprimer la diffusion. Créez ensuite une nouvelle diffusion, associez-la à votre diffusion en direct et poursuivez le processus de test.

Comme indiqué dans la documentation de la méthode liveBroadcasts.transition, vous devez confirmer que la valeur de la propriété status.streamStatus pour le flux lié à votre diffusion est active avant d'appeler cette méthode.