Overview: Dynamic Ingest API

In this topic, you will learn how to use the Dynamic Ingest API to ingest videos so that they can be delivered through Dynamic Delivery.

Introduction

Brightcove's Dynamic Ingest 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.

Also see the API Reference.

Workflow overview

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

  • 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:

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:

Best practices

See Dynamic ingest API: Best Practices.

Valid source locations

Pull-based ingestion

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

Examples:

  • https://example.com/path/to/input.avi
  • https://dl.dropboxusercontent.com/u/3641457/Bird_Titmouse.mp4
  • s3://my-bucket/video.mp4
  • ftp://server/file.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.

Notes on FTP

If your videos are in a protected FTP server, use the standard method for passing the username and password on the URL, like this:

    ftp://username:password@server/file.mp4

Source file upload

You can also upload your files to a secure, temporary location from which Dynamic Ingest can pull them. For details, see Source File Upload.

Special characters

If you are providing a URL for Video Cloud to fetch your videos, and you are sending credentials as part of the URL, you need to percent-encode certain reserved special characters:

Special Characters
Character Percent-Encoded
] %5B
[ %5D
? %3F
/ %2F
< %3C
~ %7E
# %23
` %6D
! %21
@ %40
$ %24
% %25
^ %5E
& %26
* %2A
( %28
) %29
+ %2B
= %3D
} %7D
| %7C
: %3A
" %22
; %3B
' %27
, %2C
> %3E
{ %7B
space %20

For example:

/* unencoded */
ftp://user@example.com:pass!word@example.com/path/to/input.mp3

/* encoded */
ftp://user%40example.com:pass%21word@example.com/path/to/input.mp3

Double URL Encoding

Any time a URL will be decoded once before processing, you should URL encode the input URL twice before submitting the ingest job.

For example:

A master.url of 

https://some.file.storage.com/path/to/video.mp4?Signature=some%2Bcool%2B%25sig

will be converted to the following before processing:

https://some.file.storage.com/path/to/video.mp4?Signature=some+cool+%sig

You should instead double encode it like this:

https://some.file.storage.com/path/to/video.mp4?Signature=some%252Bcool%252B%2525sig

To encode a URL, see the String Encoder document.

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.

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:

Ingest Profile

Special ingest profiles are required to create Dynamic Delivery videos. You will find several standard ingest profiles in your account when Dynamic Delivery is enabled, and these are recommended.

You can also add a custom Dynamic Delivery profile to your ingest profiles in the Admin section of Studio - see Creating Ingest Profiles for Dynamic Delivery for details.

Sample Dynamic Delivery profile

Below is a sample Dynamic Delivery profile that you can use to get started. All you need to do is replace YOUR_ACCOUNT_ID with your account id, and then you can copy and paste the profile to the ingest profile editor.

    {
      "name": "DynamicDeliveryIngestProfile",
      "description": "Dynamic Delivery ingest profile.",
      "account_id": "YOUR_ACCOUNT_ID",
      "digital_master": {
        "rendition": "passthrough",
        "distribute": false
      },
      "dynamic_origin": {
        "renditions": [
          "default/audio64",
          "default/audio96",
          "default/audio128",
          "default/video450",
          "default/video700",
          "default/video900",
          "default/video1200",
          "default/video1700",
          "default/video2000"
        ],
        "images": [
          {
            "label": "poster",
            "height": 720,
            "width": 1280
          },
          {
            "label": "thumbnail",
            "height": 90,
            "width": 160
          }
        ]
      }
    }

For details on standard dynamic delivery profiles and renditions see Standard Ingest Profiles for Dynamic Delivery

Ingesting videos

There are two API requests 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 Dynamic Ingest API to provide the URL for the video source file and specify other files and settings for the ingest as needed

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 First Dynamic Delivery 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": "https://host/master.mp4"
      },
      "profile": "DynamicDeliverIngestProfile",
      "callbacks": [
        "https://mydomain.com/di-callbacks.php"
      ]
    }

Notes

  • If you do not include the profile field, that account default profile will be used. We recommend using the account default, unless you need to use different profiles for different kinds of videos. Be sure to set the account default to the profile you (most often) want to use.
  • The callbacks field is optional, but we highly recommend that you use it as the best way to track the progress of ingest jobs. See below for more on notifications.

Viewing Renditions

You can view the renditions for your video by going to the Media Module in Studio.

To view the full properties of the renditions, you can use the CMS API request detailed below.

To retrieve URLs for playback, you can use the Playback API request detailed below.

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": "multi-platform-extended-static"
    }

Image ingest

Instead of having poster and thumbnail images captured during transcoding, you can include your own images with the ingest request or add them in a separate request later.

Sample request body

    {
      "profile": "multi-platform-extended-static",
      "poster": {
        "url": "https://bcls@solutions.brightcove.com/bcls/assets/images/great-blue-heron-poster.png",
        "width": 1280,
        "height": 720
      },
      "thumbnail": {
        "url": "https://bcls@solutions.brightcove.com/bcls/assets/images/great-blue-heron-thumbnail.png",
        "width": 160,
        "height": 90
      },
      "callbacks": [
        "https://solutions.brightcove.com/bcls/di-api/di-callbacks.php"
      ]
    }

Notifications for image asset ingestion

Below are samples of the notifications you get specifically for image ingests.

    {
        "entity": "thumbnail",
        "entityType": "ASSET",
        "version": "1",
        "action": "CREATE",
        "jobId": "0c2767c1-19ea-479d-b371-a0f5f3d154f5",
        "videoId": "5209530177001",
        "accountId": "57838016001",
        "status": "SUCCESS"
      }
      {
        "entity": "poster",
        "entityType": "ASSET",
        "version": "1",
        "action": "CREATE",
        "jobId": "0c2767c1-19ea-479d-b371-a0f5f3d154f5",
        "videoId": "5209530177001",
        "accountId": "57838016001",
        "status": "SUCCESS"
    }

Captions ingest

Captions in WebVTT format can be added to your video with the initial ingest request or in a later request.

Sample request body

    {
      "text_tracks": [
        {
          "url": "https://solutions.brightcove.com/bcls/assets/vtt/sample.vtt",
          "srclang": "en",
          "kind": "captions",
          "label": "EN",
          "default": true
        },
        {
          "url": "https://solutions.brightcove.com/bcls/assets/vtt/sample-es.vtt",
          "srclang": "es",
          "kind": "captions",
          "label": "ES",
          "default": false
        }
      ],
      "callbacks": [
        "https://solutions.brightcove.com/bcls/di-api/di-callbacks.php"
      ]
    }

Sidecar text tracks will show up in CMS or Playback responses, as they do for non-Dynamic Delivery videos:

    "text_tracks": [
        {
        "id": null,
        "src": "https://bcbolt446c5271-a.akamaihd.net/media/v1/text/vtt/clear/57838016001/3de8c552-74e8-4c53-aa11-2a4375edf658/bce0d3dc-11d9-4ca4-ae1b-a39cb7b88a1c/text.vtt?akamai_token=exp=1479236791~acl=/media/v1/text/vtt/clear/57838016001/3de8c552-74e8-4c53-aa11-2a4375edf658/bce0d3dc-11d9-4ca4-ae1b-a39cb7b88a1c/text.vtt*~hmac=df5b4ba1ef2549a7572346dd36a761534ffafe4b8cfbdf92d89013ec2f95699c",
        "srclang": "en",
        "label": "EN",
        "kind": "captions",
        "mime_type": "text/webvtt",
        "asset_id": null,
        "sources": [
          {
          "src": "https://bcbolt446c5271-a.akamaihd.net/media/v1/text/vtt/clear/57838016001/3de8c552-74e8-4c53-aa11-2a4375edf658/bce0d3dc-11d9-4ca4-ae1b-a39cb7b88a1c/text.vtt?akamai_token=exp=1479236791~acl=/media/v1/text/vtt/clear/57838016001/3de8c552-74e8-4c53-aa11-2a4375edf658/bce0d3dc-11d9-4ca4-ae1b-a39cb7b88a1c/text.vtt*~hmac=df5b4ba1ef2549a7572346dd36a761534ffafe4b8cfbdf92d89013ec2f95699c"
          }
        ],
        "in_band_metadata_track_dispatch_type": "",
        "default": false
      ]
    }

Text tracks will also show up in HLS and DASH manifests:

HLS

    #EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subtitles-0",NAME="Captions",DEFAULT=NO,AUTOSELECT=YES,LANGUAGE="es",URI="https://manifest.prod.boltdns.net/manifest/v1/hls/v5/clear/57838016001/1bd49b7b-df40-414f-bb05-8840624663e1/de8144f4-b7d7-46ca-848f-dd2f7fa453d7/rendition.m3u8?fastly_token=NTg0ZjA5MWZfMzU1N2VhY2Y2MDA3NzkzYWM0ZjU2ZWQwNWE2NTYzMmI4MzMzMmJkZWM5Y2JmNzQ1MjRjM2QxYjI0NTYzODA5Zg%3D%3D"
    #EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subtitles-0",NAME="Captions",DEFAULT=NO,AUTOSELECT=YES,LANGUAGE="en",URI="https://manifest.prod.boltdns.net/manifest/v1/hls/v5/clear/57838016001/1bd49b7b-df40-414f-bb05-8840624663e1/6399fcf2-cd27-4d97-ad30-e443f13563bd/rendition.m3u8?fastly_token=NTg0ZjA5MWZfYWMxYjllNDlkYzVlOTJkZWQ3ODk2YjE3MGI5NDlhYTlkOGQ1YzI5ZmI4ZjRlOWMzMzU5YmM1YzZkNTA4MTFmNQ%3D%3D"

DASH

    <AdaptationSet mimeType="text/vtt" lang="en">
      <Representation bandwidth="256" id="2f4bb3fb-1a7d-4f4c-bf44-00ef0e611131">
      <BaseURL>https://bcbolt446c5271-a.akamaihd.net/media/v1/dash/live/clear/57838016001/785d5ddf-6672-4ece-9191-d105445b2557/2f4bb3fb-1a7d-4f4c-bf44-00ef0e611131.vtt?akamai_token=exp=1484784452~acl=/media/v1/dash/live/clear/57838016001/785d5ddf-6672-4ece-9191-d105445b2557*~hmac=ae568ea5294280968de0a2766afd82922ea9aa83fe23a81b3379a46b8ef13284</BaseURL>
      </Representation>
      </AdaptationSet>
      <AdaptationSet mimeType="text/vtt" lang="hi">
      <Representation bandwidth="256" id="f5875617-40f4-4991-bc5b-7152c6e2a93a">
      <BaseURL>https://bcbolt446c5271-a.akamaihd.net/media/v1/dash/live/clear/57838016001/785d5ddf-6672-4ece-9191-d105445b2557/f5875617-40f4-4991-bc5b-7152c6e2a93a.vtt?akamai_token=exp=1484784452~acl=/media/v1/dash/live/clear/57838016001/785d5ddf-6672-4ece-9191-d105445b2557*~hmac=ae568ea5294280968de0a2766afd82922ea9aa83fe23a81b3379a46b8ef13284</BaseURL>
      </Representation>
    </AdaptationSet>

Notifications for text track assets

Below are samples of the notifications specific to text track ingestion.

    {
      "entity": "en-captions-EN",
      "entityType": "ASSET",
      "version": "1",
      "action": "CREATE",
      "jobId": "ed429284-77c9-4905-a700-4c8edb77be3e",
      "videoId": "5209530177001",
      "accountId": "57838016001",
      "status": "SUCCESS"
    }
    {
      "entity": "es-captions-ES",
      "entityType": "ASSET",
      "version": "1",
      "action": "CREATE",
      "jobId": "ed429284-77c9-4905-a700-4c8edb77be3e",
      "videoId": "5209530177001",
      "accountId": "57838016001",
      "status": "SUCCESS"
    }

Sample player with text tracks (English and Spanish)

Dynamic Delivery Video Player

Sidecar captions in an iOS app

Dynamic Delivery Sidecar Captions
Dynamic Delivery Sidecar Captions

Retrieve dynamic renditions

To retrieve information about the dynamic renditions for a video, submit a GET request to:

    https://cms.api.brightcove.com/v1/accounts/account_id/videos/video_id/assets/dynamic_renditions

Sample response

    [
      {
        "rendition_id": "default/audio128",
        "frame_height": null,
        "frame_width": null,
        "media_type": "audio",
        "size": 506818,
        "created_at": "2016-11-14T15:05:56.209214859Z",
        "updated_at": "2016-11-14T15:05:56.209214859Z",
        "encoding_rate": 125,
        "duration": 31488,
        "audio_configuration": "L_R",
        "language": "en"
      },
      {
        "rendition_id": "default/audio64",
        "frame_height": null,
        "frame_width": null,
        "media_type": "audio",
        "size": 261129,
        "created_at": "2016-11-14T15:05:53.926747456Z",
        "updated_at": "2016-11-14T15:05:53.926747456Z",
        "encoding_rate": 62,
        "duration": 31488,
        "audio_configuration": "L_R",
        "language": "en"
      },
      {
        "rendition_id": "default/audio96",
        "frame_height": null,
        "frame_width": null,
        "media_type": "audio",
        "size": 384568,
        "created_at": "2016-11-14T15:05:59.023381448Z",
        "updated_at": "2016-11-14T15:05:59.023381448Z",
        "encoding_rate": 94,
        "duration": 31488,
        "audio_configuration": "L_R",
        "language": "en"
      },
      {
        "rendition_id": "default/video1200",
        "frame_height": 540,
        "frame_width": 960,
        "media_type": "video",
        "size": 4761241,
        "created_at": "2016-11-14T15:06:10.410020728Z",
        "updated_at": "2016-11-14T15:06:10.410020728Z",
        "encoding_rate": 1206,
        "duration": 31465
      },
      {
        "rendition_id": "default/video1700",
        "frame_height": 540,
        "frame_width": 960,
        "media_type": "video",
        "size": 6712422,
        "created_at": "2016-11-14T15:06:15.593063021Z",
        "updated_at": "2016-11-14T15:06:15.593063021Z",
        "encoding_rate": 1703,
        "duration": 31465
      },
      {
        "rendition_id": "default/video2500",
        "frame_height": 720,
        "frame_width": 1280,
        "media_type": "video",
        "size": 9795721,
        "created_at": "2016-11-14T15:06:12.148783841Z",
        "updated_at": "2016-11-14T15:06:12.148783841Z",
        "encoding_rate": 2486,
        "duration": 31465
      },
      {
        "rendition_id": "default/video4000",
        "frame_height": 1080,
        "frame_width": 1920,
        "media_type": "video",
        "size": 15718943,
        "created_at": "2016-11-14T15:06:15.463012005Z",
        "updated_at": "2016-11-14T15:06:15.463012005Z",
        "encoding_rate": 3992,
        "duration": 31465
      },
      {
        "rendition_id": "default/video450",
        "frame_height": 270,
        "frame_width": 480,
        "media_type": "video",
        "size": 1784858,
        "created_at": "2016-11-14T15:06:20.719400854Z",
        "updated_at": "2016-11-14T15:06:20.719400854Z",
        "encoding_rate": 451,
        "duration": 31465
      },
      {
        "rendition_id": "default/video700",
        "frame_height": 360,
        "frame_width": 640,
        "media_type": "video",
        "size": 2746520,
        "created_at": "2016-11-14T15:06:10.918331816Z",
        "updated_at": "2016-11-14T15:06:10.918331816Z",
        "encoding_rate": 695,
        "duration": 31465
      },
      {
        "rendition_id": "default/video900",
        "frame_height": 360,
        "frame_width": 640,
        "media_type": "video",
        "size": 3561912,
        "created_at": "2016-11-14T15:06:17.295871425Z",
        "updated_at": "2016-11-14T15:06:17.295871425Z",
        "encoding_rate": 902,
        "duration": 31465
      }
    ]

Retrieve URLs for playback

To retrieve information about the dynamic renditions for a video, submit a GET request to:

    https://edge.api.brightcove.com/playback/v1/accounts/account_id/videos/video_id

Sample response

    {
      "description": null,
      "poster_sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/853641cb-d66b-4f08-bb02-8489b5fba897/main/1280x720/24s816ms/match/image.jpg"
      }
      ],
      "tags": [
        "dd-static"
      ],
      "cue_points": [],
      "custom_fields": {},
      "account_id": "57838016001",
      "sources": [
        {
          "ext_x_version": "4",
          "type": "application/x-mpegURL",
          "src": "https://manifest.prod.boltdns.net/manifest/v1/hls/v4/clear/57838016001/853641cb-d66b-4f08-bb02-8489b5fba897/10s/master.m3u8?fastly_token=NTk1YmE0ZmZfOGU5Njg0NGU1OWQ3NjI3ZDhmY2FhZTVmNGE0YzI1MWM1NjMyNTZkNzMzZmExMzRkN2ZmYzU0YWU5NzUyZTM2YQ%3D%3D"
        },
        {
          "ext_x_version": "5",
          "type": "application/x-mpegURL",
          "src": "https://manifest.prod.boltdns.net/manifest/v1/hls/v5/clear/57838016001/853641cb-d66b-4f08-bb02-8489b5fba897/10s/master.m3u8?fastly_token=NTk1YmE0ZmZfOTBkOThhYmQ5MWM0MmQwYmQwYTM4MGEzMjAzZTgyNDVlMDYzYzNhMzQ1ZWQ3MTMyMzVmM2Q1YjM2N2VlMjM0Yg%3D%3D"
        },
        {
          "type": "application/dash+xml",
          "src": "https://manifest.prod.boltdns.net/manifest/v1/dash/live-baseurl/clear/57838016001/853641cb-d66b-4f08-bb02-8489b5fba897/2s/manifest.mpd?fastly_token=NTk1YmE0ZmZfYzQyOWJiOTEzMGJmNGIyMjM1NmMwMzZmNGZkZjlkYjEzMzNmNzFlYmQxODg0Y2YzZDk3ZTljNzVhODg1YzRjMQ%3D%3D",
          "profiles": "urn:mpeg:dash:profile:isoff-live:2011"
        },
        {
          "avg_bitrate": 2129000,
          "width": 1280,
          "src": "https://bcbolt446c5271-a.akamaihd.net/media/v1/pmp4/static/clear/57838016001/853641cb-d66b-4f08-bb02-8489b5fba897/high.mp4?akamai_token=exp=1499178239~acl=/media/v1/pmp4/static/clear/57838016001/853641cb-d66b-4f08-bb02-8489b5fba897/high.mp4*~hmac=5880698556297bbe2f2f43ac8904c659c61fb9510db1a9bb106037eaea393339",
          "size": 13242064,
          "height": 720,
          "duration": 49690,
          "container": "MP4",
          "codec": "H264"
        },
        {
          "avg_bitrate": 574000,
          "width": 480,
          "src": "https://bcbolt446c5271-a.akamaihd.net/media/v1/pmp4/static/clear/57838016001/853641cb-d66b-4f08-bb02-8489b5fba897/mid.mp4?akamai_token=exp=1499178239~acl=/media/v1/pmp4/static/clear/57838016001/853641cb-d66b-4f08-bb02-8489b5fba897/mid.mp4*~hmac=75e51439623a41b93d2a234c25683e76d43656f97a9dfb8efe61a5342d5ff2da",
          "size": 3586929,
          "height": 270,
          "duration": 49690,
          "container": "MP4",
          "codec": "H264"
        }
      ],
      "name": "Canada_Geese_Family",
      "reference_id": null,
      "long_description": null,
      "duration": 49633,
      "economics": "AD_SUPPORTED",
      "published_at": "2017-06-05T11:20:52.412Z",
      "text_tracks": [],
      "updated_at": "2017-06-05T12:06:55.121Z",
      "thumbnail": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/853641cb-d66b-4f08-bb02-8489b5fba897/main/160x90/24s816ms/match/image.jpg",
      "poster": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/853641cb-d66b-4f08-bb02-8489b5fba897/main/1280x720/24s816ms/match/image.jpg",
      "offline_enabled": false,
      "link": null,
      "id": "5459968909001",
      "ad_keys": null,
      "thumbnail_sources": [
        {
          "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/853641cb-d66b-4f08-bb02-8489b5fba897/main/160x90/24s816ms/match/image.jpg"
        }
      ],
      "created_at": "2017-06-05T11:20:52.412Z"
    }

DRM

DRM is supported, but works differently than for ordinary video ingest. You do not need to specify packaging in the ingest profile. Instead, packaging is automatic based on DRM settings for your account. Contact Brightcove Support to set defaults for DRM packaging of your videos.

For more details, see Ingesting content with DRM.

Watermarked renditions

Watermarked renditions are supported. If you require wish to add watermarks to some or all of your videos, please Contact Brightcove Support.

Note that watermarked renditions can be added for static Dynamic Delivery profiles, but not for Context Aware Encoding (CAE) profiles.

Ingest status

You can receive information on your Dynamic Delivery ingest processing by subscribing to callbacks and/or querying a Status API to get the status of the job.

Callbacks

In your ingest request, 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

Status API

You can also get the current status of ingest jobs using the Status API. Status messages are available only for ingest jobs submitted within the past 7 days.

Endpoints

All status messages for a video
    https://cms.api.brightcove.com/v1/accounts/:account_id/videos/:video_id/ingest_jobs
Example
    https://cms.api.brightcove.com/v1/accounts/57838016001/videos/5128433746001/ingest_jobs
Status message for a particular job
    https://cms.api.brightcove.com/v1/accounts/:account_id/videos/:video_id/ingest_jobs/:job_id
Example

Responses

Below is a sample response for a job that is currently processing.

    {
    "id": "7a196557-56ba-4218-ada5-e107ed554555",
    "state": "processing",
    "account_id": "57838016001",
    "video_id": "5128433746001",
    "error_code": null,
    "error_message": null,
    "updated_at": "2016-09-16T16:51:46.313Z",
    "started_at": "2016-09-16T16:51:22.258Z"
    }

The most important items here are:

  • state : the status of the job ( processing | publishing | finished | failed - when this job is complete and the video ready to play, the state will be finished )
  • error_code and error_message : for a successful job, these will be null ; for failed jobs, you will get an error code and an explanatory message

Here is an example of a status message for a failed job for comparison:

    {
    "id": "bc9dfb58-d502-43d5-97e4-41f3dcd44265",
    "state": "failed",
    "account_id": "57838016001",
    "video_id": "5128710227001",
    "error_code": "NoMediaError",
    "error_message": "Audio-only output was requested on a file that only contains video.",
    "updated_at": "2016-09-16T20:30:58.016Z",
    "started_at": "2016-09-16T20:29:14.139Z"
    }

Context Aware Encoding

Context Aware Encoding (CAE) is a technology developed by Brightcove to analyze the source video during transcoding and generate an optimum set of renditions and bitrates based on the complexity of the video and a set of bounding parameters provided (minimum number of renditions, max bitrate, etc.).

To learn how to use CAE profiles, see Context Aware Encoding.

Multiple audio tracks

Accounts set up for Dynamic Delivery can be enabled to allow multiple audio tracks for videos.

The ability to associate multiple audio tracks with a single title can be useful in a couple of key scenarios:

  • Playing back the same video in different languages for a broader reach globally 
  • Providing audio with descriptions for the visually challenged

For details of using this feature, see Multiple Audio Tracks.

Sample Code

Learning services provides several sample apps which provide a web interface and send Dynamic Ingest API requests via a PHP proxy. View the sample apps.

In addition, the following GitHub repositories contain sample code in Java, Python, and C# - note that this sample code is not supported by Brightcove:

Limitations

  • 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.
  • The special character "%" is not supported when used as part of the source file name.