API Reference

879 Pages·2017·7.1 MB·English

AWS Elemental
MediaConvert API Reference
API Reference
AWS Elemental MediaConvert API Reference API Reference
AWS Elemental MediaConvert API Reference: API Reference
Copyright © 2022 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not
Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or
discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may
or may not be affiliated with, connected to, or sponsored by Amazon.
AWS Elemental MediaConvert API Reference API Reference
Table of Contents
Getting Started with the AWS SDKs and the CLI .................................................................................... 1
CreateJob Example Using the AWS CLI ......................................................................................... 2
CreateJob Example Using the SDK for C++ .................................................................................... 2
Finding More Information in the SDK for Go Documentation ........................................................... 8
CreateJob Example Using theSDK for Java .................................................................................... 8
CreateJob Example Using the AWS SDK for .NET ............................................................................ 9
CreateJob Example Using the SDK for Python .............................................................................. 15
Finding More Information in the SDK for Ruby Documentation ....................................................... 16
Finding More Information in the Tools for PowerShell Core Documentation ...................................... 16
Getting Started with the API ............................................................................................................. 17
Ensuring idempotency............................................................................................................... 18
AWS Elemental MediaConvert Postman Collection Files ................................................................. 18
GET Collection................................................................................................................. 19
POST Collection............................................................................................................... 22
Tagging Collection............................................................................................................ 30
Creating Your Job Specification .......................................................................................................... 38
Sample Settings in JSON.......................................................................................................... 38
Simple Example............................................................................................................... 39
Complex Example............................................................................................................. 41
Important Notes.............................................................................................................................. 48
AWS Region-Specific Endpoints .................................................................................................. 48
Versioned Endpoints................................................................................................................. 48
FIPS Endpoints......................................................................................................................... 48
Using the AWS CLI ................................................................................................................... 49
Schemas and Example Job Settings ............................................................................................ 49
Resources........................................................................................................................................ 50
Certificates............................................................................................................................. 50
URI................................................................................................................................. 50
HTTP methods................................................................................................................. 50
Schemas.......................................................................................................................... 51
Properties........................................................................................................................ 52
See also.......................................................................................................................... 52
Certificates arn....................................................................................................................... 53
URI................................................................................................................................. 53
HTTP methods................................................................................................................. 53
Schemas.......................................................................................................................... 54
Properties........................................................................................................................ 54
See also.......................................................................................................................... 55
Endpoints............................................................................................................................... 55
URI................................................................................................................................. 55
HTTP methods................................................................................................................. 55
Schemas.......................................................................................................................... 56
Properties........................................................................................................................ 57
See also.......................................................................................................................... 58
Jobs...................................................................................................................................... 59
URI................................................................................................................................. 59
HTTP methods................................................................................................................. 59
Schemas.......................................................................................................................... 61
Properties...................................................................................................................... 121
See also........................................................................................................................ 425
Jobs id................................................................................................................................. 426
URI............................................................................................................................... 426
HTTP methods............................................................................................................... 426
Schemas........................................................................................................................ 428
iii
AWS Elemental MediaConvert API Reference API Reference
Properties...................................................................................................................... 448
See also........................................................................................................................ 749
JobTemplates........................................................................................................................ 750
URI............................................................................................................................... 750
HTTP methods............................................................................................................... 750
Schemas........................................................................................................................ 752
Properties...................................................................................................................... 810
See also....................................................................................................................... 1106
JobTemplates name............................................................................................................. 1106
URI............................................................................................................................. 1106
HTTP methods............................................................................................................. 1106
Schemas...................................................................................................................... 1109
Properties.................................................................................................................... 1168
See also....................................................................................................................... 1462
Policy................................................................................................................................. 1463
URI............................................................................................................................. 1463
HTTP methods............................................................................................................. 1463
Schemas...................................................................................................................... 1466
Properties.................................................................................................................... 1467
See also....................................................................................................................... 1468
Presets............................................................................................................................... 1469
URI............................................................................................................................. 1469
HTTP methods............................................................................................................. 1469
Schemas...................................................................................................................... 1471
Properties.................................................................................................................... 1507
See also....................................................................................................................... 1711
Presets name...................................................................................................................... 1712
URI............................................................................................................................. 1712
HTTP methods............................................................................................................. 1712
Schemas...................................................................................................................... 1715
Properties.................................................................................................................... 1750
See also....................................................................................................................... 1953
Queues............................................................................................................................... 1954
URI............................................................................................................................. 1954
HTTP methods............................................................................................................. 1954
Schemas...................................................................................................................... 1956
Properties.................................................................................................................... 1958
See also....................................................................................................................... 1965
Queues name...................................................................................................................... 1965
URI............................................................................................................................. 1965
HTTP methods............................................................................................................. 1965
Schemas...................................................................................................................... 1968
Properties.................................................................................................................... 1970
See also....................................................................................................................... 1976
Tags................................................................................................................................... 1977
URI............................................................................................................................. 1977
HTTP methods............................................................................................................. 1977
Schemas...................................................................................................................... 1978
Properties.................................................................................................................... 1978
See also....................................................................................................................... 1979
Tags arn............................................................................................................................. 1979
URI............................................................................................................................. 1979
HTTP methods............................................................................................................. 1979
Schemas...................................................................................................................... 1981
Properties.................................................................................................................... 1982
See also....................................................................................................................... 1984
Document History......................................................................................................................... 1985
iv
AWS Elemental MediaConvert API Reference API Reference
AWS glossary............................................................................................................................... 1986
v
AWS Elemental MediaConvert API Reference API Reference
Getting Started with AWS Elemental
MediaConvert Using the AWS SDKs
or the AWS CLI
To get started with AWS Elemental MediaConvert using one of the AWS SDKS or the AWS Command
Line Interface (AWS CLI), follow this general procedure. For specific instructions and examples, choose a
language in the final step of this procedure.
1. Set up AWS Identity and Access Management (IAM) permissions for both yourself and for the
MediaConvert service to access your resources on your behalf:
• For information about setting up permissions for yourself, see Overview of Identity Management:
Users in the IAM User Guide.
• For information about setting up permissions for the service to access your resources, see Set Up
IAM Permissions in the MediaConvert User Guide.
2. In your client configuration, specify your authentication credentials and your AWS Region. For
instructions that are specific to the programming language that you use, choose from this list of
links to open the relevant topics in the AWS CLI or SDK guides:
• AWS CLI
• C++: credentials and Region
• Go
• Java
• JavaScript
• .NET
• PHP
• Python: credentials and Region
• Ruby
• Tools for PowerShell
3. Get your Region-specific endpoint and send your MediaConvert requests to it.
• To prevent duplicate jobs from being created, use client request tokens. For more information
see Ensuring idempotency (p. 18).
Note
When you send requests, use camelCase or PascalCase as appropriate for the language you
are using. All examples in this guide use PascalCase, which is the correct casing for the AWS
CLI and AWS SDK for Python (Boto3). The MediaConvert console JSON export function also
generates JSON job specifications in PascalCase.
When you use a language that specifies camelCase, such as JavaScript, you must convert
the casing of your properties before you submit your requests. For example, if you use the
properties "Settings" and "TimecodeConfig" in your call through the AWS CLI, you must
change those to "settings" and "timecodeConfig" for your call through the AWS SDK for
JavaScript.
1
AWS Elemental MediaConvert API Reference API Reference
CreateJob Example Using the AWS CLI
With most AWS services, you send your service request to a public endpoint. But with MediaConvert,
you request an endpoint that is specific to your Region, and then you send your service requests to
that. For information about MediaConvert FIPS endpoints, see FIPS Endpoints (p. 48).
Note
This endpoint is specific to your AWS Region and won't change. Request this endpoint once,
and then hardcode or cache it.
For specific instructions and code samples, choose one of the following topics.
• AWS CLI: CreateJob Example Using the AWS CLI (p. 2)
• C++: CreateJob Example Using the SDK for C++ (p. 2)
• Go: Finding More Information in the SDK for Go Documentation (p. 8)
• Java: CreateJob Example Using theSDK for Java (p. 8)
• JavaScript: AWS Elemental MediaConvert Examples, in the SDK for JavaScript Developer Guide
• .NET: CreateJob Example Using the AWS SDK for .NET (p. 9)
• PHP: AWS Elemental MediaConvert Examples, in the AWS SDK for PHP Developer Guide
• Python: CreateJob Example Using the SDK for Python (p. 15)
• Ruby: Finding More Information in the SDK for Ruby Documentation (p. 16)
• Tools for Powershell: Finding More Information in the Tools for PowerShell Core
Documentation (p. 16)
AWS Elemental MediaConvert CreateJob Example
Using the AWS CLI
To create a transcoding job using the AWS CLI:
1. Use describe-endpoints to get your endpoint and set your Region. In this example, the Region is
set to ap-northeast-3:
aws mediaconvert describe-endpoints --region ap-northeast-3
2. Use the --endpoint-url option to send your request to your endpoint:
aws --endpoint-url https://abcd1234.mediaconvert.region-name-1.amazonaws.com --
region region-name-1 mediaconvert create-job --cli-input-json file://~/job.json
In the preceding example, job.json specifies your transcoding job settings. You can use the
MediaConvert console to generate the JSON job specification. For more information and sample job
specifications, see Creating Your Job Specification (p. 38).
AWS Elemental MediaConvert CreateJob Example
Using the SDK for C++
To send requests using the SDK for C++:
2
AWS Elemental MediaConvert API Reference API Reference
CreateJob Example Using the SDK for C++
// MediaConvertPort.cpp : Defines the entry point for the console
application.
//
// Imports needed
#include <aws/core/Aws.h>
#include <aws/core/utils/Outcome.h>
#include <aws/mediaconvert/MediaConvertClient.h>
#include <aws/mediaconvert/Model/DescribeEndpointsRequest.h>
#include <aws/mediaconvert/Model/CreateJobRequest.h>
#include <aws/mediaconvert/Model/CreateJobResult.h>
/* ----------------------------------------------
* Permissions IAM user needs to run this example
* ----------------------------------------------
*
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"mediaconvert:DescribeEndpoints",
"mediaconvert:CreateJob"
],
"Resource": "*"
}
]
}
*/
/* --------------------------------------
* JSON job settings used in this example
* --------------------------------------
*
{
"Queue": "arn:aws:mediaconvert:us-west-2:505474453218:queues/Default",
"UserMetadata": {
"Customer": "Amazon"
},
"Role": "Your AWS Elemental MediaConvert role ARN",
"Settings": {
"OutputGroups": [
{
"Name": "File Group",
"OutputGroupSettings": {
"Type": "FILE_GROUP_SETTINGS",
"FileGroupSettings": {
"Destination": "s3://youroutputdestination"
}
},
"Outputs": [
{
"VideoDescription": {
"ScalingBehavior": "DEFAULT",
"TimecodeInsertion": "DISABLED",
"AntiAlias": "ENABLED",
"Sharpness": 50,
"CodecSettings": {
"Codec": "H_264",
"H264Settings": {
"InterlaceMode": "PROGRESSIVE",
"NumberReferenceFrames": 3,
"Syntax": "DEFAULT",
"Softness": 0,
3
AWS Elemental MediaConvert API Reference API Reference
CreateJob Example Using the SDK for C++
"GopClosedCadence": 1,
"GopSize": 90,
"Slices": 1,
"GopBReference": "DISABLED",
"SlowPal": "DISABLED",
"SpatialAdaptiveQuantization": "ENABLED",
"TemporalAdaptiveQuantization": "ENABLED",
"FlickerAdaptiveQuantization": "DISABLED",
"EntropyEncoding": "CABAC",
"Bitrate": 5000000,
"FramerateControl": "SPECIFIED",
"RateControlMode": "CBR",
"CodecProfile": "MAIN",
"Telecine": "NONE",
"MinIInterval": 0,
"AdaptiveQuantization": "HIGH",
"CodecLevel": "AUTO",
"FieldEncoding": "PAFF",
"SceneChangeDetect": "ENABLED",
"QualityTuningLevel": "SINGLE_PASS",
"FramerateConversionAlgorithm": "DUPLICATE_DROP",
"UnregisteredSeiTimecode": "DISABLED",
"GopSizeUnits": "FRAMES",
"ParControl": "SPECIFIED",
"NumberBFramesBetweenReferenceFrames": 2,
"RepeatPps": "DISABLED",
"FramerateNumerator": 30,
"FramerateDenominator": 1,
"ParNumerator": 1,
"ParDenominator": 1
}
},
"AfdSignaling": "NONE",
"DropFrameTimecode": "ENABLED",
"RespondToAfd": "NONE",
"ColorMetadata": "INSERT"
},
"AudioDescriptions": [
{
"AudioTypeControl": "FOLLOW_INPUT",
"CodecSettings": {
"Codec": "AAC",
"AacSettings": {
"AudioDescriptionBroadcasterMix": "NORMAL",
"RateControlMode": "CBR",
"CodecProfile": "LC",
"CodingMode": "CODING_MODE_2_0",
"RawFormat": "NONE",
"SampleRate": 48000,
"Specification": "MPEG4",
"Bitrate": 64000
}
},
"LanguageCodeControl": "FOLLOW_INPUT",
"AudioSourceName": "Audio Selector 1"
}
],
"ContainerSettings": {
"Container": "MP4",
"Mp4Settings": {
"CslgAtom": "INCLUDE",
"FreeSpaceBox": "EXCLUDE",
"MoovPlacement": "PROGRESSIVE_DOWNLOAD"
}
},
"NameModifier": "_1"
4
AWS Elemental MediaConvert API Reference API Reference
CreateJob Example Using the SDK for C++
}
]
}
],
"AdAvailOffset": 0,
"Inputs": [
{
"AudioSelectors": {
"Audio Selector 1": {
"Offset": 0,
"DefaultSelection": "NOT_DEFAULT",
"ProgramSelection": 1,
"SelectorType": "TRACK",
"Tracks": [
1
]
}
},
"VideoSelector": {
"ColorSpace": "FOLLOW"
},
"FilterEnable": "AUTO",
"PsiControl": "USE_PSI",
"FilterStrength": 0,
"DeblockFilter": "DISABLED",
"DenoiseFilter": "DISABLED",
"TimecodeSource": "EMBEDDED",
"FileInput": "s3://yourinputfile"
}
],
"TimecodeConfig": {
"Source": "EMBEDDED"
}
}
}
*/
int main()
{
// Initialize the C++ SDK
Aws::SDKOptions options;
Aws::InitAPI(options);
{
std::string mediaConvertRole = "arn:aws:iam::640773029566:role/media-convert-role";
std::string fileInput = "s3://media-convert-sample/my-video.mp4";
std::string fileOutput = "s3://media-convert-sample";
// Once you know what your customer endpoint is, set it here
std::string mediaConvertEndpoint = "";
// If we do not have our customer-specific endpoint
if (mediaConvertEndpoint.empty())
{
// Obtain the customer-specific MediaConvert endpoint
Aws::Client::ClientConfiguration clientConfig;
clientConfig.region = "us-west-2";
Aws::MediaConvert::MediaConvertClient client(clientConfig);
Aws::MediaConvert::Model::DescribeEndpointsRequest request;
// need to strip https:// from endpoint for C++
mediaConvertEndpoint =
client.DescribeEndpoints(request).GetResult().GetEndpoints().at(0).GetUrl().substr(8);
}
// Create MediaConvert client with the endpoints and region from above
Aws::Client::ClientConfiguration mcClientConfig;
// Also need to set region endpoint, must match endpoint embedded in custom endpoint
mcClientConfig.region = "us-west-2";
5