La vie d'une émission

Introduction

Ce document vous explique le cycle de vie 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 disposant d'un identifiant unique. Pour créer et gérer des événements en direct sur YouTube, vous utiliserez différents types de ressources définies dans l'API YouTube Data ou l'API YouTube Content ID. Les ressources listées sous l'en-tête API YouTube Live Streaming sont techniquement définies dans ces autres API, mais sont listées séparément, car elles ne sont utilisées que pour les diffusions en direct.

Ressources de l'API YouTube Live Streaming

Ressources de l'API YouTube Data

Ressources de l'API YouTube Content ID

Créer et gérer une diffusion en direct

Les étapes suivantes expliquent comment créer et gérer un événement en direct sur YouTube. Les étapes sont divisées en plusieurs phases :

  1. Configurer votre diffusion
  2. Revendiquer votre contenu
  3. Tester
  4. Mégaphone
  5. Mettre fin à votre diffusion
  6. Créer une référence

Étape 1 : Configurez votre diffusion

Étape 1.1 : Créez votre diffusion

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

Veuillez tenir compte des consignes suivantes lorsque vous configurez votre diffusion :

  • Si vous souhaitez effectuer une phase de test pour votre diffusion, pendant laquelle vous pouvez regarder votre diffusion vidéo sans que d'autres spectateurs puissent la voir, 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 pour les deux propriétés.

  • Si vous souhaitez créer une référence à partir de votre 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 soit disponible pour la lecture 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 une valeur par défaut de true.)

  • Si vous souhaitez limiter les régions dans lesquelles votre diffusion est visible, vous pouvez définir la propriété contentDetails.availabilityConfig. Cette propriété vous permet de bloquer des régions spécifiques ou de limiter la disponibilité à une liste définie de régions. Vous pouvez également spécifier des périodes pour la disponibilité régionale.

  • Vous pouvez éventuellement spécifier la catégorie de la vidéo pour la diffusion à l'aide de la propriété snippet.categoryId. Si aucune valeur n'est spécifiée, la catégorie par défaut est Entertainment.

  • Vous pouvez modifier 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 de fin programmées d'une diffusion tant que son état est created, ready ou testing.

  • Le titre, la description, la catégorie, l'état de confidentialité et les autres champs de métadonnées de la diffusion qui font partie de la ressource video de la diffusion peuvent être mis à jour à tout moment.

    Remarque : Si vous souhaitez que votre vidéo ne soit disponible que pour certains utilisateurs YouTube, définissez la valeur de 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 de cette ressource. Vous aurez besoin de cette valeur pour identifier la diffusion dans les futures requêtes API. (Vous pouvez également identifier la ressource video qui correspond à la ressource liveBroadcast à l'aide du même ID.)

Étape 1.2 : Créez votre flux

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

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

À l'exception du titre de la diffusion, ces valeurs ne peuvent pas être modifiées une fois la diffusion créée. Si vous devez les modifier, vous devez en fait créer un autre flux en répétant cette étape. Ce processus est abordé plus en détail à l'étape 3.5 de ce document.

Vous pouvez également définir des valeurs pour les propriétés suivantes :

  • snippet.description : comme le titre du flux, la description du flux peut être mise à jour après la création du flux. Ni le titre, ni la description ne sont visibles par les utilisateurs de YouTube.

  • [contentDetails.isReusable](

    /youtube/data/live/reference/rest/v3/liveStreams#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 si une chaîne présente une relation de type plusieurs-à-un ou un-à-un entre les ressources liveBroadcast et liveStream :

    • Si vous utilisez la valeur par défaut de la propriété, true, 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. Vous pouvez simplement 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, la réponse de l'API contient la ressource liveStream que vous avez créée. Votre code doit extraire et stocker le id de cette ressource. Vous aurez besoin de cette valeur pour identifier le flux dans les futures requêtes API.

Étape 1.3 : Associez votre diffusion à son flux

Après avoir créé vos ressources liveBroadcast et liveStream, vous devez maintenant les associer à l'aide de la méthode liveBroadcasts.bind. Cette action associe les éléments vidéo que vous allez transmettre à 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 de la diffusion avant le début de l'événement. Suivez les étapes ci-dessous pour configurer la diffusion, sa vidéo et ses annonces. Notez que la chaîne du propriétaire de la diffusion doit être éligible à la diffusion d'annonces.

Notez que tous les appels d'API abordés dans cette étape sont définis dans l'API YouTube Content ID.

Étape 2.1 : Créer un asset

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

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

Étape 2.2 : Définissez votre propriété de l'élément

Les données de propriété d'un élément identifient ses propriétaires ainsi que les territoires dans lesquels ils le possèdent. YouTube utilise ces données pour déterminer où un propriétaire peut définir la règle pour 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 chacun définir des règles différentes pour la vidéo de diffusion et pour les vidéos mises en ligne par les utilisateurs qui correspondent à la vidéo de diffusion. Votre règle de correspondance s'appliquera aux vidéos mises en ligne par des utilisateurs aux États-Unis, tandis que la règle de l'autre propriétaire s'appliquera aux vidéos correspondantes au Canada.

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

Étape 2.3 : Définissez la règle 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 comment YouTube doit traiter une vidéo mise en ligne qui correspond à 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 de diffusion et d'utiliser cette référence pour identifier les vidéos mises en ligne par les utilisateurs qui correspondent à votre diffusion. 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 stratégies existantes en appelant la méthode policies.list ou définir une nouvelle stratégie en appelant la méthode policies.insert. Dans les deux cas, vous devez capturer le 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

Dans cette étape, vous allez créer une revendication qui associe 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'à votre vidéo diffusée. (Les vidéos mises en ligne par des utilisateurs dont le contenu correspond à votre vidéo de diffusion sont couvertes par la règle de correspondance définie à l'étape précédente.)

Pour créer une réclamation, 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 : valeur obtenue à l'étape 2.1.
  • videoId : ID de diffusion que vous avez 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 règle 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 le id de cette ressource. Vous utiliserez cette valeur ultérieurement pour créer une référence à partir de votre vidéo traitée.

Étape 2.5 : Modifiez 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 pré-roll lorsque les spectateurs commencent à regarder votre diffusion ou diffuser des annonces pendant les pauses de votre diffusion.

  • Si vous activez les annonces pré-roll pour votre diffusion, tous les spectateurs verront une annonce lorsqu'ils commenceront à regarder votre diffusion, même s'ils commencent à la regarder en cours de route.
  • Si vous activez les annonces mid-roll pour votre diffusion, vous pourrez insérer des repères publicitaires pendant la diffusion.

Pour activer les annonces, appelez la méthode videoAdvertisingOptions.update. Dans votre requête, définissez le paramètre videoId sur la valeur id de la diffusion que vous avez obtenue à 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 n° 3 : Test

Au cours de cette étape, vous intégrez un lecteur qui affiche le flux de surveillance de votre diffusion afin de pouvoir 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 apparaîtrait aux spectateurs YouTube.

Notez que vous ne pouvez tester votre diffusion vidéo que si son flux de contrôle est activé. Par défaut, les diffusions sont activées dans le flux de surveillance. Vous pouvez désactiver le flux de surveillance d'une diffusion en définissant la propriété contentDetails.monitorStream.enableMonitorStream sur false lorsque vous créez ou modifiez 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 votre flux de contrôle.

Étape 3.2 : Lancez votre vidéo

Commencez à transmettre la vidéo sur 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 : Passez l'état de votre diffusion à "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.

Après avoir appelé la méthode liveBroadcasts.transition, la transition peut prendre plusieurs secondes, voire 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. L'état sera testing une fois la transition terminée.

Étape 3.5 : Terminer les tests

Si votre test s'est bien déroulé, vous pouvez passer à l'étape 4. Toutefois, dans certains cas, vous devrez peut-être effectuer d'autres tests. 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 procéder à la diffusion.

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

  1. Pour dissocier le flux vidéo, appelez la méthode liveBroadcasts.bind de l'étape 1.3. Dans la requête API, définissez le paramètre id sur le id obtenu à l'étape 1.1. N'incluez pas le paramètre streamId dans la requête.

  2. Pour supprimer le flux vidéo, appelez la méthode liveStreams.delete. Dans la requête, définissez le paramètre id sur le id obtenu à l'étape 1.2.

  3. 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, puis les étapes 3.1 à 3.3 pour tester le nouveau flux.

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

Une fois l'étape de test terminée, vous pouvez 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 entraînerait le démarrage de la diffusion.

Étape 4 : Diffusion

À ce stade, votre vidéo de diffusion est visible par votre audience.

Étape 4.1 : Lancez votre vidéo

Commencez à transmettre la vidéo sur votre flux vidéo.

Étape 4.2 : 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 4.3 : Faites passer l'état de votre diffusion à "En direct"

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

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 la valeur du paramètre broadcastStatus sur live.

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, après avoir commencé le streaming), vous devez généralement attendre 5 à 10 secondes pour que cette 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. Tant que la transition n'est pas terminée, l'état de la diffusion est liveStarting. L'état passe à live une fois la transition terminée. Les spectateurs peuvent alors regarder votre diffusion à partir de ce point dans votre flux de contrôle.

