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

La vie d'une émission

Introduction

Ce document vous guide tout au long d'une diffusion en direct sur YouTube, créée et gérée à l'aide de l'API YouTube Live Streaming et de l'API YouTube Content ID.

Ressources et types de ressources

Comme expliqué dans le guide de démarrage, une ressource est une entité de données individuelle avec un identifiant unique. Pour créer et gérer des événements en direct sur YouTube, vous devez utiliser différents types de ressources définies dans l'API YouTube Data ou l'API YouTube Content ID. Les ressources répertoriées sous l'en-tête API YouTube Live Streaming sont techniquement définies dans ces autres API, mais répertoriées séparément, car elles ne sont utilisées que pour les diffusions en direct.

Ressources sur l'API YouTube Live Streaming

Ressources sur l'API YouTube Data

video

Ressources de l'API YouTube Content ID

Créer et gérer une diffusion en direct

La procédure suivante vous explique comment créer et gérer un événement en direct sur YouTube. Les étapes sont réparties comme suit:

Configurer votre diffusion
Revendiquer votre contenu
Test
Mégaphone
Finaliser la diffusion
Créer une référence

Étape 1: Configurer la diffusion

Étape 1.1: Créer une diffusion

Appelez la méthode liveBroadcasts.insert pour ajouter votre diffusion au programme d'événements en direct de YouTube. La ressource liveBroadcast que vous insérez doit définir des valeurs pour les propriétés répertoriées ci-dessous.

Veuillez tenir compte des consignes suivantes lors de la configuration de votre diffusion:

Si vous souhaitez disposer d'une phase de test de votre diffusion, lorsque vous pouvez la regarder sans que les autres utilisateurs puissent également voir la diffusion, vous devez définir la propriété contentDetails.monitorStream.enableMonitorStream sur true et la propriété contentDetails.enableAutoStart sur false. Il s'agit des valeurs par défaut des deux propriétés.
Si vous souhaitez créer une référence à partir d'une diffusion enregistrée, vous devez définir la propriété contentDetails.recordFromStart de la diffusion sur true. Si vous souhaitez que la vidéo enregistrée puisse être lue immédiatement après la fin de la diffusion, vous devez également définir la propriété contentDetails.enableDvr sur true. (ces deux propriétés ont la valeur true par défaut).
Vous pouvez mettre à jour n'importe quelle propriété contentDetails tant que l'état de votre diffusion est toujours created ou ready.
Vous pouvez modifier l'heure de début et l'heure de fin planifiées de la diffusion, à condition que son état soit created, ready ou testing.
Le titre, la description et l'état de confidentialité de la diffusion, ainsi que les autres champs de métadonnées faisant partie de la ressource video de la diffusion, peuvent être mis à jour à tout moment.

Remarque:Si vous souhaitez que votre vidéo ne soit accessible qu'à certains utilisateurs YouTube, définissez la propriété status.privacyStatus sur unlisted ou private selon vos besoins.

Traiter la réponse de l'API

Lorsque vous appelez la méthode liveBroadcasts.insert, la réponse de l'API contient la ressource liveBroadcast que vous avez créée. Votre code doit extraire et stocker le id à partir de cette ressource. Vous en aurez besoin pour identifier la diffusion dans les futures requêtes d'API. (Vous pouvez également identifier la ressource video qui correspond à la ressource liveBroadcast avec le même ID.)

Étape 1.2: Créer votre flux

Une ressource liveStream vous permet de transmettre votre vidéo à YouTube et de décrire son contenu. Chaque diffusion doit être associée à un seul flux.

Appelez la méthode liveStreams.insert afin de créer le flux vidéo pour votre événement. Lorsque vous créez votre flux, vous devez définir les valeurs des propriétés répertoriées ci-dessous:

À l'exception du titre du flux, ces valeurs ne peuvent pas être mises à jour après la création du flux. Si vous devez les modifier, vous devez créer un autre flux en répétant cette étape. Ce processus est détaillé à l'étape 3.5 plus loin dans ce document.

Vous avez également la possibilité de définir des valeurs pour les propriétés suivantes:

