Encode video using API

This article is a part of the Encoding Quick Start Guide.

In this section we will use the Encoding API to encode a video. We will take the simplest path and will only do the necessary things. Axinom Encoding has a lot more capabilities. Those you can find in the other sections of the Quick Start Guide and from the Encoding documentation.

Figure 1. Axinom Encoding Overview

The basic steps to encode the first video include:

Create Storage for an Input Storage for Axinom Encoding (this is where the source material will be uploaded to) and an Output Storage (this is where Axinom Encoding) will store the encoding results.
Upload a video to the Input Storage (use a subfolder for each video).
Create a Job request (JSON)
Authenticate with a Service Account
Start encoding by sending a job requst to Encoding API. Wait until encoding is finished.
Preview encoded video.

Create Storage

The simplest way to create a Storage is using a Mosaic Hosting Service.

Follow the instructions under Storage with Mosaic Hosting Service.

Note	Make sure to allow "Public Read Access" for the `video-output` container. Otherwise, you won’t be able to play the encoded video.

With a few clicks you will get a Storage Account in Microsoft Azure, which you can use from Axinom Mosaic, but also directly using tools such as Azure Storage Explorer.

You should now have everything to set up an Acquisition and a Publishing Profile.

Note	Of course, you can use an existing Storage Account in Microsoft Azure or an S3 Bucket in AWS with Axinom Encoding. See the links below.

Upload a video

Prepare a short video for the test. If it is short (just 1-2 minutes) you save time on all the copying and processing operations.

Upload the video to your Input Storage. Following the example above, take the container video-input, create a subfolder for your video and upload the .mp4 file there. Just a single .mp4 file is enough.

To upload a file to your storage you can use a tool such as Azure Storage Explorer.

Alternatively, you can upload files directly in Axinom Portal. Go to My Mosaic / Encoding and select "Upload a Source Video". This module uploads files to your storage previously created with the Mosaic Hosting Service.

Figure 2. Upload a video using Axinom Portal

Create job request

Here is the simplest encoding job request (explanations below):

{
    "ExternalId": "<job_reference_id>",
    "ExternalType": "movie",
    "ContentAcquisition": {
        "Provider": "AzureBlob",
        "UriPath": "https://<storage_accout_name>.blob.core.windows.net/<container_name>/<input_folder_path>",
        "CredentialsName": "PLAINTEXT_STORAGE_ACCOUNT_NAME",
        "CredentialsSecret": "ENCRYPTED_SHARED_KEY",
        "CredentialsProtection": "Encrypted"
    },
    "MediaMappings": {
        "VideoStreamExpression": "^.*\\.(mp4)$"
    },
    "ContentProcessing": {
        "OutputFormat": ["Cmaf"]
    },
    "ContentPublishing": {
        "Provider": "AzureBlob",
        "UriPath": "https://<storage_accout_name>.blob.core.windows.net/<container_name>/<output_folder_path>",
        "CredentialsName": "PLAINTEXT_STORAGE_ACCOUNT_NAME",
        "CredentialsSecret": "ENCRYPTED_SHARED_KEY",
        "CredentialsProtection": "Encrypted"
    },
    "MessagePublishers": [
        {
            "Type": "azureservicebusqueue",
            "Connection": "ENCRYPTED_CONNECTION_STRING", // Unencrypted format must be: Endpoint=sb://<azure_service_bus_name>.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=<your_secret_key>
            "CredentialsProtection": "Encrypted"
        }
    ]
}

job_reference_id - you can assign any ID here to track the job.

The configuration values for the elements ContentAcquisition and ContentPublishing you have from the previous step.

By default, use video-input as a container for acquisition and video-output for publishing.

input-folder-path is where you will upload your video.

'output-folder-path` is where your encoded output will be stored (you can set it to the same as input path, but you can also use a deviating name).

Message publisher will receive all the messages from the Encoding Service about the progress of the job. You can omit it, but then you will not know what happened with the job.

As a message publisher you can use an Azure Service Bus (see Message Publishers with Azure).

Your secrets, such as your account key and service bus connection string, shall be entered encrypted (with a certificate of Axinom Encoding), so that only Axinom Encoding can access your storage. To encrypt credentials, use Credentials Protection Tool.

Authenticate a Service Account

Axinom Encoding is a part of Axinom Mosaic Platform. Log in to Mosaic Admin Portal, go to your environment, to Service Accounts and create a Service Account with a single permission Encoding / Video Encoder. Save the CLIENT_ID and CLIENT_SECRET for this account - you will need them later, every time you want to authenticate this account.

In the properties of the Service Account click Generate Access Token. You will have to enter your CLIENT_SECRET. You will receive a JWT which you can use for all API requests later.

The JWT is valid by default for 1h. If it is expired, you can authenticate the account again and receive a new JWT.

Of course, you can authenticate a Service Account programmatically - check Authenticate Service Account.

Start encoding

To start encoding, send the job request prepared above using POST to the Encoding API endpoint <service-url>/Job.

Default service URL is https://vip-eu-west-1.axinom.com. Your URL may differ, please check in the Portal under My Mosaic / Encoding.

Set the following request headers:

Accept: application/json
Content-Type: application/json
Authorization: Bearer <JWT>

The request will return very quickly.

A status code 201 indicates that the job is accepted and will be processed. The responce contains the assigned JobId (GUID) and echoes ExternalId, ExternalType:

{
    "JobId": "6a062671-596a-4f09-acfc-0ab800f9e3f1",
    "ExternalId": "<job_reference_id>",
    "ExternalType": "movie"
}

Status codes 4xx/5xx indicate an error.

Encoding process takes some time (the longer the video, the longer the process).

If you attached a Message Publisher, you can observe the progress looking at the received messages.

The job is finished when you received either JobSuccess or FinalError message.

Preview encoded video

Once encoding is finished successfully, all the produced files are uploaded to the Publish Storage: "https://<storage_accout_name>.blob.core.windows.net/<container_name>/<output_folder_path>". One of the generated files is a DASH manifest - manifest.mpd.

Now you can build the link to the DASH manifest and play it with any DASH-capable video player.

For instance, you can go to Axinom test player under https://vtb.axinom.com, paste the link to DASH Stream URL and click "Load Stream".

The video playback should start.

If you successfully reached this point, you can proceed with the other steps.