📘

Beta Feature

This feature is in beta mode. Which means it's open to everybody and fully usable and we are actively developing, gathering input and improving it quickly based on customer feedback.

Introduction

Template format

Encoding Templates are written in YAML, as there is less visual clutter in comparison to JSON, and YAML .2 is a superset of JSON. Additionally, you can enrich your Encoding Template with comments to explain configuration decisions as you would do in a custom script that uses our SDK.

Java SDK reflection is possible because the new template service uses a Java SDK which means it follows the same hierarchy, therefore it is easier to construct new Encoding Templates from scratch and understand where to place the objects in the YAML.

We offer a JSON schema to validate your Encoding Template YAML files: https://raw.githubusercontent.com/bitmovin/bitmovin-api-sdk-examples/main/bitmovin-encoding-template.json

Template Structure

Referencing the Java SDK is a good starting point, the image below demonstrates the method of transposing the API Endpoints to Java.

From the Java format, we can then see how to construct the YAML and nest the endpoints.

Sequence matters when it comes to the order of calls.
The image below shows the order that the template must be constructed in.

Additionally as shown in the Template Exampleon this page, sections that come later in the file will reference previously stated objects such as inputs, outputs and configurations all being used in the encoding section.

Supported API functions

Not all API functions are supported in the Encoding Templates, only those relevant to the configuration of the Encoding for VOD and Live are supported. Other features that are more organisational and operational such as, infrastructure and notifications are not supported, and if included in a template will cause the validation to fail.

Template example

An example Encoding Template will look like this:

metadata:
  type: VOD # can be either `LIVE` or `VOD`
  name: Standard VOD Workflow

inputs:
  https:
    encoding_https_input: # user-defined name to be used for reference within the template
    	# `properties` indicates the request payload of a POST request
      properties: # refers to the `/encoding/inputs/https` endpoint
        host: bitmovin-sample-content.s3.eu-west-1.amazonaws.com
        name: Bitmovin Sample Content

configurations:
	video:
  	h264:
    	encoding_h264:
      	properties:
    			...

encodings:
  my-encoding:
    properties:
      name: Standard VOD Workflow
      cloudRegion: AUTO
      encoderVersion: STABLE

    streams:
      video_h264:
        properties:
          inputStreams:
            - inputId: $/inputs/https/encoding_https_input # reference from line 7
              inputPath: /bbb_sunflower_1080p_60fps_normal.mp4
          codecConfigId: $/configurations/video/h264/encoding_h264
          mode: PER_TITLE_TEMPLATE
          
    ...
    
    start: # exactly one Encoding per template is required
      properties:
        encodingMode: THREE_PASS
        perTitle:
          h264Configuration: {}

Prerequisites

Create Input and Output Objects for Re-Use

While you can create new input and output objects within the Encoding Template - see "inputs" section in the example above - it is generally recommended to setup input and output objects beforehand and use the respective UUIDs in the template.

In the Dashboard

Since this is likely a one time task, we generally recommend to use the dashboard for setting this up.

The links for VOD:

• https://dashboard.bitmovin.com/encoding/inputs
• https://dashboard.bitmovin.com/encoding/outputs

The links for Live:

• https://dashboard.bitmovin.com/live/inputs
• https://dashboard.bitmovin.com/live/outputs

With the API

But since everything is API-based, you can also use any of the SDKs or directly the API to set up input and output objects.

For VOD you can find guides in the Input/Output Management section of the docs.

For Live you can find the guides in the Live Inputs section and Live Outputs section of the docs.

How To

Option 1: Experience via Dashboard

We prepared some Encoding Template examples to get you started faster with some recommended workflows. Simply go to our Bitmovin Dashboard, browse the examples and start modifying them to your needs:

Option 2: Test via Postman

🚧

Recommended for Testing Only

Integrating calling the endpoint directly into your product is discouraged. Please see Option 3 for how to utilize templates in your production environment.

The current closed-beta prototype consists of a synchronous endpoint that receives an Encoding Template. This Encoding Template must contain exactly one Encoding configuration, that the endpoint will trigger in our systems. This endpoint immediately returns the Encoding ID for further tracking via webhooks or status polling.

Endpoint: https://api.bitmovin.com/v1/encoding/templates/start

There are two ways to pass the Encoding Template to this request:

• set a Content-Type:application/yaml request header and directly put your Encoding Template YAML into the request body
• set a Content-Type:application/json request header and directly put your Encoding Template as a string-serialized YAML into a { configYaml: "metadata:..." } JSON request body

Do not forget to also set the other request headers:

• required: set X-Api-Key with your user's API keys
• (optional): set X-Tenant-Org-Id depending on your organization structure of where you want to run the Encoding

Option 3: Integrate Into Your Product via SDKs

For production deployments it's highly recommended to use the official Bitmovin OpenAPI SDKs. While Encoding Templates wrap most of the encoding configuration into a single API call, the SDK is still recommended for additional manifest creation, status checks, statistics and webhooks endpoints.

Examples

📘

VOD Examples

The examples linked currently show VOD use cases, but those can easily be adapted for Live as well. If you want to see specific Live Encoding Templates please refer to the examples in the dashboard and use them as the .yml submitted in the SDK examples.

To make it easy to get started we created examples for how to utilize Encoding Templates.

• C#
• Go
• Java
• Node.js / JavaScript
• PHP (note: not functional yet, as there are limitations with the PHP SDK)
• Python

For all examples Bitmovin offers please see the Bitmovin SDK Examples Github Repository