Amazon Elastic Transcoder
Developer Guide (API Version 2012-09-25)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

Create Job

Description

To create a job, send a POST request to the /2012-09-25/jobs resource. Jobs start as soon as you create them.

Note

You 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 Create Pipeline.

Requests

Syntax

POST /2012-09-25/jobs HTTP/1.1
Content-Type: application/json; charset=UTF-8
Accept: */*
Host: elastictranscoder.Elastic Transcoder endpoint.amazonaws.com:443
x-amz-date: 20130114T174952Z
Authorization: AWS4-HMAC-SHA256 
               Credential=AccessKeyID/request-date/Elastic Transcoder endpoint/ets/aws4_request,
               SignedHeaders=host;x-amz-date;x-amz-target,
               Signature=calculated-signature
Content-Length: number of characters in the JSON string
{
   "Input":{
      "Key":"name of the file to transcode",
      "Encryption":{
         "Mode":"AES-CBC-PKCS7|AES-CTR|AES-GCM",
         "Key":"encrypted and base64-encoded decryption key",
         "KeyMd5":"base64-encoded key digest",
         "InitializationVector":"base64-encoded initialization vector"
      },
      "FrameRate":"auto|10|15|23.97|24|25|29.97|30|50|60",
      "Resolution":"auto",
      "AspectRatio":"auto|1:1|4:3|3:2|16:9",
      "Interlaced":"auto|true|false",
      "Container":"auto|3gp|aac|asf|avi|divx|flv|m4a|mkv|mov|mp3|
         mp4|mpeg|mpeg-ps|mpeg-ts|mxf|ogg|vob|wav|webm"
   },
   "OutputKeyPrefix":"prefix for file names in Amazon S3 bucket",
   "Outputs":[
      {
         "Key":"name of the transcoded file",
         "Encryption":{
            "Mode":"S3|S3-AWS-KMS|AES-CBC-PKCS7|AES-CTR|
               AES-GCM",
            "Key":"encrypted and base64-encoded encryption key",
            "KeyMd5":"base64-encoded key digest",
            "InitializationVector":"base64-encoded initialization vector"
         },
         "ThumbnailPattern":""|"pattern",
         "Rotate":"auto|0|90|180|270",
         "PresetId":"preset to use for the job",
         "SegmentDuration":"[1,60]",
         "Watermarks":[
            {
               "InputKey":"name of the .png or .jpg file",
               "Encryption":{
                  "Mode":"S3|S3-AWS-KMS|AES-CBC-PKCS7|
                     AES-CTR|AES-GCM",
                  "Key":"encrypted and base64-encoded encryption key",
                  "KeyMd5":"base64-encoded key digest",
                  "InitializationVector":"base64-encoded initialization 
                     vector"
               },
               "PresetWatermarkId":"value of Video:Watermarks:Id in preset"
            },
            {...}
         ],
         "AlbumArt":[
            {
               "AlbumArtMerge":"Replace|Prepend|Append|Fallback",
               "AlbumArtArtwork":"can be empty, but not null":[
                  {
                     "AlbumArtInputKey":"name of the file to use as album 
                        art",
                     "Encryption":{
                        "Mode":"S3|S3-AWS-KMS|AES-CBC-PKCS7|
                           AES-CTR|AES-GCM",
                        "Key":"encrypted and base64-encoded encryption key",
                        "KeyMd5":"base64-encoded key digest",
                        "InitializationVector":"base64-encoded
                           initialization vector"
                     },
                     "AlbumArtMaxWidth":"maximum width of output album art
                        in pixels",
                     "AlbumArtMaxHeight":"maximum height of output album
                        art in pixels",
                     "AlbumArtSizingPolicy":"Fit|Fill|Stretch|Keep|
                        ShrinkToFit|ShrinkToFill",
                     "AlbumArtPaddingPolicy":"Pad|NoPad",
                     "AlbumArtFormat":"jpg|png"
                  },
                  {...}
               ]
            },
            {...}
         ],
         "Composition":[
            {
               "TimeSpan":
                  {
                     "StartTime":"starting place of the clip, in
                        HH:mm:ss.SSS or sssss.SSS",
                     "Duration":"duration of the clip, in HH:mm:ss.SSS
                        or sssss.SSS"
                  }
            }
         ],
         "Captions":{
            "MergePolicy":"MergeOverride|MergeRetain|Override",
            "CaptionSources":[
               {
                  "Key":"name of the input caption file",
                  "Encryption":{
                     "Mode":"S3|S3-AWS-KMS|AES-CBC-PKCS7|
                        AES-CTR|AES-GCM",
                     "Key":"encrypted and base64-encoded encryption key",
                     "KeyMd5":"base64-encoded key digest",
                     "InitializationVector":"base64-encoded 
                        initialization vector"
                  },
                  "Language":"language of the input caption file",
                  "TimeOffset":"starting place of the captions, in 
                     either [-+]SS.sss or [-+]HH:mm:SS.ss",
                  "Label":"label for the caption"
               },
               {...}
            ],
            "CaptionFormats":[
               {
                  "Format":"dfxp|mov-text|scc|srt|webvtt",
                  "Pattern":"myCaption/file-language",
                  "Encryption":{
                     "Mode":"S3|S3-AWS-KMS|AES-CBC-PKCS7|
                        AES-CTR|AES-GCM",
                     "Key":"encrypted and base64-encoded encryption key",
                     "KeyMd5":"base64-encoded key digest",
                     "InitializationVector":"base64-encoded 
                        initialization vector"
                  }
               },
               {...}
            ]
         }
      },
      {...}
   ],
   "Playlists":[
      {
         "Format":"HLSv3|HLSv4|Smooth",
         "Name":"name", 
         "OutputKeys":[
            "Outputs:Key to include in this playlist",
            ...
         ]
      },
      {...}
   ],
   "UserMetadata": 
      {
         "Key":"Value",
         "Second user metadata key":"Second user metadata value"
      },
   "PipelineId":"pipeline to use for transcoding"
}

Request Parameters

This operation does not use request parameters.

Request Headers

This operation uses only request headers that are common to all operations. For information about common request headers, see HTTP Header Contents.

Request Body

The JSON string in the request body contains the following objects.

Input

Information about the file that you're transcoding.

Input:Key

The name of the file that you want to transcode. 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/lasagna.mpg, include the prefix in the key. If the file isn't in the specified bucket, Elastic Transcoder returns an error.

Input:Encryption (Optional)

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.

Input:Encryption:Mode (Required for Encryption)

The specific encryption mode that you want Elastic Transcoder to use when decrypting your files.

Elastic Transcoder supports the following options:

  • Amazon S3 Server-Side Encryption: Amazon S3 handles the encryption and decryption of your files. 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 Developer Guide.

  • Server-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 originally used for HLS files.

    • AES-CTR: AES Counter Mode, a mode of operation used in some versions of PlayReady DRM.

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

    For all three types you must provide the following settings, which must be base64-encoded:

    • Key

    • Key MD5

    • Initialization Vector

Input:Encryption:Key (Required for AES Encryption)

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

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.

Input:Encryption:KeyMd5 (Required for AES Encryption)

The MD5 digest of the key that you used to encrypt your input file, 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 long before being base64-encoded.

Input:Encryption:InitializationVector (Required for AES Encryption)

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

For more information, go to Initialization Vector.

Input:FrameRate (Optional)

The frame rate of the input file. If you want Elastic Transcoder to automatically detect the frame rate of the input file, specify auto. If you want to specify the frame rate for the input file, enter one of the following values:

10, 15, 23.97, 24, 25, 29.97, 30, 50, 60

The default value is auto.

Input:Resolution (Optional)

The resolution, in pixels, of the input file. This value must be auto, which causes Elastic Transcoder to automatically detect the resolution of the input file.

Input:AspectRatio (Optional)

The aspect ratio of the input file. If you want Elastic Transcoder to automatically detect the aspect ratio of the input file, specify auto. If you want to specify the aspect ratio for the output file, enter one of the following values:

1:1, 4:3, 3:2, 16:9

The default value is auto.

Input:Interlaced (Optional)

Whether the input file is interlaced. If you want Elastic Transcoder to automatically detect whether the input file is interlaced, specify auto. If you want to specify whether the input file is interlaced, enter one of the following values:

true, false

The default value is auto.

Input:Container (Optional)

The container type for the input file. If you want Elastic Transcoder to automatically detect the container type of the input file, specify auto. If you want to specify the container type for the input file, enter one of the following values:

3gp, aac, asf, avi, divx, flv, m4a, mkv, mov, mp3, mp4, mpeg, mpeg-ps, mpeg-ts, mxf, ogg, vob, wav, webm

OutputKeyPrefix

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.

Outputs

Information about the output files. You can create a maximum of 30 outputs per job. If you specify more than one output for a job, Elastic Transcoder creates the files for each output in the order in which you specify them in the job.

Note

In early versions of Elastic Transcoder you could create just one output per job, so the object name was Output. The Output syntax still works, but we recommend that you use the Outputs syntax for all jobs, even when you want Elastic Transcoder to transcode a file into only one format. Do not use both the Outputs and Output syntaxes in the same request.

Outputs: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 OutputBucket object in the pipeline that you specify in PipelineId.

If the bucket already contains a file that has the specified name, the output fails. In the Create Job response, the value of Outputs:Status for that output will be Error, as will the final value of Status for the job. However, other outputs in the same job may succeed.

The format for file names depends 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 OutputKeyPrefix and Key.

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

  • Playlist:

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

      OutputKeyPrefixKey.m3u8

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

      OutputKeyPrefixKey_v4.m3u8

      OutputKeyPrefixKey_iframe.m3u8

  • Segment (.ts) files:

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

      OutputKeyPrefixKey00000.ts

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

      OutputKeyPrefixKey.ts

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

Note

Elastic Transcoder automatically appends the relevant file extension to the file name (.m3u8 for HLSv3 playlists, _v4.m3u8 and _iframe.m3u8 for HLSv4 playlists). If you include a file extension in Output Key, the file name will have two extensions.

OutputKeyPrefix 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 Key, for example:

OutputKeyPrefixiPhone/Key00000.ts

OutputKeyPrefixKindleFireHD/Key00000.ts

Outputs:Encryption (Optional)

The encryption settings, if any, that you want Elastic Transcoder to apply to your output files. 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 file to your Amazon S3 bucket.

Outputs:Encryption:Mode (Required for Encryption)

The specific server-side encryption mode that you want Elastic Transcoder to use when encrypting your output files. Elastic Transcoder supports the following options:

  • S3: Amazon S3 creates and manages the keys used for encrypting your files.

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

  • S3-AWS-KMS: Amazon S3 calls AWS KMS, which creates and manages the keys that are used for encrypting your files. 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 Developer Guide.

  • AES-CBC-PKCS7: A padded cipher-block mode of operation originally used for HLS files.

  • AES-CTR: AES Counter Mode, a mode of operation used in some versions of PlayReady DRM.

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

For all three AES options, you must provide the following settings, which must be base64-encoded:

  • Key

  • Key MD5

  • Initialization Vector

Important

For the AES modes, your 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.

Outputs:Encryption:Key (Required for AES Encryption)

The data encryption key that you want Elastic Transcoder to use to encrypt your output file. The key must be base64-encoded and it must be one of the following bit lengths before being base64-encoded:

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.

Outputs:Encryption:KeyMd5 (Required for AES Encryption)

The MD5 digest of the key that you want Elastic Transcoder to use to encrypt your output file, 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 long before being base64-encoded.

Outputs:Encryption:InitializationVector (Required for AES Encryption)

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 files. The initialization vector must be base64-encoded, and it must be exactly 16 bytes long before being base64-encoded.

For more information, go to Initialization Vector.

Outputs:ThumbnailPattern (Optional, Sidecar only)

Whether you want Elastic Transcoder to create thumbnails for your videos and, if so, how you want Elastic Transcoder to name the files.

If you don't want Elastic Transcoder to create thumbnails, specify "".

If you do want Elastic Transcoder to create thumbnails, specify the information that you want to include in the file name for each thumbnail. You can specify the following values in any sequence:

  • {count} (Required): If you want to create thumbnails, you must include {count} in the ThumbnailPattern object. Wherever you specify {count}, Elastic Transcoder adds a five-digit sequence number (beginning with 00001) to thumbnail file names. The number indicates where a given thumbnail appears in the sequence of thumbnails for a transcoded file.

    Important

    If you specify a literal value and/or {resolution} but you omit {count}, Elastic Transcoder returns a validation error and does not create the job.

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

  • {resolution} (Optional): If you want Elastic Transcoder to include the resolution in the file name, include {resolution} in the ThumbnailPattern object.

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

As with Outputs:Key, you can include a prefix in ThumbnailPattern that groups the applicable files together, for example, all of the thumbnails for one video in one format, or all of the thumbnails with the corresponding output file.

Outputs:Rotate (Optional)

The number of degrees clockwise by which you want Elastic Transcoder to rotate the output relative to the input. Valid values include:

auto, 0, 90, 180, 270

The value auto generally works only if the file that you're transcoding contains rotation metadata.

Outputs:PresetId

The value of the Id object for the preset that you want to use for this job. The preset determines the audio, video, and thumbnail settings that Elastic Transcoder uses for transcoding. To use a preset that you created, specify the preset ID that Elastic Transcoder returned in the response when you created the preset.

Note

If you created any presets before AAC profiles were added, Elastic Transcoder will use the AAC-LC profile for those presets.

For a list of system presets, see System Presets (You can also get these IDs using List Presets.)

Outputs:SegmentDuration (Fragmented MP4/MPEG-TS Outputs Only)

If you specify a preset for the current output for which the value of Container is fmp4 (Fragmented MP4) or ts (MPEG-TS), SegmentDuration is the target maximum duration of each segment in seconds. For HLSv3 format playlists, each media segment is stored in a separate .ts file. For HLSv4 and Smooth playlists, all media segments for an output are stored in a single file. Each segment is approximately the length of the SegmentDuration, 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 SegmentDuration, the duration of the last segment is the remainder of:

total length/SegmentDuration

Elastic Transcoder creates an output-specific playlist for each HLS output that you specify in OutputKeys. 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.

Outputs:Watermarks (Video Only)

Information about the watermarks that you want Elastic Transcoder to add to the video or artwork during transcoding. You can specify up to four watermarks for each output. Settings for each watermark must be defined in the preset that you specify in Outputs:PresetId for the current output.

Watermarks are added to the output file in the sequence in which you list them in the job output—the first watermark in the list is added to the output file 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 list in Outputs:Watermarks 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.

Outputs:Watermarks:InputKey (Video Only)

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 PipelineId; the InputBucket 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.

Outputs:Watermarks:PresetWatermarkId (Video Only)

The ID of the watermark settings that Elastic Transcoder uses to add watermarks to the file during transcoding. The settings are in the preset specified by Outputs:PresetId for the current output. In that preset, the value of Watermarks:Id tells Elastic Transcoder which settings to use.

Outputs:AlbumArt (MP3/MP4 Only)

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

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

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

Note

Album Art is available only for containers of type mp3 or mp4.

Outputs:AlbumArt:MergePolicy (MP3/MP4 Only)

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

  • Replace: The specified album art will replace any existing album art.

  • Prepend: The specified album art will be placed in front of any existing album art.

  • Append: The specified album art will be placed after any existing album art.

  • Fallback: If the input file contains artwork, Elastic Transcoder will use that artwork for the output. If the input does not contain artwork, Elastic Transcoder will use the specified album art file.

Outputs:AlbumArt:Artwork (MP3/MP4 Only)

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

Outputs:AlbumArt:Artwork:InputKey (MP3/MP4 Only)

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.

Outputs:AlbumArt:Artwork:MaxWidth (MP3/MP4 Only)

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.

Outputs:AlbumArt:Artwork:MaxHeight (MP3/MP4 Only)

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.

Outputs:AlbumArt:Artwork:SizingPolicy (MP3/MP4 Only)

A value that controls scaling of the output album art:

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

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

  • Stretch: Elastic Transcoder stretches the output art to match the values that you specified for MaxWidth and MaxHeight. If the relative proportions of the input art and the output art are different, 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 specified 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 specified 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 specified 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 effects of SizingPolicy settings on the output album art:

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 Different 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

Outputs:AlbumArt:Artwork:PaddingPolicy (MP3/MP4 Only)

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 specified for MaxWidth and MaxHeight. For more information, see the table at AlbumArt:Art:SizingPolicy.

Outputs:AlbumArt:Artwork:AlbumArtFormat (MP3/MP4 Only)

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

Outputs:Composition

Using a composition, you can create an output file that contains an excerpt from the input file. This excerpt, called a clip, can come from the beginning, middle, or end of the file. The Composition object contains settings for the clips that make up an output file.

Currently, you can specify settings for only a single clip per output file. The Composition object cannot be null. All jobs in a playlist must have the same clip settings.

Outputs:Composition:TimeSpan

Settings that determine when a clip begins and how long it lasts.

Outputs:Composition:TimeSpan:StartTime

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 file.

Outputs:Composition:TimeSpan:Duration

The duration of the 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 creates an output file from StartTime to the end of the file.

If you specify a value longer than the duration of the input file , Elastic Transcoder transcodes the file and returns a warning message.

Outputs:Captions (Video Only)

You can configure Elastic Transcoder to transcode captions, or subtitles, from one format to another. All captions must be in UTF-8. Elastic Transcoder supports two types of captions:

  • Embedded: Embedded captions are included in the same file as the audio and video. Elastic Transcoder supports only one embedded caption per language, to a maximum of 300 embedded captions per file.

    Valid input values include: CEA-608 (EIA-608, first non-empty channel only), CEA-708 (EIA-708, first non-empty channel only), and mov-text

    Valid outputs include: mov-text

    Elastic Transcoder supports a maximum of one embedded format per output.

  • Sidecar: Sidecar captions are kept in a separate metadata file from the audio and video data. Sidecar captions require a player that is capable of understanding the relationship between the video file and the sidecar file. Elastic Transcoder supports only one sidecar caption per language, to a maximum of 20 sidecar captions per file.

    Valid input values include: dfxp (first div element only), ebu-tt, scc, smpt, srt, ttml (first div element only), and webvtt

    Valid outputs include: dfxp (first div element only), scc, srt, and webvtt.

If you want ttml or smpte-tt compatible captions, specify dfxp as your output format.

Elastic Transcoder does not support OCR (Optical Character Recognition), does not accept pictures as a valid input for captions, and is not available for audio-only transcoding. Elastic Transcoder does not preserve text formatting (for example, italics) during the transcoding process.

To remove captions or leave the captions empty, set Captions to null. To pass through existing captions unchanged, set the MergePolicy to MergeRetain, and pass in a null CaptionSources array.

For more information on embedded files, see the Subtitle (caption) Wikipedia page.

For more information on sidecar files, see the Metadata Platform and Sidecar file Wikipedia pages.

Outputs:Captions:MergePolicy (Video Only)

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 file and also appear in a sidecar file, 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 CaptionSources is empty, Elastic Transcoder omits all sidecar captions from the output files.

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

MergePolicy cannot be null.

Outputs:Captions:CaptionSources (Video/Sidecar Only, Optional)

Source files for the input sidecar captions used during the transcoding process. To omit all sidecar captions, leave CaptionSources blank.

Outputs:Captions:CaptionSources:Key (Video Only)

The name of the sidecar caption file that you want Elastic Transcoder to include with the outputs.

Outputs:Captions:CaptionSources:Language (Video Only)

A string that specifies the language of the caption. Specify this as one of:

  • 2-character ISO 639-1 code

  • 3-character ISO 639-2 code

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

Outputs:Captions:CaptionSources:TimeOffset (Video Only, Optional)

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

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

Outputs:Captions:CaptionSources:Label (Video Only, Optional)

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.

Outputs:Captions:CaptionFormats (Video Only)

The file format of the output captions. If you leave this value blank, Elastic Transcoder returns an error.

Outputs:Captions:CaptionFormats:Format (Video Only)

The format you specify determines whether Elastic Transcoder generates an embedded or sidecar caption for this output.

  • Embedded Caption Formats:

    Container Type

    Supported Embedded types

    MP3

    None

    MP4

    mov-text

    MPEG-TS

    None

    ogg

    None

    webm

    None

    Elastic Transcoder supports a maximum of one embedded format per output.

  • Sidecar Caption Formats: Elastic Transcoder supports dfxp (first div element only), scc, srt, and webvtt. If you want ttml or smpte-tt compatible captions, specify dfxp as your output format.

    Container Type

    Supported Sidecar types

    fmp4

    dfxp

    Non-fmp4 containers

    All sidecar types

Note

fmp4 captions have an extension of .ismt

Outputs:Captions:CaptionFormats:Pattern (Video/Sidecar Only)

The prefix for caption filenames, 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 file names.

If you don't include {language} in the file 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 files.

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 first caption file will be Sydney-en-sunrise00000.srt.

Outputs:UserMetadata (Optional)

User-defined 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 file, 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 will be returned in the same order in which you specify them.

Outputs:UserMetadata:Key

The key of the metadata key/value pair that you want returned with the output file. 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 will return only one of the key/value pairs that use that key. There is no way to guarantee which value is returned.

Outputs:UserMetadata: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

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

Playlists (Fragmented MP4/MPEG-TS Outputs Only)

If you specify a preset in PresetId for which the value of Container is fmp4 (Fragmented MP4) or ts (MPEG-TS), Playlists contains information about the master playlists that you want Elastic Transcoder to create.

We recommend that you create at most one master playlist per playlist format. The maximum number of master playlists in a job is 30.

Playlists:Format

The format of the output playlist. Valid formats include HLSv3, HLSv4, and Smooth.

Playlists:Name

The name that you want Elastic Transcoder to assign to a master playlist, for example, nyc-vacation.m3u8. If the name includes a / character, the section of the name before the / must be identical for all Name objects. If you create more than one master playlist, the values of all Name objects must be unique.

Note

Elastic Transcoder automatically appends the relevant file extension to the file name (.m3u8 for HLSv3 playlists, _v4.m3u8 and _iframe.m3u8 for HLSv4 playlists, and .ism and .ismc for Smooth playlists). If you include a file extension in Name, the file name will have two extensions.

Any segment duration settings, clip settings, or caption settings must be the same for all outputs in the playlist. For Smooth playlists, the Audio:Profile, Video:Profile, and Video:FrameRate to Video:KeyframesMaxDist ratio must be the same for all outputs. For more information, see KeyframesMaxDist.

Playlists:OutputKeys

For each output in this job that you want to include in a master playlist, the value of the Outputs:Key object. If you include more than one output in a playlist, the value of SegmentDuration for all of the outputs must be the same.

For HLSv4 master playlists, Elastic Transcoder chooses which combinations of audio and video inputs will be linked in the output playlists. The first audio and video inputs will be linked and rendered as the default playback experience, allowing you to choose your preferred playback default. For other individual playlists in the master playlist, Elastic Transcoder chooses which audio and video bit rate combinations will provide the best playback.

PipelineId

The value of the Id object for 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 files to transcode and the bucket into which Elastic Transcoder puts the transcoded files.

Responses

Syntax

Status: 201 Created
x-amzn-RequestId: c321ec43-378e-11e2-8e4c-4d5b971203e9
Content-Type: application/json
Content-Length: number of characters in the response
Date: Mon, 14 Jan 2013 06:01:47 GMT

{
   "Job":{
      "Id":"Id that Elastic Transcoder assigns to the job",
      "Input":{
         "Key":"name of the file to transcode",
         "Encryption":{
            "Mode":"AES-CBC-PKCS7|AES-CTR|AES-GCM",
            "Key":"encrypted and base64-encoded decryption key",
            "KeyMd5":"base64-encoded key digest",
            "InitializationVector":"base64-encoded initialization vector"
         },
         "FrameRate":"auto|10|15|23.97|24|25|29.97|30|50|60",
         "Resolution":"auto|width in pixelsxheight in pixels",
         "AspectRatio":"auto|1:1|4:3|3:2|16:9",
         "Interlaced":"auto|true|false",
         "Container":"auto|3gp|aac|asf|avi|divx|flv|m4a|mkv|mov|mp3|
            mp4|mpeg|mpeg-ps|mpeg-ts|mxf|ogg|vob|wav|webm"
      },
      "OutputKeyPrefix":"prefix for file names in Amazon S3 bucket",
      "Outputs":[
         {
            "Id":"sequential counter",
            "Key":"name of the transcoded file",
            "Encryption":{
               "Mode":"S3|S3-AWS-KMS|AES-CBC-PKCS7|
                  AES-CTR|AES-GCM",
               "Key":"encrypted and base64-encoded encryption key",
               "KeyMd5":"base64-encoded key digest",
               "InitializationVector":"base64-encoded initialization
                  vector"               
            },
            "ThumbnailPattern":""|"pattern",
            "Rotate":"auto|0|90|180|270",
            "PresetId":"preset to use for the job",
            "SegmentDuration":"[1,60]",
            "Watermarks":[
               {
                  "InputKey":"name of the .png or .jpg file",
                  "Encryption":{
                     "Mode":"S3|S3-AWS-KMS|AES-CBC-PKCS7|
                        AES-CTR|AES-GCM",
                     "Key":"encrypted and base64-encoded encryption key",
                     "KeyMd5":"base64-encoded key digest",
                     "InitializationVector":"base64-encoded initialization
                        vector"
                  },
                  "PresetWatermarkId":"value of Video:Watermarks:Id in preset"
               },
               {...}
            ],
            "AlbumArt":[
               {
                  "AlbumArtMerge":"Replace|Prepend|Append|Fallback",
                  "AlbumArtArtwork":"can be empty, but not null":[
                     {
                        "AlbumArtInputKey":"name of the file to use as album
                           art",
                        "Encryption":{
                           "Mode":"S3|S3-AWS-KMS|AES-CBC-PKCS7|
                              AES-CTR|AES-GCM",
                           "Key":"encrypted and base64-encoded encryption 
                              key",
                           "KeyMd5":"base64-encoded key digest",
                           "InitializationVector":"base64-encoded 
                              initialization vector"
                        },
                        "AlbumArtMaxWidth":"maximum width of output album art
                           in pixels",
                        "AlbumArtMaxHeight":"maximum height of output album
                           art in pixels",
                        "AlbumArtSizingPolicy":"Fit|Fill|Stretch|Keep|
                           ShrinkToFit|ShrinkToFill",
                        "AlbumArtPaddingPolicy":"Pad|NoPad",
                        "AlbumArtFormat":"jpg|png"
                     },
                     {...}
                  ]
               },
               {...}
            ],
            "Composition":[
               {
                  "TimeSpan":
                     {
                        "StartTime":"starting place of the clip, in 
                           HH:mm:ss.SSS or sssss.SSS",
                        "Duration":"duration of the clip, in HH:mm:ss.SSS
                           or sssss.SSS"
                     }
               }
            ],   
            "Duration":"duration in seconds",
            "Width":"width in pixels",
            "Height":"height in pixels",
            "Status":"Submitted|Progressing|Complete|Canceled|Error",
            "StatusDetail":"additional information about job status"
            "Captions":
               {
                  "MergePolicy":"MergeOverride|MergeRetain|Override",
                  "CaptionSources":[
                     {
                        "Key":"name of the input caption file",
                        "Encryption":{
                           "Mode":"S3|S3-AWS-KMS|AES-CBC-PKCS7|
                              AES-CTR|AES-GCM",
                           "Key":"encrypted and base64-encoded encryption 
                              key",
                           "KeyMd5":"base64-encoded key digest",
                           "InitializationVector":"base64-encoded 
                              initialization vector"
                        },
                        "Language":"language of the input caption file",
                        "TimeOffset":"starting place of the captions, in
                           either [-+]SS.sss or [-+]HH:mm:SS.ss",
                        "Label":"label for the caption"
                     },
                     {...}
                  ],
                  "CaptionFormats":[
                     {
                        "Format":"dfxp|mov-text|scc|srt|webvtt",
                        "Pattern":"myCaption/file-language",
                        "Encryption":{
                           "Mode":"S3|S3-AWS-KMS|AES-CBC-PKCS7|
                              AES-CTR|AES-GCM",
                           "Key":"encrypted and base64-encoded encryption 
                              key",
                           "KeyMd5":"base64-encoded key digest",
                           "InitializationVector":"base64-encoded 
                              initialization vector"
                        }
                     },
                     {...}
                  ]
               }
         },
         {...}
      ],
      "Playlists":[
         {
            "Format":"HLSv3|HLSv4|Smooth",
            "Name":"name",
            "OutputKeys":[
               "Outputs:Key to include in this playlist",
               ...
            ]
         },
         {...}
      ],
      "UserMetadata":
         {
            "key1":"First user metadata value",
            "key2":"Second user metadata value"
         },
      "PipelineId":"pipeline to add the job to",
      "Status":"Submitted|Progressing|Complete|Canceled|Error"
   }
}

Response Headers

This operation uses only response headers that are common to most responses. For information about common response headers, see HTTP Responses.

Response Body

When you create a job, Elastic Transcoder returns the values that you specified in the request. For more information, see Request Body.

In addition, Elastic Transcoder returns the following values.

Id

The identifier that Elastic Transcoder assigned to the job. You use this value to get settings for the job or to delete the job.

Input

Information about the file that Elastic Transcoder transcoded. These are values that you specified when you created the job.

Outputs

Information about the output files. You can create a maximum of 30 outputs per job. If you specify more than one output for a job, Elastic Transcoder creates the files for each output in the order in which you specify them in the job. The Outputs:Id object identifies the position of an output in the sequence.

Note

In early versions of Elastic Transcoder, you could create just one output per job, so the object name was Output. The Output syntax still works, but we recommend that you use the Outputs syntax for all jobs, even when you want Elastic Transcoder to transcode a file into only one format. Do not use both the Outputs and Output syntaxes in the same request.

Outputs:Id

A sequential counter, starting with 1, that identifies an output among the outputs from the current job. In the Output syntax, this value is always 1.

Outputs:Encryption (Optional)

The encryption settings, if any, that you want Elastic Transcoder to apply to your output files. 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 file to your Amazon S3 bucket.

Outputs:Encryption:Mode (Required for Encryption)

The specific server-side encryption mode that you want Elastic Transcoder to use when encrypting your output files. Elastic Transcoder supports the following options:

  • S3: Amazon S3 creates and manages the keys used for encrypting your files.

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

  • S3-AWS-KMS: Amazon S3 calls AWS KMS, which creates and manages the keys that are used for encrypting your files. 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 Developer Guide.

  • AES-CBC-PKCS7: A padded cipher-block mode of operation originally used for HLS files.

  • AES-CTR: AES Counter Mode, a mode of operation used in some versions of PlayReady DRM.

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

For all three AES options, you must provide the following settings, which must be base64-encoded:

  • Key

  • Key MD5

  • Initialization Vector

Important

For the AES modes, your 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.

Outputs:Encryption:Key (Required for AES Encryption)

The data encryption key that you want Elastic Transcoder to use to encrypt your output file. The key must be base64-encoded and it must be one of the following bit lengths before being base64-encoded:

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.

Outputs:Encryption:KeyMd5 (Required for AES Encryption)

The MD5 digest of the key that you want Elastic Transcoder to use to encrypt your output file, 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 long before being base64-encoded.

Outputs:Encryption:InitializationVector (Required for AES Encryption)

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 files. The initialization vector must be base64-encoded, and it must be exactly 16 bytes long before being base64-encoded.

For more information, go to Initialization Vector.

Outputs:Duration

Duration of the output file, in seconds.

Outputs:Width

Width of the output file, in pixels.

Outputs:Height

Height of the output file, in pixels.

Outputs:Status

The status of one output in a job. If you specified only one output for the job, Outputs:Status is always the same as Job:Status. If you specified more than one output:

  • Job:Status and Outputs:Status for all of the outputs is Submitted until Elastic Transcoder starts to process the first output.

  • When Elastic Transcoder starts to process the first output, Outputs:Status for that output and Job:Status both change to Progressing. For each output, the value of Outputs:Status remains Submitted until Elastic Transcoder starts to process the output.

  • Job:Status remains Progressing until all of the outputs reach a terminal status, either Complete or Error.

  • When all of the outputs reach a terminal status, Job:Status changes to Complete only if Outputs:Status for all of the outputs is Complete. If Outputs:Status for one or more outputs is Error, the terminal status for Job:Status is also Error.

The value of Status is one of the following: Submitted, Progressing, Complete, Canceled, or Error.

Outputs:StatusDetail

Information that further explains Outputs:Status.

Outputs:Composition

Using a composition, you can create an output file that contains an excerpt from the input file. This excerpt, called a clip, can come from the beginning, middle, or end of the file. The Composition object contains settings for the clips that make up an output file.

Currently, you can specify settings for only a single clip per output file. The Composition object cannot be null. All jobs in a playlist must have the same clip settings.

Outputs:Composition:TimeSpan

Settings that determine when a clip begins and how long it lasts.

Outputs:Composition:TimeSpan:StartTime

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 file.

Outputs:Composition:TimeSpan:Duration

The duration of the 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 creates an output file from StartTime to the end of the file.

If you specify a value longer than the duration of the input file , Elastic Transcoder transcodes the file and returns a warning message.

Outputs:Captions (Video Only)

You can configure Elastic Transcoder to transcode captions, or subtitles, from one format to another. All captions must be in UTF-8. Elastic Transcoder supports two types of captions:

  • Embedded: Embedded captions are included in the same file as the audio and video. Elastic Transcoder supports only one embedded caption per language, to a maximum of 300 embedded captions per file.

    Valid input values include: CEA-608 (EIA-608, first non-empty channel only), CEA-708 (EIA-708, first non-empty channel only), and mov-text

    Valid outputs include: mov-text

    Elastic Transcoder supports a maximum of one embedded format per output.

  • Sidecar: Sidecar captions are kept in a separate metadata file from the audio and video data. Sidecar captions require a player that is capable of understanding the relationship between the video file and the sidecar file. Elastic Transcoder supports only one sidecar caption per language, to a maximum of 20 sidecar captions per file.

    Valid input values include: dfxp (first div element only), ebu-tt, scc, smpt, srt, ttml (first div element only), and webvtt

    Valid outputs include: dfxp (first div element only), scc, srt, and webvtt.

If you want ttml or smpte-tt compatible captions, specify dfxp as your output format.

Elastic Transcoder does not support OCR (Optical Character Recognition), does not accept pictures as a valid input for captions, and is not available for audio-only transcoding. Elastic Transcoder does not preserve text formatting (for example, italics) during the transcoding process.

To remove captions or leave the captions empty, set Captions to null. To pass through existing captions unchanged, set the MergePolicy to MergeRetain, and pass in a null CaptionSources array.

For more information on embedded files, see the Subtitle (caption) Wikipedia page.

For more information on sidecar files, see the Metadata Platform and Sidecar file Wikipedia pages.

Outputs:Captions:MergePolicy (Video Only)

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 file and also appear in a sidecar file, 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 CaptionSources is empty, Elastic Transcoder omits all sidecar captions from the output files.

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

MergePolicy cannot be null.

Outputs:Captions:CaptionSources (Video Only, Optional)

Source files for the input sidecar captions used during the transcoding process. To omit all sidecar captions, leave CaptionSources blank.

Outputs:Captions:CaptionSources:Key (Video Only)

The name of the sidecar caption file that you want Elastic Transcoder to include with the outputs.

Outputs:Captions:CaptionSources:Language (Video Only)

A string that specifies the language of the caption. Specify this as one of:

  • 2-character ISO 639-1 code

  • 3-character ISO 639-2 code

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

Outputs:Captions:CaptionSources:TimeOffset (Video Only)

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

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

Outputs:Captions:CaptionSources:Label (Video Only)

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.

Outputs:Captions:CaptionFormats (Video Only)

The file format of the output captions. If you leave this value blank, Elastic Transcoder returns an error.

Outputs:Captions:CaptionFormats:Format (Video Only)

The format you specify determines whether Elastic Transcoder generates an embedded or sidecar caption for this output.

  • Embedded Caption Formats:

    Container Type

    Supported Embedded types

    MP3

    None

    MP4

    mov-text

    MPEG-TS

    None

    ogg

    None

    webm

    None

    Elastic Transcoder supports a maximum of one embedded format per output.

  • Sidecar Caption Formats: Elastic Transcoder supports dfxp (first div element only), scc, srt, and webvtt. If you want ttml or smpte-tt compatible captions, specify dfxp as your output format.

    Container Type

    Supported Sidecar types

    fmp4

    dfxp

    Non-fmp4 containers

    All sidecar types

Note

fmp4 captions have an extension of .ismt

Outputs:Captions:CaptionFormats:Pattern (Video Only)

The prefix for caption filenames, 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 file names.

If you don't include {language} in the file 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 files.

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 first caption file will be Sydney-en-sunrise00000.srt.

Status

If you specified more than one output for the job, the status of the entire job. When Elastic Transcoder starts processing a job, the value of Job:Status changes to Progressing and doesn't change until Elastic Transcoder has finished processing all outputs. When processing is complete, Job:Status changes either to Complete or, if any of the outputs failed, to Error.

If you specified only one output for the job, Job:Status is the same as Outputs:Status.

The value of Job:Status is one of the following: Submitted, Progressing, Complete, Canceled, or Error.

Errors

For information about Elastic Transcoder exceptions and error messages, see Handling Errors in Elastic Transcoder.

Note

If 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.

Examples

The following example request creates a job that has two outputs.

Sample Request

POST /2012-09-25/jobs HTTP/1.1
Content-Type: application/json; charset=UTF-8
Accept: */*
Host: elastictranscoder.Elastic Transcoder endpoint.amazonaws.com:443
x-amz-date: 20130114T174952Z
Authorization: AWS4-HMAC-SHA256 
               Credential=AccessKeyID/request-date/Elastic Transcoder endpoint/ets/aws4_request,
               SignedHeaders=host;x-amz-date;x-amz-target,
               Signature=calculated-signature
