Documentation
StreamsPlaybackEncodingBitmovin Dashboard

Retrieving VOD Encoding Information with the Bitmovin API

Suggest Edits

Introduction

In most of the tutorials in our documentation and our public examples, you will find detailed instructions on how to configure various aspects of your encoding workflows with focus on producing output files that can be used directly for playback or for ingest into downstream systems. In this article however, we will focus on metadata about your encodings, and how to retrieve information about previously performed encodings, in particular for the purpose of auditing past performance, writing reports and to check on the health of your workflows.

This article also provides a few tips and tricks on how you can adjust your encoding configuration to improve your ability to retrieve specific information at a later stage.

List of encodings

In most cases, and regardless of the information you are trying to obtain, you will want to obtain a list of encodings. Use the list all encodings endpoint for that purpose. In its most basic usage, it will return a list of the last 25 encodings that have been created in the account, in reverse order of creation (ie. with the newest coming first).

Encoding Information returned

In addition to the fields that you set when creating the encoding (such as name, description and labels), and an id field with a unique identifier generated by the platform, the payload returned for each encoding in the list will also contain essential information to determine its status:

  • status with one of the following values (details about the meaning of each can be found in this FAQ):

    • CREATED for encodings that have been configured but not started
    • QUEUED for encodings that have been started, but are in a queue (either waiting for an encoding slot to be available, of for the encoder to be warmed up)
    • RUNNING for encodings that are being performed
    • CANCELED for encodings that were cancelled by the user
    • FINISHED for encodings that successfully completed
    • ERROR for encodings that failed
    • TRANSFER_ERROR for encodings that completed, but failed in the last step when attempting to transfer the output files to the Output storage (and here is how you go about resolving those)

  • progress contains a value between 0 and 100 depending on the progress of the encoding

  • timestamps for the most important stages in the encoding: createdAt, startedAt, queuedAt, runningAt and finishedAt. The latter reports the time when the encoding was completed, cancelled or stopped with an error.

    • Note that some encodings may also carry an errorAt. Since release 1.50.0 of our API, this field has been deprecated, in favour of the combination of the finishedAt property and status property (set to ERROR). It is however still included for backward compatibility

  • selectedEncoderVersion states the version of the encoder used to perform the encoding. If a version tag such as STABLE or BETA was used when configuring the encoding (as is recommended), this field will provide the actual version used.

  • selectedCloudRegion states the cloud provider and region in which the encoder performed the encoding. If the encoding was configured with AUTO, this field is resolved to the actual region used.

Query Filters

To retrieve only a logical subset of encodings, you can use query parameters when calling the list all encodings endpoint to filter the results.

Status filter

If you want to return only a list of encodings with a particular status, use the status query parameter with one of the values listed above.

Date filters

If you want encodings created or started within a certain time window, you can use and combine 6 datetime-based filters, which take ISO8601-formatted values:

  • createdAtNewerThan and its counterpart createdAtOlderThan
  • startedAtNewerThan and its counterpart startedAtOlderThan
  • finishedAtNewerThan and its counterpart finishedAtOlderThan

Search filter

The search filter allows you to do a match on some of the metadata associated with the encoding, which at the time of writing this article comprises the name and labels fields. It also allows partial matching of strings (from the start of those metadata fields), by using the * wildcard.

Tip: Naming conventions

To make best use of this filter, you need to ensure that you define metadata when you configure your encoding in such a way as to enable this type of metadata query down the line. Our recommendations are as follows:

  • Tag your encoding with one or more small labels that represents some important aspects of your encoding workflows that you may want to retrieve information about in a segmented way at a later stage, such as different encoding workflows, different targets, specific experiments you are performing, etc.
  • Alternatively, or additionally, prefix the encoding name with a short string that identifies similar or additional important aspects about the encoding for later retrieval

Other parameters and filters

There are other parameters that may be useful for the purpose of tuning the results of the query:

  • type: if you are using a mix of Live and VOD encodings in your account, you will want to set that filter to VOD.
  • sort: allows you to define the order in which the encodings are returned, by specifying a field and a direction (asc or desc). The most meaningful fields for this type of request are createdAt and startedAt. The default applied is createdAt:desc.
  • selectedEncoderVersion: to retrieve encodings performed with a specific encoder version.
  • selectedCloudRegion: to retrieve encodings performed with a specific cloud provider and in a specific region.

A full list of other parameters can be found in the API documentation for the List all encodings endpoint.

Pagination

