This topic describes the details of some parameters used in the ApsaraVideo Media Processing (MPS) API.

Input

Note The parameters in this section are involved when you call the SubmitJobs operation.
Parameter Type Required Description
Bucket String Yes The Object Storage Service (OSS) bucket that stores the input file.

You must grant the read permissions on the bucket to MPS on the Access Control page in the OSS console. For more information, see the descriptions related to buckets in Terms.

Location String Yes The OSS region in which the OSS bucket resides.

For more information, see the description of the term region in Terms.

Object String Yes The OSS object that is used as the input file.

The URL of the OSS object must comply with RFC 2396 and be encoded in UTF-8, with reserved characters being percent-encoded. For more information about OSS objects, see the description of the term object in Terms.

Output

Note The parameters in this section and their extended parameters in some of the following sections are involved when you call the SubmitJobs operation.
Parameter Type Required Description
OutputObject String Yes The name of the OSS object that is used as the output file.
  • The URL of the OSS object must comply with RFC 2396 and be encoded in UTF-8, with reserved characters being percent-encoded.
  • Example: %7BObjectPrefix%7D%7BFileName%7Dtest.mp4. In this case, if the input file of a transcoding job is a/b/c.flv, the output file of the job is a/b/ctest.mp4.
  • The placeholders in the name of the output file will be replaced with the actual values used in business operations.
    • Placeholders supported by workflows: {ObjectPrefix}, which indicates the prefix of the input file name. {FileName}, which indicates the input file name. {ExtName}, which indicates the file name extension of the input file. {DestMd5}, which indicates the MD5 hash value of the output file. {DestAvgBitrate}, which indicates the average bitrate of the output file. {RunId}, which indicates the ID of the execution instance. {MediaId}, which indicates the ID of the input file.
    • Placeholders supported by other elements: {ObjectPrefix}, {FileName}, {ExtName}, {DestMd5}, {DestAvgBitrate}.
  • Rules on file name extensions:
    • Workflows: MPS automatically adds the file name extension to the end of the value of the OutputObject parameters based on the container format of the transcoding template.
    • Other elements: In most cases, MPS does not automatically add a file name extension. However, if the container format is M3U8, MPS adds the file name extension .m3u8 to the name of the playlist. If the playlist has corresponding segment files, MPS adds a five-digit integer that starts from 00001 as the file name suffix,
  • adds a hypen (-) before the suffix, and adds the file name extension .ts to the end of each segment file.
  • For example, if the playlist name is filename.m3u8, the name of the first output segment file is filename-00001.ts.
TemplateId String Yes The ID of the transcoding template.

You can specify a custom or preset transcoding template.

Container String No If you set this parameter, the parameter setting overwrites the setting of the corresponding parameter in the transcoding template. For more information, see the Container section in this topic.
Video String No If you set this parameter, the parameter setting overwrites the setting of the corresponding parameter in the transcoding template. For more information, see the Video section in this topic.
Audio String No If you set this parameter, the parameter setting overwrites the setting of the corresponding parameter in the transcoding template. For more information, see the Audio section in this topic.
AudioStreamMap String No The sequence number of the audio stream.
  • Format: 0:a:{Sequence number}. Example: 0:a:0.
  • The sequence number is the index of the audio stream in the list and starts from 0.
  • If you do not specify a sequence number, the default audio stream is used.
MuxConfig String No If you set this parameter, the parameter setting overwrites the setting of the corresponding parameter in the transcoding template. For more information, see the MuxConfig section in this topic.
TransConfig String No The configuration of the transcoding process. If you set this parameter, the parameter setting overwrites the setting of the corresponding parameter in the transcoding template. For more information, see the TransConfig section in this topic.
Clip String No The clip. The value must be a JSON object. For more information, see the Clip section in this topic.

Example: {"TimeSpan":{"Seek":"123.45","Duration":"3.45"}}.

WaterMarks WaterMark[] No The watermarks. The value must be a JSON array. For more information, see the WaterMarks section in this topic.
  • The JSON array can contain up to four JSON objects, which means that a job supports up to four watermarks in the job output.
  • Example: [{"InputFile":{"Bucket":"example-bucket","Location":"oss-cn-hangzhou","Object":"example-logo.png"},"WaterMarkTemplateId":"88c6ca184c0e47098a5b665e2a126797"}].
MergeList String No The configuration of clip merging. You can merge up to four clips. For more information, see the MergeList section in this topic.
  • Example of using a single clip: [{"MergeURL":"http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/tail_comm_01.mp4"}].
  • Example of merging two clips: [{"MergeURL":"http://exampleBucket****m.oss-cn-hangzhou.aliyuncs.com/tail_comm_01.mp4","Start":"1","Duration":"20"},{"MergeURL":"http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/tail_comm_02.mp4","Start":"5.4","Duration":"10.2"}].
MergeConfigUrl String No You can specify only one of the MergeList and MergeConfigUrl parameters.
  • The file that you specify for the MergeConfigUrl parameter can contain up to 50 merged clips.
  • When you set the MergeConfigUrl parameter, specify the URL of the configuration file for clip merging.
  • Example: http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/mergeConfigfile.
  • Make sure that the configuration file is stored as an object in OSS and MPS can access the OSS object. For more information, see the MergeList section in this topic.
  • Example of a configuration file: {"MergeList":[{"MergeURL":"http://jexampleBucket****.oss-cn-hangzhou.aliyuncs.com/tail_comm.mp4"}]}.
M3U8NonStandardSupport String No The non-standard support of the M3U8 format. For more information, see the M3U8NonStandardSupport section in this topic. Example: {"TS":{"Md5Support":true,"SizeSupport":true}}.
Encryption String No The encryption configuration. An encrypted file is generated in the M3U8 format.
  • Example: {"Type":"hls-aes-128","Key":"ZW5jcnlwdGlvbmtleTEyMw","KeyType":"Base64","KeyUri":"aHR0cDovL2FsaXl1bi5jb20vZG9jdW1lbnQvaGxzMTI4LmtleQ=="}.
  • For more information, see the Encryption section in this topic.
