media processing parameter description for vod api - ApsaraVideo VOD

This topic describes the media processing parameters for ApsaraVideo VOD APIs.

EncryptConfig: HLS encryption settings

Field Name	Type	Required	Description
CipherText	String	Yes	The ciphertext of the key. Use this to obtain the plaintext key.
DecryptKeyUri	String	Yes	The URI used to obtain the decryption key based on the ciphertext of the key. Example: `http://example.aliyundoc.com?CipherText=ZjJmZGViNzUtZWY1Mi00Y2RlLTk****`.
KeyServiceType	String	Yes	The type of the key service. Default value: `KMS`. KMS is the abbreviation for Alibaba Cloud Key Management Service.

Sample EncryptConfig parameters

{
  "CipherText":"ZjJmZGViNzUtZWY1Mi00Y2RlLTk****",
  "DecryptKeyUri":"http://example.aliyundoc.com?CipherText=ZjJmZGViNzUtZWY1Mi00Y2RlLTk****",
  "KeyServiceType":"KMS"
}

OverrideParams: Transcoding job parameter override settings

Field Name	Type	Required	Description
Watermarks	Watermark[]	No	Required to replace watermarks.
SubtitleSetting	SubtitleSetting	No	Required to replace subtitles. Note The transcoding template that you use must have subtitle parameters configured in advance. Otherwise, the subtitle parameters are not overwritten. For more information about subtitle settings, see SubtitleConfig. The URL of the replacement subtitle file must be an HTTP (not HTTPS) OSS URL. URLs of CDN-accelerated domain names are not supported. Example: `http://out-dda****.cn-shanghai.aliyuncs.com/subtitle/subtitle.ass`
PackageSubtitleSetting	PackageSubtitleSetting[]	No	Required to overwrite the subtitle URL during adaptive bitrate streaming packaging.
TranscodeTemplateList	TranscodeTemplate[]	No	Required to replace template parameters. Supports overwriting the Video, Audio, Clip, Rotate, and TranscodeFileRegular parameters in the transcoding template. Parameters of original quality templates cannot be overwritten. The TranscodeTemplateId parameter is required to overwrite parameters.

Note

Currently, you can replace only the image file or text content of a watermark.

TranscodeTemplateList example

        [
                {
                  "TranscodeTemplateId":"9580424e49b28c952a46544e3e8f****",
                  "Video":{
                          "Width":720,
                          "Height":480,
                          "Bitrate":"600"
                  },
                  "Audio":{
                          "Bitrate":128
                  },
                  "Clip":{
                          "TimeSpan":{
                                "Seek":"1",
                                "Duration":"5"
                        },
                  "Rotate":"270",
                  "TranscodeFileRegular":"{MediaId}/{JobId}/{PlayDefinition}"
                  }
                }
        ]

Watermark: Watermark parameter override settings

Field name	Type	Required	Description
WatermarkId	String	Yes	The ID of the watermark that is associated with the transcoding template. You can find the ID in the ApsaraVideo VOD console. For more information, see Watermark management.
FileUrl	String	No	The OSS URL of the watermark file. This parameter is required for image watermarks. For more information about how to obtain the OSS URL of a file, see CreateUploadAttachedMedia.
Content	String	No	The content of the text watermark. This parameter is required for text watermarks.

Important

The FileUrl must match the storage location of the video source.

SubtitleSetting: Subtitle parameter override settings

Field Name	Type	Required	Description
SubtitleList	Subtitle	Yes	The list of replacement subtitles.

Subtitle Configuration

Field Name

Type

Required

Description

SubtitleUrl

String

Yes

The OSS URL of the subtitle file. HTTPS URLs are not supported.

CharEncode

String

Yes

The encoding format of the subtitle content. Valid values:

auto (automatic detection)
UTF-8
GBK
BIG5

Note

Set CharEncode to a specific encoding format. If you set this parameter to auto, the encoding format may be incorrectly detected.

PackageSubtitleSetting: Packaged subtitle replacement parameters

Field name	Type	Required	Description
PackageSubtitleList	PackageSubtitle[]	Yes	Required to replace subtitles.

PackageSubtitle: Packaged subtitle replacement parameters

Field name	Type	Required	Description
SubtitlePackageTemplateId	String	Yes	The ID of the subtitle packaging template.
Language	String	Yes	The language. For more information, see RFC 5646. Example: en-US. Note The Language parameter is used only to retrieve the subtitle file to be replaced. The language itself is not replaced.
SubtitleUrl	String	Yes	The subtitle URL. Only HTTP OSS URLs are supported. HTTP CDN URLs and HTTPS URLs are not supported. Note Currently, only one HTTP URL is supported. Subtitle files can be stored only in the system buckets that are allocated by ApsaraVideo VOD.

Note

The SubtitlePackageTemplateId and Language parameters are used to retrieve the URL of the subtitle to be replaced. The language itself cannot be replaced.

Sample OverrideParams parameters

