Amazon Elastic Transcoder

(1)

Amazon Elastic Transcoder

Developer Guide

API Version 2012-09-25

(2)

Amazon Elastic Transcoder: Developer Guide

(3)

What is Amazon Elastic Transcoder?

Topics

• Accessing Elastic Transcoder (p. 2)

• Choosing a Region for Your Elastic Transcoder Resources (p. 2)

• Limits on the Number of Elastic Transcoder Pipelines, Jobs, and Presets (p. 2)

Amazon Elastic Transcoder lets you convert media files that you have stored in Amazon Simple Storage Service (Amazon S3) into media files in the formats required by consumer playback devices. For example, you can convert large, high-quality digital media files into formats that users can play back on mobile devices, tablets, web browsers, and connected televisions.

Elastic Transcoder has four components:

• Jobs do the work of transcoding. Each job converts one file into up to 30 formats. For example, if you want to convert a media file into six different formats, you can create files in all six formats by creating a single job.

When you create a job, you specify the name of the file that you want to transcode, the names that you want Elastic Transcoder to give to the transcoded files, and several other settings. For each format that you want to transcode into, you also specify a template, known as a preset (see below), that contains the audio and video settings that you want to use for the transcoded file or files.

• Pipelines are queues that manage your transcoding jobs. When you create a job, you specify which pipeline you want to add the job to. Elastic Transcoder starts processing the jobs in a pipeline in the order in which you added them. If you conﬁgure a job to transcode into more than one format, Elastic Transcoder creates the ﬁles for each format in the order in which you specify the formats in the job.

One common conﬁguration is to create two pipelines—one for standard-priority jobs, and one for high-priority jobs. Most jobs go into the standard-priority pipeline; you use the high-priority pipeline only when you need to transcode a ﬁle immediately.

If a pipeline already contains jobs when you create a new job, Elastic Transcoder queues the newest job and begins processing it as soon as resources are available for that pipeline. If the pipeline is already using all of its resources, Elastic Transcoder begins processing the next job in the pipeline when it ﬁnishes one of the jobs that it's currently processing.

A pipeline can process more than one job simultaneously, and the time required to complete a job varies significantly based on the size of the file you're converting and the job specifications.

Accordingly, jobs don't necessarily complete in the order in which you create them.

You can temporarily stop processing jobs by pausing the pipeline.

• Presets are templates that contain most of the settings for transcoding media ﬁles from one format to another. Elastic Transcoder includes some default presets for common formats, for example, several iPod and iPhone versions. You can also create your own presets for formats that aren't included among the default presets. You specify which preset you want to use when you create a job.

• Notifications let you optionally configure Elastic Transcoder and Amazon Simple Notification Service to keep you apprised of the status of a job: when Elastic Transcoder starts processing the job, when Elastic Transcoder finishes the job, and whether Elastic Transcoder encounters warning or error conditions during processing. Notifications eliminate the need for polling to determine when a job has finished. You configure notifications when you create a pipeline.

(7)

Accessing Elastic Transcoder

Elastic Transcoder is a RESTful web service that uses HTTPS as the protocol and JavaScript Object Notation (JSON) as the message format. Your application code can make requests directly to the Elastic Transcoder API. When using the REST API directly, you must write the necessary code to sign and authenticate your requests. For more information about the API and about signing requests, see API Reference (p. 133).

Elastic Transcoder also provides a management console. You can use the console to perform all of the same operations that you can perform using the Elastic Transcoder API. For information about using the console to create and manage pipelines, presets, and jobs, see the applicable topic:

• Working with Jobs (p. 17)

• Working with Pipelines (p. 8)

• Working with Presets (p. 41)

Regions and Endpoints

You create pipelines in a speciﬁc AWS region. You always send your Elastic Transcoder requests to a region-speciﬁc endpoint. For a list of supported AWS regions, go to the Regions and Endpoints section in the Amazon Web Services General Reference.

Choosing a Region for Your Elastic Transcoder Resources

Pipelines and jobs are closely associated with speciﬁc regions. When you create pipelines and jobs, they're created in the current region. When you create a new job, you must specify a pipeline in the current region.

You can specify Amazon S3 buckets in a diﬀerent region than your Elastic Transcoder resources, but we don't recommend it because you'll incur additional charges for transferring ﬁles between AWS regions.

For more information on cross-regional fees, see Data Transfer Pricing in Amazon S3 Pricing.

Limits on the Number of Elastic Transcoder Pipelines, Jobs, and Presets

Elastic Transcoder pipelines, jobs, and presets are subject to the following limitations:

• Pipelines: For each region, 4 pipelines per AWS account

• Maximum number of queued jobs: 1,000,000 per pipeline

• Maximum number of outputs: 30 per job

• Maximum number of jobs processed simultaneously by each pipeline: 100 per pipeline

