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

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

video

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 :

Configurer votre diffusion
Revendiquer votre contenu
Tester
Mégaphone
Terminer votre diffusion
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 programme 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 immédiatement après la fin de la diffusion, vous devez également définir la propriété contentDetails.enableDvr sur true. (La valeur par défaut de ces deux propriétés est true.)
Vous pouvez modifier n'importe quelle propriété contentDetails tant que l'état de votre diffusion est created ou ready.
Vous pouvez modifier l'heure de début et de fin prévue d'une diffusion tant que son état est created, ready ou testing.
Vous pouvez modifier à tout moment le titre, la description et l'état de confidentialité de la diffusion, ainsi que les autres champs de métadonnées qui font partie de la ressource video de la diffusion.

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 en utilisant le 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 plus loin dans ce document.

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

snippet.description : comme le titre de la diffusion, la description peut être modifiée une fois la diffusion créée. Ni le titre ni la description ne sont visibles par les utilisateurs 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 si un canal a une relation plusieurs-à-un ou un-à-un entre les ressources liveBroadcast et liveStream :
- Si vous utilisez la valeur par défaut true 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. Au lieu de cela, 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 la requête d'API envoyée au flux, 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

Maintenant que vous avez créé vos ressources liveBroadcast et liveStream, vous devez les associer à l'aide de la méthode liveBroadcasts.bind. Cette action associe les bits 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. Les étapes suivantes décrivent ce processus. 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éez un composant

Une ressource asset représente un contenu protégé par des droits de propriété intellectuelle. Dans ce cas, l'élément est votre diffusion. Appelez la méthode assets.insert pour créer votre composant.

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 d'API.

Étape 2.2 : Définissez votre propriété sur le composant

Les données de propriété d'un élément identifient ses propriétaires ainsi que les pays 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 dont le contenu correspond aux États-Unis, tandis que celle de l'autre propriétaire s'appliquera aux vidéos correspondantes au Canada.

Pour définir vos territoires de propriété pour 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éfinissez la règle de correspondance de l'élément

Les règles de correspondance d'un élément expliquent 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 des règles de correspondance si vous prévoyez de créer une référence à partir de votre vidéo de diffusion et de l'utiliser 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 : Revendiquer 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 un règlement qui s'applique uniquement à votre vidéo de diffusion. (Les vidéos mises en ligne par des utilisateurs dont le contenu correspond à votre vidéo de diffusion sont couvertes par les règles de correspondance définies à 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 : vous avez obtenu cette valeur à l'étape 2.1.
videoId : il s'agit de l'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 règle 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 : Mettez à 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 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 la rejoignent 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 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 3 : Test

Au cours de cette étape, vous allez intégrer 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 de la diffusion telle qu'elle apparaîtra aux spectateurs YouTube.

Notez que vous ne pouvez tester votre diffusion vidéo que si son flux de surveillance 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 lorsque vous créez ou mettez à jour cette diffusion.

Étape 3.1 : Intégrer un lecteur de flux de surveillance

Récupérez votre diffusion à l'aide de la méthode liveBroadcasts.list et 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 caméra.

Étape 3.2 : Démarrer 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 sur "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 la valeur du paramètre broadcastStatus sur testing.

Après avoir appelé la méthode liveBroadcasts.transition, plusieurs secondes, voire une minute, peuvent s'écouler avant que cette transition ne soit terminée. Pendant cette période, 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 : Finaliser vos tests

Si votre test s'est déroulé sans problème, 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 y remédier avant de diffuser votre émission.

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 correctement configuré s'il spécifie un format vidéo incorrect.

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.
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.
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 : Activez les propriétés `autoStart` et `autoStop`

Une fois la phase 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 proprement dite. Ces propriétés ne peuvent pas être définies sur true avant la phase 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 : Démarrer 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

Étape 4.3 : Passer l'état de votre diffusion à "En direct"

Important : Cette étape rend votre vidéo visible par 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, après avoir commencé le streaming), vous devez généralement attendre 5 à 10 secondes pour que la transition se termine. La transition peut prendre jusqu'à une minute. Pendant cette période, 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 sera live une fois la transition terminée et les spectateurs pourront regarder votre diffusion à partir de ce point dans le flux de votre moniteur.

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érer 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 pause (en secondes) que vous souhaitez afficher. (La valeur par défaut est 30.)

À ce moment-là, YouTube tente de lire une annonce dans le lecteur vidéo pour tous les spectateurs qui regardaient la diffusion lorsque le repère publicitaire a été inséré. La diffusion d'une annonce dépend de plusieurs facteurs, comme sa disponibilité et l'historique de visionnage d'annonces du spectateur. Les spectateurs qui voient une série d'annonces reviennent à votre diffusion une fois la série terminée, tandis que ceux qui n'en voient pas continuent de regarder la diffusion pendant la pause.

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

Étape 5 : Terminez votre diffusion

Étape 5.1 : Arrêter le streaming

C'est la fin de votre test du système de diffusion en direct YouTube.

Étape 5.2 : Faites passer 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, 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 regarder immédiatement la rediffusion 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é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 stocké à l'étape 2.4.

Envoi de contenus en direct pour Content ID

Certains partenaires YouTube peuvent créer une référence avant que leur diffusion 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 la diffusion. YouTube recherche également les vidéos mises en ligne par les utilisateurs pendant la diffusion. 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 en direct de votre contenu avec Content ID, 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 qu'elle n'ait lieu, l'API renverra 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.