Guide de migration pour l'abandon des diffusions et des flux par défaut

Présentation

Ce guide est destiné aux développeurs d'applications clientes de l'API qui utilisent les ressources liveStream et liveBroadcast par défaut des chaînes YouTube pour diffuser du contenu en direct. Notre objectif est de vous aider à gérer correctement l'abandon des diffusions et des flux par défaut. Nous vous conseillons également de vous y conformer si l'une des affirmations suivantes s'applique à votre application:

  • Elle vérifie la valeur de la propriété isDefaultBroadcast de la ressource liveBroadcast.
  • Elle vérifie la valeur de la propriété isDefaultStream de la ressource liveStream.

  • Il appelle la méthode liveBroadcasts.list et définit la valeur du paramètre broadcastType sur persistent. À la date d'abandon:

    • Si la valeur du paramètre broadcastType est persistent, la méthode liveBroadcasts.list ne renvoie aucun résultat.
    • Si la valeur du paramètre broadcastType est all, la méthode liveBroadcasts.list ne renvoie pas les diffusions persistantes qui existaient avant ce délai.

Si votre application est affectée, veuillez vous reporter à la section Mettre à jour votre application, qui explique les modifications de procédure que votre application devra peut-être apporter après cet abandon. Cette section décrit les étapes du guide Déroulement d'une diffusion que votre client API risque de ne pas suivre s'il utilise actuellement la diffusion et le flux par défaut.

Quelle est la situation ?

Depuis 2015, YouTube crée automatiquement une diffusion par défaut et une diffusion par défaut pour une chaîne lorsque cette dernière est activée. Le flux par défaut existe indéfiniment et ne peut pas être supprimé. De même, la diffusion par défaut était considérée comme persistante. Il existait toujours, n'était pas associé à une heure de début ou de fin et n'était pas lié à un événement particulier.

À partir de la date d'abandon mentionnée ci-dessus, YouTube ne créera plus de diffusions ni de diffusions par défaut. Ce changement affecte les applications clientes qui s'appuient sur ces ressources pour diffuser du contenu en direct. Elle affectera également les applications dans lesquelles l'interface utilisateur est personnalisée pour différencier ces ressources par défaut des autres diffusions et flux créés par les propriétaires de chaînes.

Au lieu de s'appuyer sur les ressources par défaut, les clients API doivent créer et gérer des ressources liveBroadcast et liveStream, et les lier entre elles.

Mise à jour de votre application

Pour revoir rapidement la terminologie, une diffusion représente un événement pouvant être regardé en direct sur YouTube. Un flux est le mécanisme qui permet d'envoyer le contenu vidéo à YouTube. Une diffusion peut être et doit être liée à un seul flux.

Migrer depuis des diffusions par défaut

Avant cet abandon, les clients API pouvaient choisir d'utiliser la diffusion par défaut d'un canal ou de créer une diffusion spécifique à un événement. La diffusion par défaut était une ressource persistante qui pouvait être réutilisée pour plusieurs événements, tandis qu'une ressource de diffusion spécifique à un événement est une ressource à usage unique correspondant exactement à une vidéo YouTube.

Votre application cliente utilise la diffusion par défaut si elle appelle la méthode liveBroadcasts.list et effectue l'une des opérations suivantes:

  • Elle définit la valeur du paramètre broadcastType sur persistent. Cette requête ne récupère que la diffusion par défaut.
  • Elle définit la valeur du paramètre broadcastType sur all, puis identifie la ressource liveBroadcast dans la réponse de l'API pour laquelle la valeur de la propriété isDefaultBroadcast est true.

Suite à cet abandon, YouTube n'acceptera plus que les diffusions spécifiques à un événement. Cela signifie qu'au lieu de s'appuyer sur la diffusion par défaut, les applications clientes doivent créer des ressources liveBroadcast pour chaque événement de diffusion.

Pour créer une ressource liveBroadcast, appelez la méthode liveBroadcasts.insert. Ce processus est expliqué à l'étape 1.1 du guide "La vie d'une diffusion".

Si ce n'est pas déjà fait, votre interface utilisateur doit également fournir des mécanismes permettant aux utilisateurs de distinguer les émissions à venir et spécifiques, et de les sélectionner.