Notez les effets suivants de cette commande :

  • Si vous avez activé le flux de contrôle pour votre diffusion (voir l'étape 3.1), vous pourrez le voir dans un lecteur intégré.
  • Si vous avez 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 diffusion

Appelez la méthode liveBroadcasts.cuepoint pour insérer un 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.)

À ce moment-là, YouTube tente de diffuser une annonce dans le lecteur vidéo pour tous les spectateurs qui regardaient la diffusion lorsque le point de repère d'annonce a été inséré. La diffusion d'une annonce dépend de plusieurs facteurs, tels que la disponibilité des annonces et l'historique de visionnage de l'utilisateur. Les spectateurs qui voient une coupure publicitaire reviennent à votre diffusion une fois la coupure terminée, tandis que ceux qui ne voient pas d'annonce continuent de regarder la diffusion pendant la coupure.

Le guide Premiers pas fournit plus d'informations sur l'expérience de visionnage pendant une coupure publicitaire d'une diffusion en direct.

Étape 5 : Terminez votre diffusion

Étape 5.1 : Arrêter le streaming

Le test du système de diffusion en direct de YouTube est terminé.

Étape 5.2 : Passez l'état de votre diffusion à "Terminée"

Lorsque vous êtes prêt à arrêter la diffusion, appelez la méthode liveBroadcasts.transition de l'API 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, puis 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 regarder immédiatement la lecture de l'événement en direct une fois celui-ci terminé.

