Présentation de l'API YouTube Live Streaming

L'API YouTube Live Streaming vous permet de créer, modifier et 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 est en fait composée de 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 YouTube Content ID API permet d'interagir avec le système de gestion des droits de YouTube. Toutefois, toutes les ressources qui composent l'API Live Streaming 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 écrire des applications pour faciliter la diffusion en direct sur YouTube. Il explique les concepts de base de YouTube et de l'API elle-même. Il fournit également une présentation des différentes fonctions compatibles avec l'API.

Concepts fondamentaux

Diffusions

Une diffusion représente un événement qui peut être regardé sur YouTube en direct. 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.

Flux

Un flux identifie le contenu audio-vidéo qui est communiqué à YouTube. Chaque diffusion est associée à un flux vidéo.

Points de repère

Un cuepoint représente une coupure publicitaire qui peut être insérée dans une diffusion en direct.

Cas d'utilisation d'API

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

• Planifiez des diffusions et définissez les paramètres de diffusion. Votre application peut permettre aux utilisateurs de prédéfinir les paramètres de diffusion, puis de sélectionner ceux à appliquer à une diffusion spécifique.

• Associez des flux vidéo et des diffusions.

• Permettez 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 (par exemple, testing ou live) et permettez aux utilisateurs d'insérer des points de repère.

Avant de commencer

1. Vous avez besoin d'un compte Google pour accéder à la Google Cloud console, demander une clé API et enregistrer votre application.

2. Enregistrez votre application auprès de Google afin qu'il puisse envoyer des requêtes API.

3. Après avoir enregistré votre application, sélectionnez le YouTube Data API comme l'un des services utilisés par votre application :

   1. Accédez à la Cloud console et sélectionnez le projet que vous venez d'enregistrer.
   2. Accédez à la page API activées. Dans la liste des API, assurez-vous que l'état est ACTIVÉ pour l'API YouTube Data v3 et, si vous êtes un partenaire de contenu YouTube, pour l'API YouTube Content ID.

4. Familiarisez-vous avec les concepts de base du format de données JavaScript Object Notation (JSON). JSON est un format de données courant qui ne dépend pas d'un langage et qui fournit une représentation textuelle simple de structures de données arbitraires. Pour en savoir plus, consultez json.org.

Autoriser les requêtes API

Comme indiqué ci-dessus, l'API Live Streaming utilise des fonctionnalités qui font techniquement partie de l'API YouTube Data ou de l'API YouTube Content ID. Vous pouvez utiliser l'API Content ID pour fournir à YouTube des métadonnées, des informations sur la propriété et des informations sur les règles pour vos assets. (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 adressées à l'API Content IDContent ID API, qui sont différentes de celles requises pour autoriser d'autresLive Streaming API requêtes de l'API Live Streaming.

Appeler le Data API

La requête API doit être autorisée par le compte Google propriétaire de la chaîne YouTube de diffusion.

Appeler le Content ID API

La requête API doit être autorisée par un compte Google associé au propriétaire du contenu qui possède la chaîne YouTube de diffusion.

Ressources et types de ressources

Une ressource est une entité de données individuelle disposant d'un identifiant unique. Le tableau ci-dessous décrit les différents types de ressources avec lesquels vous interagirez à l'aide de l' Live Streaming API. Techniquement, toutes ces ressources sont en fait définies dans l'API YouTube DataYouTube Data API ou dans l'API YouTube Content IDYouTube Content ID API. Toutefois, les liveBroadcast, liveStream, et cuepoint ressources 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 liveBroadcast ressource est une extension d'une ressource vidéo YouTube et définit les métadonnées vidéo 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, la liveBroadcast ressource et la video ressource 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 peut être liée à une seule ressource liveBroadcast. De même, la liveBroadcast ressource ne peut être liée qu'à une seule liveStream ressource.
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 liveBroadcasts.cuepoint méthode pour insérer un point de repère pendant 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 mettre à jour les métadonnées de la vidéo, telles que le lieu d'enregistrement ou les régions où la diffusion sera visible.
videoAdvertisingOptions	Définit les paramètres publicitaires d'une vidéo (ou d'une diffusion). Vous utilisez le YouTube Content ID API pour définir les options publicitaires.
asset	Représente une œuvre de propriété intellectuelle, comme un film ou un épisode d'une série. Dans ce cas, la vidéo de diffusion est l'asset. Vous utiliserez le YouTube Content ID API pour créer et gérer des ressources asset.
claim	Associe une vidéo à un asset auquel elle correspond. Vous créez une revendication à l'aide de l' YouTube Content ID API pour vous identifier comme le propriétaire de la vidéo de diffusion.
policy	Définit des règles qui spécifient les circonstances dans lesquelles vous souhaitez que votre contenu soit visible sur YouTube ou bloqué sur YouTube. Vous devez appliquer une règle à votre vidéo de diffusion. Vous pouvez également spécifier une règle que YouTube appliquera aux vidéos mises en ligne par les utilisateurs et qui correspondent à votre vidéo de diffusion.

