Encode a 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.
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.
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.
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.
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 / "Videos: Encode". 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.
Next steps
- ...
See also
- Encoding a video using UI
- Storage with Azure - if you want to create a Storage Account directly in Microsoft Azure using the Azure portal, Azure PowerShell, Azure CLI, or an Azure Resource Manager template
- Storage with AWS - if you want to create an S3 Bucket directly in AWS
- Azure Storage Explorer
- Message Publishers with Azure
- Mosaic Admin - here you can activate/deactivate/configure Mosaic services
- Credentials Protection
- Authenticate Service Account