LiveBroadcasts

L'API vous permet désormais de marquer vos diffusions en direct comme "conçues pour les enfants". La ressource liveBroadcast contient désormais une propriété qui identifie leur état "conçue pour les enfants". Les conditions d'utilisation des services d'API YouTube et le règlement pour les développeurs ont également été mis à jour le 10 janvier 2020. Pour en savoir plus, consultez l'historique des révisions du service de l'API YouTube Live Streaming et les Conditions d'utilisation des services d'API YouTube.

Une ressource liveBroadcast représente un événement qui sera diffusé en direct sur YouTube.

Méthodes

L'API accepte les méthodes suivantes pour les ressources liveBroadcasts:

list
Renvoie une liste d'annonces YouTube correspondant aux paramètres de requête de l'API. Essayer
insérer
Crée une diffusion. Essayer
mettre à jour
Met à jour une annonce. Par exemple, vous pouvez modifier les paramètres de diffusion définis dans l'objet contentDetails de la ressource liveBroadcast. Essayer maintenant
supprimer
Supprime une diffusion. Essayer
liaison
Relie une diffusion YouTube à un flux ou supprime une liaison existante entre une diffusion et un flux. Une diffusion ne peut être liée qu'à un seul flux vidéo, même si celui-ci peut être lié à plusieurs diffusions. Essayer
transition
Modifie l'état d'une diffusion en direct YouTube 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 la vidéo au flux de surveillance de cette diffusion. Avant d'appeler cette méthode, vérifiez que la valeur de la propriété status.streamStatus pour le flux associé à votre diffusion est active. Essayer maintenant
point de repère
Insère un point de repère dans une diffusion en direct. Le point de repère peut déclencher une coupure publicitaire.

Représentation des ressources

La structure JSON suivante illustre le format d'une ressource liveBroadcasts:

{
  "kind": "youtube#liveBroadcast",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "scheduledStartTime": datetime,
    "scheduledEndTime": datetime,
    "actualStartTime": datetime,
    "actualEndTime": datetime,
    "isDefaultBroadcast": boolean,
    "liveChatId": string
  },
  "status": {
    "lifeCycleStatus": string,
    "privacyStatus": string,
    "recordingStatus": string,
    "madeForKids": string,
    "selfDeclaredMadeForKids": string,
  },
  "contentDetails": {
    "boundStreamId": string,
    "boundStreamLastUpdateTimeMs": datetime,
    "monitorStream": {
      "enableMonitorStream": boolean,
      "broadcastStreamDelayMs": unsigned integer,
      "embedHtml": string
    },
    "enableEmbed": boolean,
    "enableDvr": boolean,
    "recordFromStart": boolean,
    "enableClosedCaptions": boolean,
    "closedCaptionsType": string,
    "projection": string,
    "enableLowLatency": boolean,
    "latencyPreference": boolean,
    "enableAutoStart": boolean,
    "enableAutoStop": boolean
  },
  "statistics": {
    "totalChatCount": unsigned long
  },
  "monetizationDetails": {
    "cuepointSchedule": {
      "enabled": boolean,
      "pauseAdsUntil": datetime,
      "scheduleStrategy": string,
      "repeatIntervalSecs": unsigned integer,
    }
  }
}

Propriétés

Le tableau suivant définit les propriétés qui apparaissent dans cette ressource:

Propriétés
kind string
Identifie le type de ressource API. La valeur est youtube#liveBroadcast.
etag etag
Etag de cette ressource.
id string
ID attribué par YouTube pour identifier la diffusion de manière unique.
snippet object
L'objet snippet contient des informations de base sur l'événement, y compris son titre, sa description, son heure de début et son heure de fin.
snippet.publishedAt datetime
Date et heure d'ajout de la diffusion au calendrier de diffusion en direct de YouTube. La valeur est spécifiée au format ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ).
snippet.channelId string
ID utilisé par YouTube pour identifier de façon unique la chaîne sur laquelle la diffusion est diffusée.
snippet.title string
Titre de la diffusion. Notez que la diffusion ne représente qu'une seule vidéo YouTube. Pour définir ce champ, modifiez la ressource de diffusion ou définissez le champ title de la ressource vidéo correspondante.
snippet.description string
Description de la diffusion. Comme pour title, vous pouvez définir ce champ en modifiant la ressource de diffusion ou en définissant le champ description de la ressource vidéo correspondante.
snippet.thumbnails object
Carte des vignettes associées à la diffusion. Pour chaque objet imbriqué dans cet objet, la clé est le nom de l'image miniature et la valeur est un objet contenant d'autres informations sur la vignette.
snippet.thumbnails.(key) object
Les clés-valeurs valides sont les suivantes:
  • default : vignette par défaut. La miniature par défaut d'une vidéo (ou d'une ressource faisant référence à une vidéo, comme un élément de playlist ou un résultat de recherche) mesure 120 pixels de large sur 90 pixels de haut. Par défaut, la miniature d'une chaîne mesure 88 pixels de large sur 88 pixels de haut.
  • medium : version haute résolution de l'image de la miniature. Pour une vidéo (ou une ressource faisant référence à une vidéo), cette image mesure 320 pixels de large sur 180 pixels de haut. Pour une chaîne, cette image mesure 240 pixels de large sur 240 pixels de haut.
  • high : version haute résolution de l'image de la miniature. Pour une vidéo (ou une ressource faisant référence à une vidéo), cette image mesure 480 pixels de large sur 360 pixels de haut. Pour une chaîne, cette image mesure 800 pixels de large sur 800 pixels de haut.