SubtitleConfig String No The subtitle configuration. The value must be a JSON object.
  • For more information, see the SubtitleConfig section in this topic.
  • Example: {"ExtSubtitleList":[{"Input":{"Bucket":"example-bucket-****","Location":"oss-cn-hangzhou","Object":"example.srt"},"CharEnc":"UTF-8"}]}.
OpeningList String No The opening parts. The value must be a JSON object.
  • For more information, see the Opening section in this topic.
  • Example: [{"OpenUrl":"http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/opening.flv","Start":"1","Width":"1920","Height":"1080"}].
TailSlateList String No The ending parts. The value must be a JSON object.
  • For more information, see the TailSlate section in this topic.
  • Example: [{"TailUrl":"http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/tail.flv","Start":"1","BlendDuration":"2","Width":"1920","Height":"1080","IsMergeAudio":false,"BgColor":"White"}].
DeWatermark String No The configuration of watermark blurring. The value must be a JSON object. For more information, see the DeWatermark section in this topic.
Amix String No The mixing configuration. This parameter is suitable for scenarios where background music is added or two audio tracks in a video are merged. For more information, see the Amix section in this topic.

If you specify this parameter, you must also specify the AudioStreamMap parameter to select the audio tracks of the input video.

The value of this parameter must be a JSON object. Example: {"AmixURL":"[{"AmixURL":"http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/tail.flv","Start":"1","Duration":"2"}]"}].
UserData Srting No The custom data, which can be up to 1,024 bytes in size.
Priority String No The priority of the job in the MPS queue to which the job is added.
  • Valid values: [1, 10].
  • A value of 10 indicates the highest priority.
  • Default value: 6.
Rotate String No The video rotation angle in the clockwise direction.

Valid values: [0, 360).

Container

Parameter Type Required Description
Format String No The container format.
  • Default value: mp4.
  • Video transcoding supports the FLV, MP4, HLS (M3U8 + TS), and MPEG-DASH (MPD + fMP4) formats.
  • Audio transcoding supports the MP3, MP4, OGG, FLAC, and M4A formats.
  • Supported image formats are GIF and WebP.
  • If the container format is GIF, the video codec must be set to GIF.
  • If the container format is WebP, the video codec must be set to WebP.
  • If the container format is FLV, the video codec cannot be set to H.265.

Video

Parameter Type Required Description Remarks
Codec String No The video codec. Valid values: H.264, H.265, GIF, and WEBP.

Default value: H.264.

Profile String No The encoding profile. Valid values: baseline, main, and high.

Default value: high.

  • baseline: suitable for mobile devices.
  • main: suitable for standard-definition devices.
  • high: suitable for high-definition 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.

Note This parameter is valid only when the Codec parameter is set to H.264.
Bitrate String No The bitrate of the output video.
  • Valid values: [10, 50000].
  • Unit: Kbit/s.
Crf String No The constant rate factor.
  • Valid values: [0, 51].
  • Default value when the Codec parameter is set to H.264: 23. Default value when the Codec parameter is set to H.265: 26.
Note If you specify this parameter, the setting of the Bitrate parameter becomes invalid.
Width String No The width.
  • Default value: the original width of the video.
  • Valid values: [128, 4096].
  • Unit: pixel.
Height String No The height.
  • Default value: the original height of the video.
  • Valid values: [128, 4096].
  • Unit: pixel.
Fps String No The frame rate.
  • Default value: the frame rate of the input file.
  • 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: 10.
  • If you specify the maximum number of frames, no unit is required.
  • Value values: [1,100000].
Preset String No The preset video algorithm. Valid values: veryfast, fast, medium, slow, and slower. Default value: medium.
Note This parameter is valid only when the Codec parameter is set to H.264.
ScanMode String No The scan mode. Valid values: interlaced and progressive.
Bufsize String No The buffer size.
  • Valid values: [1000, 128000].
  • Default value: 6000.
  • Unit: KB.
Maxrate String No The maximum bitrate of the output video. Valid values: [10, 50000]. Unit: Kbit/s.
PixFmt String No The pixel format for video color encoding. Valid values: standard pixel formats such as yuv420p and yuvj420p.

The default pixel format can be yuv420p or the original color format.

Remove String No Specifies whether to delete the video stream.
  • true: deletes the video stream.
  • false: retains the video stream.
  • Default value: false.
Crop String No The method of video cropping. Valid values:
  • border: automatically detects and removes 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.
  • The image width of the output video corresponds to the long side of the mezzanine file or the image height of the mezzanine file in portrait mode.
  • The image height of the output video corresponds to the short side of the mezzanine file or the image width of the mezzanine file in portrait mode.
  • true: enables the auto-rotate screen feature.
  • false: disables the auto-rotate screen feature.

Default value: false.

The following table describes the supported combinations of container formats, video codecs, and audio codecs.
Note If the video is in the HLS format, pay attention to the audio and video codecs. If you set the video codec to H.264, set the audio codec to AAC. Otherwise, the transcoding is successful but the output file cannot be played.
Container 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 N/A 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/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 bgr8

Audio

Parameter Type Required Description
Codec String No The audio codec. Valid values: AAC, MP3, VORBIS, and FLAC.

Default value: 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.
  • Default value: 44100.
  • Valid values: 22050, 32000, 44100, 48000, and 96000.
  • Unit: Hz.
Note
  • If the container format for the video files is FLV and the audio codec is MP3, this parameter cannot be set to 32000, 48000, or 96000.
  • If the audio codec is MP3, this parameter cannot be set to 96000.
Bitrate String No The audio bitrate of the output file.
  • Valid values: [8,1000].
  • Unit: Kbit/s.
  • Default value: 128.
Channels String No The number of sound channels.

Default value: 2.

Note If the Codec parameter is set to MP3, this parameter can be set to 1 or 2.
If the Codec parameter is set to AAC, this parameter can be set to 1, 2, 4, 5, 6, or 8.
Remove String No Specifies whether to delete the audio stream.
  • true: deletes the audio stream.
  • false: retains the audio stream.
  • Default value: false.
