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 se compose des composants des API YouTube Data et YouTube Content ID. L'API Data permet aux utilisateurs YouTube de gérer leur compte YouTube, tandis que l'YouTube Content ID API leur permet d'interagir avec le système de gestion des droits de YouTube. Cependant, toutes les ressources de l'API Live Streaming ne servent qu'à créer et à gérer des événements en direct.

Ce document s'adresse 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 présente également les différentes fonctions prises en charge par l'API.

Concepts fondamentaux

diffusions
Une diffusion correspond à un événement pouvant être regardé sur YouTube en temps réel. Les diffusions peuvent également être enregistrées et sauvegardées sous forme de vidéos YouTube afin que les utilisateurs puissent les regarder après leur diffusion.
appareils IoT et flux d'application.
Un flux identifie le contenu audio/vidéo diffusé sur 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 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 les paramètres à appliquer à une diffusion spécifique.

  • Associer 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 devez disposer d'un compte Google pour accéder à Google API Console, demander une clé API et enregistrer votre application.

  2. Enregistrez votre application auprès de Google afin qu'il puisse envoyer des demandes d'API.

  3. 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, assurez-vous que l'état est ACTIVÉ pour l'API YouTube Data version 3 et, si vous êtes un partenaire de contenu YouTube, l'API Content ID.

  4. Familiarisez-vous avec les concepts fondamentaux du format de données JSON (JavaScript Object Notation). JSON est un format de données commun, 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 Live Streaming utilise une fonctionnalité qui fait partie techniquement 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 règles concernant 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 vos vidéos.

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

Appeler le Data API
La requête API doit être autorisée par le compte Google auquel appartient 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 de contenu auquel appartient 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 lesquelles vous interagirez à l'aide de la Live Streaming API Techniquement, toutes ces ressources réellement défini dans le YouTube Data API ou YouTube Content ID API. Toutefois, liveBroadcast, liveStream cuepoint ressources sont utilisées uniquement 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. A La ressource liveBroadcast est une extension d'une ressource vidéo YouTube et définit le Des métadonnées de vidéo qui seraient pertinentes pour une diffusion en direct, mais pas pour d'autres vidéos YouTube.

Ainsi, une ressource liveBroadcast correspond à exactement une ressource vidéo YouTube. En fait, le liveBroadcast et la ressource video partagent le avec le même identifiant. Après avoir créé la diffusion à l'aide de l'API Live Streaming, vous pouvez utiliser la L'API YouTube Data permet de fournir des métadonnées supplémentaires sur la vidéo.
liveStream Contient des informations relatives au flux vidéo que vous transmettez à YouTube. Le flux fournit le contenu qui sera diffusé auprès des utilisateurs de YouTube. Une fois créé, un liveStream ressource ne peut être liée qu'à une seule ressource liveBroadcast. De même, le 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 la diffusion, ce qui peut déclencher une coupure publicitaire. Utilisez le liveBroadcasts.cuepoint pour insérer un point de repère pendant une diffusion.
video Représente une vidéo YouTube unique. 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 concernant 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 d'une diffusion). Vous utilisez le YouTube Content ID API pour définir les options publicitaires.
asset Représente un contenu protégé par des droits de propriété intellectuelle, tel qu'un film ou un épisode d'une série. Dans ce cas, il s'agit de la diffusion vidéo. 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 de l'YouTube Content ID API pour vous identifier comme le propriétaire de la vidéo diffusée.
policy Ces règles définissent les circonstances dans lesquelles vous souhaitez que votre contenu soit visible sur YouTube ou qu'il n'apparaisse pas sur YouTube. Vous devez appliquer une règle à votre vidéo diffusée, mais également définir une règle que YouTube appliquera aux vidéos mises en ligne par des utilisateurs dont le contenu correspond à la vidéo diffusée.

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 des données dans votre requête.
bind Associe une ressource liveBroadcast à une ressource liveStream ou supprime ce type d'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 la vidéo au flux de contrôle de cette diffusion.
delete Supprime (DELETE) une ressource spécifique.

Le tableau ci-dessous présente 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 une autorisation de l'utilisateur. Dans certains cas, les méthodes list prennent en charge les requêtes autorisées et non autorisées. Les requêtes non autorisées ne récupèrent que des 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 permet, et exige de récupérer 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 de réseau, de processeur et de 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 ressources de niveau supérieur (non imbriquées) à inclure dans une réponse de l'API. Par exemple, une ressource liveStream se compose des é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 non) récupérer. Par conséquent, avec le paramètre part, vous devez sélectionner les composants de ressources que votre application utilise réellement. Cette exigence remplit deux fonctions importantes:

  • Il 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.
  • Il réduit l'utilisation de la bande passante en réduisant (ou en éliminant) la quantité de données inutiles que votre application est susceptible de récupérer.