snippet.thumbnails.(key).url string
URL de l'image.
snippet.thumbnails.(key).width unsigned integer
Largeur de l'image.
snippet.thumbnails.(key).height unsigned integer
Hauteur de l'image.
snippet.scheduledStartTime datetime
Date et heure prévues de début de la diffusion. La valeur est spécifiée au format ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ). Creator Studio vous permet de créer une diffusion sans planifier d'heure de début. Dans ce cas, la diffusion commence dès que le propriétaire de la chaîne lance la diffusion. Pour ces diffusions, la valeur datetime correspond à l'heure UNIX zéro, et cette valeur ne peut pas être modifiée via l'API ni dans Creator Studio.
snippet.scheduledEndTime datetime
Date et heure auxquelles la diffusion doit se terminer. La valeur est spécifiée au format ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ). Si une ressource liveBroadcast ne spécifie pas de valeur pour cette propriété, la diffusion est programmée pour se poursuivre indéfiniment. De même, si vous n'indiquez aucune valeur pour cette propriété, YouTube traite la diffusion comme si elle durait indéfiniment.
snippet.actualStartTime datetime
Date et heure auxquelles la diffusion a réellement commencé. Ces informations ne sont disponibles que lorsque l'état de la diffusion est live. La valeur est spécifiée au format ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ).
snippet.actualEndTime datetime
Date et heure de fin effective de la diffusion. Ces informations ne sont disponibles que lorsque l'état de la diffusion est complete. La valeur est spécifiée au format ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ).
snippet.isDefaultBroadcast boolean
Cette propriété sera obsolète à compter du 1er septembre 2020. À cette date, YouTube cessera de créer un flux et une diffusion par défaut lorsqu'une chaîne est activée pour le streaming en direct. Pour en savoir plus, consultez l'annonce d'abandon.
Cette propriété indique si cette diffusion est la diffusion par défaut.

Fonctionnement des diffusions par défaut

Lorsque le streaming en direct est activé sur une chaîne YouTube, YouTube crée un flux et une diffusion par défaut pour la chaîne. Le flux définit la manière dont le propriétaire de la chaîne envoie des vidéos en direct à YouTube, et la diffusion permet aux spectateurs de voir la diffusion par défaut. Les propriétaires de chaîne peuvent identifier ces ressources à l'aide des méthodes liveStreams.list et liveBroadcasts.list.

Lorsqu'une chaîne commence à diffuser une vidéo en streaming sur son flux par défaut, elle est visible sur sa diffusion par défaut. À la fin de la diffusion, YouTube la convertit en vidéo YouTube et lui attribue un ID vidéo YouTube.

Une fois la conversion terminée, la vidéo est incluse dans la liste des vidéos mises en ligne par la chaîne. La vidéo n'est pas disponible immédiatement après la fin de la diffusion, et la durée du décalage dépend de la durée réelle de la diffusion.
snippet.liveChatId string
ID du chat en direct YouTube de la diffusion. Avec cet ID, vous pouvez utiliser les méthodes de la ressource liveChatMessage pour récupérer, insérer ou supprimer des messages de chat. Vous pouvez également ajouter ou supprimer des modérateurs de chat, interdire à des utilisateurs de participer au chat en direct ou annuler des exclusions existantes.
status object
L'objet status contient des informations sur l'état de l'événement.
status.lifeCycleStatus string
État de l'annonce. L'état peut être mis à jour à l'aide de la méthode liveBroadcasts.transition de l'API.