snippet.description : comme le titre du flux, sa description peut être mise à jour après sa création. Ni le titre, ni la description ne sont visibles par les utilisateurs de YouTube.
contentDetails.isReusable : indique si le flux est réutilisable, ce qui signifie qu'il peut être associé à plusieurs diffusions. La valeur de cette propriété détermine efficacement si un canal a une relation plusieurs à un ou un à un entre les ressources liveBroadcast et liveStream:
- Si vous utilisez la valeur true par défaut de la propriété, vous pouvez utiliser la même ressource liveStream pour toutes les diffusions d'une chaîne. Cela signifie que vous n'avez pas besoin de répéter cette étape (1.2) pour chaque diffusion. Il vous suffit de réutiliser l'ID de flux pour les diffusions suivantes.
- Si vous définissez la valeur de la propriété sur false, vous devez créer un flux pour chaque diffusion.

Une fois que vous avez envoyé la requête API au flux, la réponse de l'API contient la ressource liveStream que vous avez créée. Votre code doit extraire et stocker la classe id à partir de cette ressource. Vous en aurez besoin pour identifier le flux dans les futures requêtes de l'API.

Étape 1.3: Associez votre diffusion à son flux

Après avoir créé vos ressources liveBroadcast et liveStream, vous devez maintenant associer les deux à l'aide de la méthode liveBroadcasts.bind. Cette action associe les bits que vous transmettrez à YouTube à la diffusion de l'événement pour cette vidéo.

Lorsque vous appelez la méthode liveBroadcasts.bind, définissez le paramètre id sur l'ID de diffusion obtenu à l'étape 1.1 et le paramètre streamId sur l'ID de flux obtenu à l'étape 1.2.

Étape 2: Revendiquez 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. Les étapes suivantes expliquent ce processus. Notez que tous les appels d'API abordés à cette étape sont définis dans l'API YouTube Content ID.

Étape 2.1: Créer un asset

Une ressource asset représente une propriété intellectuelle. Dans ce cas, l'élément est votre annonce. Appelez la méthode assets.insert pour créer l'élément.

La réponse de l'API contient la ressource asset que vous avez créée. Votre code doit extraire et stocker le id de cette ressource, car vous en aurez besoin pour identifier l'élément dans les futures requêtes d'API.

Étape 2.2: Définir la propriété de l'élément

Les données de propriété d'un élément identifient les propriétaires et les territoires où ils sont propriétaires de l'élément. YouTube utilise ces données pour déterminer où un propriétaire peut définir les règles d'une vidéo revendiquée.

Par exemple, si vous avez le droit de diffuser un événement aux États-Unis et qu'un autre diffuseur détient les mêmes droits pour le Canada, vous pouvez définir des règles différentes pour la vidéo et la vidéo mise en ligne par un utilisateur qui correspondent à la vidéo diffusée. Votre règle de correspondance s'appliquera aux vidéos mises en ligne par des utilisateurs correspondantes aux États-Unis, tandis que l'autre propriétaire s'appliquera aux vidéos correspondantes au Canada.

Pour définir les territoires où vous êtes propriétaire de l'élément, appelez la méthode ownership.update. Dans cette requête, définissez le paramètre assetId sur le id que vous avez stocké à l'étape 2.1.

Étape 2.3: Définir les règles de correspondance de l'asset

La règle de correspondance d'un élément explique ce que YouTube doit faire lorsqu'un utilisateur met en ligne une vidéo qui correspond à une référence associée à l'élément. Dans ce cas, la règle de correspondance indique la façon dont YouTube doit traiter une vidéo mise en ligne correspondant à votre diffusion en direct.

Remarque : Vous devez définir une règle de correspondance si vous prévoyez de créer une référence à partir de votre vidéo diffusée et d'utiliser cette référence pour identifier les vidéos mises en ligne par des utilisateurs qui correspondent à votre annonce. Dans le cas contraire, veuillez ignorer cette étape.

Pour définir la règle de correspondance, vous devez d'abord identifier celle que vous souhaitez appliquer. Vous pouvez récupérer la liste des règles existantes en appelant la méthode policies.list, ou en définir une nouvelle en appelant la méthode policies.insert. Dans les deux cas, vous devez capturer l'id de la règle que vous souhaitez appliquer.