Volume String No The volume configuration. For more information, see the Volume section in this section.
The following table describes the supported combinations of audio codecs and container formats.
Container Audio codec
MP3 MP3
MP4 AAC
OGG VORBIS and FLAC
FLAC FLAC

Volume

Parameter Type Required Description
Method String No The volume adjustment method.

Valid values: auto, dynamic, and linear.

IntegratedLoudnessTarget String No The new volume.
  • Valid values: [-70,-5].
  • This parameter is valid only when the Method parameter is set to dynamic.
  • Default value: -6.
TruePeak String No The peak volume.
  • Valid values: [-9, 0].
  • This parameter is valid only when the Method parameter is set to dynamic.
  • Default value: -1.
LoudnessRangeTarget String No The range of the volume.
  • Valid values: [1, 20].
  • This parameter is valid only when the Method parameter is set to dynamic.
  • Default value: 8.

MuxConfig

Parameter Type Required Description
Segment String No The segment configuration. The value must be a JSON object.
  • For more information, see the Segment section in this topic.
  • Example: {"Duration":"34"}.

Segment

Parameter Type Required Description
Duration String No The segment length.
  • The value must be an integer.
  • Unit: seconds.
  • Valid values: [1, 60].

Default value: 10.

ForceSegTime String No Specifies the points in time at which you want to segment the media file. You can specify up to 10 points in time. Separate the points in time with commas (,).
  • Each point in time 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.

TransConfig

Parameter Type Required Description
TransMode String No The transcoding mode.
  • Default value: onepass.
  • Valid values: onepass, twopass, and CBR.
AdjDarMethod String No The method of resolution adjustment.
  • Default value: none.
  • Valid values: rescale, crop, pad, and none.
IsCheckReso String No Specifies whether to check the resolution.
  • If this parameter is specified 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. true: checks the resolution.
  • false: does not check the resolution.
  • Default value: false.
IsCheckResoFail String No Specifies whether to check the resolution.
  • If this parameter is specified 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.
  • true: checks the resolution.
  • false: does not check the resolution.
  • Default value: false.
IsCheckVideoBitrate String No Specifies whether to check the video bitrate.
  • If this parameter is specified 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.
  • true: checks the video bitrate.
  • false: does not check the video bitrate.
  • Default value: false.
IsCheckAudioBitrate String No Specifies whether to check the audio bitrate.
  • If this parameter is specified 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.
  • true: checks the audio bitrate.
  • false: does not check the audio bitrate.
  • Default value: false.
IsCheckAudioBitrateFail String No Specifies whether to check the audio bitrate. If the bitrate of the output audio is greater than that of the input audio, the input file is not transcoded.
  • true: checks the audio bitrate.
  • false: does not check the audio bitrate.
  • Default value: false.
  • This parameter takes precedence over the IsCheckAudioBitrate parameter.
IsCheckVideoBitrateFail String No Specifies whether to check the video bitrate. If the bitrate of the output audio is greater than that of the input audio, the input file is not transcoded.
  • true: checks the video bitrate.
  • false: does not check the video bitrate.
  • Default value: false.
  • This parameter takes precedence over the IsCheckVideoBitrate parameter.

Clip

Parameter Type Required Description
TimeSpan String No The time span of the clip to be captured from the original file.

For more information, see TimeSpan.

ConfigToClipFirstPart Boolean No Specifies whether to crop the first part of the file into a clip before clip merging.
  • false: merges the clips and then crops the merged clips. This is the default value.
  • true: crops the first part of the file into a clip and then merges the clips.

TimeSpan

Parameter Type Required Description
Seek String No The start point in time of the clip.
  • Format 1: hh:mm:ss[.SSS].
  • Valid values: [00:00:00.000, 23:59:59.999].

  • Format 2: sssss[.SSS].
  • Valid values: [0.000, 86399.999].

Examples: 01:59:59.999 and 32000.23.

Duration String No The duration of the clip.
  • Format 1: hh:mm:ss[.SSS].
  • Valid values: [00:00:00.000, 23:59:59.999].

  • Format 2: sssss[.SSS].
  • Valid values: [0.000, 86399.999].

Example: 01:00:59.999 or 32000.23.

End String No The length of the end part of the original video to be cropped out.

If you specify this parameter, the setting of the Duration parameter becomes invalid.

  • Format 1: hh:mm:ss[.SSS].
  • Valid values: [00:00:00.000, 23:59:59.999].

  • Format 2: sssss[.SSS].
  • Value values: [0.000,86399.999].

Example: 01:00:59.999 or 32000.23.

WaterMarks

Parameter Type Required Description
WaterMarkTemplateId String No The ID of the watermark template.
If you do not specify this parameter, the default watermark template that contains the following settings is used:
  • The watermark is in the upper-right corner of the output video image.
  • The horizontal and vertical offsets relative to the output video image are 0.
  • The watermark width is 0.12 times the width in the output video resolution.
  • The watermark height is proportionally scaled based on the watermark width and the aspect ratio of the original image.
InputFile String Yes The watermark input. You can use an image in the PNG format or a file in the MOV format as the watermark input.
Width String No The watermark width. If you specify this parameter, the watermark width setting in the template is ignored. The value can be an integer or a decimal number.
  • Format 1: an integer, which indicates the pixel value of the watermark width.
    • Valid values: [8, 4096].
    • Unit: pixel.
  • Format 2: a decimal number, which indicates the ratio of the pixel value to the width in the output video resolution in pixels.
    • Valid values: (0, 1).
    • The decimal number can be accurate to four decimal places, such as 0.9999. Excessive digits are automatically deleted.
Height String No The watermark height. If you specify this parameter, the watermark height setting in the template is ignored. The value can be an integer or a decimal number.
  • Format 1: an integer, which indicates the pixel value of the watermark height.
    • Valid values: [8, 4096].
    • Unit: pixel.
  • Format 2: a decimal number, which indicates the ratio of the pixel value to the height in the output video resolution in pixels.
    • Valid values: (0, 1).
    • The decimal number can be accurate to four decimal places, such as 0.9999. Excessive digits are automatically deleted.