Les valeurs valides pour cette propriété sont les suivantes :
  • complete : la diffusion est terminée.
  • created : la diffusion présente des paramètres incomplets. Elle n'est donc pas prête à passer à l'état live ou testing, mais elle a été créée et est valide pour d'autres raisons.
  • live : la diffusion est active.
  • liveStarting : la diffusion est en cours de transition vers l'état live.
  • ready : les paramètres de diffusion sont finalisés, et la diffusion peut passer à l'état live ou testing.
  • revoked : cette diffusion a été supprimée par une action de l'administrateur.
  • testStarting : la diffusion est en cours de transition vers l'état testing.
  • testing : seul le partenaire peut voir la diffusion.
status.privacyStatus string
État de confidentialité de la diffusion. Notez que la diffusion ne représente qu'une seule vidéo YouTube. Par conséquent, les paramètres de confidentialité sont identiques à ceux acceptés pour les vidéos. Vous pouvez également définir ce champ en modifiant la ressource de diffusion ou en définissant le champ privacyStatus de la ressource vidéo correspondante.

Les valeurs valides pour cette propriété sont les suivantes :
  • private
  • public
  • unlisted
status.recordingStatus string
État d'enregistrement de la diffusion.

Les valeurs valides pour cette propriété sont les suivantes :
  • notRecording
  • recorded
  • recording
status.madeForKids boolean
Cette valeur indique si la diffusion est destinée aux enfants. Cette valeur de propriété est en lecture seule.
status.selfDeclaredMadeForKids boolean
Dans une demande liveBroadcasts.insert, cette propriété permet au propriétaire de la chaîne d'indiquer que la diffusion est destinée aux enfants. Dans une requête liveBroadcasts.list, la valeur de propriété n'est renvoyée que si le propriétaire de la chaîne a autorisé la requête API.
contentDetails object
L'objet contentDetails contient des informations sur le contenu vidéo de l'événement, par exemple si celui-ci peut être affiché dans un lecteur vidéo intégré ou s'il sera archivé et donc disponible une fois l'événement terminé.
contentDetails.boundStreamId string
Cette valeur identifie de manière unique la live stream liée à la diffusion.
contentDetails.boundStreamLastUpdateTimeMs datetime
Date et heure de la dernière mise à jour de la diffusion en direct référencée par boundStreamId.
contentDetails.monitorStream object
L'objet monitorStream contient des informations sur le flux de surveillance, que le diffuseur peut utiliser pour examiner le contenu de l'événement avant que le flux de diffusion ne soit diffusé publiquement.
contentDetails.monitorStream.enableMonitorStream boolean
Cette valeur détermine si le flux de surveillance est activé pour la diffusion. Si le flux de surveillance est activé, YouTube diffuse le contenu de l'événement dans un flux spécial réservé à l'usage du diffuseur. Le diffuseur peut utiliser le flux pour examiner le contenu de l'événement et identifier les meilleurs moments pour insérer des points de repère.

Définissez cette valeur sur true si vous prévoyez de définir une étape de testing pour votre diffusion ou de définir un délai de diffusion pour votre événement. En outre, si la valeur de cette propriété est true, vous devez faire passer votre annonce à l'état testing avant de pouvoir la faire passer à l'état live. Si la valeur de la propriété est false, votre diffusion ne peut pas avoir d'étape testing. Vous pouvez donc la faire passer directement à l'état live.

Lorsque vous exécutez la commande update a broadcast, cette propriété doit être définie si votre requête API inclut la partie contentDetails dans la valeur du paramètre part. Toutefois, lorsque vous insert a broadcast, la propriété est facultative et a la valeur par défaut true.

Important:Cette propriété ne peut pas être mise à jour une fois que l'état de la diffusion est testing ou live.
contentDetails.monitorStream.broadcastStreamDelayMs unsigned integer
Si vous avez défini la propriété enableMonitorStream sur true, cette propriété détermine la durée du délai de diffusion en direct.

Lorsque vous exécutez la commande update a broadcast, cette propriété doit être définie si votre requête API inclut la partie contentDetails dans la valeur du paramètre part. Toutefois, lorsque vous insert a broadcast, la propriété est facultative et a la valeur par défaut 0. Cette valeur indique que la diffusion ne présente pas de délai de diffusion. Remarque:Cette propriété ne peut pas être mise à jour une fois que l'état de la diffusion est testing ou live.
contentDetails.monitorStream.embedHtml string
Code HTML qui intègre un lecteur qui lit le flux de surveillance.
contentDetails.enableEmbed boolean
Ce paramètre indique si la vidéo diffusée peut être lue dans un lecteur intégré. Si vous choisissez d'archiver la vidéo (à l'aide de la propriété enableArchive), ce paramètre s'applique également à la vidéo archivée.

