Overview: Brightcove Live API

In this overview, you will learn what the Live API is for and how to use it. Topics included in this document include supported AWS regions and CDNs, live channels and events, and inserting ID3 timed metadata into a live stream.

Introduction

The Live API is a REST-based API that allows you to create and manage live streaming events. Optional features include:

  • Server-side ad insertion ( SSAI )
  • AES-128 encryption
  • Create video-on-demand assets from clips taken from the live stream
  • DVR capability
  • Multiple CDNs

Also see the API Reference.

Base URL

The base URL for the Live API is:

https://api.bcovlive.io

Headers

When making a request to the Live API, you will need to authenticate using an API key. To get the Live API key, open a customer support ticket. The key is passed in an X-API-KEY header. A Content-Type header is also required:

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

Supported AWS regions

The following AWS regions are supported:

Supported AWS Regions
Location AWS Name SSAI Support
Oregon us-west-2
Virginia us-east-1
Tokyo ap-northeast-1
Singapore ap-southeast-1
Seoul ap-northeast-2
Sydney ap-southeast-2
Mumbai ap-south-1
Frankfurt eu-central-1
Ireland eu-west-1

Note that SEP jobs are limited by account where the standard limit is 3 except for the us-west-2: its limitation is up to 10. All limitations are set by account and not by region.

Supported CDNs

The following CDNs are supported for live streaming:

  • Akamai
  • Cloudfront

Other file-based CDNs should work, but have not been tested and are not actively supported.

Channels and event hours

There are two purchasing options for Live:

  • Purchase event hours of streaming time
  • Purchase streaming channels

You may also purchase both event streaming hours and channels. Contact your Customer Success Manager for more information on the offerings.

Billable states

Billing for live jobs applies to Active states:

Active states (billing applies)

  • waiting
  • processing
  • disconnected

Inactive states (billing does not apply)

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

Token authentication

Brightcove offers the option of adding token authentication to live video stream playback URLs. If you would like to add token authentication, Contact Brightcove Support. It may take up to three days for token authentication to be set up.

The TTL (time-to-live) for the tokens can be set to any value from one hour to 365 days. How long you set the TTL will depend on what kinds of live streams you deploy. Be aware that the TTL is an account-wide setting, however, and will apply to all live streams.

DVR capability

Brightcove Live streams have DVR capability. To use this capability, you must:

  • Use the playback_url_dvr URL for playback
  • Use a player that has DVR capability

DVR capability is limited to 86,400 seconds.

The DVR stream will remain available for 7 days after the live stream is completed.

Endpoints and operations

The main operations for the Live API are creating and managing live streams, and generate VOD clips from live streams. These operations are carried out through requests to following endpoints, which are explained in more detail in the remainder of the document.

Creating and managing jobs

Creating clips

Managing SSAI

Creating and managing jobs

These operations allow you to create a live job, get the details of it, and stop it. There is also an endpoint to create an immediate cue point for an ad break.

Create a Live Job

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

This endpoint is used to create live streams via a POST request. In addition to specifying properties of the live stream itself, the request can also specify VOD clips to be generated from the live stream (this can also be done later via the endpoint). Details of the fields that can be included in the request body are given in the API Reference.

Input protocol

Brightcove Live supports multiple input protocols. Use the protocol field in the request body when you create the job to specify the one you will use. Supported values are:

  • rtmp (the default)
  • rtp
  • rtp-fec
  • srt

The RTMP protocol is for delivery a stream in FLV format. The other protocols are for delivering MPEG2-TS.

If you use rtp, rtp-fec or srt, you must also specify a cidr_whitelist (see Classless Inter-Domain Routing).

If you use rtmp, you can specify an ip_whitelist for the input instead, but this is not required.

Example request body for RTP+FEC job:

{
    "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"]
}

The Live API Quick Start walks you through creating a live stream job and setting up a Brightcove Player to play it.

List Live Jobs

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

This endpoint is used to list your live streams via a GET request. The endpoint supports pagination, sorting, and search filtering. Details of the fields that can be included in the request body are given in the API Reference and some additional information can be found in Getting a List of Live or VOD Jobs.

Get Live Job Details

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

This endpoint allows you to get the detailed information about a live stream, which is also returned when you originally create the job. See the API Reference for details of the response fields.

Manual Ad Cue Point Insertion

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

Typically your encoder will be sending cue points for ad breaks, but you can also create an immediate ad break by sending a request to this endpoint. See the API Reference for details.

Note that a timecode in the form DD:HH:MM:SS is required for the cue point.

Stop a Live Job

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

Use this endpoint to stop a live stream immediately. Once cancelled, a live stream cannot be restarted. See the API Reference for details.

Creating clips

You can create video-on-demand clips from a live stream and store them in a Video Cloud account, or send them to S3 bucket or FTP address. You can define the clips when you create the live stream, or create them later using the endpoint described below. Also see the Creating Clips guide.

When creating clips, the highest quality rendition from the selected Live Ingest Profile is used as the source for the clip. The default uploading ingest profile for the account is used when creating renditions for the clip.

