Vue d'ensemble : API Live Brightcove

Dans cette vue d'ensemble, vous apprendrez à quoi sert l'API Live et comment l'utiliser. Les sujets inclus dans ce document incluent les régions et les CDN AWS pris en charge, les canaux et événements en direct, et l'insertion de métadonnées temporelles ID3 dans un flux en direct.

Introduction

L' Live API est une API basée sur REST qui vous permet de créer et de gérer des événements de streaming en direct. Les fonctionnalités optionnelles incluent :

  • Insertion de publicités côté serveur ( SSAI)
  • AES-128 cryptage
  • Créez des ressources de vidéo à la demande à partir de clips extraits du flux en direct
  • DVR capacité
  • Multiples CDNs

Voir aussi le Référence API.

URL de base

L'URL de base de l' Live API est :

https://api.bcovlive.io

Headers

Lorsque vous faites une demande à l'API Live, vous devez vous authentifier à l'aide d'une clé API. Pour obtenir la clé Live API, ouvrez un ticket de support client. La clé est passée dans un X-API-KEY entête. UNE Content-Type l'en-tête est également requis :

X-API-KEY : YOUR_APIKey
      Content-Type: application/json

Régions AWS prises en charge

Les régions AWS suivantes sont prises en charge :

Régions AWS prises en charge
Emplacement Nom AWS Soutien SSAI
Oregon us-west-2
Virginie us-east-1
Tokyo ap-northeast-1
Singapour ap-southeast-1
Sydney ap-southeast-2
Mumbai ap-south-1 <
Francfort eu-central-1
Irlande eu-west-1

Notez que les tâches SEP sont limitées par compte où la limite standard est de 3, sauf pour le us-west-2 : sa limite est de 10. Toutes les limitations sont définies par compte et non par région.

CDN pris en charge

Les CDN suivants sont pris en charge pour la diffusion en direct :

  • Akamai
  • Cloudfront

D'autres CDN basés sur des fichiers devraient fonctionner, mais n'ont pas été testés et ne sont pas activement pris en charge.

Chaînes et heures de l'événement

Il existe deux options d'achat pour Live :

  • Achetez des heures de diffusion en continu pour l'événement
  • Acheter des chaînes de streaming

Vous pouvez également acheter à la fois des heures de diffusion d'événements et des chaînes. Contactez votre Customer Success Manager pour plus d'informations sur les offres.

États facturables

La facturation des travaux en direct s'applique à Actif États:

