Creates a custom transcoding template that covers various settings, such as the settings of a container, a video, and audio.
Usage notes
You can call this operation to set the parameters that are related to the container, audio streams, and video streams. For some parameters, if you do not specify them, streams that are generated by using the template do not have the corresponding settings.
QPS limits
You can call this operation up to 100 times per second per account. Requests that exceed this limit are dropped and you will experience service interruptions. We recommend that you take note of this limit when you call this operation. For more information, see QPS limit.
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
---|---|---|---|---|
Action | String | Yes | AddTemplate | The operation that you want to perform. Set the value to AddTemplate. |
Name | String | Yes | mps-example | The name of the template. The name can be up to 128 bytes in length. |
Container | String | No | {"Format":"mp4"} | The container configuration. The value must be a JSON object and contains the Format parameter. If you do not configure the container, the transcoded media file is in MP4 format by default. If you want to use the transcoding template to generate media files in other formats, this parameter is required. For more information, see the Parameter nested under the Container parameter section of this topic.
Note If the container format is FLV, the video codec cannot be set to H.265.
Note If the container format is GIF, the video codec must be GIF. If the container format is WebP, the video codec must be set to WebP. |
Video | String | No | {"Codec":"H.264","Profile":"high","Bitrate":"500","Crf":"15","Width":"256","Height":"800","Fps":"25","Gop":"10s"} | The video stream configuration. The value must be a JSON object. For more information, see the Parameters nested under the Video parameter section of this topic. Note If you do not set this parameter, output files do not contain video streams. If you need to retain the video streams, this parameter is required. |
Audio | String | No | {"Codec":"H.264","Samplerate":"44100","Bitrate":"500","Channels":"2"} | The audio stream configuration. The value must be a JSON object. For more information, see the Parameters nested under the Audio parameter section of this topic. Note If you do not set this parameter, output files do not contain audio streams. If you need to retain the audio streams, this parameter is required. |
TransConfig | String | No | {"TransMode":"onepass"} | The general transcoding configuration. The value must be a JSON object. For more information, see the Parameters nested under the TransConfig parameter section of this topic. If you do not set this parameter, the default settings of this parameter are used. If the default settings cannot meet your transcoding needs, set the parameters nested under the TransConfig parameter as required. |
MuxConfig | String | No | {"Segment":{"Duration":"10"}} | The segment configuration. The value must be a JSON object. For more information, see the Parameters nested under the MuxConfig parameter section of this topic. If you do not set this parameter, media segment files are not generated. If you want to generate media segment files, this parameter is required. |
Parameter |
Type |
Required |
Description |
---|---|---|---|
Format |
String |
No |
Default value: mp4. Video formats include FLV, MP4, HLS (M3U8 + TS), and MPEG-DASH (MPD + fMP4) Audio formats include MP3, MP4, Ogg, FLAC, and M4A Image formats include GIF and WebP. If you set the container format to GIF or WebP, the video codec must be respectively set to GIF or WebP. If you set the container format to FLV, the video codec cannot be set to H.265. |
Parameter |
Type |
Required |
Description |
---|---|---|---|
Codec |
String |
No |
The video codec. Valid video codecs: H.264, H.265, GIF, and WebP. Default video codec: H.264. |
Profile |
String |
No |
The codec profile. Valid values: baseline, main, and high. Default value: high. A value of baseline specifies that media files are transcoded for mobile devices. A value of main specifies that media files are transcoded for standard-resolution devices. A value of high specifies that media files are transcoded for high-resolution devices. If multiple definitions exist, we recommend that you set this parameter to baseline for the lowest definition to ensure normal playback on low-end devices. Set this parameter to main or high for other definitions. This parameter is valid only when the video codec is set to H.264. |
Bitrate |
String |
No |
The bitrate. Valid values: 10 to 50000. Unit: Kbit/s. |
Crf |
String |
No |
The constant rate factor. Valid values: 0 to 51. Default value: 26. If this parameter is returned, the setting of the Bitrate parameter is invalid. |
Width |
String |
No |
The width of the video. Default value: the width of the input video. Valid values: 128 to 4096. Unit: pixel. |
Height |
String |
No |
The height of the video. Default value: the height of the input video. Valid values: 128 to 4096. Unit: pixel. |
Fps |
String |
No |
The frame rate. By default, the frame rate of the input file is used. The value is 60 if the frame rate of the input file exceeds 60. Valid values: (0,60]. Unit: frames per second. |
Gop |
String |
No |
The group of pictures (GOP) size. The GOP size can be the maximum interval of keyframes or the maximum number of frames in a frame group. If you specify the maximum interval of keyframes, the unit (s) is required. Default value: 10s. If you specify the maximum number of frames, the value has no unit. Valid values: 1 to 100000. |
Preset |
String |
No |
The preset video algorithm. Valid values: veryfast, fast, medium, slow, and slower. Default value: medium. This parameter is valid only when the video codec is set to H.264. |
ScanMode |
String |
No |
The scan mode. Valid values: interlaced and progressive. |
Bufsize |
String |
No |
The size of the buffer. Valid values: [1000,128000]. Default value: 6000. Unit: KB. |
Maxrate |
String |
No |
The maximum video bitrate. Valid values: [10,50000]. Unit: Kbit/s. |
PixFmt |
String |
No |
The pixel format for video color encoding. Standard pixel formats such as yuv420p and yuvj420p are supported. The default pixel format can be yuv420p or the original color format. |
Remove |
String |
No |
Specifies whether to delete the video stream. A value of true specifies to delete the video stream. A value of false specifies to retain the video stream. Default value: false. |
Crop |
String |
No |
The method of video cropping. A value of border specifies to automatically detect and crop the black borders. A value in the format of width:height:left:top specifies to crop the video image based on the custom setting. Example: 1280:800:0:140. |
Pad |
String |
No |
The black borders to be added to the video. Format: width:height:left:top. Example: 1280:800:0:140. |
LongShortMode |
String |
No |
Specifies whether to enable the auto-rotate screen feature. If this feature is enabled, the width of the output video corresponds to the long side of the input video, which is the height of the input video in portrait mode. The height of the output video corresponds to the short side of the input video, which is the width of the input video in portrait mode. A value of true specifies to enable the feature. A value of false specifies to disable the feature. Default value: false. |
The following table describes the supported combinations of container formats, video codecs, and audio codecs.
Container format |
Audio codec |
Video codec |
---|---|---|
FLV |
AAC and MP3 |
H.264 |
MP4 |
AAC and MP3 |
H.264 and H.265 |
TS |
AAC and MP3 |
H.264 and H.265 |
M3U8 |
AAC and MP3 |
H.264 and H.265 |
GIF |
No |
GIF |
The following table describes the video stream parameters that are supported by different video codecs. A value of Y indicates that a parameter is supported. A value of N indicates that a parameter is not supported.
Video stream parameter/Codec |
H.264 |
H.265 |
GIF |
---|---|---|---|
Profile |
Y |
N |
N |
Bitrate |
Y |
Y |
N |
Crf |
Y |
Y |
N |
Width |
Y |
Y |
Y |
Height |
Y |
Y |
Y |
Fps |
Y |
Y |
Y |
Gop |
Y |
Y |
N |
Preset |
Y |
N |
N |
ScanMode |
Y |
Y |
Y |
Bufsize |
Y |
Y |
N |
Maxrate |
Y |
Y |
N |
PixFmt |
Y |
Y |
Y (only BGR8) |
Parameter |
Type |
Required |
Description |
---|---|---|---|
Codec |
String |
No |
The audio codec. Valid audio codecs: AAC, MP3, VORBIS, and FLAC. Default audio codec: AAC. |
Profile |
String |
No |
The codec profile of the audio. Valid values when the audio codec is set to AAC: aac_low, aac_he, aac_he_v2, aac_ld, and aac_eld. |
Samplerate |
String |
No |
The sampling rate. Valid values: 22050, 32000, 44100, 48000, and 96000. Default value: 44100. Unit: Hz. If the video container format is FLV and the audio codec is MP3, the sampling rate cannot be 32000, 48000, or 96000. If the audio codec is MP3, the sampling rate cannot be 96000. |
Bitrate |
String |
No |
The audio bitrate of the output file. Valid values:[8,1000]. Default value: 128. Unit: Kbit/s. |
Channels |
String |
No |
The number of sound channels. Default value: 2. Valid values when the audio codec is set to MP3: 1 and 2. Valid values when the audio codec is set to AAC: 1, 2, 4, 5, 6, and 8. |
Remove |
String |
No |
Specifies whether to delete the audio stream. A value of true specifies to delete the audio stream. A value of false specifies to retain the audio stream. Default value: false. |
The following table describes the supported combinations of audio codecs and container formats.
Container format |
Audio codec |
---|---|
MP3 |
MP3 |
MP4 |
AAC |
OGG |
VORBIS and FLAC |
FLAC |
FLAC |
Parameter |
Type |
Required |
Description |
---|---|---|---|
TransMode |
String |
No |
The transcoding mode. Valid values: onepass, twopass, and CBR. Default value: onepass. |
AdjDarMethod |
String |
No |
The method of resolution adjustment. Valid values: rescale, crop, pad, and none. Default value: none. |
IsCheckReso |
String |
No |
Specifies whether to check the resolution. If this feature is enabled and the system detects that the resolution of the output file is higher than that of the input file based on the width or height, the resolution of the input file is retained after transcoding. A value of true specifies to check the resolution. A value of false specifies not to check the resolution. Default value: false. |
IsCheckResoFail |
String |
No |
Specifies whether to check the resolution. If this feature is enabled and the system detects that the resolution of the output file is higher than that of the input file based on the width or height, an error that indicates a transcoding failure is returned. A value of true specifies to check the resolution. A value of false specifies not to check the resolution. Default value: false. |
IsCheckVideoBitrate |
String |
No |
Specifies whether to check the video bitrate. If this feature is enabled and the system detects that the video bitrate of the output file is greater than that of the input file, the video bitrate of the input file is retained after transcoding. A value of true specifies to check the video bitrate. A value of false specifies not to check the video bitrate. Default value: false. |
IsCheckAudioBitrate |
String |
No |
Specifies whether to check the audio bitrate. If this feature is enabled and the system detects that the audio bitrate of the output file is greater than that of the input file, the audio bitrate of the input file is retained after transcoding. A value of true specifies to check the audio bitrate. A value of false specifies not to check the audio bitrate. Default value: false. |
IsCheckAudioBitrateFail |
String |
No |
Specifies whether to check the audio bitrate. If this feature is enabled and the system detects that the audio bitrate of the output file is higher than that of the input file, the input file is not transcoded. A value of true specifies to check the audio bitrate. A value of false specifies not to check the audio bitrate. Default value: false. This parameter has a higher priority than the IsCheckAudioBitrate parameter. |
IsCheckVideoBitrateFail |
String |
No |
Specifies whether to check the video bitrate. If this feature is enabled and the system detects that the video bitrate of the output file is higher than that of the input file, the input file is not transcoded. A value of true specifies to check the video bitrate. A value of false specifies not to check the video bitrate. Default value: false. This parameter has a higher priority than the IsCheckVideoBitrate parameter. |
Parameter |
Type |
Required |
Description |
---|---|---|---|
Segment |
String |
No |
The segment configuration. The value must be a JSON object. For more information, see the following section. |
Parameter |
Type |
Required |
Description |
---|---|---|---|
Duration |
String |
No |
The length of the segment. The value must be an integer. Unit: seconds. Valid values: [1,60]. Default value: 10. |
ForceSegTime |
String |
No |
Specifies the time points at which you want to segment the media file. You can specify up to 10 time points. Separate the time points with commas (,). The time points can be accurate to three decimal places. Unit: seconds. For example, if you set this parameter to 23,55,60, the media file will be segmented at the 23rd, 55th, and 60th seconds. |
Response parameters
Parameter | Type | Example | Description |
---|---|---|---|
RequestId | String | FA258E67-09B8-4EAA-8F33-BA567834A2C3 | The ID of the request. |
Template | Object | The details of the transcoding template. |
|
Video | Object | The video codec configuration. |
|
Bufsize | String | 6000 | The size of the buffer.
|
LongShortMode | String | false | Indicates whether to enable the auto-rotate screen feature. Default value: false. Valid values:
Note If this feature is enabled, the width of the output video corresponds to the long side of the input video, which is the height of the input video in portrait mode. The height of the output video corresponds to the short side of the input video, which is the width of the input video in portrait mode. |
Degrain | String | 10 | The level of quality control on the video. |
BitrateBnd | Object | The bitrate range of the video. |
|
Max | String | 1500 | The maximum bitrate. |
Min | String | 800 | The minimum bitrate. |
PixFmt | String | yuv420p | The pixel format for video color encoding. Standard pixel formats such as yuv420p and yuvj420p are supported. The default pixel format can be yuv420p or the original color format. |
Pad | String | 1280:800:0:140 | The black borders to be added to the video. Format: width:height:left:top. |
Codec | String | H.264 | The video codec. Valid video codecs: H.264, H.265, GIF, and WebP. Default video codec: H.264. |
Height | String | 800 | The height of the video.
|
Qscale | String | 1 | The level of the independent denoising algorithm. |
Crop | String | border | The method of video cropping. Valid values:
|
Bitrate | String | 500 | The bitrate of the output video. Unit: Kbit/s. |
Maxrate | String | 500 | The maximum video bitrate. Unit: Kbit/s. |
MaxFps | String | 60 | The maximum frame rate. |
Profile | String | high | The codec profile. Valid values:
If multiple definitions exist, we recommend that you set this parameter to baseline for the lowest definition to ensure normal playback on low-end devices. Set this parameter to main or high for other definitions. Note This parameter is valid only when the video codec is set to H.264. |
Crf | String | 15 | The constant rate factor. Default value when the video codec is set to H.264: 23. Default value when the video codec is set to H.265: 26. Note If this parameter is returned, the setting of the Bitrate parameter is invalid. |
Remove | String | false | Indicates whether to delete the video stream.
|
Gop | String | 10s | The GOP size. The GOP size can be the maximum interval of keyframes or the maximum number of frames in a frame group. If you specified the maximum interval, the value contains the unit (s). If you specified the maximum number of frames, the value does not contain a unit. Default value: 10s. |
Width | String | 256 | The width of the video.
|
Fps | String | 25 | The frame rate. By default, the frame rate of the input file is used. The value is 60 if the frame rate of the input file exceeds 60. Unit: frames per second. |
Preset | String | fast | The preset video algorithm. Default value: medium. Valid values:
Note This parameter is valid only when the video codec is set to H.264. |
ScanMode | String | interlaced | The scan mode. Valid values:
|
ResoPriority | String | 0 | The policy of resolution adjustment. |
TransConfig | Object | The general transcoding configuration. |
|
IsCheckAudioBitrate | String | true | Indicates whether to check the audio bitrate. If this feature is enabled and the system detects that the audio bitrate of the output file is greater than that of the input file, the audio bitrate of the input file is retained after transcoding. In this case, the setting of the Bitrate parameter is invalid. This parameter has a lower priority than the IsCheckAudioBitrateFail parameter.
|
TransMode | String | onepass | The transcoding mode. Valid values:
|
IsCheckReso | String | true | Indicates whether to check the resolution. If this feature is enabled and the system detects that the resolution of the output file is higher than that of the input file based on the width or height, the resolution of the input file is retained after transcoding.
|
IsCheckVideoBitrateFail | String | true | Indicates whether to check the video bitrate. If the video bitrate of the output file is found to be greater than that of the input file, this parameter has a higher priority than the IsCheckVideoBitrate parameter. Valid values:
|
AdjDarMethod | String | rescale | The method of resolution adjustment. Default value: none. Valid values:
|
IsCheckVideoBitrate | String | true | Indicates whether to check the video bitrate. If this feature is enabled and the system detects that the video bitrate of the output file is greater than that of the input file, the video bitrate of the input file is retained after transcoding.
|
IsCheckResoFail | String | true | Indicates whether to check the resolution. If this feature is enabled and the system detects that the resolution of the output file is higher than that of the input file based on the width or height, an error that indicates a transcoding failure is returned.
|
IsCheckAudioBitrateFail | String | true | Indicates whether to check the audio bitrate. If the bitrate of the output audio is greater than that of the input audio, this parameter has a higher priority than the IsCheckAudioBitrate parameter.
|
State | String | Narmal | The status of the template.
|
MuxConfig | Object | The transmuxing configuration. |
|
Webp | Object | The transmuxing configuration for WebP. |
|
Loop | String | 0 | The loop count. |
Gif | Object | The transmuxing configuration for GIF. |
|
FinalDelay | String | 0 | The duration for which the final frame is paused. Unit: centiseconds. |
DitherMode | String | sierra | The color dithering algorithm of the palette. Valid values: sierra and bayer. |
Loop | String | 0 | The loop count. |
IsCustomPalette | String | false | Indicates whether the custom palette is used. |
Segment | Object | The segment configuration. |
|
Duration | String | 10 | The length of the segment. Unit: seconds. |
Name | String | mps-example | The name of the template. |
Audio | Object | The audio codec configuration. |
|
Profile | String | aac_low | The codec profile of the audio. Valid values when the audio codec is set to AAC:
|
Remove | String | true | Indicates whether to delete the audio stream.
|
Codec | String | aac | The audio codec format. Default value: aac. Valid values:
|
Samplerate | String | 44100 | The sampling rate.
|
Qscale | String | 5 | The level of the independent denoising algorithm. |
Channels | String | 2 | The number of sound channels. Default value: 2. |
Volume | Object | The details of the volume. |
|
Method | String | auto | The volume adjustment method. Valid values:
|
Level | String | -20 | The volume adjustment range.
|
Bitrate | String | 500 | The audio bitrate of the output file.
|
Id | String | 16f01ad6175e4230ac42bb5182cd**** | The ID of the transcoding template. We recommend that you keep this ID for subsequent operation calls. |
Container | Object | The container configuration. |
|
Format | String | mp4 | The format of the container. |
Examples
Sample requests
http(s)://mts.cn-hangzhou.aliyuncs.com/?Action=AddTemplate
&Name=mps-example
&Container={"Format":"mp4"}
&Video={"Codec":"H.264","Profile":"high","Bitrate":"500","Crf":"15","Width":"256","Height":"800","Fps":"25","Gop":"10s"}
&Audio={"Codec":"H.264","Samplerate":"44100","Bitrate":"500","Channels":"2"}
&TransConfig={"TransMode":"onepass"}
&MuxConfig={"Segment":{"Duration":"10"}}
&<Common request parameters>
Sample success responses
XML
format
HTTP/1.1 200 OK
Content-Type:application/xml
<AddTemplateResponse>
<RequestId>FA258E67-09B8-4EAA-8F33-BA567834A2C3</RequestId>
<Template>
<Video>
<Bufsize>6000</Bufsize>
<LongShortMode>false</LongShortMode>
<Degrain>10</Degrain>
<BitrateBnd>
<Max>1500</Max>
<Min>800</Min>
</BitrateBnd>
<PixFmt>yuv420p</PixFmt>
<Pad>1280:800:0:140</Pad>
<Codec>H.264</Codec>
<Height>800</Height>
<Qscale>1</Qscale>
<Crop>border</Crop>
<Bitrate>500</Bitrate>
<Maxrate>500</Maxrate>
<MaxFps>60</MaxFps>
<Profile>high</Profile>
<Crf>15</Crf>
<Remove>false</Remove>
<Gop>10s</Gop>
<Width>256</Width>
<Fps>25</Fps>
<Preset>fast</Preset>
<ScanMode>interlaced</ScanMode>
<ResoPriority>0</ResoPriority>
</Video>
<TransConfig>
<IsCheckAudioBitrate>true</IsCheckAudioBitrate>
<TransMode>onepass</TransMode>
<IsCheckReso>true</IsCheckReso>
<IsCheckVideoBitrateFail>true</IsCheckVideoBitrateFail>
<AdjDarMethod>rescale</AdjDarMethod>
<IsCheckVideoBitrate>true</IsCheckVideoBitrate>
<IsCheckResoFail>true</IsCheckResoFail>
<IsCheckAudioBitrateFail>true</IsCheckAudioBitrateFail>
</TransConfig>
<State>Narmal</State>
<MuxConfig>
<Webp>
<Loop>0</Loop>
</Webp>
<Gif>
<FinalDelay>0</FinalDelay>
<DitherMode>sierra</DitherMode>
<Loop>0</Loop>
<IsCustomPalette>false</IsCustomPalette>
</Gif>
<Segment>
<Duration>10</Duration>
</Segment>
</MuxConfig>
<Name>mps-example</Name>
<Audio>
<Profile>aac_low</Profile>
<Remove>true</Remove>
<Codec>aac</Codec>
<Samplerate>44100</Samplerate>
<Qscale>5</Qscale>
<Channels>2</Channels>
<Volume>
<Method>auto</Method>
<Level>-20</Level>
</Volume>
<Bitrate>500</Bitrate>
</Audio>
<Id>16f01ad6175e4230ac42bb5182cd****</Id>
<Container>
<Format>mp4</Format>
</Container>
</Template>
</AddTemplateResponse>
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"RequestId" : "FA258E67-09B8-4EAA-8F33-BA567834A2C3",
"Template" : {
"Video" : {
"Bufsize" : "6000",
"LongShortMode" : "false",
"Degrain" : "10",
"BitrateBnd" : {
"Max" : "1500",
"Min" : "800"
},
"PixFmt" : "yuv420p",
"Pad" : "1280:800:0:140",
"Codec" : "H.264",
"Height" : "800",
"Qscale" : "1",
"Crop" : "border",
"Bitrate" : "500",
"Maxrate" : "500",
"MaxFps" : "60",
"Profile" : "high",
"Crf" : "15",
"Remove" : "false",
"Gop" : "10s",
"Width" : "256",
"Fps" : "25",
"Preset" : "fast",
"ScanMode" : "interlaced",
"ResoPriority" : "0"
},
"TransConfig" : {
"IsCheckAudioBitrate" : "true",
"TransMode" : "onepass",
"IsCheckReso" : "true",
"IsCheckVideoBitrateFail" : "true",
"AdjDarMethod" : "rescale",
"IsCheckVideoBitrate" : "true",
"IsCheckResoFail" : "true",
"IsCheckAudioBitrateFail" : "true"
},
"State" : "Narmal",
"MuxConfig" : {
"Webp" : {
"Loop" : "0"
},
"Gif" : {
"FinalDelay" : "0",
"DitherMode" : "sierra",
"Loop" : "0",
"IsCustomPalette" : "false"
},
"Segment" : {
"Duration" : "10"
}
},
"Name" : "mps-example",
"Audio" : {
"Profile" : "aac_low",
"Remove" : "true",
"Codec" : "aac",
"Samplerate" : "44100",
"Qscale" : "5",
"Channels" : "2",
"Volume" : {
"Method" : "auto",
"Level" : "-20"
},
"Bitrate" : "500"
},
"Id" : "16f01ad6175e4230ac42bb5182cd****",
"Container" : {
"Format" : "mp4"
}
}
}
Error codes
For a list of error codes, see Service error codes.