Create VOD Clip

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

The start and end points for the clips can be defined in terms of offsets from the start of the stream or UNIX timestamps. Details of the request body fields can be found in the API Reference.

Get a list of VOD (clip) jobs

To get a list of your VOD jobs for clips, see Getting a List of Live or VOD Jobs and the API Reference.

Managing SSAI

Using server-side ad insertion ( SSAI), you can insert as many ad breaks as you like into your live stream. You can also ingest slate assets (VOD clips) to fill any unused ad time with a be-right-back message or whatever you like.

More details of setting up SSAI can be found in Server-Side Ad Insertion Using the Brightcove Live API and the API Reference.

Get Account Ad Configurations

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

This endpoint allows you to get all ad configurations that have been set up for an account. Details of the response fields can be found in the API Reference.

Create Ad Configuration

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

Create an ad configuration that defines how ads will be retrieved for SSAI. Details of the request body fields can be found in the API Reference.

Get Ad Configuration

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

Use this endpoint to get the details of an ad configuration you have created. Details of the response fields can be found in the API Reference.

Update Ad Configuration

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

Update the details of an ad configuration. Details of the request body fields can be found in the API Reference.

Get Slate Media Source Assets

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

Get the slate media assets that have been defined for an account. Slate media assets are used to fill ad break time that is not filled by ads. Details of the response fields can be found in the API Reference.

Ingest Slate Media Source Asset

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

Add a media asset for slates to fill unfilled ad break time. Details of the request body fields can be found in the API Reference.

Delete Slate Media Source Asset

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

Deletes a slate media asset.

Static entry points

The Static Entry Points (SEP) feature allows for a long-running live job that can be activated and deactivated while keeping the entry point URLs and playback URLs static and re-usable. This feature allows for customers to configure their encoder in their facilities or the field and allows the customer to create their own scheduling logic for live channels or programs. See Static Entry Points for details.

There is also scheduler that allows you to schedule the activation and/or deactivation of SEP jobs. See Overview: Live Scheduler.

Captions

If captions are inside the h264 input signal (correctly signaled in the user_data packet) those are passed through to the h264 outputs.

If you are using a broadcast Elemental live encoder you can get captions from SDI (EIA-608/CEA-608) or other sources (SCTE-20, SCC, Teletext, DVB-Sub, Ancillary, ARIB, TTML, SCTE-27, STL, SRT, SMI) and put them into the h264 stream that you send to us. Other broadcast grade encoders probably can do the same, but we have not formally tested them.

Insert ID3 timed metadata

This information has been moved to Insert ID3 timed metadata.

Limitations

  • In order for Live jobs created using the API to appear and cannot be used in the Live Module, You must include the videocloud object in the request body when you create the job.

    For example:

    {
  "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" }
    }
  }
  • The initial connection from encoder provides the bandwidth information to be created with the Live playlist. If the initial connection is low, even if the job configuration had high output, the playlist will still maintain the same information on the playlist until the following is done:
    • Encoder is restarted
    • The CDN cache may also need to be cleared
  • Currently the framerate for input streams is limited to 30 FPS. If you are interested in using a higher frame rate, please contact Support.
  • By default the resolution of the input stream is limited to 1080p.
  • When disconnecting and reconnecting, the stream settings must stay the same. Any changes to the number of audio channels, resolutions, or codec settings will result in unpredictable behavior.
  • Although you can add DASH and MP4 for remote sources for Video Cloud videos, Live currently supports HLS only.
  • Only AAC audio is supported for input streams.
  • A maximum of 5 active waiting, unstarted jobs is allowed at any time.

    Additional limitations on concurrent jobs:

    • The number of channel (24x7) jobs is limited to 0 or a low number per region (depending on the account type).
    • The number of concurrently running event jobs is limited by region, generally to 100.
    • The number of concurrently waiting to connect event jobs is limited to 5.
    • The number of SEP jobs per region is limited to 3 or 10 (see Supported AWS regions).

    Any of these limits can be adjusted on an account level by Support. Contact your Customer Success Manager if you need additional capacity.

  • The "RTMP" address returned as the stream_url for Live jobs is an Akamai HD Live stream, not a legacy FMS RTMP stream - it is not supported by older versions of Internet Explorer.
  • Live streams are delivered over HTTPS, and if your Brightcove account is not enabled for HTTPS, the Brightcove player will fail to load the live stream. If your account does not have HTTPS support for origin serving enabled, please Contact Brightcove Support to get HTTPS support for origin serving enabled to prevent playback issues.
  • When using a transmuxed rendition within a multi-bitrate HLS output, segment_size can be included when transmuxing, but should be set so that it is a multiple of the GOP size of the input stream. So if the input is 30 fps with keyframes every 60 frames, the GOP size is 2 seconds, and the segment size should be a multiple of 2. If you do not do this, the stream segments will be of varying sizes.

    Also, keyframe_interval should not be specified on any outputs.

  • When using your own FTP or S3 origin location, your CDN must be configured to fallback to your origin location. The Brightcove Live system will not validate that the origin locations for the CDNs provided in the job request.