Lorsque vous exécutez la commande update a broadcast, cette propriété doit être définie si votre requête API inclut la partie contentDetails dans la valeur du paramètre part. Toutefois, lorsque vous insert a broadcast, la propriété est facultative et a la valeur par défaut true.

Remarque:Cette propriété ne peut pas être mise à jour une fois que l'état de la diffusion est testing ou live.
contentDetails.enableDvr boolean
Ce paramètre détermine si les spectateurs peuvent accéder aux commandes de l'enregistreur DVR pendant qu'ils regardent la vidéo. Les commandes de l'enregistreur numérique vidéo (DVR) permettent aux utilisateurs de contrôler l'expérience de lecture des vidéos en les mettant en pause, en faisant un retour arrière ou en utilisant une avance rapide. La valeur par défaut de cette propriété est true.

Lorsque vous exécutez la commande update a broadcast, cette propriété doit être définie si votre requête API inclut la partie contentDetails dans la valeur du paramètre part. Toutefois, lorsque vous insert a broadcast, la propriété est facultative et a la valeur par défaut true.

Important:Vous devez définir la valeur sur true et la valeur de la propriété enableArchive sur true si vous souhaitez que la lecture soit disponible immédiatement après la fin de la diffusion. De plus, cette propriété ne peut pas être mise à jour une fois que la diffusion est à l'état testing ou live.
contentDetails.recordFromStart boolean
Ce paramètre indique si YouTube lancera automatiquement l'enregistrement de la diffusion une fois que l'état de l'événement passera à "En direct".

La valeur par défaut de cette propriété est true. Elle ne peut être définie sur false que si la chaîne de diffusion est autorisée à désactiver les enregistrements pour les diffusions en direct.

Si votre chaîne n'est pas autorisée à désactiver les enregistrements et que vous tentez d'insérer une diffusion avec la propriété recordFromStart définie sur false, l'API renverra une erreur Forbidden. De plus, si votre chaîne ne dispose pas de cette autorisation et que vous essayez de mettre à jour une diffusion pour définir la propriété recordFromStart sur false, l'API renvoie une erreur modificationNotAllowed.

Lorsque vous exécutez la commande update a broadcast, cette propriété doit être définie si votre requête API inclut la partie contentDetails dans la valeur du paramètre part. Toutefois, lorsque vous insert a broadcast, la propriété est facultative et a la valeur par défaut true.

Important:Vous devez également définir la valeur de la propriété enableDvr sur true si vous souhaitez que la lecture soit disponible immédiatement après la fin de la diffusion. Si vous définissez la valeur de cette propriété sur true, mais pas la propriété enableDvr sur true, il peut s'écouler environ un jour avant que la vidéo archivée ne soit disponible pour la lecture.

Remarque:Cette propriété ne peut pas être mise à jour une fois que l'état de la diffusion est testing ou live.
contentDetails.enableClosedCaptions boolean
Cette propriété est obsolète depuis le 17 décembre 2015. Utilisez plutôt la propriété contentDetails.closedCaptionsType.

Ce paramètre indique si le sous-titrage HTTP POST est activé pour cette diffusion. Pour les clients API qui utilisent déjà cette propriété:
  • Définir la valeur de la propriété sur true équivaut à définir la propriété contentDetails.closedCaptionsType sur closedCaptionsHttpPost.
  • Définir la valeur de la propriété sur false équivaut à définir la propriété contentDetails.closedCaptionsType sur closedCaptionsDisabled.
contentDetails.closedCaptionsType string
Remarque: Cette propriété remplace la propriété contentDetails.enableClosedCaptions.

Elle indique si le sous-titrage est activé pour votre diffusion et, le cas échéant, le type de sous-titres que vous fournissez:
  • closedCaptionsDisabled: les sous-titres sont désactivés pour la diffusion en direct.
  • closedCaptionsHttpPost: vous envoyez les sous-titres via HTTP POST à une URL d'ingestion associée à votre diffusion en direct.
  • closedCaptionsEmbedded: les sous-titres seront encodés dans le flux vidéo aux formats EIA-608 et/ou CEA-708.
contentDetails.projection string
Format de projection de cette diffusion. La valeur par défaut de cette propriété est rectangular.

