Re-encoding videos (by API)

A RESTful API operation is available to remotely start the video re-encoding process for an item in the library or a sequence.

RESTful re-encoding endpoint:

  • /rest-api/v1/op/reencode - Start video re-encoding.

An object containing the itemType, itemId and blobId must be POSTed to the endpoint.

Where itemType is libraryitem or sequence, itemId is the sequence or item identifier and blobId is the BLOB identifier referring to the video resource that requires re-encoding. 

Example POST to start re-encoding

{
  "itemType": "libraryitem",
  "itemId": "12345678901234",
  "blobId": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA-12345678"
}

When re-encoding a library item, the blobId can be omitted. The largest video resource within the library item will be re-encoded.

To find the blobId of a recently uploaded or imported video it will be necessary to query the library item or sequence using the REST API after uploading or importing is complete. Alternatively the BLOB ID can be constructed using the MD5 and size of the raw uploaded data.

Re-encode server response

A server will respond with an object containing a pendingId.

The pendingId is a datasource reference that can be used to query the status of the asynchronous re-encoding operation. Typically this will be of the format process-[BLOB-ID]-serverName-number. 

{
  "pendingId": "process-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA-12345678-europe3-48"
}

 

Query the status of re-encoding

The re-encoding process progress is visible in the administration interface as a progress bar over the item. It can also be queried using a REST call to the datasource endpoint.

RESTful datasource endpoint:

  • /rest-api/v1/datasource/[PENDING-ID] - GET the status of the re-encoding operation.

Datasource server response

The re-encoding process progress can be found by reading the blobProcessingProgress within the data object of the response. This will be a percentage value from 0 to 100.  

{
  "type": "datasource";
  ...
  "data": {
    ...
    "blobProcessingProgress": "12.3"
  }

When re-encoding is complete, the new video resource will be transferred to its final storage locations. This process can also be monitored using the datasource API.

When re-encoding is complete the data object will contain redirect. This refers to another datasource.

{
  "type": "datasource";
  ...
  "data": {
    ...
    "redirect": "https://www.example.com/re-encoded-video.mp4",
    "blobProcessingProgress": "100.0"
 }

Query this datasource to find the progress (bytes transferred to our server) and blobDeployProgress (bytes transferred to final storage locations).

The datasource API requires addresses in the query to be encoded to protect special characters it may contain.

  • /rest-api/v1/datasource?uri=[URL-ENCODED-REDIRECT] - GET the deployment status of the re-encoded video.
{
  "type": "datasource";
  ...
  "data": {
    ...
    "progress": "1000000",
    "length": "1000000",
    "blobDeployProgress": "100000",
    "blobDeployLength": "2000000"
 }

When re-encoding and deployment is complete, the datasource will include a snapshot object.

The snapshot contain a list of the resources generated from the re-encoding process including the new blobId that refers to the re-encoded video.

Please note that the original video will remain in the item but will no longer be enabled or transferred to devices.

 

Advanced encoding options

Advanced video encoding options can be passed through to the re-encoding service.

Add options to the request:

{
  "itemType": "libraryitem",
  "itemId": "12345678901234",
  "blobId": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA-12345678"
  "options": {
    "video_codec": "hevc",
    "format": "mp4",
    "crf": "28"
  }
}

This example instructs the encoder to use H.265/HEVC with a constant rate factor (quality) of 28 and to package as an MP4. These settings can provide significant storage and bandwidth reduction but be aware that many web browsers can not play H.265/HEVC which means the preview option may not work.

Option passthrough

The platform uses Zencoder to perform video re-encoding.

The following options will be passed through to this service:

Boolean strict;

Integer width;
Integer height;
Boolean upscale;
String aspect_mode;

Integer quality;
Integer crf;
Integer video_bitrate;
Integer audio_quality;
Integer audio_bitrate;

Integer max_video_bitrate;
Integer speed;
Integer decoder_bitrate_cap;
Integer decoder_buffer_size;
Boolean one_pass;
Boolean audio_constant_bitrate;

Float frame_rate;
Float max_frame_rate;

String format;

Integer video_reference_frames;
String video_codec;
String video_codec_profile;
Float video_codec_level;
Integer video_bframes;
String color_metadata;

Integer audio_sample_rate;
Integer max_audio_sample_rate;
Integer audio_channels;
Integer audio_bit_depth;
String audio_language;
Integer input_audio_channels;
Integer output_audio_channels;
Float audio_loudness_level;

Integer rotate;
String deinterlace;
Boolean sharpen;
Boolean denoise;
Boolean autolevel;
Boolean deblock;

Integer h264_reference_frames;
String h264_profile;
Float h264_level;
Integer h264_bframes;
String tuning;

String max_aac_profile;
String force_aac_profile;

See Zencoder documentation here:

https://zencoder.support.brightcove.com/encoding-settings/index.html