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, mettre à jour 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 se compose de composants des API YouTube Data et Content ID. L'API Data permet aux utilisateurs de 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 de l'API Live Streaming sont utilisées uniquement 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 fondamentaux de YouTube et de l'API elle-même. Il présente également les différentes fonctions compatibles avec l'API.

Concepts fondamentaux

diffusions: Une diffusion désigne un événement qui peut être regardé sur YouTube en temps réel. Les annonces peuvent également être enregistrées en tant que vidéos YouTube afin que les utilisateurs puissent les regarder une fois qu'elles ont eu lieu.
ruisseau: Un flux identifie le contenu audio 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 qui peut être insérée dans une diffusion en direct.

Cas d'utilisation des 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 des paramètres de diffusion, puis de sélectionner ceux à appliquer à une diffusion en particulier.
Associez des flux vidéo et des diffusions.
Autorisez les diffuseurs à définir des informations sur une diffusion et sa vidéo (à l'aide de l'API YouTube Data) en même temps.
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 au 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 comme l'un des services qu'elle utilise:
1. Accédez à API Console, puis 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 la version 3 de l'API YouTube Data et, si vous êtes un partenaire de contenu YouTube, pour l'API YouTube Content ID.
Familiarisez-vous avec les concepts fondamentaux du format de données JSON (JavaScript Object Notation). JSON est un format de données commun et 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é qui fait techniquement partie de l'API YouTube Data ou de l'API YouTube Content ID. L'API Content ID vous permet de fournir à YouTube des métadonnées, ainsi que des informations sur la propriété et les règles de vos éléments. (Une diffusion vidéo en direct est un exemple d'élément.) L'API vous permet également de revendiquer des vidéos et de définir des règles relatives aux annonces pour celles-ci.

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

J'appelle Data API: La demande API doit être autorisée par le compte Google propriétaire de la chaîne YouTube de diffusion.
J'appelle Content ID API: La demande API doit être autorisée par un compte Google associé au propriétaire de contenu propriétaire de la chaîne YouTube de 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 interagirez à l'aide de Live Streaming API. Techniquement, toutes ces ressources sont en fait définies comme faisant partie de YouTube Data API ou de 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. Elle définit des métadonnées vidéo pertinentes pour une diffusion en direct, mais pas pour d'autres vidéos YouTube. Par conséquent, une ressource `liveBroadcast` correspond à une seule 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 de diffusion en direct, 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 de YouTube. Une fois créée, une ressource `liveStream` peut être liée à une seule ressource `liveBroadcast`. De même, la ressource `liveBroadcast` ne peut être lié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 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 modifier 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 la YouTube Content ID API pour définir les options publicitaires.
`asset`	Représente du contenu protégé par des droits de propriété intellectuelle, comme un film ou un épisode d'une série. 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`	associe une vidéo à un élément auquel elle correspond. Vous créez une revendication à l'aide des YouTube Content ID API pour vous identifier comme le propriétaire de la vidéo diffusée.
`policy`	Définit des règles qui spécifient les circonstances dans lesquelles vous souhaitez que votre contenu soit visible sur YouTube ou bloqué. Vous devez appliquer une règle à votre vidéo diffusée en direct. Vous pouvez également spécifier une règle que YouTube appliquera aux vidéos mises en ligne par des utilisateurs qui correspondent à la vôtre.

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 comportant 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`	Associe une ressource `liveBroadcast` à une ressource `liveStream`, ou supprime ce type de lien.
`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 la vidéo au flux de surveillance de cette diffusion.
`delete`	Supprime (`DELETE`) une ressource spécifique.

Le tableau ci-dessous identifie les opérations acceptées pour différents types de ressources. Les opérations d'insertion, de mise à jour ou de suppression de ressources nécessitent toujours une autorisation de l'utilisateur. Dans certains cas, les méthodes list sont compatibles avec les requêtes autorisées et non autorisées. Celles-ci 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 compatibles
	list	insert	update	bind	transition	cuepoint	delete
liveBroadcast
liveStream

Ressources partielles

L'API autorise et nécessite réellement la récupération d'une partie des ressources afin que les applications évitent le transfert, l'analyse et le stockage de données inutiles. Cette approche garantit également que l'API utilise plus efficacement les ressources réseau, mémoire et processeur.

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 niveau supérieur (non imbriquées) à inclure dans la réponse de l'API. Par exemple, une ressource liveStream se compose des parties suivantes:

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 non) récupérer. Par conséquent, le paramètre part nécessite que vous sélectionniez 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 passer du temps à récupérer les champs de métadonnées que votre application n'utilise pas.
Il 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 éléments, ces avantages ne font 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 diffusée avant le début de l'événement. Pour revendiquer des contenus, vous devez être un partenaire de contenus 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. Lorsque vous revendiquez une vidéo en direct, vous devez la faire avant qu'elle n'existe réellement. L'API permet cela, et le document 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