Dx String No The horizontal offset of the watermark relative to the output video image. If you specify this parameter, the horizontal offset setting in the template is ignored.

Default value: 0.

The value can be an integer or a decimal number.
  • Format 1: an integer, which indicates the pixel value of the horizontal offset.
    • Valid values: [8, 4096].
    • Unit: pixel.
  • Format 2: a decimal number, which indicates the ratio of the pixel value to the width in the output video resolution in pixels.
    • Valid values: (0, 1).
    • The decimal number can be accurate to four decimal places, such as 0.9999. Excessive digits are automatically deleted.
Dy String No The vertical offset of the watermark relative to the output video image. If you specify this parameter, the vertical offset setting in the template is ignored.

Default value: 0.

The value can be an integer or a decimal number.
  • Format 1: an integer, which indicates the pixel value of the vertical offset.
    • Valid values: [8, 4096].
    • Unit: pixel.
  • Format 2: a decimal number, which indicates the ratio of the pixel value to the height in the output video resolution in pixels.
    • Valid values: (0, 1).
    • The decimal number can be accurate to four decimal places, such as 0.9999. Excessive digits are automatically deleted.
ReferPos String No The position of the watermark. If you specify this parameter, the watermark position setting in the template is ignored.

Valid values: TopRight, TopLeft, BottomRight, and BottomLeft.

Type String No The type of the watermark. If you specify this parameter, the watermark type setting in the template is ignored. Valid values: Image and Text. Default value: Image.
  • A value of Image indicates an image watermark.
  • A value of Text indicates a text watermark.
Note If you set this parameter to Text, you must specify the TextWaterMark parameter.
Timeline String No The timeline of the watermark. If you specify this parameter, the watermark timeline setting in the template is ignored. For more information, see the Timeline section in this topic.
TextWaterMark String No The configuration of the text watermark. If the watermark is a text watermark, you must specify this parameter. The value must be a JSON object.
  • For more information, see the TextWaterMark section in this topic.
  • Example: {"Content":"5rWL6K+V5paH5a2X5rC05Y2w","Top":2,"Left":10}.

Config in the AddWaterMarkTemplate operation

Parameter Type Required Description
Width String No The watermark width.

The value can be an integer or a decimal number.

  • Format 1: an integer, which indicates the pixel value of the watermark width.
    • Valid values: [8, 4096].
    • Unit: pixel.
  • Format 2: a decimal number, which indicates the ratio of the pixel value to the width in the output video resolution in pixels.
    • Valid values: (0, 1).
    • The decimal number can be accurate to four decimal places, such as 0.9999. Excessive digits are automatically deleted.
Height String No The watermark height. The value can be an integer or a decimal number.
  • Format 1: an integer, which indicates the pixel value of the watermark height. Valid values: [8, 4096]. Unit: pixel.
  • Format 2: a decimal number, which indicates the ratio of the pixel value to the height in the output video resolution in pixels.
    • Valid values: (0, 1).
    • The decimal number can be accurate to four decimal places, such as 0.9999. Excessive digits are automatically deleted.
Dx String No The horizontal offset of the watermark relative to the output video image.

Default value: 0.

The value can be an integer or a decimal number.
  • Format 1: an integer, which indicates the pixel value of the horizontal offset.
    • Valid values: [8, 4096].
    • Unit: pixel.
  • Format 2: a decimal number, which indicates the ratio of the pixel value to the width in the output video resolution in pixels.
    • Valid values: (0, 1).
    • The decimal number can be accurate to four decimal places, such as 0.9999. Excessive digits are automatically deleted.
Dy String No The vertical offset of the watermark relative to the output video image.

Default value: 0.

The value can be an integer or a decimal number.
  • Format 1: an integer, which indicates the pixel value of the vertical offset.
    • Valid values: [8, 4096].
    • Unit: pixel.
  • Format 2: a decimal number, which indicates the ratio of the pixel value to the height in the output video resolution in pixels.
    • Valid values: (0, 1).
    • The decimal number can be accurate to four decimal places, such as 0.9999. Excessive digits are automatically deleted.
ReferPos String No The position of the watermark.
  • Valid values: TopRight, TopLeft, BottomRight, and BottomLeft. The four values indicate the upper-right, upper-left, lower-right, and lower-left corners.
  • Default value: TopRight.
Type String No The type of the watermark. Valid values: Image and Text.
  • Default value: Image.
  • MPS allows you to use templates for only image watermarks.
Timeline String No The timeline of the watermark. For more information, see the Timeline section in this topic.

The following list provides notes on the Width and Height parameters:

  • If you do not specify the Width or Height parameter, the watermark width is 0.12 times the width of the output video resolution, and the watermark height is proportionally scaled based on the watermark width and the aspect ratio of the original image.
  • If you specify only the Width parameter, the watermark height is proportionally scaled based on the specified width and the aspect ratio of the original image. If you specify only the Height parameter, the watermark width is proportionally scaled based on the specified height and the aspect ratio of the original image.
  • You can also specify both the Width and Height parameters to determine the width and height of the watermark.

Timeline

Parameter Type Required Description
Start String No The beginning of the time range during which the watermark is displayed.
  • Unit: seconds.
  • Value values: integers.
  • Default value: 0.
Duration String No The display duration of the watermark.
  • Valid values: integers and ToEND.
  • Default value: ToEND.

TextWaterMark

Parameter Type Required Description
Content String Yes The text to be displayed as the watermark. The text must be encoded in the Base64 format.

For example, if the original text is Test Text Watermark, the encoded text is 5rWL6K+V5paH5a2X5rC05Y2w.

FontName String No The front of the text. Default value: SimSun. For more information, see Fonts.
FontSize Integer No The size of the text.
  • Default value: 16.
  • Valid values: (4, 120).
FontColor String No The color of the text. For more information, see Text colors.
FontAlpha Integer No The transparency of the text.
  • Valid values: (0, 1].
  • Default value: 1.