Une fois la stratégie identifiée, appelez la méthode assetMatchPolicy.update. Dans cette requête, définissez le paramètre assetId sur le id que vous avez stocké à l'étape 2.1.

Étape 2.4: Revendiquez votre vidéo

Au cours de cette étape, vous allez créer une revendication associant la vidéo que vous allez diffuser à l'élément que vous avez créé à l'étape 2.1. La revendication définit une règle qui ne s'applique qu'à la vidéo diffusée. (Les vidéos mises en ligne par des utilisateurs correspondant à votre vidéo de diffusion sont soumises à la règle de correspondance définie à l'étape précédente.)

Pour créer une revendication, appelez la méthode claims.insert. Dans la ressource claim que vous insérez, vous devez définir des valeurs pour les propriétés suivantes:

assetId : vous avez obtenu cette valeur à l'étape 2.1.
videoId : ID de diffusion obtenu à l'étape 1.1.
policy : il s'agit d'une ressource policy. Vous pouvez appliquer une règle existante en définissant la propriété id de cette ressource sur l'ID de la stratégie existante. L'étape précédente explique comment récupérer l'ID d'une stratégie existante.
contentType : définissez cette valeur sur audiovisual.

Traiter la réponse de l'API

Lorsque vous insérez la revendication, la réponse de l'API contient la ressource claim que vous avez créée. Votre code doit extraire et stocker la classe id à partir de cette ressource. Vous utiliserez cette valeur plus tard pour créer une référence à partir de votre vidéo traitée.

Étape 2.5: Mettre à jour les paramètres des annonces pour la diffusion

Vous devez définir les options publicitaires de votre vidéo si vous souhaitez diffuser une annonce vidéo pré-roll lorsque les spectateurs commencent à la regarder ou la diffuser pendant les pauses.

Si vous activez les annonces vidéo pré-roll pour votre diffusion, toutes les personnes verront une annonce lorsqu'elles commenceront à regarder votre diffusion, même si elles commencent à la regarder en plein milieu.
Si vous activez les annonces vidéo mid-roll pour votre diffusion, vous pouvez y insérer des points de repère d'annonce.

Pour activer les annonces, appelez la méthode videoAdvertisingOptions.update. Dans votre requête, définissez le paramètre videoId sur le id de diffusion obtenu à l'étape 1.1. Utilisez la propriété adFormats[] de la ressource videoAdvertisingOption pour identifier les formats d'annonces (preroll, midroll ou postroll) que vous souhaitez activer.

Étape 3: Test

Au cours de cette étape, vous intégrez un lecteur qui affiche le flux de surveillance de votre diffusion afin de tester l'expérience de visionnage. Le flux de contrôle est un flux privé qui vous permet de prévisualiser la vidéo diffusée telle qu'elle s'afficherait pour les spectateurs YouTube.

Notez que vous ne pouvez tester votre annonce vidéo que si son flux de contrôle est activé. Par défaut, les flux de surveillance des diffusions sont activés. Vous pouvez désactiver le flux de surveillance d'une diffusion en définissant la propriété contentDetails.monitorStream.enableMonitorStream sur false lors de la création ou de la mise à jour de cette diffusion.

Étape 3.1: Intégrer un lecteur de flux de contrôle

Récupérez votre diffusion à l'aide de la méthode liveBroadcasts.list, puis extrayez la valeur de la propriété contentDetails.streamDetails.monitorStreamEmbedHtml. Cette valeur contient le code HTML dont vous avez besoin pour intégrer un lecteur YouTube qui affiche le flux de votre moniteur.

Étape 3.2: Lancez la vidéo

Commencez à transmettre des vidéos dans votre flux vidéo.

Étape 3.3: Vérifiez que votre flux vidéo est actif

Appelez la méthode liveStreams.list pour récupérer la ressource liveStream associée à votre diffusion. Vérifiez que la valeur de la propriété status.streamStatus est active, ce qui indique que les serveurs YouTube reçoivent correctement les données de votre encodeur.

Étape 3.4: Faites passer l'état de votre diffusion au test

Appelez la méthode liveBroadcasts.transition pour mettre à jour l'état de la diffusion. Définissez la valeur du paramètre id sur l'ID de diffusion obtenu à l'étape 1.1 et définissez la valeur du paramètre broadcastStatus sur testing.

Une fois que vous avez appelé la méthode liveBroadcasts.transition, la transition peut prendre plusieurs secondes, voire jusqu'à une minute. Pendant ce temps, vous devez interroger l'API pour vérifier l'état de la diffusion. Tant que la transition n'est pas terminée, l'état de la diffusion est testStarting. Une fois la transition terminée, l'état sera testing.

Étape 3.5: Effectuer les tests

Si le test s'est déroulé correctement, vous pouvez passer à l'étape 4. Toutefois, dans certains cas, des tests supplémentaires peuvent être nécessaires. Par exemple, si vos tests révèlent que le flux vidéo n'est pas configuré correctement, vous devez résoudre ce problème avant de poursuivre la diffusion.

Si le flux vidéo n'est pas configuré correctement, vous devez le dissocier (et le supprimer) et en créer un autre. Par exemple, un flux peut ne pas être configuré correctement s'il spécifie un format vidéo incorrect.

Pour annuler la liaison du flux vidéo, appelez la méthode liveBroadcasts.bind à l'étape 1.3. Dans la requête API, définissez le paramètre id sur la valeur id obtenue à l'étape 1.1. N'incluez pas le paramètre streamId dans la requête.
Pour supprimer le flux vidéo, appelez la méthode liveStreams.delete. Dans la requête, définissez le paramètre id sur la valeur id obtenue à l'étape 1.2.
Répétez l'étape 1.2 pour créer une ressource liveStream correctement configurée. Répétez ensuite l'étape 1.3 pour associer le nouveau flux à votre diffusion et les étapes 3.1 à 3.3 pour tester le nouveau flux.

Étape 3.6: Activer les propriétés `autoStart` et `autoStop`

Une fois l'étape de test terminée, vous avez la possibilité de définir les propriétés contentDetails.enableAutoStart et contentDetails.enableAutoStop de la diffusion sur true avant le début de la diffusion. Ces propriétés ne peuvent pas être définies sur true avant l'étape de test, car le test déclencherait en réalité la diffusion.

Étape 4: Diffusion

Au cours de cette étape, votre vidéo est accessible à votre audience.

Étape 4.1: Lancez la vidéo

Commencez à transmettre des vidéos dans votre flux vidéo.

Étape 4.2: Vérifiez que votre flux vidéo est actif

Étape 4.3: Faites passer l'état de votre diffusion au direct

Important : Cette étape rend votre vidéo visible pour votre audience.

Si vous définissez la propriété contentDetails.enableAutoStart de la ressource liveBroadcast sur true, vous n'avez pas besoin d'appeler la méthode liveBroadcasts.transition.

Après avoir effectué cet appel d'API ou, si vous avez défini la propriété contentDetails.enableAutoStart sur true, vous devez attendre entre 5 et 10 secondes pour que la transition se termine. La transition peut prendre jusqu'à une minute. Pendant ce temps, vous devez interroger l'API pour vérifier l'état de la diffusion. La diffusion reste associée à l'état liveStarting jusqu'à la fin de la transition. Une fois la transition terminée, l'état sera live, et les spectateurs pourront regarder votre diffusion à partir de ce point dans le flux du moniteur.

Notez les effets suivants de cette commande:

Si vous avez activé le flux de surveillance pour votre diffusion (voir l'étape 3.1), le flux de surveillance s'affiche dans un lecteur intégré.
Si vous aviez défini une valeur pour la propriété contentDetails.streamDetails.broadcastStreamDelayMs de la diffusion, le flux de diffusion, visible par les autres spectateurs, sera retardé de cette durée.

Étape 4.4: Insérez des coupures publicitaires dans votre annonce

Appelez la méthode liveBroadcasts.cuepoint pour insérer un point de repère. Le point de repère peut déclencher une coupure publicitaire. Dans la ressource cuepoint fournie dans le corps de la requête, définissez la propriété durationSecs sur la durée souhaitée de la coupure (en secondes) que vous souhaitez afficher. La valeur par défaut est 30.

Pour le moment, YouTube tente de lire une annonce dans le lecteur vidéo pour tous les spectateurs qui regardaient la diffusion alors que le point de repère de l'annonce était inséré. La lecture d'une annonce dépend de plusieurs facteurs, tels que la disponibilité de l'annonce et l'historique du visionnage de l'utilisateur. Les spectateurs qui voient une coupure publicitaire reviennent à la diffusion une fois celle-ci terminée, tandis que ceux qui ne voient pas d'annonce continuent de regarder le flux de diffusion pendant la coupure publicitaire.

Le guide de démarrage fournit davantage d'informations sur le visionnage d'une coupure publicitaire en direct.

Étape 5: Finalisez votre diffusion

Étape 5.1: Arrêter la diffusion

Vous êtes parvenu à la fin du test du système de diffusion en direct de YouTube.

Étape 5.2: Effectuez la transition de votre diffusion pour la terminer

Lorsque vous êtes prêt à arrêter la diffusion, appelez la méthode API liveBroadcasts.transition pour mettre à jour l'état de la diffusion. Définissez la valeur du paramètre id sur l'ID de diffusion obtenu à l'étape 1.1 et définissez la valeur du paramètre broadcastStatus sur complete.

Si vous avez défini les propriétés contentDetails.recordFromStart et contentDetails.enableDvr de la diffusion sur true, votre audience peut immédiatement regarder la diffusion de l'événement en direct à la fin de celle-ci.

Étape 6: Créer une référence

Une fois l'enregistrement en direct terminé, vous pouvez créer une référence à partir de la vidéo enregistrée. Cette action demande à YouTube de rechercher les vidéos mises en ligne par des utilisateurs dont le contenu correspond à la diffusion et de les traiter conformément à la règle de correspondance définie à l'étape 2.3.

Important:Pour créer la référence, vous devez avoir défini la propriété contentDetails.recordFromStart de la diffusion sur true.

Étape 6.1: Sondage de l'API Data pour l'état de la vidéo

YouTube doit terminer le traitement d'une diffusion ou d'une vidéo mise en ligne avant que vous puissiez créer une référence à partir de cette vidéo. Pour savoir si le traitement de la vidéo est terminé, interrogez la méthode videos.list de l'API YouTube Data, en définissant le paramètre part sur status et le paramètre id sur l'ID de diffusion que vous avez enregistré à l'étape 1.1.

La réponse de l'API à votre requête d'interrogation contient une ressource video. Lorsque la valeur de la propriété status.uploadStatus de cette ressource est processed, passez à l'étape 6.2.

Étape 6.2: Créer une référence à partir de la vidéo traitée

Pour créer votre référence, appelez la méthode references.insert de l'API Content ID et définissez le paramètre claimId sur l'ID de revendication que vous avez enregistré à l'étape 2.4.

Diffusion Content ID en direct

Certains partenaires YouTube peuvent créer une référence avant la transition de leur diffusion à l'état testing, mais cette fonctionnalité n'est pas disponible pour tous les partenaires. Ainsi, YouTube génère et met à jour en permanence la référence à partir du flux de diffusion de votre événement en direct pendant que la diffusion est en cours. En outre, YouTube recherche les vidéos mises en ligne par des utilisateurs correspondantes pendant que la diffusion est en cours. Notez que la création d'une référence avant le début d'une diffusion active automatiquement l'enregistrement pour la diffusion et que l'enregistrement ne peut pas être désactivé une fois la référence créée.

Pour activer la diffusion en direct de Content ID, suivez les étapes décrites à l'étape 6.2 après avoir revendiqué votre vidéo à l'étape 2.4. Si votre compte partenaire n'a pas été autorisé à créer une référence pour une diffusion en direct avant la diffusion, l'API renverra une erreur fingerprintingNotAllowed. Dans ce cas, vous devez attendre la fin de la diffusion, comme décrit aux étapes 6.1 et 6.2 ci-dessus, avant de créer la référence.