Remember that if you are planning to pull information for a large number of encodings, the results will come in batches, by default of 25 items, and you will need to paginate through the results with the limit and `offset´ parameters. The first defines how many objects are returned in the response payload (with a maximum of 100), and the latter at what index to start returning results. Note that the payload returned for this type of query will always include a count of the total number of encodings that match the filters, as well as URLs to the next (and previous) batch of encodings for the applied filters.

Examples

Encodings with errors

To return the last 50 VOD encodings that failed, you would make a call to

https://api.bitmovin.com/v1/encoding/encodings
   ?type=VOD
   &status=ERROR
   &limit=50

Note that with our SDKs, query and filter parameters are typically provided as properties of a specific object that is passed as a single property to the list method. The response from that endpoint would be a PaginationResponse payload that contains pagination information and an array of items.

For example, with the Java SDK, the query above would look like this:

EncodingListQueryParams queryParams = new EncodingListQueryParams();
queryParams.setType("VOD");
queryParams.setStatus("ERROR");
queryParams.setLimit(50);

List<Encoding> encodings = bitmovinApi.encoding.encodings.list(queryParams).getItems();

Encodings performed on a specific day for a specific workflow

To return a full list of completed encodings in a specific 24 hour period in natural time order of creation of the encodings, for a labeled workflow and an experiment "A" (which was used as prefix to the encoding name):

https://api.bitmovin.com/v1/encoding/encodings
   ?sort=createdAt:asc
   &type=VOD
   &status=FINISHED
   &search=labels:workflow1 AND name:ExperimentA*
   &createdAtNewerThan=2020-09-17T10:00:00Z
   &finishedAtOlderThan=2020-09-18T10:00:00Z

This payload will only return the first 25 encodings. The call to get the next 25 would be

https://api.bitmovin.com/v1/encoding/encodings
   ?sort=createdAt:asc
   &type=VOD
   &status=FINISHED
   &search=labels:workflow1 AND name:ExperimentA*
   &createdAtNewerThan=2020-09-17T10:00:00Z
   &finishedAtOlderThan=2020-09-18T10:00:00Z
   &limit=25
   &offset=25

Let’s look at it in Python this time:

page = bitmovin_api.encoding.encodings.list(
   query_params=EncodingListQueryParams(
      type_="VOD",
      status="FINISHED",
      search="labels:workflow1 AND name:ExperimentA*",
      created_at_newer_than=datetime(2020, 9, 17, 10, 00, 00),
      finished_at_older_than=datetime(2020, 9, 18, 10, 00, 00),
      offset=25,
      limit=25 
   )
)
encodings = page.items

Detailed status

To get more details about the status of your encoding, and in particular finer grained details about the various stages of the encodings, and details of warnings and errors that may have occurred, you will need to query the specific status endpoint for each encoding in turn. In addition to the same information as above, additional significant information in the response payload comprises:

  • subTasks list the major phases in the encoding (eg. queue, file download, file analysis, encoding, muxing, etc.) and provide for each:
    • status and progress information
    • timing information
    • optionally metadata containing statistics relevant to the phase (eg. size of the download, number of bytes or frames encoded, etc.
  • messages providing detailed information about stages reached in the encoding (info, debug), as well as errors and warnings

Input information

In certain cases, you may want to be able to determine the spec of the input file (or files) that were used in your encodings, for example because you want to analyse the encoding performance in relation to the type of file you ingested, or you want to get an idea of why an encoding failed with a specific file, or understand how a specific stream condition was applied.

When you configure an encoding, you provide information on how to access the input file directly or indirectly (through an IngestInputStream) when creating the (output) Stream. Since it is possible to have different streams to use different files (for example, if audio and video input files are distinct), you may need to first retrieve a list of streams for your encoding and collect the identifier of the relevant stream(s) to go further.

File path and Stream selection

Determining the file path and input stream selection parameters used when configuring the encoding will depend on whether the input file information was provided directly in the Stream creation payload or as an IngestInputStream. The difference is explained in this FAQ. On that basis, you therefore need to either:

File specification

The Bitmovin API also allows you to retrieve the details of the analysis of your input file, such as the list of streams found in the file, and their specification (for example, file size, duration, codecs, dimensions, channel format, etc.)

To retrieve this information, use the stream input details endpoint with your encoding ID and stream ID. Note that the information returned is for the whole input file, and does not take into consideration the stream selection configuration of your stream. This may be an advantage if all your streams use the same input file, as a single call will return all the information you might be interested in.

Here is an example of the type of input file analysis information returned:

{
  "data": {
    "result": {
      "formatName": "matroska,webm",
      "startTime": 0.0,
      "duration": 263.013,
      "size": 51107796,
      "bitrate": 1554532,
      "tags": {
        "ENCODER": "Lavf56.24.101",
        "COMPATIBLE_BRANDS": "isommp42",
        "MAJOR_BRAND": "mp42",
        "MINOR_VERSION": "0"
      },
      "audioStreams": [
        {
          "id": "e7328177-ff24-41db-b213-b03ed0004c6b",
          "position": 1,
          "codec": "aac",
          "sampleRate": 44100,
          "channelFormat": "2",
          "hearingImpaired": false
        }
      ],
      "videoStreams": [
        {
          "id": "5c916072-2f49-4233-b25d-b8347b6d8987",
          "position": 0,
          "codec": "h264",
          "fps": "24000/1001",
          "width": 1280,
          "height": 720,
          "par": 1.0
        }
      ]
    }
  }
}

Note: At the time of writing, it is only possible to get full details about the input files when the encoding only used 1 file per (output) stream. For use cases such as concatenation of files, the information is not available for all files. This will be added in a future version of the API.*

Updated over 1 year ago