Top Integer No The top margin of the text.
  • Default value: 0.
  • Valid values: [0, 4096].
Left Integer No The left margin of the text.
  • Default value: 0.
  • Valid values: [0, 4096].
BorderWidth Integer No The outline width of the text.
  • Default value: 0.
  • Valid values: [0, 4096].
BorderColor String No The outline color of the text.

MergeList

Parameter Type Required Description
MergeURL String Yes The OSS URL of the clip.
  • Example: http://example-bucket-****.oss-cn-hangzhou.aliyuncs.com/example-object.flv.
  • The URL must comply with RFC 2396 and be encoded in UTF-8, with reserved characters being percent-encoded.
Start String No The start point in time of the clip.
  • Valid formats: hh:mm:ss[.SSS] and sssss[.SSS].
  • Examples: 01:59:59.999 and 32000.23.
Duration String No The duration of the clip.
  • Valid formats: hh:mm:ss[.SSS] and sssss[.SSS].
  • Examples: 01:59:59.999 and 32000.23.

M3U8NonStandardSupport

Parameter Type Required Description
TS String No The non-standard support of the M3U8 format for the TS format. The value must be a JSON object. For more information, see the TS section in this topic.

TS

Parameter Type Required Description
Md5Support Boolean No Specifies whether to support the generation of the MD5 hash value of the TS file in the output M3U8 video.
SizeSupport Boolean No Specifies whether to support the generation of the size information about the TS file in the output M3U8 video.

Encryption

Parameter Type Required Description
Type String Yes The encryption type. Set the value to hls-aes-128.
Key String Yes The key that is used to encrypt the video.
  • The key must be encrypted. For more information, see the KeyType parameter.
  • For example, if the key is encryptionkey128, you can encrypt the key in the Base64 format or use Key Management Service (KMS) to encrypt the key.
KeyUri String Yes The URL that is used to request the key. The URL is encrypted in the Base64 format.
KeyType String Yes The key cannot be transmitted to MPS in plaintext. You must encrypt the key. You can encrypt the key in the Base64 format or use KMS to encrypt the key.
Note Alibaba Cloud provides the master key. To obtain the master key, submit a ticket. Base64 is a basic encryption format. If you use KMS, the key is first encrypted in the Base64 format and then encrypted by KMS.

SubtitleConfig

Parameter Type Required Description
ExtSubtitleList ExtSubtitle[] No The external subtitles. The value must be a JSON array that contains up to four JSON objects.
  • For more information, see the ExtSubtitle section in this topic.
  • Example: [{"Input":{"Bucket":"example-bucket","Location":"oss-cn-hangzhou","Object":"example.srt"},"CharEnc":"UTF-8"}].

ExtSubtitle

Parameter Type Required Description
Input String Yes The OSS object for the external subtitle. The value must be a JSON object.
  • The object must be in the SRT or ASS format.
  • For more information, see the Input section in this topic.
  • Example: {"Bucket":"example-bucket","Location":"oss-cn-hangzhou","Object":"example.srt"}.
Note
  • This parameter supports the {ObjectPrefix}, {FileName}, and {ExtName} placeholders in the OSS URL.
  • Example 1 of the Object parameter: a/b/c/test.flv.
  • Example 2 of the Object parameter: You can use {ObjectPrefix}{FileName}-cn.srt, which contains two placeholders, to specify the OSS URL of the external subtitle object. If you set the Object parameter to %7bObjectPrefix%7d%7bFileName%7d-cn.srt, the object identified by MPS is a/b/c/test-cn.srt. The OSS URL must comply with RFC 2396 and be encoded in UTF-8, with reserved characters being percent-encoded.
CharEnc String No The character set used by the external subtitle.
  • Valid values: UTF-8, GBK, BIG5, and auto.
  • Default value: auto.
Note If you set this parameter to auto, the detected character set may not be the actual character set. We recommend that you set this parameter to another value.

Opening

Parameter Type Required Description
OpenUrl String Yes The OSS URL of the opening part of the video.
Start String No The amount of time after which the opening part is played.
  • Unit: seconds.
  • Default value: 0.
Width String No The width of the opening part.
  • Valid values: values in the range of (0, 4096), -1, and full.
  • A value of -1 indicates that the width of the source of the opening part is retained.
  • A value of full indicates that the width of the main part is used for the opening part.
  • Default value: -1.
Height String No The height of the opening part.
  • Valid values: values in the range of (0, 4096), -1, and full.
  • A value of -1 indicates that the height of the source of the opening part is retained.
  • A value of full indicates that the height of the main part is used for the opening part.
  • Default value: -1.

TailSlate

Parameter Type Required Description
TailUrl String Yes The OSS URL of the ending part of the video.
BlendDuration String No The amount of time between the end of the main part and the beginning of the ending part. During the video part transition, the last frame of the main part fades out, and the first frame of the ending part fades in. Unit: seconds. Default value: 0.
Width String No The width of the ending part.
  • Valid values: values in the range of (0, 4096), -1, and full.
  • A value of -1 indicates that the width of the source of the ending part is retained.
  • A value of full indicates that the width of the main part is used for the ending part.
  • Default value: -1.
Height String No The height of the ending part.
  • Valid values: values in the range of (0, 4096), -1, and full.
  • A value of -1 indicates that the height of the source of the ending part is retained.
  • A value of full indicates that the height of the main part is used for the ending part.
  • Default value: -1.
IsMergeAudio Boolean No Specifies whether to merge the audio content in the ending part. Default value: true.
BgColor String No The color of the borders that are added to the ending part if the size of the ending part is smaller than that of the main part. Default value: White. For more information, see Background colors.

DeWatermark

The value must be a JSON object. Example:
{
        "0": [
            {
                "l": 10,
                "t": 10,
                "w": 10,
                "h": 10
            },
            {
                "l": 100,
                "t": 0.1,
                "w": 10,
                "h": 10
            }
        ],
        "128000": [],
        "250000": [
            {
                "l": 0.2,
                "t": 0.1,
                "w": 0.01,
                "h": 0.05
            }
        ]
    }
                