Opérations prises en charge

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 ressource ou plus.
insert	Crée (POST) une ressource.
update	Modifie (PUT) une ressource existante pour refléter les données de votre requête.
bind	Associe une ressource liveBroadcast à une ressource liveStream ou supprime un tel lien.
transition	Modifie l'état d'une ressource liveBroadcast et lance tous les processus associés au nouvel état. Par exemple, lorsque vous passez l'état d'une diffusion à testing, YouTube commence à transmettre la vidéo au flux de surveillance de cette diffusion.
delete	Supprime (DELETE) une ressource spécifique.

Le tableau suivant identifie les opérations compatibles avec différents types de ressources. Les opérations qui insèrent, mettent à jour ou suppriment des ressources nécessitent toujours l'autorisation de l'utilisateur. Dans certains cas, les méthodes list sont compatibles avec 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 réservées à l'utilisateur authentifié.

Opérations compatibles
	list	insert	update	bind	transition	cuepoint	delete
liveBroadcast
liveStream

Ressources partielles

L'API autorise, voire exige, la récupération de ressources partielles afin que les applications évitent de transférer, d'analyser et de stocker des données inutiles. Cette approche garantit également que l'API utilise plus efficacement les ressources réseau, CPU et mémoire.

Le paramètre part est 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 ressource de premier niveau (non imbriquées) qui doivent être incluses dans une réponse de l'API. Par exemple, une ressource liveStream comporte les parties suivantes :

• snippet
• cdn
• status

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

• Elle réduit la latence en empêchant le serveur API de perdre du temps à récupérer des 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 peut récupérer.

Au fil du temps, à mesure que les ressources ajoutent des parties, ces avantages ne feront qu'augmenter, car votre application ne demandera pas les 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 de diffusion avant le début de l'événement. Pour revendiquer du contenu, vous devez être un partenaire de contenu YouTube participant au programme Content ID.

La procédure de revendication de votre vidéo de diffusion en direct est différente de la procédure normale de revendication d'une vidéo. Lorsque vous revendiquez une vidéo en direct, vous devez créer votre revendication avant que la vidéo n'existe réellement. L'API est compatible avec cette fonctionnalité, et le document de diffusion explique les YouTube Content ID API appels qui vous permettent de créer votre revendication.

Prévisualiser et tester votre contenu

Une fois que YouTube a reçu votre flux vidéo entrant, il peut diffuser cette vidéo sur deux flux sortants différents :

• Le flux de surveillance vous permet de prévisualiser (et de tester) votre diffusion vidéo. Il s'agit d'un flux privé auquel vous seul avez accès. Vous ne pouvez passer une diffusion à la phase testing que si le flux de surveillance de la diffusion est activé. Le flux de surveillance n'affiche pas de coupures publicitaires.

• Le flux de diffusion est le flux visible par votre audience. Vous pouvez définir l'état de confidentialité de la diffusion sur public, private ou unlisted. (Une diffusion privée n'est visible que par les utilisateurs qui ont été explicitement invités à la regarder, tandis qu'une diffusion non répertoriée est visible par toute personne disposant d'un lien pour la visionner.)

  Vous pouvez choisir de retarder le flux de diffusion afin qu'il ne s'exécute pas en même temps que le flux de surveillance. En retardant le flux de diffusion, vous pouvez contrôler plus précisément le moment où vous insérez des points de repère dans la diffusion.

  Toutefois, le fait de retarder le flux de diffusion rend difficile l'interaction de vos présentateurs en direct avec votre audience. De plus, le fait de retarder la diffusion augmente la probabilité que les spectateurs découvrent des informations clés sur l'événement à partir de sources autres que votre diffusion. Par exemple, si vous diffusez un événement sportif avec un délai de 60 secondes, les spectateurs peuvent découvrir des moments critiques de l'événement à partir d'autres sources d'actualités en temps réel avant de les voir dans la diffusion.