• Presets: 50 user-deﬁned presets per AWS account (Elastic Transcoder also includes predeﬁned presets that don't count against the limit.)

• Maximum rate at which you can submit job requests:

(8)

• Create Job: You can submit two Create Job requests per second per AWS account at a sustained rate; brief bursts of 100 requests per second are allowed.

• Read Job: You can submit four Read Job requests per second per AWS account at a sustained rate;

brief bursts of 50 requests per second are allowed.

You can request higher limits at https://console.aws.amazon.com/support/home#/case/create?

issueType=service-limit-increase&limitType=service-code-elastic-transcoders.

(9)

Getting Started with Elastic Transcoder

The example in this topic gives you a quick overview of how to use Amazon Elastic Transcoder to transcode media files from one media format into another. You only need to perform a few basic steps to start transcoding your media files using Elastic Transcoder. The first step is signing up for AWS. After that, you create an Amazon S3 bucket and upload a media file that you want to transcode. You then create a pipeline to process your jobs, and create a job to transcode a specific file into a specific format.

If you want to transcode to a format for which we don't provide a preset (a template), you can create a custom preset before you create the job.

NoteIf you aren't already acquainted with jobs, pipelines, and presets—the basic concepts behind Elastic Transcoder—take a quick look at the short overview topic: What is Amazon Elastic Transcoder? (p. 1)

Topics

• Step 1: Sign Up for AWS (p. 4)

• Step 2: Create an Amazon S3 Bucket or Two, and Upload a Media File (p. 4)

• Step 3: Create a Pipeline (p. 5)

• Step 4: (Optional) Create a Preset (p. 6)

• Step 5: Create a Job (p. 6)

• Step 6: Monitor the Progress of Your Job (p. 7)

Step 1: Sign Up for AWS

To use Elastic Transcoder, you need an AWS account. If you don't already have an account, you'll be prompted to create one when you sign up. You're not charged for any AWS services that you sign up for unless you use them.

To sign up for AWS

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a veriﬁcation code on the phone keypad.

Step 2: Create an Amazon S3 Bucket or Two, and Upload a Media File

Create an Amazon S3 bucket for the ﬁles that you want to transcode (the input bucket) and another bucket for the transcoded ﬁles (the output bucket). You can also use the same bucket for the input bucket and the output bucket.

(10)

To create Amazon S3 buckets and upload a media ﬁle

1. Sign in to the AWS Management Console and open the Amazon S3 console at https://

console.aws.amazon.com/s3/.

2. In the Amazon S3 console, click Create Bucket.

3. In the Create Bucket dialog box, enter a bucket name. If you want to create separate input and output buckets, give the bucket an appropriate name.

4. Select a region for your bucket. By default, Amazon S3 creates buckets in the US Standard region.

We recommend that you choose a region close to you to optimize latency, minimize costs, or to address regulatory requirements. This is also the region in which you want Elastic Transcoder to do the transcoding.

5. Click Create.

6. If you want to create separate buckets for the files that you are transcoding and the files that Elastic Transcoder has finished transcoding, repeat Step 2 through Step 5.

7. In the Buckets pane, click the name of your input bucket.

8. Click Actions and then click Upload.

9. On the Upload - Select Files page, click Add Files, and upload a media ﬁle that you want to transcode.

10. Click Start Upload.

Step 3: Create a Pipeline

A pipeline manages the jobs that transcode your ﬁles. Typically, you'll create two or more pipelines, for example, to manage standard-priority jobs and high-priority jobs. In this example, you'll create a single pipeline. For more information about pipelines, see Working with Pipelines (p. 8).

To create a pipeline using the Elastic Transcoder console

1. Open the Elastic Transcoder console at https://console.aws.amazon.com/elastictranscoder/.

2. In the navigation bar of the Elastic Transcoder console, select the region in which you want to create the pipeline.

(11)

3. In the left pane of the console, click Pipelines.

4. On the Pipelines page, click Create New Pipeline.

5. Enter the applicable values. For more information about each ﬁeld, see Settings that You Specify When You Create an Elastic Transcoder Pipeline (p. 10).

NoteIf you want to monitor the progress of your job, specify the Amazon Simple Notiﬁcation Service (Amazon SNS) topic that you want to notify when Elastic Transcoder begins processing a job and when Elastic Transcoder has completed the job.

6. Click Create Pipeline.

Step 4: (Optional) Create a Preset

A preset is a template that contains the settings that you want Elastic Transcoder to apply during the transcoding process, for example, the codec and the resolution that you want in the transcoded ﬁle.

When you create a job, you specify which preset you want to use. We provide system presets that create media files that play on many common devices and system presets that target specific devices. For maximum compatibility, choose a preset that creates output that plays on a wide range of devices. For optimum quality and file size, choose a preset that creates output for a specific device or class of devices.

For the current list of system presets, see the list of presets on the Elastic Transcoder detail page.

If none of the system presets contain the settings that you need, you can create your own presets. For more information, see Creating a Preset in Elastic Transcoder (p. 41).

Step 5: Create a Job

A job does the work of transcoding. You specify the name of the file that you want to transcode (the input file), the name that you want Elastic Transcoder to give the transcoded file, the preset that you want Elastic Transcoder to use, and a few other settings. Elastic Transcoder gets the input file from the Amazon S3 input bucket that you specified in your pipeline, transcodes the file, and saves the transcoded file or files in the Amazon S3 output bucket that you specified in the pipeline.

For more information about jobs, see Working with Jobs (p. 17).

(12)

To create a job using the Elastic Transcoder console

1. Open the Elastic Transcoder console at https://console.aws.amazon.com/elastictranscoder/.

2. In the navigation bar of the Elastic Transcoder console, select the region in which you want to create the job.

3. In the left pane of the console, click Pipelines. (You create the job in the pipeline—the queue—that you want to use to transcode the ﬁle.)

4. On the Pipelines page, click Create New Job.

5. Enter the applicable values. For more information about each ﬁeld, see Settings that You Specify When You Create an Elastic Transcoder Job (p. 19).

6. Click Create Job.

Step 6: Monitor the Progress of Your Job

When you created a pipeline in Step 3: Create a Pipeline (p. 5), you had the option to conﬁgure

notifications, so Elastic Transcoder sends a message to an Amazon Simple Notification Service (Amazon SNS) topic when Elastic Transcoder begins processing a job and finishes processing a job. If you

conﬁgured notiﬁcations and if you subscribed to the applicable Amazon SNS topic, you can monitor the progress of your job.

(13)

Working with Pipelines

Topics

• Creating a Pipeline in Elastic Transcoder (p. 8)

• Pausing and Reactivating Pipelines in Elastic Transcoder (p. 9)

• Updating Pipeline Notiﬁcations in Elastic Transcoder (p. 9)

• Listing and Viewing Pipelines in Elastic Transcoder (p. 10)

• Deleting an Elastic Transcoder Pipeline (p. 10)

• Settings that You Specify When You Create an Elastic Transcoder Pipeline (p. 10)

Pipelines are queues that manage your transcoding jobs. When you create a job, you specify the pipeline to which you want to add the job. Elastic Transcoder starts processing the jobs in a pipeline in the order in which you added them.

One common conﬁguration is to create two pipelines—one for standard-priority jobs, and one for high- priority jobs. Most jobs go into the standard-priority pipeline; you use the high-priority pipeline only when you need to transcode a ﬁle immediately.

If there are other jobs in a pipeline when you create a job, Elastic Transcoder starts processing the new job when resources are available. A pipeline can process more than one job simultaneously, and the time required to complete a job varies significantly based on the size of the file you're converting and the job specifications. As a result, jobs don't necessarily complete in the order in which you create them.

You can temporarily pause a pipeline so it stops processing jobs. This is useful if you want to cancel one or more jobs, which you can do only until Elastic Transcoder starts processing the jobs.

Creating a Pipeline in Elastic Transcoder

You can create a pipeline using the AWS Management Console or using the Elastic Transcoder Create Pipeline API action. The following procedure explains how to create a pipeline using the console. For information about how to create a pipeline using the API, see Create Pipeline (p. 146).

To create a pipeline using the Elastic Transcoder console

1. Sign in to the AWS Management Console and open the Elastic Transcoder console at https://

console.aws.amazon.com/elastictranscoder/.

2. In the navigation bar of the Elastic Transcoder console, select the region in which you want to create the pipeline. This region is where you'll create your jobs.

3. In the navigation (left) pane of the console, click Pipelines.

4. On the Pipelines page, click Create New Pipeline.

5. Enter the applicable values. For more information about each ﬁeld, see Settings that You Specify When You Create an Elastic Transcoder Pipeline (p. 10).

6. Click Create Pipeline.

(14)

Pausing and Reactivating Pipelines in Elastic Transcoder

If you want to cancel a job, we recommend that you ﬁrst pause the corresponding pipeline so Elastic Transcoder doesn't start processing the job. After the status of a job changes from Submitted to Progressing, you can't cancel it.

The following procedure explains how to pause and reactivate a pipeline by using the console. For information about how to pause and reactivate a pipeline by using the API, see Update Pipeline Status (p. 168).

To pause or reactivate a pipeline using the Elastic Transcoder console

2. In the navigation bar of the Elastic Transcoder console, select the region in which you want to pause or reactivate a pipeline.

3. In the navigation (left) pane, click Pipelines.

4. Select the check box next to the pipeline that you want to pause or reactivate.

5. Click Pause or Activate as applicable.

Updating Pipeline Notiﬁcations in Elastic Transcoder

When you create a pipeline, you can optionally configure Elastic Transcoder to send a message to an Amazon Simple Notification Service (Amazon SNS) topic when the status of a job changes, including when Elastic Transcoder starts or finishes processing a job, and when Elastic Transcoder encounters a warning or error condition while processing a job. You can change whether you want Elastic Transcoder to send a message, and, if so, you can change which SNS topic to send the message to.

Amazon SNS offers a variety of notification options, including the ability to send Amazon SNS messages to Amazon Simple Queue Service (Amazon SQS) queues. For more information, see the Amazon Simple Notification Service Developer Guide.

The following procedure explains how to update notifications using the console. For information about how to update notifications using the API, see Update Pipeline Notifications (p. 171).

To update pipeline notiﬁcations using the Elastic Transcoder console

2. In the navigation bar of the Elastic Transcoder console, select the region in which you want to pause or reactivate a pipeline.

3. In the navigation (left) pane, click Pipelines.

4. Select the check box next to the pipeline for which you want to change notiﬁcations.

5. Click Edit.

6. Change values as applicable. For more information, see Settings that You Specify When You Create an Elastic Transcoder Pipeline (p. 10).

(15)

7. Click Save to save your changes.

Listing and Viewing Pipelines in Elastic Transcoder

You can list the pipelines associated with the current AWS account, and you can also view the settings for a speciﬁed pipeline. The following procedure explains how to list pipelines and how to view settings for a pipeline by using the console.

For information about how to use the API to:

• List pipelines for the current AWS account, see List Pipelines (p. 152).

• Get settings for a speciﬁed pipeline, see Read Pipeline (p. 157).

To list pipelines and view pipeline settings using the Elastic Transcoder console 1. Sign in to the AWS Management Console and open the Elastic Transcoder console at https://

2. In the navigation bar of the Elastic Transcoder console, select the region in which you want to list jobs.

3. In the navigation (left) pane of the console, click Pipelines. The right pane lists the pipelines that are associated with the current account.

4. To display detailed information about a pipeline, click the icon next to the pipeline.

Deleting an Elastic Transcoder Pipeline

You can delete a pipeline by using the AWS Management Console or by using the Elastic Transcoder Delete Pipeline API. The following procedure explains how to delete pipelines using the console. For information about how to delete pipelines using the API, see Delete Pipeline (p. 174).

NoteYou can't delete a pipeline that contains unprocessed jobs.

To delete a pipeline using the Elastic Transcoder console

2. In the navigation bar of the Elastic Transcoder console, select the region that contains the pipeline that you want to delete.

3. In the navigation (left) pane of the console, click Pipelines.

4. Select the check box for the pipeline that you want to delete.

5. Click Remove.

Settings that You Specify When You Create an Elastic Transcoder Pipeline

When you create a pipeline using the Elastic Transcoder console, you can specify the following values.

Topics

(16)

• Region (p. 11)

• General Settings (p. 11)

• Conﬁgure Amazon S3 Bucket for Transcoded Files and Playlists (p. 11)

• Conﬁgure Amazon S3 Bucket for Thumbnails (p. 13)

• Notiﬁcations (p. 15)

Region

Elastic Transcoder creates your pipeline in the region you are in. Choose the region you plan to run jobs in.

General Settings

Pipeline Name

The name of the pipeline. We recommend that the name be unique within the AWS account, but uniqueness is not enforced. The maximum length of a pipeline name is 40 characters.

Input Bucket

The Amazon S3 bucket in which you saved the media ﬁles that you want to transcode and the graphics ﬁles, if any, that you want to use for watermarks.

IAM Role

The IAM Amazon Resource name (ARN) for the role that you want Elastic Transcoder to use to transcode jobs for this pipeline.

AWS KMS Key ARN

The AWS Key Management Service (AWS KMS) key that you want to use with this pipeline.

If you use either s3 or s3-aws-kms as your Encryption:Mode, you don't need to provide a key with your job because a default key, known as an AWS-KMS key, is created for you automatically. You need to provide an AWS-KMS key only if you want to use a non-default AWS-KMS key, or if you are using an Encryption:Mode of aes-pkcs7, aes-ctr, or aes-gcm.

Conﬁgure Amazon S3 Bucket for Transcoded Files and Playlists

Use the settings in this section to specify the Amazon S3 bucket in which you want Elastic Transcoder to save transcoded files and playlists for jobs that are submitted to this pipeline, the Amazon S3 storage class that you want to assign to the files, which users you want to have access to the files, and the type of access you want users to have.

Bucket

The Amazon S3 bucket in which you want Elastic Transcoder to save transcoded ﬁles and playlists (if applicable) for jobs that you submit to this pipeline.

Storage Class

The Amazon S3 storage class, Standard or Reduced Redundancy, that you want Elastic Transcoder to assign to the transcoded ﬁles and playlists that it stores in your Amazon S3 bucket. For more information, see Reduced Redundancy Storage in the Amazon Simple Storage Service User Guide.

(17)

Grantee Type

Specify how you want to identify the users or groups that you want to have access to transcoded ﬁles and playlists. When you select a grantee type, the Grantee Type ﬁeld appears:

• Canonical: The value of Grantee is either the canonical user ID for an AWS account or an origin access identity for an Amazon CloudFront distribution. For more information about canonical user IDs, see Access Control List (ACL) Overview in the Amazon Simple Storage Service User Guide.

For more information about using CloudFront origin access identities to require that users use CloudFront URLs instead of Amazon S3 URLs, see Using an Origin Access Identity to Restrict Access to Your Amazon S3 Content in the Amazon CloudFront Developer Guide.

Important

A canonical user ID is not the same as an AWS account number.

• Email: The value of Grantee is the registered email address of an AWS account.

• Group: The value of Grantee is one of the following predeﬁned Amazon S3 groups: AllUsers, AuthenticatedUsers, or LogDelivery.

Grantee

The AWS user or group that you want to have access to transcoded ﬁles and playlists. To identify the user or group, you can specify the canonical user ID for an AWS account, an origin access identity for a CloudFront distribution, the registered email address of an AWS account, or a predeﬁned Amazon S3 group. For more information, see Grantee Type.

Access

The permission that you want to give to the AWS user that you speciﬁed in Grantee. Permissions are granted on the transcoded ﬁles and playlists that Elastic Transcoder adds to the bucket. Valid values include:

• Open/Download: The grantee can read the objects and metadata for transcoded ﬁles and playlists that Elastic Transcoder adds to the Amazon S3 bucket.

• View Permissions: The grantee can read the object ACL for transcoded ﬁles and playlists that Elastic Transcoder adds to the Amazon S3 bucket.

• Edit Permissions: The grantee can write the ACL for transcoded ﬁles and playlists that Elastic Transcoder adds to the Amazon S3 bucket.

• Full Control: The grantee has permissions to read objects, and view and edit the ACL for transcoded ﬁles and playlists that Elastic Transcoder adds to the Amazon S3 bucket.

(18)

Conﬁgure Amazon S3 Bucket for Thumbnails

Use the settings in this section to specify the Amazon S3 bucket in which you want Elastic Transcoder to save thumbnails for jobs that are submitted to this pipeline, the Amazon S3 storage class that you want to assign to the thumbnails, which users you want to have access to the thumbnails, and the type of access you want users to have.

Bucket

The Amazon S3 bucket in which you want Elastic Transcoder to save thumbnails for jobs that you submit to this pipeline.

Storage Class

The Amazon S3 storage class, Standard or Reduced Redundancy, that you want Elastic Transcoder to assign to the thumbnails that it stores in your Amazon S3 bucket. For more information, see Reduced Redundancy Storage in the Amazon Simple Storage Service User Guide.

Grantee Type

Specify how you want to identify the users or groups that you want to have access to thumbnails.

When you select a grantee type, the Grantee Type ﬁeld appears:

• Canonical: The value of Grantee is either the canonical user ID for an AWS account or an origin access identity for an Amazon CloudFront distribution. For more information about canonical user IDs, see Access Control List (ACL) Overview in the Amazon Simple Storage Service User Guide.

For more information about using CloudFront origin access identities to require that users use

(19)

CloudFront URLs instead of Amazon S3 URLs, see Using an Origin Access Identity to Restrict Access to Your Amazon S3 Content in the Amazon CloudFront Developer Guide.

Important

A canonical user ID is not the same as an AWS account number.

• Email: The value of Grantee is the registered email address of an AWS account.

• Group: The value of Grantee is one of the following predeﬁned Amazon S3 groups: AllUsers, AuthenticatedUsers, or LogDelivery.

Grantee

The AWS user or group that you want to have access to thumbnails. To identify the user or group, you can specify the canonical user ID for an AWS account, an origin access identity for a CloudFront distribution, the registered email address of an AWS account, or a predeﬁned Amazon S3 group. For more information, see Grantee Type.

Access

The permission that you want to give to the AWS user that you speciﬁed in Grantee. Permissions are granted on the thumbnails that Elastic Transcoder adds to the bucket. Valid values include:

• Open/Download: The grantee can read the objects and metadata for thumbnails that Elastic Transcoder adds to the Amazon S3 bucket.

• View Permissions: The grantee can read the object ACL for thumbnails that Elastic Transcoder adds to the Amazon S3 bucket.

• Edit Permissions: The grantee can write the ACL for thumbnails that Elastic Transcoder adds to the Amazon S3 bucket.

• Full Control: The grantee has permissions to read objects, and view and edit the ACL for thumbnails that Elastic Transcoder adds to the Amazon S3 bucket.

(20)

Notiﬁcations

Use the settings in this section to conﬁgure Elastic Transcoder to notify you when the status of a job changes.

On Progressing Event

The Amazon Simple Notiﬁcation Service (Amazon SNS) topic that you want to notify when Elastic Transcoder has started to process the job.

Important

To receive notiﬁcations, you must also subscribe to the new topic in the Amazon SNS console.

Amazon SNS offers a variety of notification options, including the ability to send Amazon SNS messages to Amazon Simple Queue Service (Amazon SQS) queues. For more information, see the Amazon Simple Notification Service Developer Guide.

On Complete Event

The Amazon SNS topic that you want to notify when Elastic Transcoder has ﬁnished processing the job.

On Warning Event

The Amazon SNS topic that you want to notify when Elastic Transcoder encounters a warning condition.

(21)

On Error Event

The Amazon SNS topic that you want to notify when Elastic Transcoder encounters an error condition.

(22)

Working with Jobs

Topics

• Creating a Job in Elastic Transcoder (p. 17)

• Listing Jobs and Viewing Job Settings in Elastic Transcoder (p. 18)

• Canceling an Elastic Transcoder Job (p. 18)

• Settings that You Specify When You Create an Elastic Transcoder Job (p. 19)

A job does the work of transcoding a media file from one format into another format. When you create a job, you specify the information that Elastic Transcoder needs to perform the transcoding: which file to transcode, what to name the transcoded file, which preset to use (a preset is a template that contains the settings that you want Elastic Transcoder to apply), and so on.

Creating a Job in Elastic Transcoder

You can create a job using the AWS Management Console or using the Elastic Transcoder Create Job API action. The following procedure explains how to create a job by using the console. For information about how to create a job using the API, see Create Job (p. 179).

You can conﬁgure Elastic Transcoder to notify you when the status of a job changes, including when Elastic Transcoder starts and ﬁnishes processing a job, and when it encounters a warning or error condition. For more information, see Creating a Pipeline in Elastic Transcoder (p. 8).

You cannot update a job after you have created it. If you need to change settings in a job, cancel it, create a new job based on the one that you canceled, update the applicable values, and create the new job.

NoteBefore you can create a job, you must create the pipeline (the queue) that will manage the job. For more information about creating a pipeline, see Creating a Pipeline in Elastic Transcoder (p. 8). In addition, if you want to transcode a ﬁle using settings other than those provided in the Elastic Transcoder default presets, you must create a new preset. For more information about creating a preset, see Creating a Preset in Elastic Transcoder (p. 41).

To create a job using the Elastic Transcoder console

2. In the navigation bar of the Elastic Transcoder console, select the region corresponding to the pipeline that you want to use for the transcoding job. Pipelines are available only in the regions where they were created.

3. In the navigation (left) pane of the console, click Pipelines. (You create the job in the pipeline—the queue—that you want to use to transcode the ﬁle.)

4. On the Pipelines page, click Create New Job.

5. Enter the applicable values. For more information about each ﬁeld, see Settings that You Specify When You Create an Elastic Transcoder Job (p. 19).

6. Click Create Job. Jobs start as soon as they are created.

NoteIf a job fails with an Access Denied error, we recommend that you run the Test Role API action to determine what is causing the error. For more information, see Test Role (p. 176).

(23)

Listing Jobs and Viewing Job Settings in Elastic Transcoder

You can list the jobs in a speciﬁed pipeline or with a speciﬁed status either by using the Elastic

Transcoder console or by using the applicable API action. You can also view the settings for an individual job. The following procedure explains how to list jobs and how to view settings for a job by using the console.

Note

When you list jobs by pipeline, Elastic Transcoder lists all of the jobs that you've created in the last six months for that pipeline. When you list jobs by status, Elastic Transcoder lists all of the jobs that you created during the past six months that currently have the speciﬁed status.

For information about how to use the API to:

• List jobs in a speciﬁed pipeline, see List Jobs by Pipeline (p. 190).

• List jobs that have a speciﬁed status, see List Jobs by Status (p. 199).

• Get settings for a speciﬁed job, see Read Job (p. 208).

NoteIf you have speciﬁed more than one output for your jobs (for example, one output for the Kindle Fire and another output for the Apple iPhone 4s), you currently must use the Elastic Transcoder API to list the jobs.

To list jobs and view job settings using the Elastic Transcoder console

2. In the navigation bar of the Elastic Transcoder console, select the region in which you want to list jobs.

3. In the navigation (left) pane of the console, click Jobs.

4. On the Jobs page, specify the applicable values. For more information about a ﬁeld, click the icon next to the ﬁeld.

5. Click Search.

6. To display detailed information about a job that is listed in the search results, click the icon next to the job.

Canceling an Elastic Transcoder Job

You can cancel a job that still has a status of Submitted, which means that Elastic Transcoder hasn't started to transcode your ﬁle. The following procedure explains how to cancel a job using the Elastic Transcoder console.

To cancel a job using the API, pause the corresponding pipeline so Elastic Transcoder doesn't start processing the job, list jobs that have a status of Submitted to get the applicable job ID, then cancel the job using the job ID to identify which job you want to cancel. For more information, see:

• Update Pipeline Status (p. 168)

• List Jobs by Status (p. 199)

(24)

• Cancel Job (p. 217)

To cancel a job using the Elastic Transcoder console

2. In the navigation bar of the Elastic Transcoder console, select the region in which you want to cancel a job.

3. Optional but recommended: Pause the pipeline to which you submitted the job, so Elastic

Transcoder doesn't begin to process the job. You can't cancel a job after Elastic Transcoder begins to process it.

a. In the navigation (left) pane, click Pipelines.

b. Select the check box next to the pipeline that you want to pause.

c. Click Pause.

4. In the navigation pane of the console, click Jobs.

5. On the Jobs page, specify the following values:

Search By Click Status.

Job Status

Select Submitted.

NoteYou can only cancel a job that has a status of Submitted.

For Order and Number of Jobs, enter the applicable values.

6. Click Search.

7. In the search results, if you need to view more details about a job to determine whether it's the one you want to cancel, click the icon next to the job.

8. To cancel a job, select the check box next to the job, and click Cancel.

9. If you paused the pipeline in Step 3, reactivate it so it resumes processing jobs.

a. In the navigation pane, click Pipelines.

b. Select the check box next to the pipeline that you want to reactivate.

c. Click Activate.

Settings that You Specify When You Create an Elastic Transcoder Job

When you create a job using the Elastic Transcoder console, you can specify the following values.

NoteYou can configure Elastic Transcoder to notify you when the status of a job changes, including when Elastic Transcoder starts and finishes processing a job, and when Elastic Transcoder encounters a warning or error condition. For more information, see Notifications of Job Status (p. 84).

Topics

(25)

• Region (p. 20)

• General Settings (p. 20)

• Input Details, Part 1 (p. 20)

• Input Details, Part 2, Clip and Caption Settings (p. 22)

• Output Details, Part 1 (p. 24)

• Output Details, Part 2 (p. 26)

• Output Details, Part 3, Caption Settings (p. 27)

• (Optional) Output Encryption (p. 28)

• (Video/Thumbnails Only) Watermarks (p. 30)

• (FLAC/MP3/MP4 Only) Album Art (p. 31)

• (Optional) User Metadata (p. 34)

• (Fragmented MP4/MPEG-TS Outputs Only) Playlist (p. 35)

• (Fragmented MP4/MPEG-TS Outputs Only, Optional) HLS Content Protection (p. 36)

• (HLSv3 and Smooth Playlists Only, Optional) Digital Rights Management (p. 38)

Region

Elastic Transcoder creates your job in the region you are in.

General Settings

Pipeline

The name of the pipeline that you want Elastic Transcoder to use for transcoding. The pipeline determines several settings, including the Amazon S3 bucket from which Elastic Transcoder gets the ﬁles to transcode and the bucket into which Elastic Transcoder puts the transcoded ﬁles.

Output Key Preﬁx

The value, if any, that you want Elastic Transcoder to prepend to the names of all files that this job creates, including output files, thumbnails, and playlists. If you specify a value, it must contain a / somewhere after the first character, which simplifies Amazon S3 file management.

Input Details, Part 1

Use the settings in this section to specify information about the input files. If you provide more than one input file, Elastic Transcoder transcodes them and then stitches them together into one output file. For more information, see Clip Stitching (p. 86).

(26)

Input Key

The name of the files that you want to transcode. To determine from which Amazon S3 bucket to get the file, Elastic Transcoder refers to the Input Bucket field in the pipeline that you specified for this job.

If a file name includes a prefix—for example, cooking/lasagna.mpg—include the prefix in the key.

If the ﬁle isn't in the speciﬁed bucket, Elastic Transcoder returns an error.

Input Decryption

The encryption settings, if any, that are used for decrypting your input files. If your input file is encrypted, you must specify the mode that Elastic Transcoder will use to decrypt your file.

Decryption Mode (Required for Decryption)

The speciﬁc encryption mode that you want Elastic Transcoder to use when decrypting your ﬁles.

Elastic Transcoder supports the following options:

• Amazon S3 Server-Side Encryption: Amazon S3 handles the encryption and decryption of your ﬁles. As long as Elastic Transcoder has access permissions to your Amazon S3 bucket, you don't need to take any action.

For more information, see Protecting Data Using Server-Side Encryption in the Amazon Simple Storage Service User Guide.

• Client-Side Encryption Using Customer-Provided Keys: Elastic Transcoder supports three types of encryption using customer-provided keys:

• aes-cbc-pkcs7: A padded cipher-block mode of operation.

• aes-ctr: AES Counter Mode.

• aes-gcm: AES Galois Counter Mode, a mode of operation that is an authenticated encryption format, meaning that a ﬁle, key, or initialization vector that has been tampered with will fail the decryption process.

If you chose one of the AES-encryption modes, you must also specify the following three values (all three must be base64-encoded):

• Encryption Key

• Encryption Key MD5

• Encryption Initialization Vector Decryption Key (Required for AES Decryption)

The data encryption key used to encrypt your ﬁle. The key must be base64-encoded and it must be one of the following bit lengths before being base64-encoded:

96 (AES-GCM only), 128, 192, or 256.

The key must also be encrypted by using AWS KMS. For more information, see Encrypting and Decrypting Data in the AWS Key Management Service Developer Guide.

Decryption Key MD5 (Required for AES Decryption)

The MD5 digest of the key used to encrypt your input ﬁle, and that you want Elastic Transcoder to use as a checksum to make sure your key was not corrupted in transit. The key MD5 must be base64- encoded, and it must be exactly 16 bytes before being base64-encoded.

Decryption Initialization Vector (Required for AES Decryption)

The series of random bits created by a random bit generator, unique for every encryption operation, that you used to encrypt your input ﬁles. The initialization vector must be base64-encoded, and it must be exactly 16 bytes before being base64-encoded.

For more information, go to Initialization Vector.

(27)

Input Details, Part 2, Clip and Caption Settings

Use the settings in this section to specify information about clips and captions for the input ﬁles. These settings are available only when you provide multiple inputs.

For more information on captions, see Captions (p. 87) (Optional) Clip Start Time

You can create an output file that contains an excerpt from the input file. Clip Start Time indicates the place in the input file where you want a clip to start. The format can be either HH:mm:ss.SSS (maximum value: 23:59:59.999; SSS is thousandths of a second) or sssss.SSS (maximum value:

86399.999). If you don't specify a value, Elastic Transcoder starts at the beginning of the input ﬁle.

(Optional) Clip Duration

The duration of your excerpt clip. The format can be either HH:mm:ss.SSS (maximum value:

23:59:59.999; SSS is thousandths of a second) or sssss.SSS (maximum value: 86399.999). If you don't specify a value, Elastic Transcoder clips from Clip Start Time to the end of the ﬁle.

If you specify a value longer than the duration of the input ﬁle, Elastic Transcoder transcodes from Clip Start Time to the end of the ﬁle and returns a warning message.

(Video Only) Captions Merge Policy

A policy that determines how Elastic Transcoder handles the existence of multiple captions.

• MergeOverride: Elastic Transcoder transcodes both embedded and sidecar captions into outputs.

If captions for a language are embedded in the input ﬁle and also appear in a sidecar ﬁle, Elastic Transcoder uses the sidecar captions and ignores the embedded captions for that language.

• MergeRetain: Elastic Transcoder transcodes both embedded and sidecar captions into outputs.

If captions for a language are embedded in the input file and also appear in a sidecar file, Elastic Transcoder uses the embedded captions and ignores the sidecar captions for that language. If Caption Source is empty, Elastic Transcoder omits all sidecar captions from the output files.

• Override: Elastic Transcoder transcodes only the sidecar captions that you specify in Caption Source.

(28)

(Video Only, Optional) Input Key

The name of the sidecar caption ﬁle that you want Elastic Transcoder to transcode and include with the outputs.

(Video Only) Language

A string that speciﬁes the language of the caption in one of the following formats:

• 2-character ISO 639-1 code, for example, en for English

• 3-character ISO 639-2 code, for example, eng for English

For more information on ISO language codes, see List of ISO 639-1 codes.

(Video Only, Optional) TimeOﬀset

For clip generation or captions that do not start at the same time as the associated video ﬁle, the TimeOﬀset tells Elastic Transcoder how much of the video to encode before including captions.

Specify the TimeOﬀset in the form [+-]SS.sss or [+-]HH:mm:SS.ss.

(Video Only, Optional) Label

The label of the caption shown in the player when choosing a language. We recommend that you put the caption language name here, in the language of the captions.

(29)

Output Details, Part 1

Use the settings in this section to specify information about the output ﬁles.

Preset

The preset that you want to use for this output. The preset determines the audio, video, and thumbnail settings that Elastic Transcoder uses for transcoding.

(Fragmented MP4/MPEG-TS Outputs Only) Segment Duration

If you specify a preset for the current output for which the value of Container is either ts (MPEG-TS) or fmp4 (Fragmented MP4), Segment Duration is the target maximum duration of each segment in seconds. For HLSv3 format playlists, each media segment is stored in a separate .ts ﬁle. For HLSv4, MPEG-DASH, and Smooth playlists, all media segments for an output are stored in a single ﬁle. Each

(30)

segment is approximately the length of the Segment Duration, though individual segments might be shorter or longer.

The range of valid values is 1 to 60 seconds. If the duration of the video is not evenly divisible by Segment Duration, the duration of the last segment is the remainder of:

total length/Segment Duration

Elastic Transcoder creates an output-speciﬁc playlist for each HLS output that you specify in Output Keys. To add an output to a master playlist for this job, include it in Outputs in Master Playlist.

Elastic Transcoder applies this segmenting to any captions associated with the output video.

For more information, see HTTP Live Streaming or Smooth Streaming Technical Overview.

Output Key

The name that you want Elastic Transcoder to assign to the transcoded file and playlist. Elastic Transcoder saves the file or files in the Amazon S3 bucket specified by the Bucket field in the pipeline that you specify in Pipeline (p. 20). If the bucket already contains a file that has the specified name, the output fails. However, other outputs in the same job might succeed.

The format for file names depends on the container type and whether the segment duration is set. If the container type is not ts or the segment duration is not provided, the name of the output file is a concatenation of Output Key Prefix and Output Key.

If the container type is ts and segment duration is provided, Elastic Transcoder uses the value of Output Key to name both the playlist for the output and the .ts ﬁles:

• Playlist:

• HLSv3: The file name is a concatenation of Output Key Prefix and Output Key plus the file name extension .m3u8:

Output Key PreﬁxOutput Key.m3u8

• HLSv4: The file name is a concatenation of Output Key Prefix and Output Key plus the file name extension _v4.m3u8. Video outputs create a second file with a file name that is a concatenation of Output Key Prefix and Output Key plus the file name extension _iframe.m3u8:

Output Key PreﬁxOutput Key_v4.m3u8

Output Key PreﬁxOutput Key_iframe.m3u8 (Video only)

• Segment (.ts) ﬁles:

• HLSv3: The file name is a concatenation of Output Key Prefix and Output Key, plus a five-digit sequential counter beginning with 00000, and the file name extension .ts:

Output Key PreﬁxOutput Key00000.ts

• HLSv4: The file name is a concatenation of Output Key Prefix and Output Key plus the file name extension .ts:

Output Key PreﬁxOutput Key.ts

If a segmented ts output is not included in a master playlist, Elastic Transcoder treats the output as HLSv3.

NoteElastic Transcoder automatically appends the relevant file extension to outputs in an HLSv3 or HLSv4 playlist. If you include a file extension in the Output Key for HLSv3 or HLSv4 playlist outputs, the filename will have two extensions.

(31)

Output Key Prefix groups all of the files for a job together in your Amazon S3 bucket. If you want to group the files for each output within a job, you can include a prefix in the value of Output Key, for example:

OutputKeyPreﬁxiPhone/Key00000.ts OutputKeyPreﬁxKindleFireHD/Key00000.ts Segment Filename Preview

The name of the ﬁrst segment ﬁle, based on the value that you entered for Output Key.

Output Details, Part 2

Use the settings in this section to specify information about the output ﬁles.

(Video Only) Create Thumbnails

If you want Elastic Transcoder to create thumbnails for your videos, select Yes, and specify the format for the ﬁle names in the Thumbnail Filename Pattern ﬁeld.

(Video Only) Thumbnail Filename Pattern

If you selected Yes for Thumbnail Filename Pattern, specify the format for the ﬁle names. You can specify the following values in any sequence:

• {count} (Required): A ﬁve-digit number beginning with 00001 that indicates where a given thumbnail appears in the sequence of thumbnails for a transcoded ﬁle. You must include {count}

somewhere in the field. If you omit it, Elastic Transcoder automatically appends the count to the end of the file name, immediately before the file name extension (.jpg or .png).

• (Optional) Literal values: You can specify literal values anywhere in the field, for example, as a file name prefix or as a delimiter between {resolution} and {count}.

• (Optional) {resolution}: If you want Elastic Transcoder to include the resolution in the ﬁle name, include {resolution} in the ﬁeld.

The Thumbnail Filename Preview ﬁeld displays a sample of ﬁle names for thumbnails based on the value that you entered in Thumbnail Filename Pattern.

When creating thumbnails, Elastic Transcoder automatically saves the files in the format (.jpg or .png) that appears in the preset that you specified in Preset (p. 24). Elastic Transcoder also appends the applicable file name extension.

(Video/Thumbnails Only, Optional) Output Rotation

The number of degrees clockwise by which you want Elastic Transcoder to rotate the output relative to the input. If you want Elastic Transcoder to automatically detect whether the input ﬁle is rotated,

(32)

select auto. Note, however, that Elastic Transcoder generally can only detect whether the output needs to be rotated if the ﬁle that you're transcoding contains rotation metadata.

Output Details, Part 3, Caption Settings

Use the settings in this section to specify information about captions for the output ﬁles.

For more information on captions, see Captions (p. 87).

(Video Only) Caption Format

The format you specify determines whether Elastic Transcoder generates an embedded or sidecar caption for this output. If you leave this value blank, Elastic Transcoder returns an error.

• Embedded Caption Formats: For MP4 containers, mov-text and CEA-708 are supported. For MPEG-TS containers, CEA-708 is supported. For other container types, no embedded caption formats are supported.

CEA-708 captions are embedded in the H.264 SEI user data of the stream. Elastic Transcoder supports a maximum of one embedded format per output.

• Sidecar Caption Formats: Elastic Transcoder supports dfxp, scc, srt, and webvtt. Fmp4 containers with Smooth playlists support only dfxp, and Elastic Transcoder creates a ﬁle with the extension .ismt. Fmp4 containers with MPEG-DASH playlists support only webvtt, and Elastic Transcoder creates a ﬁle with the extension .vtt. If you want ttml or smpte-tt compatible captions, specify dfxp as your output format.

(33)

(Video Only) Captions Filename Pattern

The preﬁx for caption ﬁlenames, in the form description-{language}, where:

• description is a description of the video.

• {language} is a literal value that Elastic Transcoder replaces with the two- or three-letter code for the language of the caption in the output ﬁle names.

If you don't include {language} in the ﬁle name pattern, Elastic Transcoder automatically appends

"{language}" to the value that you specify for the description. In addition, Elastic Transcoder automatically appends the count to the end of the segment ﬁles.

For example, suppose you're transcoding into srt format. When, you enter "Sydney-{language}- sunrise", and the language of the captions is English (en), the name of the ﬁrst caption ﬁle will be Sydney-en-sunrise00000.srt.

(Video Only) Captions Filename Preview

The name of the first caption file, based on the value that you entered for Captions Filename Pattern. The preview uses the English ISO code "en" to show how {language} will look in your file name.

(Optional) Output Encryption

You can specify encryption settings for any output ﬁles that you want to use for a transcoding job. This includes the output ﬁle and any watermarks, thumbnails, album art, or captions that you want to use.

You must specify encryption settings for each ﬁle individually.

Output Encryption

The encryption settings, if any, that you want Elastic Transcoder to apply to your output ﬁles. If you choose to use encryption, you must specify a mode to use. If you choose not to use encryption, Elastic Transcoder will write an unencrypted ﬁle to your Amazon S3 bucket.

(Required for ﬁle-level Encryption) Encryption Mode

The speciﬁc encryption mode that you want Elastic Transcoder to use when encrypting your output ﬁles individually. Elastic Transcoder supports the following Encryption Mode options:

• s3: Amazon S3 creates and manages the keys used for encrypting your ﬁles.

(34)

For more information, see Protecting Data Using Server-Side Encryption in the Amazon Simple Storage Service User Guide.

• s3-aws-kms: Amazon S3 calls AWS KMS, which creates and manages the keys that are used for encrypting your ﬁles. If you specify s3-aws-kms and you don't want to use the default key, you must add the AWS-KMS key that you want to use to your pipeline.

For more information, see Protecting Data Using Server-Side Encryption with AWS KMS-Managed Keys in the Amazon Simple Storage Service User Guide.

• aes-cbc-pkcs7: A padded cipher-block mode of operation.

• aes-ctr: AES Counter Mode.

• aes-gcm: AES Galois Counter Mode, a mode of operation that is an authenticated encryption format, meaning that a ﬁle, key, or initialization vector that has been tampered with will fail the decryption process.

If you chose one of the AES-encryption modes, you must also specify the following three values (all three must be base64-encoded):

• Encryption Key

• Encryption Key MD5

• Encryption Initialization Vector

If you chose one of the AES-encryption modes, and you want Elastic Transcoder to generate a 128- bit AES encryption key for you, do not specify values for the Encryption Key, Encryption Key MD5, or Encryption Initialization Vector. Once Elastic Transcoder has generated the key, you can retrieve the key by calling ReadJob. The key is not included in the CreateJobResponse object.

Important

For the AES modes, your media-speciﬁc private encryption keys and your unencrypted data are never stored by AWS; therefore, it is important that you safely manage your encryption keys. If you lose them, you won't be able to decrypt your data.

(Optional) Encryption Key

If you want Elastic Transcoder to generate a key for you, leave this ﬁeld blank. Once Elastic Transcoder has generated the key, you can retrieve the key by calling Read Job. The key is not included in the Create Job Response object.

If you choose to supply your own key, you must encrypt the key by using AWS KMS. The key must be base64-encoded, and it must be one of the following bit lengths before being base64-encoded:

96 (AES-GCM only), 128, 192, or 256.

If you conﬁgured Elastic Transcoder to generate a key for you, Elastic Transcoder leaves this ﬁeld blank in the Create Job response. To retrieve your generated data encryption key, submit a Read Job request.

For more information about encrypting your key with AWS KMS, see Encrypting and Decrypting Data in the AWS Key Management Service Developer Guide.

(Required if an Encryption Key is supplied) Encryption Key MD5

The MD5 digest of the key that you want Elastic Transcoder to use to encrypt your output ﬁle, and that you want Elastic Transcoder to use as a checksum to make sure your key was not corrupted in transit. The key MD5 must be base64-encoded, and it must be exactly 16 bytes before being base64- encoded.

If Elastic Transcoder is generating your key for you, you must leave this ﬁeld blank.

(35)

(Required if an Encryption Key is supplied) Encryption Initialization Vector

The series of random bits created by a random bit generator, unique for every encryption operation, that you want Elastic Transcoder to use to encrypt your output ﬁles. The initialization vector must be base64-encoded, and it must be exactly 16 bytes before being base64-encoded.

If Elastic Transcoder is generating your key for you, you must leave this ﬁeld blank.

For more information, go to Initialization Vector.

(Video/Thumbnails Only) Watermarks

Information about the watermarks that you want Elastic Transcoder to add to the video during transcoding. You can specify up to four watermarks for each output. Settings for each watermark must be deﬁned in the preset that you specify in Preset for the current output.

Watermarks are added to the output video in the sequence in which you list them in the job output—

the first watermark in the list is added to the output video first, the second watermark in the list is added next, and so on. As a result, if the settings in a preset cause Elastic Transcoder to place all watermarks in the same location, the second watermark that you add will cover the first one, the third one will cover the second, and the fourth one will cover the third.

For more information about watermarks, see Watermarks (p. 88).

(36)

Preset Watermark ID

The ID of the watermark settings that Elastic Transcoder uses to add watermarks to the video during transcoding. The settings are in the preset speciﬁed by Preset for the current output. In that preset, the value of Watermarks Id tells Elastic Transcoder which settings to use.

Input Key for Preset Watermark Id

The name of the .png or .jpg file that you want to use for the watermark. To determine which Amazon S3 bucket contains the specified file, Elastic Transcoder checks the pipeline specified by Pipeline; the Input Bucket object in that pipeline identifies the bucket.

If the file name includes a prefix, for example, logos/128x64.png, include the prefix in the key. If the file isn't in the specified bucket, Elastic Transcoder returns an error.

(FLAC/MP3/MP4 Only) Album Art

The album art to be associated with the output ﬁle, if any.

To remove artwork or leave the artwork empty, you can either set Artwork to null, or set the Merge Policy to "Replace" and use an empty Artwork array.

To pass through existing artwork unchanged, set the Merge Policy to "Prepend", "Append", or "Fallback", and use an empty Artwork array.

NoteAlbum art is available for audio-only outputs in flac, mp3, or mp4 containers.

(37)

Album Art Merge Policy

A policy that determines how Elastic Transcoder will handle the existence of multiple album artwork ﬁles.

• Replace: The speciﬁed album art will replace any existing album art.

• Prepend: The speciﬁed album art will be placed in front of any existing album art.

• Append: The speciﬁed album art will be placed after any existing album art.

• Fallback: If the input ﬁle contains artwork, Elastic Transcoder will use that artwork for the output.

If the input does not contain artwork, Elastic Transcoder will use the speciﬁed album art ﬁle.

Album Art Artwork

The ﬁle to be used as album art. There can be multiple artworks associated with an audio ﬁle, to a maximum of 20.

Album Art Input Key

The name of the file to be used as album art. To determine which Amazon S3 bucket contains the specified file, Elastic Transcoder checks the pipeline specified by PipelineId; the InputBucket object in that pipeline identifies the bucket.

If the file name includes a prefix, for example, cooking/pie.jpg, include the prefix in the key. If the file isn't in the specified bucket, Elastic Transcoder returns an error.

Album Art Format

The format of album art, if any. Valid formats are jpg and png.

Album Art Max Width

The maximum width of the output album art in pixels. If you specify auto, Elastic Transcoder uses 600 as the default value. If you specify a numeric value, enter an even integer between 32 and 4096, inclusive.

Album Art Max Height

The maximum height of the output album art in pixels. If you specify auto, Elastic Transcoder uses 600 as the default value. If you specify a numeric value, enter an even integer between 32 and 3072, inclusive.

Album Art Sizing Policy

A value that controls scaling of the output album art:

• Fit: Elastic Transcoder scales the output art so it matches the value that you speciﬁed in either MaxWidth or MaxHeight without exceeding the other value.

• Fill: Elastic Transcoder scales the output art so it matches the value that you speciﬁed in either MaxWidth or MaxHeight and matches or exceeds the other value. Elastic Transcoder centers the output art and then crops it in the dimension (if any) that exceeds the maximum value.

• Stretch: Elastic Transcoder stretches the output art to match the values that you speciﬁed for MaxWidth and MaxHeight. If the relative proportions of the input art and the output art are diﬀerent, the output art will be distorted.

• Keep: Elastic Transcoder does not scale the output art. If either dimension of the input art exceeds the values that you speciﬁed for MaxWidth and MaxHeight, Elastic Transcoder crops the output art.

• ShrinkToFit: Elastic Transcoder scales the output art down so that its dimensions match the values that you speciﬁed for at least one of MaxWidth and MaxHeight without exceeding either value. If you specify this option, Elastic Transcoder does not scale the art up.

• ShrinkToFill: Elastic Transcoder scales the output art down so that its dimensions match the values that you speciﬁed for at least one of MaxWidth and MaxHeight without dropping below either value. If you specify this option, Elastic Transcoder does not scale the art up.

The following table shows possible eﬀects of SizingPolicy settings on the output album art:

(38)

SizingPolicy Output Album Art May Be Scaled Up

Output Album Art May Be Padded When Padding Policy Is

"Pad"

Output Album Art May Have a Diﬀerent Pixel Aspect Ratio than Input Album Art

Output Album Art May Be Cropped

Fit Yes Yes

Fill Yes Yes

Stretch Yes Yes

Keep Yes Yes Yes

ShrinkToFit Yes

ShrinkToFill Yes Yes

Album Art Padding Policy

When you set PaddingPolicy to Pad, Elastic Transcoder might add white bars to the top and bottom and/or left and right sides of the output album art to make the total size of the output art match the values that you speciﬁed for MaxWidth and MaxHeight. For more information, see the table at AlbumArt:Art:SizingPolicy.

(39)

(Optional) User Metadata

User-deﬁned metadata that you want to associate with an Elastic Transcoder job. You specify metadata in key/value pairs. You can use the key/value pairs to track details about a ﬁle, for example, Season 1: Episode 3.

You can add up to 10 key/value pairs to each job. Elastic Transcoder does not guarantee that key/value pairs are returned in the same order in which you specify them.

Metadata Key

The key of the metadata key/value pair that you want returned with the output ﬁle. Each key must be a unique string between 1-128 characters, and must use only characters from the following list:

• 0-9

• A-Z and a-z

• Space

• The following symbols: _.:/=+-%@

You can use keys as a numbering system for organizing your metadata, for storing an extra 128 characters of metadata, or for labeling the metadata stored in the value. If you want to use only value metadata, you can put throw-away strings in your keys such as key1, and ignore the keys when you retrieve your metadata from Elastic Transcoder.

Important

You must specify unique strings for all of the keys in a job. If the same string is used for more than one key in a job, Elastic Transcoder returns only one of the key/value pairs that use that key. There is no way to guarantee which value is returned.

Metadata Value

The value of the metadata key/value pair that you want returned with your job. Each value must be a string between 0-256 characters, and must use only characters from the following list:

• 0-9

• A-Z and a-z

• Space

Amazon Elastic Transcoder

Amazon Elastic Transcoder

Developer Guide

API Version 2012-09-25

Amazon Elastic Transcoder: Developer Guide

Table of Contents

What is Amazon Elastic Transcoder?

Accessing Elastic Transcoder

Regions and Endpoints

Choosing a Region for Your Elastic Transcoder Resources

Limits on the Number of Elastic Transcoder Pipelines, Jobs, and Presets

Getting Started with Elastic Transcoder

Step 1: Sign Up for AWS

Step 2: Create an Amazon S3 Bucket or Two, and Upload a Media File

Step 3: Create a Pipeline

Step 4: (Optional) Create a Preset

Step 5: Create a Job

Step 6: Monitor the Progress of Your Job

Working with Pipelines

Creating a Pipeline in Elastic Transcoder

Pausing and Reactivating Pipelines in Elastic Transcoder

Updating Pipeline Notiﬁcations in Elastic Transcoder

Listing and Viewing Pipelines in Elastic Transcoder

Deleting an Elastic Transcoder Pipeline

Settings that You Specify When You Create an Elastic Transcoder Pipeline

Region

General Settings

Conﬁgure Amazon S3 Bucket for Transcoded Files and Playlists

Conﬁgure Amazon S3 Bucket for Thumbnails

Notiﬁcations

Working with Jobs

Creating a Job in Elastic Transcoder

Listing Jobs and Viewing Job Settings in Elastic Transcoder

Canceling an Elastic Transcoder Job

Settings that You Specify When You Create an Elastic Transcoder Job

Region

General Settings

Input Details, Part 1

Input Details, Part 2, Clip and Caption Settings

Output Details, Part 1

Output Details, Part 2

Output Details, Part 3, Caption Settings

(Optional) Output Encryption

(Video/Thumbnails Only) Watermarks

(FLAC/MP3/MP4 Only) Album Art

(Optional) User Metadata