In this example, the three presentation timestamps (PTS) indicate the points in time at which the watermarks are blurred. Unit: milliseconds.
  • L: a number that indicates the left margin of the blurred area.
  • T: a number that indicates the top margin of the blurred area.
  • W: a number that indicates the width of the blurred area.
  • H: a number that indicates the height of the blurred area.

If the value of the L, T, W, or H field is greater than 1, the number indicates the pixel value. Otherwise, the number indicates the ratio of the pixel value to the corresponding pixel value of the watermark source. The blurred area is specified based on the nearest integers of the values of the L, T, W, and H fields.

This example specifies the following settings:
  • Blur two watermarks in the video image starting from the first frame. The first watermark is 10 × 10 pixels away from the upper-left corner of the video image and is 10 × 10 pixels in size. The second watermark is 100 pixels away from the left side of the video image and is 10 × 10 pixels in size. The distance between the top of the video image and the watermark is calculated by using the following formula: 0.1 × Height of the source.
  • Blur the two watermarks in the video image within the first 128,000 milliseconds.
  • Blur the watermark in the video image starting from the 250,000th millisecond. The watermark width is 0.01 times the width of the source, and the watermark height is 0.05 times the height of the source. The distance between the left side of the video image and the watermark is calculated by using the following formula: 0.2 × Width of the source. The distance between the top of the video image and the watermark is calculated by using the following formula: 0.1 × Height of the source.

Amix

Parameter Type Required Description
AmixURL String Yes The URL of the audio track to be mixed as the background music.

The URL must be an OSS URL or the value of the Input parameter in the form of a string.

If you want to mix two audio tracks in a video, set this parameter to the value of the Input parameter in the form of a string.

Map String No The audio track to be mixed. Format: 0:a:{audio_index}. Example: 0:a:0.
MixDurMode String No The mode to specify the mixing duration. Valid values: first and longest.
  • A value of first indicates that the length of the output media equals the length of the input media.
  • A value of longest indicates that the length of the output media equals the length of the longer input media.
  • Default value: longest.
Start String No The start point in time. You can specify a numeric value or a time value. Examples: 1:25:36.240 and 32000.23.
Duration String No The duration. You can specify a numeric value or a time value.

SnapshotConfig

Note The parameters in this section and their extended parameters in some of the following sections are involved when you call the SubmitSnapshotJob operation.
Parameter Type Required Description
Format String No The snapshot format.
  • Default value: null.
  • If you set this parameter to vtt, each output snapshot is in the WebVTT format.
BlackLevel String No The threshold that is used to filter out black frames for the first snapshot to be captured. This feature is available if you request the system to capture multiple snapshots.
  • Default value: null.
  • Value values: [30,100].

A smaller value indicates a smaller proportion of black pixels in the video image.

  • If you set the Time parameter to a value greater than 0, this parameter is invalid, which means that the filtering feature is disabled.
  • If you set the Time parameter to 0 and the Num parameter to a value greater than 1, this parameter is valid and takes effect only on the first snapshot within the first 5 seconds. If all frames within the first 5 seconds are black, the first black frame is returned as the captured snapshot.
  • If you set the Time parameter to 0 and the Num parameter to 1, this parameter is invalid and black frames are forcibly filtered out for snapshot capturing.

If you want to filter out pure black frames for the first snapshot, we recommend that you set this parameter to 100.

For example, if you set the Time parameter to 0 and the Num parameter to 10, and you want to filter out pure black frames for the first snapshot, set this parameter to 100.

PixelBlackThreshold String No The color value threshold that determines whether a pixel is black.
  • Value values: [0, 255].
  • If you set this parameter to 70, pixels whose color value is less than 70 are black.

Notes:

  1. You can set this parameter together with the BlackLevel parameter to modify the effect of black frame filtering.
  2. You can dynamically modify this parameter to adjust the identification of black pixels.
For example, you have set this parameter to 50 and you find that the effect of black frame filtering is not as expected. In this case, you can set this parameter to 100.
OutputFile String Yes The configuration of the output. This value must be a JSON object. For more information, see the OutputFile section in this topic.
TileOutputFile String No The configuration of the output in tile mode. The value must be a JSON object in the same format as the OutputFile parameter.
  • If you specify JPG as the snapshot format and you want to asynchronously capture multiple snapshots in sequence, you must use the {TileCount} placeholder for the Object parameter in this parameter to distinguish between different snapshots. The {TileCount} placeholder specifies the sequence number of a snapshot. For example, if you set the Num parameter to 3 and set the Object field to {TileCount}.jpg for this parameter, the output snapshots are named 00001.jpg, 00002.jpg, and 00003.jpg.
  • This parameter is required if you want to tile the captured snapshots. It specifies the URL of the tiled snapshot to be generated.
Time String Yes The point in time at which a snapshot is captured. Unit: milliseconds.
Interval String No The interval for snapshot capturing.
  • You must set this parameter to a value greater than 0 if you want to asynchronously captures multiple snapshots in sequence.
  • Default value: 10.
  • Unit: seconds.
  • If you set this parameter to 0, the system captures snapshots at fixed intervals based on the length of the video.
Num String No The number of snapshots to be captured.

If you want to asynchronously capture snapshots in sequence, you must specify a parameter value greater than 0.

  • If the result of Time + Interval × Number equals a value greater than the value that indicates the length of the video, no more snapshots are captured and the snapshots that have been captured are returned.
  • If you set this parameter to 1, the Interval parameter does not take effect, and only one snapshot is captured.
Width String No The width of a snapshot.
  • Unit: pixel.
  • Valid values: [8, 4096].
Height String No The height of a snapshot.
  • Unit: pixel.
  • Valid values: [8, 4096].
FrameType String No The snapshot type. Valid values:
  • normal: normal frame
  • intra: I-frame
Default value: intra.
TileOut String No The tiling configuration. The value must be a JSON object. For more information, see the TileOut section in this topic.
SubOut String No The configuration of the tiled snapshot in the WebVTT format. For more information, see the SubOut Webvtt section in this topic.

