Overview: Dynamic Ingest API

In this topic, you will learn how to use the Dynamic Ingest API to upload and manage video content.

API functionality

Brightcove's Dynamic Ingest (DI) API is based on functionality where video source files are downloaded from the customer's storage location and specified renditions of the source files are created. (There is also an option to upload your source files to a temporary location where Dynamic Ingest can access them.) The platform is cloud-centric, globally-distributed and based on modern practices to deliver best in class consistency and speed.

Advantages of Dynamic Ingest

Strengths of the DI API are:

  • Predictability: Queue time and end-to-end processing time is determinate.
  • Speed: Brightcove's transcoding solution provides superior speed and scalability.
  • Features: Input format support, 99.9% transcoding success rate and a simplified usage workflow are just a few of the API's advantages.
  • Insight: Notifications when videos are available for playback are provided.

Workflow overview

A number of systems/technologies are used in the overall transcoding and storage of media. They are:

  • Content Management System (CMS) API: Creates a video object for use in the DI API
  • Zencoder: Transcodes the video creating multiple renditions
  • Amazon S3: Moves the master and renditions to storage, based on profile settings
  • Catalog: Stores requisite information associated with the video

After initial transcoding, you have the following actions you can perform on the media:

  • Re-transcode: Create new renditions when master is present (error if master is not present)
  • Replace: Point to a new master, or replace an existing master

Operations

When you use the DI API you will perform different operations, such as reading an ingest profile and writing ingest information to your account. The following is a complete list of operations required for DI tasks:

  • video-cloud/video/create
  • video-cloud/video/read
  • video-cloud/video/update
  • video-cloud/ingest-profiles/profile/read
  • video-cloud/ingest-profiles/account/read
  • video-cloud/ingest-profiles/account/write
  • video-cloud/ingest-profiles/profile/write

To obtain client credentials, use the Studio admin tools or see one of the following documents:

Valid source locations

Dynamic Ingest can pull source video files from: HTTP/HTTPS or S3 - with or without authentication

Examples:

  • http://example.com/path/to/input.avi
  • https://dl.dropboxusercontent.com/u/3641457/Bird_Titmouse.mp4
  • s3://my-bucket/video.mp4

Notes on S3

If your videos are in a protected S3 bucket, see Using Dynamic Ingest with S3 for details on how to set up permissions for Dynamic Ingest to access your files.

The advantages of using pull-based ingest include a simpler workflow and having a repository of your own digital masters. If this is not an option for you, however, you can also use Source File Upload to upload your videos and other assets to a temporary location from which Dynamic Ingest can access them.

Source file names

To avoid issues in accessing videos and assets in the Brightcove Player, you should avoid using any special characters in source file names, whether videos, images, or text tracks (WebVTT files). This also applies to remote assets. File names should only include the following:

  • Letters (upper or lower case)
  • Numbers
  • Dashes (-) and underscores (_)
  • Spaces

Ingesting videos

There are two API calls required for ingesting videos:

  1. Call the CMS API to create a video object in the Video Cloud system and get its id
  2. Call the DI API to provide the URL for the video source file and specify the ingest profile to be used

A sample set of basic requests would look like the following:

CMS API request

HTTP method
POST
Request URL
https://cms.api.brightcove.com/v1/accounts/{account_id}/videos
Request body
{
    "name": "My new video"
}

The response data will include the video id, which is used in the next request.

Ingest API request

HTTP method
POST
Request URL
https://ingest.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/ingest-requests
Request body
{
  "master": {
      "url": "http://host/master.mp4"
  },
  "profile": "high-resolution"
}

See the Quick Start for details of the API calls, and you can also see a working sample.

For CMS API call to create the video in the Video Cloud system, see the CMS API Overview. Note that the video name is required, and that the name and any other strings included for video metadata (such as the description) must be URI-encoded.

Sample assets

Brightcove Learning Services provides some sample assets you can use to experiment with in getting started with Dynamic Ingest. These assets include short videos, images, and WebVTT captions in multiple languages:

Best practices

To insure good performance and results with Dynamic Ingest, it's important that you follow these best practices!

If you have a high volume of videos to ingest on a regular basis, you will need to combine your ingest app with a notification receiver to know when you need to pause and resume ingest requests. See Fallback / Retry Strategy for more details.

Replace a video

To replace a video with a new version or a new set of renditions, the Dynamic Ingest API call is exactly the same as it would be for ingesting new videos - the only difference is that you do not need to make a prior call to the CMS API to create the video object in the Video Cloud system and get an id for it. If the source video file at the specified URL is the same one originally ingested, you will simply get a new set of renditions. If the source file is new, you will be replacing the existing video. All videos will remain playable with existing renditions until retranscoding is complete.

See the working sample here.

Retranscode a video

If you chose to archive a master when you ingested the video through the Dynamic Ingest API or the Studio Upload Module, then you can also retranscode the video from the master. Again the URL for the ingest request will be the same, but the request body will have the following:

// request
POST /v1/accounts/{account_id}/videos/{video_id}/ingest-requests

// request body
{
    "master": { "use_archived_master": true },
    "profile": "videocloud-default-v1"
}

Images

You can use the Dynamic Ingest API to capture poster and thumbnail images from your video, or to add your own images. For details, see Images and the Dynamic Ingest API.

Ingest captions

You can also add WebVTT captions to your video or upload them for an existing video using Dynamic Ingest. For details, see Ingesting WebVTT Files.

DRM and HLSe

Dynamic Ingest handles videos that use any of the DRM types supported by Brightcove. HLSe is also supported.

Archiving Renditions

By default, all video and image renditions are automatically archived. If you want to turn archiving of renditions off, contact Brightcove Support. Note that digital masters are archived if that is specified in the ingest profile.

Notifications

You can specify a one or more callback URLs to receive notifications of the results of the ingest process. The URLs you specify should be for apps than can accept POST requests. Notifications will be sent in JSON format.

Details of receiving and interpreting notifications can be found in Notifications: Dynamic Ingest and CMS APIs

Limitations

Transcode profiles
Dynamic Ingest uses one of the ingestion profiles described here. It does not use the rendition set defined in your Video Cloud account settings. See Managing Ingest Profiles for information on creating custom ingest profiles.