Au fil du temps, à mesure que les ressources ajouteront des éléments, ces avantages ne feront qu'augmenter, car votre application ne demandera plus de nouvelles propriétés non compatibles.

Conseils et bonnes pratiques

Revendiquer votre contenu

Si vous souhaitez diffuser des annonces pendant une diffusion, vous devez revendiquer la vidéo 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 pour que la vidéo existe réellement. L'API est compatible avec cette fonctionnalité, 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 diffuser cette vidéo 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'une diffusion privée qui n'est accessible qu'à vous. Vous ne pouvez faire passer une diffusion à la phase testing que si le flux de contrôle de la diffusion est activé. Le flux de contrôle n'affiche aucune coupure publicitaire.

  • Le flux de diffusion est le flux 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 n'est visible que par les utilisateurs qui y ont été explicitement invités, tandis qu'une diffusion non répertoriée est visible par toute personne disposant du lien permettant de la visionner.

    Vous pouvez choisir de différer 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 temps pendant lequel vous insérez des points de repère dans la diffusion.

    Cependant, si vous retardez la diffusion, il sera plus difficile pour les présentateurs de s'adresser à 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 en provenance d'autres sources. Par exemple, si vous diffusez un événement sportif avec un retard de 60 secondes, les spectateurs peuvent se renseigner sur les moments importants de l'événement grâce à d'autres sources d'actualités en temps réel avant de les voir réellement dans la diffusion.

Nous vous recommandons d'activer le flux de contrôle pour votre diffusion afin de pouvoir tester votre contenu. Vous devez choisir de retarder également votre diffusion en fonction de votre désir de contrôler l'heure des points de repère, 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

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

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

  1. Il a une durée prédéfinie, que vous définissez à l'aide de l'attribut cuepoint de la ressource durationSecs . À la fin de la coupure publicitaire, les spectateurs reviennent à la diffusion en direct.

  2. Lors d'une coupure publicitaire, l'annonce n'est diffusée dans le lecteur vidéo que pour les spectateurs la diffusion lorsque le point de repère est inséré. Une annonce n'est pas diffusée lorsque les internautes actualisent la page. où la diffusion est en cours ou lorsque les visiteurs commencent à la regarder après la point de repère inséré.

La séquence d'étapes ci-dessous reflète les bonnes pratiques 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 doit être inséré à un moment précis de la diffusion. Les options disponibles varient selon que le flux diffusé pour votre vidéo est décalé.

  • Si le flux de diffusion n'est pas retardé, vous pouvez insérer le point de repère immédiatement ou utiliser l'/le/la walltimeMs pour que la coupure publicitaire démarre à un moment précis.

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

      Important:Notez que les utilisateurs ne voient pas l'annonce générée. le contenu immédiatement. Un délai d'environ 30 secondes peut s'écouler avant que le contenu de l'annonce ne soit visibles par les utilisateurs. Pendant ce délai, votre flux vidéo reste visible par votre les spectateurs. Vous devez regarder le flux de la diffusion pour déterminer quand le contenu de l'annonce s'affiche réellement à la place de votre flux de surveillance.

    • Pour lancer la coupure publicitaire à un moment précis, appelez la méthode liveBroadcasts.cuepoint et d'utiliser la méthode 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 diffusion est retardée, vous pouvez insérer le point de repère immédiatement décrites ci-dessus, spécifiez une heure comme indiqué ci-dessus, ou vous pouvez spécifier un décalage temporel pour déterminer quand la coupure publicitaire commencera. Le décalage temporel indique un moment précis de votre diffusion quand 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 contrôle démarre lorsque votre diffusion passe à l'état testing. Sinon, votre Le flux de surveillance commence lorsque votre diffusion passe à l'état live.

    Lorsque vous insérez un point de repère, définissez la valeur de la ressource cuepoint 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 contrôle. 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élai de décalage peuvent être calculées comme suit:

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

Le Δ est un tampon de cinq secondes 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 retardé de 60 secondes après le flux de surveillance.
  • Le diffuseur insère le point de repère quatre minutes après la transition de la diffusion vers État de live. (trois minutes après que le flux de diffusion est visible).

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

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

  • elapsed_time=540000 : le flux de surveillance est exécuté depuis 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 gestion des erreurs

Les consignes suivantes expliquent comment résoudre des problèmes spécifiques pouvant survenir. Pour les listes que chaque méthode d'API peut renvoyer, consultez la section API YouTube Live Streaming – Erreurs.

  • Lorsqu'une diffusion passe d'un état à un autre, elle peut se voir temporairement attribuer un autre état pendant que YouTube effectue les actions associées à cette 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 annonce se bloque 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, vérifiez que la valeur de la propriété status.streamStatus du flux lié à votre diffusion est active avant d'appeler cette méthode.