Les valeurs valides pour cette propriété sont les suivantes :
  • 360
  • rectangular
contentDetails.enableLowLatency boolean
Indique si cette diffusion doit être encodée pour le streaming à faible latence. Un flux à faible latence permet de réduire la durée nécessaire pour que la vidéo soit visible par les utilisateurs qui regardent une diffusion, mais cela peut également avoir un impact sur la résolution pour les spectateurs.
contentDetails.latencyPreference string
Indique le paramètre de latence à utiliser pour cette diffusion. Cette propriété peut être utilisée à la place de enableLowLatency, qui n'est pas compatible avec ultraLow.

Un flux à faible latence peut réduire le temps nécessaire pour que la vidéo soit visible pour les utilisateurs qui regardent une diffusion, mais cela peut également affecter la fluidité de la lecture.

Un flux de propriété à très faible latence réduit encore plus le temps nécessaire pour que la vidéo soit visible par les spectateurs, ce qui facilite les interactions avec les spectateurs, mais la latence ultra-faible et 0 n'est pas compatible avec les valeurs de sous-titres plus élevées.

  • normal
  • low
  • ultraLow
contentDetails.enableAutoStart boolean
Indique si cette diffusion doit démarrer automatiquement lorsque vous lancez la diffusion d'une vidéo en streaming sur l'élément live stream lié.
contentDetails.enableAutoStop boolean
Indique si la diffusion doit s'arrêter automatiquement environ une minute après que le propriétaire de la chaîne a arrêté de diffuser la vidéo dans le flux vidéo associé.
statistics object
L'objet statistics contient des statistiques sur une diffusion en direct. Les valeurs de ces statistiques peuvent changer pendant la diffusion et ne peuvent être récupérées que pendant la diffusion.
statistics.totalChatCount unsigned long
Nombre total de messages de chat en direct associés à la diffusion. La propriété et sa valeur sont présentes si la diffusion est visible par l'utilisateur, si la fonctionnalité de chat en direct est activée et si elle contient au moins un message. Notez que cette propriété ne spécifie aucune valeur après la fin de la diffusion. Ainsi, cette propriété n'identifie pas le nombre de messages de chat d'une vidéo archivée d'une diffusion en direct terminée.
monetizationDetails object
L'objet monetizationDetails contient des informations sur les détails de monétisation du flux, par exemple si l'outil de création automatique des annonces est activé ou si l'insertion des annonces mid-roll est retardée.

monetizationDetails.cuepointSchedule object
L'objet cuepointSchedule spécifie les paramètres d'automatisation des annonces pour la diffusion.
monetizationDetails.cuepointSchedule.enabled boolean
Cette valeur détermine si les annonces sont automatiquement insérées lors de la diffusion. Si la valeur est true, YouTube insère automatiquement des annonces mid-roll dans la diffusion. Le calendrier de diffusion des annonces sera déterminé par la valeur des autres champs de l'objet monetizationDetails.cuepointSchedule.
monetizationDetails.cuepointSchedule.pauseAdsUntil datetime
Cette valeur indique que YouTube ne doit pas insérer d'annonces mid-roll dans la diffusion avant la date et l'heure spécifiées. La valeur est spécifiée au format ISO 8601 (AAAA-MM-JJThh:mm:ss.sZ). La valeur doit être définie sur une date/heure future pour mettre en veille les annonces. La valeur du champ peut également être définie sur une date/heure à venir afin de réactiver les annonces une fois le temps écoulé.
monetizationDetails.cuepointSchedule.scheduleStrategy string
Cette valeur spécifie la stratégie que YouTube doit suivre pour planifier les points de repère. Les valeurs possibles sont les suivantes :
  • CONCURRENT: les points de repère sont planifiés à la même heure pour tous les spectateurs
  • NON_CONCURRENT: les points de repère sont planifiés à différents moments en fonction des spectateurs. Cette approche permet de diffuser les annonces à un taux accru, ce qui permet aux spectateurs de recevoir des points de repère lorsqu'ils sont éligibles.
monetizationDetails.cuepointSchedule.repeatIntervalSecs unsigned integer
Cette valeur spécifie l'intervalle, en secondes, entre l'insertion automatique d'annonces lors d'une diffusion. Par exemple, si la valeur est 300, YouTube peut insérer des points de repère pour les annonces vidéo mid-roll à des intervalles de cinq minutes.

Notez que cette valeur spécifie le délai entre le début des points de repère successifs. Autrement dit, l'intervalle n'est pas mesuré entre la fin d'un point de repère et le début du suivant.