On This Page

Overview: Dynamic Ingest API (Legacy Ingest)

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

Note that this overview is for Dynamic Ingest with the legacy ingest system. If you have a new Video Cloud account, or have converted your account to Dynamic Delivery, go to this page instead.

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.

Note: for segmented video types (HLS and DASH) some players do not handle the case where the audio and video stream lengths differ by more than a segment's duration. If you encounter this, try using a shorter segment length.

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

video-cloud/upload-urls/read

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

If you are ingesting files in batches, limit concurrent normal priority jobs to 100 and wait for one job to complete processing before adding another

Validate ingest profile changes before ingesting full batches

You should not have duplicate jobs processing for the same asset. An asset in this instance is defined as a video object, an audio track in a specific language, a text track in a specific language, or a specific image type. Here are some examples to illustrate the point:

UNACCEPTABLE: Submit an ingest request for a video file and then submit another video ingest request with the same Video ID before the first ingest job completes

ACCEPTABLE: Submit an ingest request for a video file, then submit an ingest request for a text track in English associated with the same Video ID, and then submit an ingest request for a thumbnail image with the same Video ID

ACCEPTABLE: Submit an ingest job for a text track in English and then submit an ingest request for a text track in Spanish in parallel

UNACCEPTABLE: Submit a request to ingest a Spanish audio track and then immediately submit a request to ingest another Spanish audio track on the same Video ID

The profile field for ingest requests is optional. Avoid hard-coding the profile in apps and integrations - instead, set the most commonly used profile as the default for the account, and omit the field, or fetch the available profiles for the account and force the user to choose one.

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:

Video file names (including the extension) must not exceed 120 single-byte (60 double-byte) characters. If it does, the video will be ingested successfully, but you will not be able to retranscode it later

Hostnames (for file locations or callback URLs) must not contain underscore characters or certain other punctuation or special characters per IETF specifications. See this Wikipedia article for more information. Errors will be returned if hostnames do not conform to the IETF standard.

Dynamic Ingest can not ingest files hosted on Google Drive, because Google Drive does not generate direct links to video files.

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

All input urls must properly url encoded according to RFC 3986 when being sent to Brightcove. This means that any reserved characters found in the path of the url are percent encoded (spaces being encoded to %20), and any reserved characters found in the query of the url are percent encoded (spaces being encoded to + or %20, and + being encoded to %2B).

A pre-signed S3 (v2 contains Signature, Expires and AWSAccessKeyId, and v4 contains X-Amz-Algorithm, X-Amz-Credential, X-Amz-Date, X-Amz-Expires, X-Amz-SignedHeaders, and X-Amz-Signature) or GCS (contains Signature, Expires, and GoogleAccessId) url should already be properly encoded and can be used as is.

Note that double-byte unicode characters are allowed in file names.

Ingesting videos

There are two API calls required for ingesting videos:

Call the CMS API to create a video object in the Video Cloud system and get its id

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.

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:

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.

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:

If the master was not archived, or the video was not ingested using the Dynamic Ingest API or the Upload Module, you will receive an error

The recommended standard ingest profiles (videocloud-default-v1, screencast-1280, high-resolution, smart-player-transition, single-bitrate-standard, and single-bitrate-high) will all archive the master. If you are using a custom ingest profile, you must specify that that the master should be archived if you want to be able to retranscode from the master later.

The master is never modified during retranscoding

Settings for archiving and distributing masters are never modified during retranscoding

Known Issue: when you retranscode a video using Dynamic Ingestion, the activation date for the video is updated to the current date. If you use Smart Playlists ordered by activation date, this will affect the order of the videos in the playlist.

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.

If your images will be pulled from a protected S3 bucket, you will need to set a bucket policy to allow Video Cloud to access the files. See Using Dynamic Ingest with S3 for details.

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.

Notes:

for images and text tracks, only public HTTP or HTTPS URLs or signed S3 URLs are supported

for text tracks, Dynamic Ingest only adds/appends them to video’s vtt list even if it’s a re-transcode request. customer should use the CMS API to manage them (update/delete)

Dynamic Ingest accepts up to 100 text tracks at a time

mime_type is not supported

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.