É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 les utilisateurs qui correspondent à la diffusion et de les traiter conformément à la règle de correspondance que vous avez 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 : Interrogez l'API Data pour connaître l'état de la vidéo

YouTube doit terminer le traitement d'une diffusion ou d'une vidéo importée avant que vous puissiez créer une référence à partir de cette vidéo. Pour déterminer 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 la diffusion que vous avez stocké à l'étape 1.1.

La réponse de l'API à votre requête d'interrogation contiendra 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éez 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 stocké à l'étape 2.4.

Envoi de contenus en direct avec Content ID

Certains partenaires YouTube peuvent créer une référence avant que leur diffusion ne passe à l'état testing, mais cette fonctionnalité n'est pas disponible pour tous les partenaires. Dans ce flux, YouTube génère et met à jour en continu la référence à partir du flux de diffusion de votre événement en direct pendant que la diffusion est en cours. De plus, YouTube recherche les vidéos mises en ligne par les utilisateurs qui correspondent à la diffusion pendant qu'elle est en cours. Notez que si vous créez une référence avant le début d'une diffusion, l'enregistrement de la diffusion est automatiquement activé. Vous ne pourrez plus le désactiver une fois la référence créée.

Pour activer la diffusion de Content ID en direct, effectuez les actions 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é approuvé pour créer une référence pour une diffusion en direct avant que celle-ci n'ait lieu, l'API renvoie une erreur fingerprintingNotAllowed. Dans ce cas, vous devez attendre la fin de votre diffusion, comme décrit dans les étapes 6.1 et 6.2 ci-dessus, avant de créer la référence.