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:
- Accédez à API Console et sélectionnez le projet que vous venez d'enregistrer.
- 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
ouunlisted
. 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 ressourcecuepoint
. 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
sur0
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.
-
Pour lancer la coupure publicitaire immédiatement, appelez la méthode
-
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'étatlive
.Lorsque vous insérez un point de repère, définissez la propriété
insertionOffsetTimeMs
de la ressourcecuepoint
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éthodeliveBroadcasts.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 deready
àtesting
, YouTube définira l'état de la diffusion surtestStarting
, 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
ouliveStarting
, vous devez appeler la méthodeliveBroadcasts.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 estactive
avant d'appeler cette méthode.