OutputFile

Parameter Type Required Description
Bucket String Yes The OSS bucket that stores the output. For more information, see the description of the term object in Terms.
Location String Yes The OSS region in which the OSS bucket resides. For more information, see the description of the term region in Terms.
Object String Yes The one or more OSS objects that are generated as the output. The objects must be in the JPG format, and their URLs must comply with RFC 2396 and be encoded in UTF-8, with reserved characters being percent-encoded. Example: %7BObjectPrefix%7D%7BFileName%7D%7BCount%7D.jpg. In this case, if the input file is a/b/c.flv, the output snapshots may be a/b/c00001.jpg and a/b/c00002.jpg.
The placeholders in the URL will be replaced with the actual values used in your business operations.
  • Placeholders supported by workflows: {ObjectPrefix}, which indicates the prefix of the input file name. {FileName}, which indicates the input file name. {ExtName}, which indicates the file name extension of the input file. {SnapshotTime}, which indicates the point in time at which the snapshot is captured. {Count}, which indicates the sequence number of the snapshot. {RunId}, which indicates the ID of the execution instance. {MediaId}, which indicates the ID of the input file.
  • Placeholders supported by other elements: {ObjectPrefix}, which indicates the prefix of the input file name. {FileName}, which indicates the input file name. {ExtName}, which indicates the file name extension of the input file. {SnapshotTime}, which indicates the point in time at which the snapshot is captured. {Count}, which indicates the sequence number of the snapshot.

Notes: If you want to asynchronously capture multiple snapshots in sequence, the specified URL must contain %7BCount%7D. The {Count} placeholder can distinguish between different snapshots. For example, if you set the Num parameter to 3 and set the Object parameter to %7BCount%7D.jpg for OutputFile, the output snapshots are named 00001.jpg, 00002.jpg, and 00003.jpg.

TileOut

Parameter Type Required Description
Lines String No The number of rows that the tiled snapshot contains.
  • Integer
  • Value values: (0, 10000].
  • Default value: 10.
Columns String No The number of columns that the tiled snapshot contains.
  • Integer
  • Value values: (0, 10000].
  • Default value: 10.
CellWidth String No The width of a single snapshot before tile. The default value is the value of the Width parameter in SnapshotConfig.
CellHeight String No The height of a single snapshot before tile. The default value is the value of the Height parameter in SnapshotConfig.
Margin String No The margin width of the tiled snapshot.
  • Default value: 0.
  • Unit: pixel.
Padding String No The spacing between two adjacent snapshots. Default value: 0. Unit: pixel.
Color String No The background color.
  • You can set the Color parameter to a color keyword or random.
  • Default value: black.
  • If you want to set the background color to black, you can specify one of the following three keywords: Black, black, and #000000.
IsKeepCellPic String No Specifies whether to retain single snapshots.
  • Valid values: true and false.
  • Default value: true.

SubOut Webvtt

Parameter Type Required Description
IsSptFrag String No Specifies whether to tile the snapshots.
  • A value of true indicates that snapshots are to be tiled.
  • Default value: false.

NotifyConfig

Parameter Type Required Description
QueueName String No The name of the queue that is created in Message Service (MNS).
  • MPS allows you to associate an MPS queue with an MNS queue. After a job in the MPS queue is complete, MPS sends the execution result of the job to the associated MNS queue.
  • For information about how to receive messages, see Receive notifications.
  • Before you perform the association operation, you must create a queue in the MNS console.
Topic String No The name of the topic that is created in MNS.
  • MPS allows you to associate an MPS queue with an MNS topic. After a job in the MPS queue is complete, MPS sends the execution result of the job to the associated MNS topic.
  • The associated MNS topic pushes a message about the execution result to the URL that subscribes to the MNS topic.
  • Before you perform the association operation, you must create a topic in the MNS console.

Parameters related to input in the SubmitJobs operation

Parameter Type Required Description
Bucket String Yes The OSS bucket that stores the input file.
  • You must grant the read permissions on the bucket to MPS on the Access Control page in the OSS console.
  • For more information, see the description of the term bucket in Terms.
Location String Yes The OSS region in which the OSS bucket resides.

For more information, see the description of the term region in Terms.

Object String Yes The OSS object that is used as the input file.
  • The URL of the OSS object must comply with RFC 2396 and be encoded in UTF-8, with reserved characters being percent-encoded.
  • For more information, see the description of the term object in Terms.
Audio String No The audio configuration of the input file. The value must be a JSON object.
Note This parameter is required if the input file is in the ADPCM or PCM format.
  • For more information, see the InputAudio section in this topic.
  • Example: {"Channels":"2","Samplerate":"44100"}.
Container String No The container configuration of the input file. The value must be a JSON object.
Note This parameter is required if the input file is in the ADPCM or PCM format.
  • For more information, see the InputContainer section in this topic.
  • Example: {"Format":"u8"}.

InputContainer

Parameter Type Required Description
Format String Yes The audio format of the input file.

Valid values: alaw, f32be, f32le, f64be, f64le, mulaw, s16be, s16le, s24be, s24le, s32be, s32le, s8, u16be, u16le, u24be, u24le, u32be, u32le, and u8.

InputAudio

Parameter Type Required Description
Channels String Yes The number of sound channels in the input file. Valid values: [1, 8].
Samplerate String Yes The audio sampling rate of the input file.
  • Valid values: (0, 320000].
  • Unit: Hz.

AnalysisConfig

Parameter Type Required Description
QualityControl String No The configuration of the output file quality. The value must be a JSON object. For more information, see the AnalysisConfig section in this topic.
PropertiesControl String No The property configuration. The value must be a JSON object. For more information, see the PropertiesControl section in this topic.

QualityControl

Parameter Type Required Description
RateQuality String No The quality level of the output file.
  • Value values: (0, 51).
  • The value must be an integer.
  • Default value: 25.
MethodStreaming String No The playback mode. Valid values: network and local.

Default value: network.

PropertiesControl