YouTube vous recommande d'activer le flux de surveillance pour votre diffusion afin de pouvoir tester votre contenu. Vous devez choisir de retarder ou non votre diffusion en fonction de votre souhait de contrôler le timing des points de repère plutôt que de votre souhait d'interagir avec votre audience ou de fournir une couverture en temps réel d'un événement.

Diffuser des annonces mid-roll pendant un flux de diffusion

Pendant une diffusion, vous pouvez insérer un cuepoint pour indiquer qu’une coupure publicitaire doit commencer dans la diffusion dès que possible ou à une heure spécifiée. La coupure publicitaire permet à YouTube de diffuser des annonces mid-roll pendant la diffusion.

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

1. Elle a une durée prédéfinie, que vous définissez à l'aide de la propriété cuepoint de la ressource durationSecs. Une fois la coupure publicitaire terminée, les spectateurs reviennent à la diffusion en direct.

2. 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 au moment où le point de repère est inséré. Une annonce n'est pas diffusée lorsque les spectateurs actualisent la page où la diffusion est en cours de lecture ou lorsque les visiteurs commencent à regarder la diffusion 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 spécifier qu'il doit être inséré immédiatement ou qu'il doit être inséré à un moment précis de la diffusion. Vos options dépendent du fait que le flux de diffusion de votre vidéo soit retardé ou non.

• Si votre flux de diffusion n'est pas retardé, vous pouvez insérer le point de repère immédiatement ou utiliser la walltimeMs propriété pour que la coupure publicitaire commence à une heure précise.

  • Pour démarrer immédiatement la coupure publicitaire, appelez la méthode liveBroadcasts.cuepoint. Dans la ressource du corps de la requête, définissez la valeur de la propriété insertionOffsetTimeMs sur 0 ou ne spécifiez pas de valeur pour cette propriété et ne spécifiez pas de valeur pour la propriété walltimeMs.

    Important : Notez que les spectateurs ne voient pas immédiatement le contenu publicitaire résultant. Il peut y avoir un délai d'environ 30 secondes avant que le contenu de l'annonce ne soit visible par les utilisateurs. Pendant ce délai, votre flux de diffusion reste visible par vos spectateurs, et vous devez regarder le flux de diffusion pour déterminer quand le contenu de l'annonce s'affiche réellement au lieu de votre flux de surveillance.

  • Pour démarrer la coupure publicitaire à une heure précise, appelez la liveBroadcasts.cuepoint méthode et utilisez la walltimeMs propriété pour spécifier l'heure souhaitée. La valeur de la propriété est un entier qui représente un code temporel 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 décrit ci-dessus ou spécifier un décalage temporel pour déterminer quand la coupure publicitaire commencera. Le décalage temporel spécifie un moment de votre diffusion où les spectateurs doivent voir une annonce.

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

  Lorsque vous insérez un point de repère, définissez la propriété cuepoint de la ressource insertionOffsetTimeMs 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 YouTube Player pour le lecteur qui lit le flux de surveillance. 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 temporel peuvent être calculées comme suit :

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

Le Δ est une mémoire tampon de cinq secondes au début et à la fin des horodatages possibles lorsque YouTube ne peut pas insérer précisément un point de repère. Exemple :

• Une diffusion comporte une phase de test de cinq minutes.
• Le flux de diffusion est retardé de 60 secondes après le flux de surveillance.
• Le diffuseur insère le point de repère quatre minutes après que la diffusion passe à l'état live (Soit trois minutes après que le flux de diffusion devient visible.)

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

Ces heures sont spécifiées en millisecondes et sont calculées à l'aide des valeurs suivantes :

• elapsed_time=540000 : le flux de surveillance s'est 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 : mémoire 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 qui peuvent survenir. Pour obtenir la liste des erreurs que chaque méthode d'API peut renvoyer, consultez API YouTube Live Streaming – Erreurs.

• Lorsqu'une diffusion passe d'un état à un autre, elle peut temporairement être associée à un autre état pendant que YouTube effectue les actions associées à la transition. Par exemple, si vous envoyez une requête liveBroadcasts.transition pour modifier l'état d'une diffusion de ready à testing, YouTube définit l'état de la diffusion sur testStarting, puis effectue les actions associées au changement d'état. Une fois toutes ces actions effectuées, YouTube met à jour l'état de la diffusion sur testing, indiquant ainsi que la transition est terminée.

  Si une diffusion est bloquée avec l'état testStarting ou liveStarting, vous devez appeler la méthode liveBroadcasts.delete et supprimer la diffusion. Créez ensuite une 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 vérifier que la valeur de la propriété status.streamStatus pour le flux lié à votre diffusion est active avant d'appeler cette méthode.