{
  "Watermarks":[
    {
      "WatermarkId":"watermark1",
      "FileUrl":"http://****.bucket.aliyuncs.com/image/replace.png"
    },
    {
      "WatermarkId":"watermark2",
      "Content":"Watermark test"
    }
  ],
  "SubtitleSetting":{
          "SubtitleList":[
                {
                "SubtitleUrl":"http://outin-****.oss-cn-shanghai.aliyuncs.com/subtitles/7b850b-724c-4011-b885-dd16c****.ass",
                "CharEncode":"UTF-8"
                },
                {
                "SubtitleUrl":"http://outin-****.oss-cn-shanghai.aliyuncs.com/subtitles/7b86db-724c-4011-b885-dd161d****.srt",
                "CharEncode":"auto"
                }
        ]
  },
  "PackageSubtitleSetting": {
    "PackageSubtitleList": [
      {
        "Language": "en-US",
        "SubtitlePackageTemplateId": "32d665807c08d25d4a5d513395****", 
        "SubtitleUrl": "http://outin-****.oss-cn-shanghai.aliyuncs.com/789679188D1F36A00AEB****.vtt" 
      },
      {
        "Language": "ja",  
        "SubtitlePackageTemplateId": "32d665807c08d25d4a5d513395ad****",
        "SubtitleUrl": "http://outin-****.oss-cn-shanghai.aliyuncs.com/F43FD90FF4B936A00AEB****.vtt"
      }
    ]
  }
}

WatermarkConfig: Watermark settings

If the watermark type is Image

Parameter name	Parameter type	Required	Description
Dx	String	Yes	The horizontal offset is available in two forms. Pixel value: [8,4096] Screen percentage: (0,1). A value of 0 represents 0%, a value of 1 represents 100%, and a value of 0.5 represents 50%. Other values are interpreted proportionally.
Dy	String	Yes	The vertical offset can be specified in two formats. Pixel value: [8,4096] Screen proportion: (0,1). A value of 0 represents 0% of the screen, 1 represents 100%, and 0.5 represents 50%. Other values are interpreted in the same way.
Width	String	Yes	You can specify the watermark width in two formats. Pixel value: [8,4096] Screen proportion: (0,1). A value of 0 represents 0% of the screen, a value of 1 represents 100%, and a value of 0.5 represents 50%. Other values are interpreted in the same way.
Height	String	Yes	The high watermark supports two value formats. Pixel value: [8,4096] Image proportion: (0,1). A value of 0 represents 0% of the image area, 1 represents 100%, and 0.5 represents 50%. Other values are interpreted proportionally.
ReferPos	String	Yes	Watermark position: BottomRight (bottom right) BottomLeft (bottom left) TopRight (top right) TopLeft (top left)
Timeline	Timeline	No	The timeline of the watermark. This specifies the start and end time for the watermark display. The value is a JSON string.

Important

The Timeline parameter is valid only for image watermarks.

If the watermark type is Text

Parameter name	Parameter type	Required	Description
Content	String	Yes	The content of the text watermark. Example: "Text watermark".
FontName	String	No	Font name
FontColor	String	No	Font color
FontAlpha	String	No	The font transparency. Valid values: (0, 1]. Default value: 1.0.
BorderColor	String	No	Outline color
Top	Integer	No	The top margin of the text. Only integer values are supported. Unit: px. Default value: 0. Valid values: [0, 4096].
Left	Integer	No	The left margin of the text. Only integer values are supported. Unit: px. Default value: 0. Valid values: [0, 4096].
FontSize	Integer	No	The font size. Only integer values are supported. Default value: 16. Valid values: (4, 120).
BorderWidth	Integer	No	The outline width. Only integer values are supported. Unit: px. Default value: 0. Valid values: (0, 4096].

Watermark Timeline

Parameter name	Type	Required	Description
Start	String	Yes	The time when the watermark starts to appear. Unit: seconds. The value must be a number. Default value: 0.
Duration	String	Yes	The duration for which the watermark is displayed. Unit: seconds. Valid values: a number or `ToEND`. Default value: `ToEND`, which indicates the end of the video.

Important

The Timeline parameter is valid only for image watermarks.

Font name

Font name	Description
SimSun	Song typeface
WenQuanYi Zen Hei	WenQuanYi Zen Hei
WenQuanYi Zen Hei Mono	WenQuanYi Zen Hei Monospace
WenQuanYi Zen Hei Sharp	WenQuanYi Zen Hei Bitmap
Yuanti SC	Simplified Round, Regular

Video snapshots

Snapshot template settings

SnapshotTemplateConfig

Name

Type

Required

Description

SnapshotType

String

Yes

The snapshot type. Valid values:

NormalSnapshot: a normal snapshot.
SpriteSnapshot: a sprite.
WebVttSnapshot: a WebVTT snapshot.

SnapshotConfig

JSON

Yes

The snapshot template settings. The settings vary based on the value of SnapshotType. For more information, see SnapshotConfig below.

SnapshotConfig

Note

A sprite is created by taking normal snapshots and then combining them. Therefore, the SnapshotConfig parameter is required for both normal snapshots and sprites.