États actifs (la facturation s'applique)

  • waiting
  • processing
  • disconnected

États inactifs (la facturation ne s'applique pas)

  • standby
  • cancelling
  • finishing
  • cancelled
  • finished
  • failed

Authentification par jeton

Brightcove offre la possibilité d'ajouter une authentification par jeton aux URL de lecture de flux vidéo en direct. Si vous souhaitez ajouter une authentification par jeton, Contacter l'assistance Brightcove. La configuration de l'authentification par jeton peut prendre jusqu'à trois jours.

Le TTL (durée de vie) des jetons peut être défini sur n'importe quelle valeur d'une heure à 365 jours. La durée pendant laquelle vous définissez la durée de vie dépendra des types de flux en direct que vous déployez. Sachez toutefois que la durée de vie est un paramètre à l'échelle du compte et s'appliquera à tous les flux en direct.

DVR capacité

Les flux Brightcove Live ont des DVR capacités. Pour utiliser cette fonctionnalité, vous devez :

  • Utilisez le playback_url_dvr URL de lecture
  • Utilisez un lecteur qui a DVR aptitude

La capacité du DVR est limitée à 86 400 secondes.

Le DVR flux restera disponible pendant 7 jours après la fin de la diffusion en direct.

Points de terminaison et opérations

Les principales opérations de Live API sont la création et la gestion de flux en direct, et générer des clips VOD à partir de flux en direct. Ces opérations sont effectuées via des requêtes aux points de terminaison suivants, qui sont expliqués plus en détail dans la suite du document.

Création et gestion d'emplois

Création de clips

Gestion de la SSAI

Création et gestion d'emplois

Ces opérations vous permettent de créer une tâche en direct, d'en obtenir les détails et de l'arrêter. Il existe également un point de terminaison pour créer un point de repère immédiat pour une pause publicitaire.

Créer un travail en direct

POST https://api.bcovlive.io/v1/jobs

Ce point de terminaison est utilisé pour créer des flux en direct via un POST demander. En plus de spécifier les propriétés du flux en direct lui-même, la demande peut également spécifier les clips VOD à générer à partir du flux en direct (cela peut également être fait plus tard via le point final). Les détails des champs qui peuvent être inclus dans le corps de la requête sont donnés dans le Référence API.

Protocole d'entrée

Brightcove Live prend en charge plusieurs protocoles d'entrée. Utilisez le protocol dans le corps de la demande lorsque vous créez le travail pour spécifier celui que vous utiliserez. Les valeurs prises en charge sont :

  • rtmp(valeur par défaut)
  • rtp
  • rtp-fec
  • srt

Le protocole RTMP permet de délivrer un flux au format FLV. Les autres protocoles sont destinés à fournir MPEG2-TS.

Si vous utilisez rtp, rtp-fec ou srt, vous devez également spécifier un cidr_whitelist(voir Routage interdomaine sans classe).

Si vous utilisez rtmp, vous pouvez spécifier un ip_whitelist pour l'entrée à la place, mais cela n'est pas obligatoire.

Exemple de corps de requête pour le travail RTP+FEC :

{
    "live_stream":true,
    "region":"us-west-2",
    "reconnect_time":300,
    "outputs":[
      {
        "label": "hls720p",
        "live_stream": true,
        "height": 720,
        "video_bitrate": 800,
        "segment_seconds": 6,
        "keyframe_interval": 90
      }
    ],
    "protocol": "rtp-fec",
    "cidr_whitelist": ["127.0.0.1/32"]
}

Le Live API Quick Start vous guide à travers la création d'une tâche en direct et la configuration d'un lecteur Brightcove pour y jouer.

Répertorier les emplois en direct

GET https://api.bcovlive.io/v1/jobs

Ce point de terminaison est utilisé pour répertorier vos diffusions en direct via un GET demander. Le point de terminaison prend en charge la pagination, le tri et le filtrage de recherche. Les détails des champs qui peuvent être inclus dans le corps de la requête sont donnés dans le Référence API et quelques informations supplémentaires peuvent être trouvées dans Obtenir une liste de travaux en direct ou en VOD.

Obtenez les détails du travail en direct

GET https://api.bcovlive.io/v1/jobs/:jobId

Ce point de terminaison vous permet d'obtenir des informations détaillées sur un flux en direct, qui sont également renvoyées lors de la création initiale du travail. Voir le Référence API pour plus de détails sur les champs de réponse.

Insertion manuelle de point de repère publicitaire

POST https://api.bcovlive.io/v1/jobs/:jobId/cuepoint

En règle générale, votre encodeur enverra des points de repère pour les coupures publicitaires, mais vous pouvez également créer une coupure publicitaire immédiate en envoyant une demande à ce point de terminaison. Voir le Référence API pour les détails.

Notez qu'un timecode sous la forme DD:HH:MM:SS est requis pour le point de repère.

Arrêter un travail en direct

PUT https://api.bcovlive.io/v1/jobs/:jobId/cancel

Utilisez ce point de terminaison pour arrêter immédiatement une diffusion en direct. Une fois annulé, un flux en direct ne peut pas être redémarré. Voir le Référence API pour les détails.

Création de clips

Vous pouvez créer des clips vidéo à la demande à partir d'un flux en direct et les stocker dans un compte Video Cloud, ou les envoyer vers un compartiment S3 ou une adresse FTP. Vous pouvez définir les clips lorsque vous créez le flux en direct, ou les créer plus tard à l'aide du point de terminaison décrit ci-dessous. Voir aussi le Création d'extraits guider.

Créer un clip VOD

POST https://api.bcovlive.io/v1/vods

Les points de début et de fin des clips peuvent être définis en termes de décalages par rapport au début du flux ou d'horodatages UNIX. Les détails des champs du corps de la requête peuvent être trouvés dans le Référence API.

Obtenez une liste des travaux de VOD (clip)

Pour obtenir une liste de vos tâches VOD pour les clips, consultez Obtenir une liste de travaux en direct ou en VOD et le Référence API.

Gestion SSAI

À l'aide de l'insertion d'annonces côté serveur ( SSAI), vous pouvez insérer autant de pauses publicitaires que vous le souhaitez dans votre diffusion en direct. Vous pouvez également ingérer des actifs d'ardoise (clips VOD) pour remplir tout temps publicitaire inutilisé avec un message de retour ou tout ce que vous voulez.

SSAI Vous trouverez plus de détails sur la configuration dans Insertion d'annonces côté serveur à l'aide de Brightcove Live API et de l' API Reference.

Obtenir les configurations d'annonces de compte

GET https://api.bcovlive.io/v1/ssai/applications/:account_id

Ce point de terminaison vous permet d'obtenir toutes les configurations d'annonces qui ont été configurées pour un compte. Les détails des champs de réponse peuvent être trouvés dans le Référence API.

Créer une configuration d'annonce

POST https://api.bcovlive.io/v1/ssai/application

Créez une configuration d'annonce qui définit la manière dont les annonces seront récupérées SSAI. Les détails des champs du corps de la requête peuvent être trouvés dans le Référence API.

Obtenir la configuration de l'annonce

GET https://api.bcovlive.io/v1/ssai/application/:application_id

Utilisez ce point de terminaison pour obtenir les détails d'une configuration d'annonce que vous avez créée. Les détails des champs de réponse peuvent être trouvés dans le Référence API.

Mettre à jour la configuration des annonces

PUT https://api.bcovlive.io/v1/ssai/application/account/:application_id

Mettez à jour les détails d'une configuration d'annonce. Les détails des champs du corps de la requête peuvent être trouvés dans le Référence API.

Obtenir des ressources Slate Media Source

GET https://api.bcovlive.io/v1/ssai/slates/:ACCOUNT_ID

Obtenez les ressources multimédias de l'ardoise qui ont été définies pour un compte. Les éléments multimédias Slate sont utilisés pour remplir le temps de pause publicitaire qui n'est pas rempli par les publicités. Les détails des champs de réponse peuvent être trouvés dans le Référence API.

Ingérer l'actif de la source multimédia Slate

POST https://api.bcovlive.io/v1/ssai/slates

Ajoutez un élément multimédia pour les ardoises afin de remplir le temps de pause publicitaire non rempli. Les détails des champs du corps de la requête peuvent être trouvés dans le Référence API.

Supprimer l'actif de la source multimédia Slate

DELETE https://api.bcovlive.io/v1/ssai/slates/:SLATE_MSA_ID

Supprime un élément multimédia d'ardoise.

Points d'entrée statiques

La fonction Static Entry Points (SEP) permet une tâche en direct de longue durée qui peut être activée et désactivée tout en gardant les URL de point d'entrée et les URL de lecture statiques et réutilisables. Cette fonctionnalité permet aux clients de configurer leur encodeur dans leurs installations ou sur le terrain et permet au client de créer sa propre logique de programmation pour les chaînes ou les programmes en direct. Voir Points d'entrée statiques pour les détails.

Il existe également un planificateur qui vous permet de programmer l'activation et/ou la désactivation des tâches SEP. Voir la vue d'ensemble : Planificateur en direct.

Légendes

Si des légendes se trouvent dans le signal d'entrée h264 (correctement signalées dans le paquet user_data), elles sont transmises aux sorties h264.

Si vous utilisez un encodeur en direct Elemental de diffusion, vous pouvez obtenir des sous-titres de SDI (EIA-608/CEA-608) ou d'autres sources (SCTE-20, SCC, Teletext, DVB-Sub, Ancillary, ARIB, TTML, SCTE-27, STL, SRT, SMI) et les mettre dans le flux h264 que vous nous envoyez. D'autres encodeurs de qualité diffusion peuvent probablement faire la même chose, mais nous ne les avons pas testés formellement.

Insérer des métadonnées programmées ID3

Ces informations ont été déplacées vers Insérer des métadonnées temporelles ID3.

Contraintes

  • Pour que les tâches en direct créées à l'aide de l'API apparaissent et ne puissent pas être utilisées dans le module Live, vous devez inclure l' videocloud objet dans le corps de la demande lorsque vous créez la tâche.

    Par exemple :

    {
  "live_stream": true,
  "region": "eu-central-1",
  "reconnect_time": 1800,
  "live_sliding_window_duration_ms": 0,
  "outputs": [
    { "label": "hls720p", "live_stream": true, "width": 1280, "height": 720, "video_codec": "h264", "h264_profile": "high", "video_bitrate": 2100, "segment_seconds": 4, "keyframe_interval": 60 }
    ,
    { "label": "hls540p", "live_stream": true, "width": 960, "height": 540, "video_codec": "h264", "h264_profile": "main", "video_bitrate": 1500, "segment_seconds": 4, "keyframe_interval": 60 }
    ,
    { "label": "hls360p", "live_stream": true, "width": 640, "height": 360, "video_codec": "h264", "h264_profile": "main", "video_bitrate": 800, "segment_seconds": 4, "keyframe_interval": 60 }
  ],
  "videocloud": {
    "video":
      { "name": "live event UI", "description": "live event UI", "long_description": "", "tags": [], "reference_id": "", "state": "ACTIVE" }
    }
  }
  • La connexion initiale de l'encodeur fournit les informations de bande passante à créer avec la liste de lecture Live. Si la connexion initiale est faible, même si la configuration du travail avait un rendement élevé, la liste de lecture conservera toujours les mêmes informations sur la liste de lecture jusqu'à ce que les étapes suivantes soient effectuées :
    • L'encodeur est redémarré
    • Le cache CDN peut également avoir besoin d'être vidé
  • Actuellement, le framerate pour les flux d'entrée est limité à 30 FPS. Si vous souhaitez utiliser une fréquence d'images plus élevée, veuillez contacter le support.
  • Par défaut, la résolution du flux d'entrée est limitée à 1080p.
  • Lors de la déconnexion et de la reconnexion, les paramètres du flux doivent rester inchangent. Toute modification du nombre de canaux audio, de résolutions ou de paramètres de codec entraînera un comportement imprévisible.
  • Bien que vous puissiez ajouter DASH et MP4 pour les sources distantes pour les vidéos Video Cloud, Live prend actuellement en charge HLS uniquement.
  • Seul l'audio AAC est pris en charge pour les flux d'entrée.
  • Un maximum de 5 actifs en attente, non commencé les travaux sont autorisés à tout moment.

    Limitations supplémentaires sur les tâches simultanées :

    • Le nombre de channel (24x7) jobs est limité à 0 ou à un petit nombre par région (selon le type de compte).
    • Le nombre de simultanément fonctionnement event emplois est limité par région, généralement à 100.
    • Le nombre de simultanément en attente de connexion event les emplois sont limités à 5.
    • Le nombre d'emplois SEP par région est limité à 3 ou 10 (voir Régions AWS prises en charge).

    Chacune de ces limites peut être ajustée au niveau du compte par l'assistance. Contactez votre Customer Success Manager si vous avez besoin d'une capacité supplémentaire.

  • L'adresse « RTMP » renvoyée stream_url pour les tâches Live est un flux Akamai HD Live, et non un flux RTMP FMS existant. Elle n'est pas prise en charge par les anciennes versions d'Internet Explorer.
  • Les flux en direct sont diffusés via HTTPS, et si votre compte Brightcove n'est pas activé pour HTTPS, le lecteur Brightcove ne parviendra pas à charger le flux en direct. Si votre compte n'a pas activé la prise en charge HTTPS pour la diffusion d'origine, veuillez Contacter l'assistance Brightcove pour que la prise en charge HTTPS pour la diffusion d'origine soit activée afin d'éviter les problèmes de lecture.
  • Lors de l'utilisation d'un rendu transmuxé dans une sortie HLS à plusieurs débits, segment_size peut être inclus lors du transmuxage, mais doit être réglé de manière à ce qu'il soit un multiple du GOP taille du flux d'entrée. Donc, si l'entrée est de 30 ips avec des images clés toutes les 60 images, le GOP la taille est de 2 secondes et la taille du segment doit être un multiple de 2. Si vous ne le faites pas, les segments de flux seront de tailles différentes.

    Aussi, keyframe_interval devrait ne pas être spécifié sur toutes les sorties.

  • Lorsque vous utilisez votre propre emplacement d'origine FTP ou S3, votre CDN doit être configuré pour revenir à votre emplacement d'origine. Le système Brightcove Live ne validera pas les emplacements d'origine des CDN fournis dans la demande de travail.