Migrer à partir de flux par défaut

Un flux vous permet de transmettre du contenu audiovisuel à YouTube et définit les paramètres de diffusion de votre contenu sur YouTube. Il est courant que les diffuseurs réutilisent le même flux pour de nombreuses émissions différentes si celles-ci ont lieu à des moments différents.

Même si votre application ne peut pas utiliser le flux par défaut, elle peut créer un flux réutilisable qui peut être réutilisé pour chaque diffusion. Pour créer une ressource liveStream, appelez la méthode liveStreams.insert en suivant les instructions de l'étape 1.2 du guide "La vie d'une diffusion". Par défaut, les nouveaux flux sont réutilisables. Toutefois, si vous préférez, vous pouvez définir la propriété contentDetails.isReusable sur false pour créer des flux à usage unique et avoir une relation un à un entre les diffusions et les flux.

La liste suivante contient les quatre propriétés, en plus du titre et de la description, que vous pouvez définir lors de la création d'un flux. La liste présente les valeurs que les flux par défaut utilisent pour chaque propriété. Il s'agit probablement des paramètres que vous souhaitez utiliser dans une application cliente si vous migrez les flux par défaut.

Associer des diffusions à des flux

Chaque ressource liveBroadcast doit être associée à un seul flux pour que la diffusion en direct sur YouTube puisse commencer. (La diffusion n'est liée à aucun flux au moment de sa création.)

Le processus de liaison a été géré automatiquement pour la diffusion par défaut, qui était inextricablement associée au flux par défaut. Toutefois, après la date d'abandon, les applications clientes doivent gérer ce processus pour toutes les diffusions.

Pour lier une diffusion à un flux, appelez la méthode liveBroadcasts.bind comme expliqué à l'étape 1.3 du guide "La vie d'une diffusion".

  • Si vous utilisez un flux réutilisable, vous pouvez créer un flux une fois, puis lier chaque diffusion à ce flux.
  • Si vous n'utilisez pas un flux réutilisable, vous devez créer une diffusion et une diffusion, puis les lier.

Tester votre diffusion

Si vous n'utilisez pas la diffusion par défaut, vous avez la possibilité de tester votre diffusion. Pour effectuer un test, intégrez un lecteur permettant de prévisualiser la vidéo diffusée telle qu'elle apparaîtrait sur YouTube, mais les autres utilisateurs ne la verront pas.

Si votre client API a déjà utilisé la diffusion et le flux par défaut, et que vous souhaitez ajouter une phase de test à votre processus de diffusion, consultez la étape 3 du guide "Life of a broadcast" (La vie d'une diffusion).

Si vous souhaitez tester votre flux, lorsque vous insérez une 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 pour les deux propriétés.

Utiliser les fonctionnalités de démarrage et d'arrêt automatique

La diffusion par défaut a démarré automatiquement chaque fois que vous avez commencé à diffuser une vidéo sur la diffusion par défaut. De même, la diffusion par défaut s'est arrêtée lorsque vous avez arrêté la diffusion de la vidéo. Chaque session de streaming utilisant ces ressources par défaut est devenue une vidéo sur votre chaîne.

Bien que les fonctionnalités de démarrage et d'arrêt automatique soient le comportement par défaut des diffusions par défaut, ces fonctionnalités sont facultatives et doivent être activées pour d'autres diffusions. Si vous souhaitez utiliser ces fonctionnalités, lorsque vous insérez une diffusion, vous devez définir les valeurs de propriété contentDetails.enableAutoStart et contentDetails.enableAutoStop sur true. Ces fonctionnalités étant indépendantes, vous pouvez choisir d'utiliser l'une ou l'autre.

Si vous n'activez pas les fonctionnalités de démarrage et d'arrêt automatiques pour les nouvelles diffusions, votre client API doit appeler la méthode liveBroadcasts.transition afin de mettre à jour l'état de la diffusion lorsque vous démarrez et terminez sa diffusion. Dans le guide "Life of a Broadcast", consultez l'étape 4.3 et l'étape 5.2 pour savoir comment gérer ces transitions au début et à la fin d'une diffusion.