Content-Length: number of characters in the JSON string
{
   "Input":{
      "Key":"recipes/lasagna.mp4",

      "FrameRate":"auto",
      "Resolution":"auto",
      "AspectRatio":"auto",
      "Interlaced":"auto",
      "Container":"mp4"
   },
   "OutputKeyPrefix":"recipes/",
   "Outputs":[
      {
         "Key":"mp4/lasagna-kindlefirehd.mp4",

         "ThumbnailPattern":"mp4/thumbnails/lasagna-{count}",
         "Rotate":"0",
         "PresetId":"1351620000000-100080",
         "Watermarks":[
            {
               "InputKey":"logo/128x64.png",
               "PresetWatermarkId":"company logo 128x64"

            }
         ],
         "Captions":{
            "MergePolicy":"MergeOverride",
            "CaptionSources":[
               {
                  "Key":"scc/lasagna-kindlefirehd.scc",

                  "Language":"en",
                  "Label":"English"
               },
               {
                  "Key":"srt/lasagna-kindlefirehd.srt",

                  "Language":"fr",
                  "TimeOffset":"1:00:00",
                  "Label":"French"
               }
            ],
            "CaptionFormats":[
               {
                  "Format":"scc",
                  "Pattern":"scc/lasagna-{language}"

               },
               {
                  "Format":"srt",
                  "Pattern":"srt/lasagna-{language}",

               }
            ]
         }
      },
      {
         "Key":"iphone/lasagna-1024k",
         "ThumbnailPattern":"iphone/th1024k/lasagna-{count}",

         "Rotate":"0",
         "PresetId":"1351620000000-987654",
         "SegmentDuration":"5"
      },
      {
         "Key":"iphone/lasagna-512k",
         "ThumbnailPattern":"iphone/th512k/lasagna-{count}",
         "Rotate":"0",
         "PresetId":"1351620000000-456789",
         "SegmentDuration":"5"
      },
   ],
   "Playlists": [
      {
         "Format": "HLSv3",
         "Name": "playlist-iPhone-lasagna.m3u8",
         "OutputKeys": [
            "iphone/lasagna-1024k",
            "iphone/lasagna-512k"
         ]
      }
   ],
   "UserMetadata":
      {
         "Food type":"Italian",
         "Cook book":"recipe notebook"
      },
   "PipelineId":"1111111111111-abcde1"
}

