Overview: Brightcove Live API

Product(s)
Live
Role(s)
API Developer
Topic(s)
ID3
Live Streaming
API(s)
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

All requests are authenticated using an API key that will be provided to you when your account is set up. 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 SEP Job Limit
Oregon us-west-2 Yes 10
Virginia us-east-1 Yes 3
Tokyo ap-northeast-1 Yes 3
Singapore ap-southeast-1 Yes 3
Sydney ap-southeast-2 Yes 3
Mumbai ap-south-1 Yes 3
Frankfurt eu-central-1 Yes 3
Ireland eu-west-1 No 3

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 account manager for more information on the offerings.

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 24 hours 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.

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.

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.

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

To insert ID3 timed metadata for an ongoing job, make a POST request to:

https://api.bcovlive.io/v1/jobs/JOB_ID/id3tag

Sample request body

{
"id3_tag": {
"name": "BCOV",
"value": "my value",
"timecode": "15:50:49:16"
}
}

Notes:

  • ID3v2 states tag name can be up to 4 characters
  • value can be up to 256KB
  • timecode is optional - when omitted, insertion will be immediate

Sample response

{
"id": "JOB_ID",
"id3_tag": {
"tag_name": "BCOV",
"tag_value": "my value"
}
}

Limitations

  • Live jobs created using the API will not appear and cannot be used in the Live Module.
  • 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 account 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 RMTP 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, the segment_size and keyframe_interval should be avoided on any of the outputs to ensure segments and keyframes follow the input GOP structure. If not, the system will return an error in the job creation request.
  • 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 CDN’s provided in the job request.