Dès réception de votre flux vidéo entrant, YouTube peut la diffuser sur deux flux sortants différents:

Le flux de contrôle 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 faire passer une diffusion à la phase testing que si le flux de surveillance de la diffusion est activé. Le flux de surveillance n'affiche aucune coupure publicitaire.
Le flux de diffusion est celui que votre audience peut voir. Vous pouvez définir l'état de confidentialité de la diffusion sur public, private ou unlisted. (Une diffusion privée est uniquement visible par les utilisateurs qui ont été explicitement invités à la regarder, alors qu'une diffusion non répertoriée est visible par toute personne disposant du lien permettant de la regarder.)

Vous pouvez choisir de retarder le flux de diffusion afin qu'il ne s'exécute pas simultanément avec le flux de surveillance. 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, retarder la diffusion ne permet pas aux présentateurs d'interagir avec votre audience. De plus, retarder la diffusion augmente la probabilité que les spectateurs découvrent des informations clés sur l'événement depuis d'autres sources que la vôtre. Par exemple, si vous diffusez un événement sportif avec un retard de 60 secondes, les spectateurs peuvent se renseigner sur les moments clés de l'événement grâce à d'autres sources d'actualités en temps réel avant de les voir.

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 la diffusion si vous souhaitez contrôler la chronologie des points de repère, et non interagir avec votre audience ou fournir une couverture en temps réel d'un événement.

Diffuser des annonces mid-roll pendant une diffusion

Lors d'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:

Sa durée est 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.
En cas de coupure publicitaire, l'annonce n'est diffusée dans le lecteur vidéo que pour les internautes 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 en cours de lecture ou lorsqu'ils commencent à la regarder après l'insertion du point de repère.

La séquence d'étapes ci-dessous reflète les bonnes pratiques à suivre pour insérer une coupure publicitaire pendant la 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 à un point spécifique de la diffusion. Les options disponibles varient selon que le flux de diffusion de votre vidéo est décalé ou non.

Si le 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 commence à un moment précis.
- Pour lancer la coupure publicitaire immédiatement, appelez la méthode liveBroadcasts.cuepoint. Dans la ressource dans le corps de la requête, définissez la valeur de la propriété insertionOffsetTimeMs sur 0 ou n'indiquez pas de valeur pour cette propriété et n'en spécifiez aucune pour la propriété walltimeMs.
  
  Important:Sachez que les spectateurs ne voient pas immédiatement le contenu publicitaire obtenu. Un délai d'environ 30 secondes peut être nécessaire avant que le contenu de l'annonce ne soit visible par les utilisateurs. Pendant ce laps de temps, les spectateurs peuvent toujours voir le flux de diffusion, et vous devez le regarder pour déterminer à quel moment le contenu publicitaire doit s'afficher à la place de votre flux d'écran.
- Pour lancer 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 code temporel d'epoch.
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 le début de la coupure publicitaire. Le décalage horaire spécifie le moment de la diffusion où les spectateurs doivent voir l'annonce.

La valeur de décalage est mesurée en millisecondes à partir du début du flux de surveillance de votre diffusion. Notez que si votre diffusion comporte une phase de test, le flux de surveillance démarre lorsqu'elle passe à l'état testing. Sinon, le flux de surveillance démarre lorsqu'il 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 du 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 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 du temps de décalage peuvent être calculées comme suit:

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

Le Δ est une mémoire tampon de cinq secondes située au début et à la fin des décalages temporels possibles lorsque YouTube ne peut pas insérer de point de repère avec précision. Exemple :

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

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

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

elapsed_time=540000 : le flux de surveillance s'exécute 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 dans lequel le point de repère ne peut pas être inséré de manière fiable.

Dépannage et gestion des erreurs

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

Lorsqu'une diffusion passe d'un état à un autre, il est possible qu'elle soit temporairement attribué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 faire passer 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 définit l'état de la diffusion sur testing, indiquant ainsi 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 la supprimer. Créez ensuite une diffusion, associez-la à votre diffusion en direct et poursuivez la procédure 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 du flux associé à votre diffusion est active avant d'appeler cette méthode.