Sample Response

Status: 201 Created
x-amzn-RequestId: c321ec43-378e-11e2-8e4c-4d5b971203e9
Content-Type: application/json
Content-Length: number of characters in the response
Date: Mon, 14 Jan 2013 06:01:47 GMT

{
   "Job":{
      "Id":"3333333333333-abcde3",
      "Input":{
         "Key":"cooking/lasagna.mp4",

         "FrameRate":"auto",
         "Resolution":"auto",
         "AspectRatio":"auto",
         "Interlaced":"auto",
         "Container":"mp4"
      },
      "Outputs":[
         {
            "Id":"1",
            "Key":"mp4/lasagna-kindlefirehd.mp4",

            "ThumbnailPattern":"mp4/thumbnails/lasagna-{count}",
            "Rotate":"0",
            "PresetId":"1351620000000-100080",
            "Watermarks":[
               {
                  "InputKey":"logo/128x64.png",
                  "PresetWatermarkId":"company logo 128x64",

               }
            ],
            "Duration":"1003",
            "Width":"1280",
            "Height":"720",
            "Status":"Progressing",
            "StatusDetail":"",
            "Captions":{
               "MergePolicy":"MergeOverride",
               "CaptionSources":[
                  {
                     "Key":"scc/lasagna-kindlefirehd.scc",

                     "Language":"en",
                     "Label":"English"
                  },
                  {
                     "Key":"srt/lasagna-kindlefirehd.srt",

                     "Language":"fr",
                     "TimeOffset":"1:00:00",
                     "Label":"French"
                  }
               ],
               "CaptionFormats":[
                  {
                     "Format":"scc",
                     "Pattern":"scc/lasagna-{language}",

                  },
                  {
                     "Format":"srt",
                     "Pattern":"srt/lasagna-{language}",

                  },
                  {
                     "Format":"mov-text"
                  }
               ]
            }
         },
         {
            "Id":"2",
            "Key":"iphone/lasagna-1024k",

            "ThumbnailPattern":"iphone/th1024k/lasagna-{count}",
            "Rotate":"0",
            "PresetId":"1351620000000-987654",
            "SegmentDuration":"5",
            "Duration":"1003",
            "Width":"1136",
            "Height":"640",
            "Status":"Progressing",
            "StatusDetail":""
         },
         {
            "Id":"3",
            "Key":"iphone/lasagna-512k",
            "ThumbnailPattern":"iphone/th512k/lasagna-{count}",
            "Rotate":"0",
            "PresetId":"1351620000000-456789",
            "SegmentDuration":"5",
            "Duration":"1003",
            "Width":"1136",
            "Height":"640",
            "Status":"Complete",
            "StatusDetail":""

         }
      ],
      "Playlists":[
         {
            "Format":"HLSv3",
            "Name":"playlist-iPhone-lasagna.m3u8",
            "OutputKeys": [
               "iphone/lasagna-1024k",
               "iphone/lasagna-512k"
            ]
         }
      ],
      "UserMetadata":
         {
            "Food type":"Italian",
            "Cook book":"recipe notebook"
         },
      "PipelineId":"1111111111111-abcde1",
      "Status":"Progressing"
   }
}