Parameter Type Required Description
Deinterlace String No Specifies whether to forcibly runs deinterlacing. Valid values:
  • Auto: automatically runs deinterlacing.
  • Force: forcibly runs deinterlacing.
  • None: forbids deinterlacing.
Crop String No The cropping configuration of the video image.
  • By default, automatic cropping is performed.
  • If you do not set this parameter to an empty JSON object, the Mode parameter is required.
  • For more information, see the Crop section in this topic.

Crop

Parameter Type Required Description
Mode String No The cropping mode. This parameter is required if the value of the Crop parameter is not an empty JSON object. Valid values:
  • Auto: automatically runs cropping.
  • Force: forcibly runs cropping.
  • None: forbids cropping.
Width Integer No The width of the video image after the margins are cropped out.
  • Valid values: [8, 4096].
  • If you set the Mode parameter to Auto or None, the setting of this parameter is invalid.
Height Integer No The height of the video image after the margins are cropped out.
  • Valid values: [8, 4096].
  • If you set the Mode parameter to Auto or None, the setting of this parameter is invalid.
Top Integer No The top margin to be cropped out.
  • Valid values: [8, 4096].
  • If you set the Mode parameter to Auto or None, the setting of this parameter is invalid.
Left Integer No The left margin to be cropped out.
  • Valid values: [8, 4096].
  • If you set the Mode parameter to Auto or None, the setting of this parameter is invalid.

TransFeatures

Parameter Type Required Description
MergeList String No The URLs of the clips to be merged.
  • The value must be a JSON array that contains up to four JSON objects. For more information, see the MergeList section in this topic.
  • Example: [{"MergeURL":"http://example-bucket-****.oss-cn-hangzhou.aliyuncs.com/k/mp4.mp4"},{"MergeURL":"http://example-bucket-****.oss-cn-hangzhou.aliyuncs.com/c/ts.ts","Start":"1:14","Duration":"29"}].

Parameters related to output in the SubmitJobs operation

Parameter Type Required Description
URL String No The OSS URL of the output file.
  • Example: http://example-bucket-****.oss-cn-hangzhou.aliyuncs.com/example.flv.
  • If you do not specify this parameter, the Bucket, Location, and Object parameters are required.
Bucket String No
  • The OSS bucket that stores the output file. If you do not specify the URL parameter, this parameter is required.
  • Otherwise, the setting of this parameter is invalid. Before you specify a bucket, grant the write permissions on the bucket to MPS on the Access Control page in the OSS console.
  • For more information, see the description of the term bucket in Terms.
Location String No
  • The OSS region in which the OSS bucket resides. If you do not specify the URL parameter, this parameter is required.
  • Otherwise, the setting of this parameter is invalid.
  • For more information, see the description of the term region in Terms.
Object String No
  • The name of the OSS object as the output file. If you do not specify the URL parameter, this parameter is required.
  • Otherwise, the setting of this parameter is invalid. The parameter value must comply with RFC 2396 and be encoded in UTF-8, with reserved characters being percent-encoded.
  • For more information about OSS objects, see the description of the term object in Terms.

MultiBitrateVideoStream

Parameter Type Required Description
URI String No The name of the output video stream, which must end with .m3u8. Example: a/b/test.m3u8. Format: ^[a-z]{1}[a-z0-9./-]+$.
RefActivityName String Yes The name of the associated activity.
ExtXStreamInfo Json Yes The information about the stream. Example: {"BandWidth": "111110","Audio": "auds","Subtitles": "subs"}.

ExtXMedia

Parameter Type Required Description
Name String Yes Required. The name of the resource, which can be up to 64 bytes in length and must be encoded in UTF-8. This parameter corresponds to NAME in the HTTP Live Streaming (HLS) V5 protocol.
Language String No Optional. The language of the resource, which must comply with RFC 5646. This parameter corresponds to LANGUAGE in the HLS V5 protocol.
URI String Yes Required. The path of the resource.

Format: ^[a-z]{1}[a-z0-9./-]+$. Example: a/b/c/d/audio-1.m3u8.

MasterPlayList

Parameter Type Required Description
MultiBitrateVideoStreams JsonArray Yes The array of multiple streams. Example: [{"RefActivityName": "video-1","ExtXStreamInfo": {"BandWidth": "111110","Audio":"auds","Subtitles": "subs"}}].

ExtXStreamInfo

Parameter Type Required Description
BandWidth String Yes Required. The upper limit of the total bitrate. This parameter corresponds to BANDWIDTH in the HLS V5 protocol.
Audio String No Optional. The ID of the audio stream group. This parameter corresponds to AUDIO in the HLS V5 protocol.
Subtitles String No Optional. The ID of the subtitle stream group. This parameter corresponds to SUBTITLES in the HLS V5 protocol.

AdaptationSet

Parameter Type Required Description
Group String Yes Required. The name of the group. Example:
<AdaptationSet group="videostreams" mimeType="video/mp4" par="4096:1744"
              minBandwidth="258157" maxBandwidth="10285391" minWidth="426" maxWidth="4096"
              minHeight="180" maxHeight="1744" segmentAlignment="true"
              startWithSAP="1">
Lang String No The language. You can specify this parameter for audio and subtitle resources.

Representation

Parameter Type Required Description
Id String Yes Required. The ID of the stream. Example:
<Representation id="240p250kbps" frameRate="24" bandwidth="258157"
              codecs="avc1.4d400d" width="426" height="180">
URI String Yes Required. The path of the resource. Format: ^[a-z]{1}[a-z0-9./-]+$. Example: a/b/c/d/video-1.mpd.

InputConfig

Parameter Type Required Description
Format String Yes Required. The format of the input subtitle file. Valid values: stl, ttml, and vtt.
InputFile String Yes
Example 1: {"Bucket":"example-bucket-****","Location":"oss-cn-hangzhou","Object":"example-logo****.png"}
               
              Example 2: {"URL":"http://exampleBucket****.oss-cn-hangzhou.aliyuncs.com/subtitle/test****.chs.vtt"}