Parameter Name	Type	Required	Description
FrameType	String	Yes	The frame type for snapshots. Valid values: intra: keyframe. normal: normal frame.
Count	Long	Yes	The number of snapshots to capture.
Interval	Long	Yes	The interval at which to capture snapshots. The value must be greater than or equal to 0. Unit: seconds. A value of 0 indicates that snapshots are captured at even intervals based on the video duration and the value of Count.
SpecifiedOffsetTime	Long	Yes	The start time for capturing snapshots. Unit: milliseconds.
Width	Integer	No	The width of the snapshot. Valid values: [8, 4096]. Default value: the width of the source video. Unit: px.
Height	Integer	No	The height of the snapshot. Valid values: [8, 4096]. Default value: the height of the source video. Unit: px.
SpriteSnapshotConfig	JSON	No	The sprite settings. This parameter is required if SnapshotType is set to SpriteSnapshot. For more information, see SpriteSnapshotConfig below.
Format	String	No	The format of the output snapshot file. Set the value to `vtt`. This parameter is valid only if SnapshotType is set to `WebVttSnapshot`.
SubOut	JSON	No	Controls how snapshots are displayed when SnapshotType is set to WebVttSnapshot. For more information, see SubOut below.

SpriteSnapshotConfig

Parameter name	Type	Required	Description
CellWidth	String	No	The width of each small image in the sprite. Default value: the width of a normal snapshot. Unit: px.
CellHeight	String	No	The height of each small image in the sprite. Default value: the height of a normal snapshot. Unit: px.
Padding	String	Yes	The padding of each small image. Unit: px.
Margin	String	Yes	The margin of each small image. Unit: px.
Color	String	Yes	The background color of the sprite. For more information, see Color settings. Note Setting the color using RGB values is not supported.
Columns	String	Yes	The number of columns of small images. Valid values: [1, 10000].
Lines	String	Yes	The number of rows of small images. Valid values: [1, 10000].
KeepCellPic	String	Yes	Specifies whether to keep the small images. Valid values: keep: Retain. delete: Removes the item.

SubOut

Parameter Name

Type

Required

Description

IsSptFrag

String

Yes

Valid values:

false: Store each snapshot as a separate image.
true: Combine snapshots into a large image similar to a sprite before storing.

Sample snapshot template

{
  "SnapshotConfig": {
    "Count": 10,
    "SpecifiedOffsetTime": 0,
    "Interval": 1
  },
  "SnapshotType": "NormalSnapshot"
}

Animated images from videos

Animated image template settings

DynamicImageTemplateConfig

Parameter Name	Type	Required	Description
Name	String	Yes	The name of the animated image template.
Video	JSON	Yes	The video settings for the animated image. For more information, see Video below.
Container	JSON	Yes	The container format settings for the animated image. For more information, see Container below.
Clip	JSON	Yes	The clipping settings for the animated image. For more information, see Clip below.
SetDefaultCover	String	Yes	Specifies whether to set the generated animated image as the video thumbnail by default. Valid values: true: Set as the default thumbnail. false: Do not set as the default thumbnail.

Video

Note

If you do not set Width and Height, the output animated image has the same dimensions as the source video.
If you set only Width, the height is scaled proportionally based on the aspect ratio of the source video.
If you set only Height, the width is scaled proportionally based on the aspect ratio of the source video.

Parameter Name	Type	Required	Description
Width	String	No	The width of the output animated image. Valid values: [128, 4096].
Height	String	No	The height of the output animated image. Valid values: [128, 4096].
Fps	String	Yes	The frame rate. Valid values: (0, 60].

Container

Parameter name

Type

Required

Description

Format

String

Yes

The format of the output animated image. Valid values:

webp
gif

Clip

Parameter name	Type	Required	Description
TimeSpan	JSON	Yes	The timeline settings for clipping. For more information, see TimeSpan below.

TimeSpan

Note

To clip the video based on a duration, specify both the Seek and Duration parameters. To clip the video by trimming the start and end, specify both the Seek and End parameters.
If you specify Seek, Duration, and End at the same time, the Seek and End parameters take effect.

Parameter Name	Type	Required	Description
Seek	String	Yes	The start time of the clip for the animated image. Format 1: sssss[.SSS]. Valid values: [0.000, 86399.999]. Example: 0 Format 2: hh:mm:ss[.SSS]. Valid values: [00:00:00.000, 23:59:59.999]. Example: 00:00:05.003
Duration	String	No	The duration of the clip. Format 1: sssss[.SSS]. Valid values: [0.000, 86399.999]. Example: 15 Format 2: hh:mm:ss[.SSS]. Valid values: [00:00:00.000, 23:59:59.999]. Example: 00:00:10.003
End	String	No	The duration of the tail part of the video to discard. If you specify this parameter, the Duration parameter becomes invalid. Format 1: sssss[.SSS]. Valid values: [0.000, 86399.999]. Example: 12000.55 Format 2: hh:mm:ss[.SSS]. Valid values: [00:00:00.000, 23:59:59.999]. Example: 00:00:15.003

Sample animated image template

{
  "Video": {
    "Fps": 5,
    "Width": 1024
  },
  "Clip": {
    "TimeSpan": {
      "Seek": 0,
      "Duration": 15
    }
  },
  "Container": {
    "Format": "gif"
  },
  "SetDefaultCover": "false"
}