How to encode with a custom transform - CLI

When encoding with Azure Media Services, you can get started quickly with one of the recommended built-in presets, based on industry best practices, as demonstrated in the Streaming files quickstart. You can also build a custom preset to target your specific scenario or device requirements.

Considerations

When creating custom presets, the following considerations apply:

  • All values for height and width on AVC content must be a multiple of 4.
  • In Azure Media Services v3, all of the encoding bitrates are in bits per second. This is different from the presets with our v2 APIs, which used kilobits/second as the unit. For example, if the bitrate in v2 was specified as 128 (kilobits/second), in v3 it would be set to 128000 (bits/second).

Prerequisites

Create a Media Services account.
Make sure to remember the resource group name and the Media Services account name.

CLI Shell

It is recommended to use Azure Cloud Shell to execute CLI commands. Cloud Shell is a free, interactive shell that you can use to run the steps in this article. Common Azure tools are preinstalled and configured in Cloud Shell for you to use with your account. It provides the flexibility of choosing the shell experience that best suits the way you work. Linux users can opt for a Bash experience, while Windows users can opt for PowerShell.

You can also install the CLI locally. See Install the Azure CLI for instructions for your platform.

Sign in

Using a local install of the CLI requires signing in to Azure. This step is not required for Azure Cloud Shell. Sign in with the az login command.

If the CLI can open your default browser, it will do so and load a sign-in page. Otherwise, you need to open a browser page and follow the instructions on the command line to enter an authorization code after navigating to https://aka.ms/devicelogin in your browser.

Specify location of files

Many Media Services CLI commands allow you to pass a parameter with a file name. If you are using Cloud Shell, you can upload your file to your clouddrive (using Bash or PowerShell).

Upload files

Whether you are using a local CLI or Cloud Shell, you need to specify the file path according to the OS or Cloud Shell (Bash or PowerShell) that you are using. Below are some examples:

Relative path to the file (all OS)

  • @"mytestfile.json"
  • @"../mytestfile.json"

Absolute file path on Linux/Mac and Windows OS

  • @ "/usr/home/mytestfile.json"
  • @"c:\tmp\user\mytestfile.json"

Use {file} if the command is asking for a path to the file. For example, az ams transform create -a amsaccount -g resourceGroup -n custom --preset .\customPreset.json.
Use @{file} if the command is going to load the specified file. For example, az ams account-filter create -a amsaccount -g resourceGroup -n filterName --tracks @tracks.json.

Define a custom preset

The following example defines the request body of a new Transform. We define a set of outputs that we want to be generated when this Transform is used.

In this example, we first add an AacAudio layer for the audio encoding and two H264Video layers for the video encoding. In the video layers, we assign labels so that they can be used in the output file names. Next, we want the output to also include thumbnails. In the example below we specify images in PNG format, generated at 50% of the resolution of the input video, and at three timestamps - {25%, 50%, 75} of the length of the input video. Lastly, we specify the format for the output files - one for video + audio, and another for the thumbnails. Since we have multiple H264Layers, we have to use macros that produce unique names per layer. We can either use a {Label} or {Bitrate} macro, the example shows the former.

We are going to save this transform in a file. In this example, we name the file customPreset.json.

{
    "@odata.type": "#Microsoft.Media.StandardEncoderPreset",
    "codecs": [
        {
            "@odata.type": "#Microsoft.Media.AacAudio",
            "channels": 2,
            "samplingRate": 48000,
            "bitrate": 128000,
            "profile": "AacLc"
        },
        {
            "@odata.type": "#Microsoft.Media.H264Video",
            "keyFrameInterval": "PT2S",
            "stretchMode": "AutoSize",
            "sceneChangeDetection": false,
            "complexity": "Balanced",
            "layers": [
                {
                    "width": "1280",
                    "height": "720",
                    "label": "HD",
                    "bitrate": 3400000,
                    "maxBitrate": 3400000,
                    "bFrames": 3,
                    "slices": 0,
                    "adaptiveBFrame": true,
                    "profile": "Auto",
                    "level": "auto",
                    "bufferWindow": "PT5S",
                    "referenceFrames": 3,
                    "entropyMode": "Cabac"
                },
                {
                    "width": "640",
                    "height": "360",
                    "label": "SD",
                    "bitrate": 1000000,
                    "maxBitrate": 1000000,
                    "bFrames": 3,
                    "slices": 0,
                    "adaptiveBFrame": true,
                    "profile": "Auto",
                    "level": "auto",
                    "bufferWindow": "PT5S",
                    "referenceFrames": 3,
                    "entropyMode": "Cabac"
                }
            ]
        },
        {
            "@odata.type": "#Microsoft.Media.PngImage",
            "stretchMode": "AutoSize",
            "start": "25%",
            "step": "25%",
            "range": "80%",
            "layers": [
                {
                    "width": "50%",
                    "height": "50%"
                }
            ]
        }
    ],
    "formats": [
        {
            "@odata.type": "#Microsoft.Media.Mp4Format",
            "filenamePattern": "Video-{Basename}-{Label}-{Bitrate}{Extension}",
            "outputFiles": []
        },
        {
            "@odata.type": "#Microsoft.Media.PngFormat",
            "filenamePattern": "Thumbnail-{Basename}-{Index}{Extension}"
        }
    ]
}

Create a new transform

In this example, we create a Transform that is based on the custom preset we defined earlier. When creating a Transform, you should first check if one already exist. If the Transform exists, reuse it. The following show command returns the customTransformName transform if it exists:

az ams transform show -a amsaccount -g amsResourceGroup -n customTransformName

The following CLI command creates the Transform based on the custom preset (defined earlier).

az ams transform create -a amsaccount -g amsResourceGroup -n customTransformName --description "Basic Transform using a custom encoding preset" --preset customPreset.json

For Media Services to apply the Transform to the specified video or audio, you need to submit a Job under that Transform. For a complete example that shows how to submit a job under a transform, see Quickstart: Stream video files - CLI.

See also

Azure CLI