Parameters for media processing in ApsaraVideo VOD - ApsaraVideo VOD

This topic describes the media processing parameters that are used in the ApsaraVideo VOD API.

EncryptConfig: the configurations for HLS encryption

Parameter	Type	Required	Description
CipherText	String	Yes	The ciphertext key that is used to obtain the plaintext key.
DecryptKeyUri	String	Yes	The address that is used to obtain the decryption key based on the ciphertext key. Example: `http://example.aliyundoc.com?CipherText=ZjJmZGViNzUtZWY1Mi00Y2RlLTk****`.
KeyServiceType	String	Yes	The type of the key service. Default value: KMS, which indicates Key Management Service of Alibaba Cloud.

Example of the EncryptConfig parameter

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

OverrideParams: the configurations for a transcoding job

Parameter	Type	Required	Description
Watermarks	Watermark[]	No	The watermark configurations. To replace a watermark, you must set this parameter.
SubtitleSetting	SubtitleSetting	No	The subtitle package. To replace the subtitles for a video, you must set this parameter. Note Make sure that subtitle parameters are set in advance for the transcoding template that you use. Otherwise, you cannot modify the subtitle configurations. For more information about how to set subtitle parameters, see SubtitleConfig. The new URL that is used to obtain the subtitle file must be an HTTP-based Object Storage Service (OSS) URL, such as `http://out-dda**.cn-shanghai.aliyuncs.com/subtitle/subtitle.ass`. CDN URLs and HTTPS-based OSS URLs are not supported.**
PackageSubtitleSetting	PackageSubtitleSetting[]	No	The configurations of subtitle packaging. To replace the URL that is used to obtain the subtitle file for an adaptive bitrate streaming template, you must set this parameter.
TranscodeTemplateList	TranscodeTemplate[]	No	The configurations of the transcoding template. To modify the configurations of a transcoding template, you must set this parameter. You can modify the Video, Audio, Clip, Rotate, and TranscodeFileRegular parameters of a transcoding template. You cannot modify the parameters of an original quality template. To modify the configurations of a transcoding template, you must set the TranscodeTemplateId parameter.

Note

You can replace only the image or text for a watermark.

Example of the TranscodeTemplateList parameter

        [
                {
                  "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: the watermark configurations

Parameter	Type	Required	Description
WatermarkId	String	Yes	The watermark ID that is associated with the transcoding template. You can query watermark IDs in the ApsaraVideo VOD console. For more information, see Manage watermarks.
FileUrl	String	No	The OSS URL of the watermark file. To configure an image watermark, you must set this parameter. For more information about how to obtain OSS URLs, see CreateUploadAttachedMedia.
Content	String	No	The content of the text watermark. To configure a text watermark, you must set this parameter.

Important

The watermark file must be stored on the same origin as the source video.

SubtitleSetting: the subtitle files

Parameter	Type	Required	Description
SubtitleList	Subtitle	Yes	The subtitle files.

Subtitle: the subtitle configurations

Parameter

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: We recommend that you set the CharEncode parameter to a valid encoding format based on your business requirements. If you set the parameter to auto, the detected encoding format may not be the actual encoding format.

PackageSubtitleSetting: the subtitle packaging settings

Parameter	Type	Required	Description
PackageSubtitleList	PackageSubtitle[]	Yes	The subtitle package. To replace the subtitles for a video, you must set this parameter.

PackageSubtitle: the configurations of subtitle packaging

Parameter	Type	Required	Description
SubtitlePackageTemplateId	String	Yes	The ID of the subtitle package template.
Language	String	Yes	The subtitle language, such as en-US. For more information, see RFC 5646. Note This parameter is used only to query the URL of the subtitle file to be replaced and cannot be used to change the subtitle language.
SubtitleUrl	String	Yes	The URL of the subtitle file. Only HTTP OSS URLs are supported. HTTP CDN URLs and HTTPS URLs are not supported. Note You can specify only one HTTP URL. You can store subtitle files only in the buckets that are allocated by ApsaraVideo VOD.

Note

The SubtitlePackageTemplateId and Language parameters are used only to query the URL of the subtitle file to be replaced and cannot be used to change the subtitle language.

Example of the OverrideParams parameter

{
  "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: the watermark configurations

Parameters for image watermarks

Parameter	Type	Required	Description
Dx	String	Yes	The horizontal offset of the watermark. The following types of values are supported: Pixel value: [8,4096] Image ratio: (0,1). A value of 0 indicates that the proportion of the vertical offset to the height of the video image is 0%. A value of 1 indicates that the proportion is 100%. A value of 0.5 indicates that the proportion is 50%. Other values can be converted in the same manner.
Dy	String	Yes	The vertical offset of the watermark. The following types of values are supported: Pixel value: [8,4096] Image ratio: (0,1). A value of 0 indicates that the proportion of the vertical offset to the height of the video image is 0%. A value of 1 indicates that the proportion is 100%. A value of 0.5 indicates that the proportion is 50%. Other values can be converted in the same manner.
Width	String	Yes	The width of the watermark. The following types of values are supported: Pixel value: [8,4096] Image ratio: (0,1). A value of 0 indicates that the proportion of the horizontal offset to the width of the video image is 0%. A value of 1 indicates that the proportion is 100%. A value of 0.5 indicates that the proportion is 50%. Other values can be converted in the same manner.
Height	String	Yes	The height of the watermark. The following types of values are supported: Pixel value: [8,4096] Image ratio: (0,1). A value of 0 indicates that the proportion of the horizontal offset to the width of the video image is 0%. A value of 1 indicates that the proportion is 100%. A value of 0.5 indicates that the proportion is 50%. Other values can be converted in the same manner.
ReferPos	String	Yes	The position of the watermark. Valid values: BottomRight BottomLeft TopRight TopLeft
Timeline	Timeline	No	The timeline for watermark display, including the start time and end time. The value is a JSON string.

Important

This parameter is valid only for image watermarks.

Parameters for text watermarks

Parameter	Type	Required	Description
Content	String	Yes	The content of the text watermark. Example: "Text Watermark".
FontName	String	No	The name of the font. For more information, see Parameter values for font names.
FontColor	String	No	The color of the font. For more information, see Color setting parameters.
FontAlpha	String	No	The transparency of the text watermark. Valid values: (0,1]. Default value: 1.0.
BorderColor	String	No	The color of the font outline. For more information, see Color setting parameters.
Top	Integer	No	The top margin of the text watermark. Only integer values are supported. Default value: 0. Valid values: [0,4096].
Left	Integer	No	The left margin of the text watermark. Only integer values are supported. Default value: 0. Valid values: [0,4096].
FontSize	Integer	No	The size of the font. Only integer values are supported. Default value: 16. Valid values: (4,120).
BorderWidth	Integer	No	The width of the font outline. Only integer values are supported. Default value: 0. Valid values: (0,4096].

Timeline: the configurations for a watermark timeline

Parameter	Type	Required	Description
Start	String	Yes	The beginning of the time range in which the watermark is displayed. Unit: seconds. Valid values: positive numbers. Default value: 0.
Duration	String	Yes	The time range in which the watermark is displayed. Unit: seconds. Valid values: [The value of the Start parameter,ToEND]. Default value: ToEND, which indicates the end of the video.

Important

This parameter is valid only for image watermarks.

Parameter values for font names

Font name	Description
SimSun	Simplified Chinese-SimSun
WenQuanYi Zen Hei	WenQuanYi Zen Hei
WenQuanYi Zen Hei Mono	Simplified Chinese-WenQuanYi Zen Hei Mono
WenQuanYi Zen Hei Sharp	Simplified Chinese-WenQuanYi Zen Hei Sharp
Yuanti SC	Yuanti SC Regular

Video snapshots

Snapshot template configuration

SnapshotTemplateConfig

Parameter

Type

Required

Description

SnapshotType

String

Yes

The type of the snapshot. Valid values:

NormalSnapshot: normal snapshot
SpriteSnapshot: image sprite
WebVttSnapshot: WebVTT snapshot

SnapshotConfig

JSON

Yes

The snapshot configurations, which vary based on the snapshot type. For more information, see SnapshotConfig.

SnapshotConfig

Note

An image sprite is composed of multiple normal snapshots. Therefore, the SnapshotConfig parameter is required for both image sprites and normal snapshots.

Parameter	Type	Required	Description
FrameType	String	Yes	The frame type of the snapshots. Valid values: intra: keyframes normal: normal frames
Count	Long	Yes	The number of snapshots that you want to capture.
Interval	Long	Yes	The snapshot interval. The value must be greater than or equal to 0. Unit: seconds. If you set this parameter to 0, snapshots are captured at even intervals based on the video duration divided by the value of the Count parameter.
SpecifiedOffsetTime	Long	Yes	The point in time when the first snapshot is captured. Unit: milliseconds.
Width	Integer	No	The width of each snapshot. Valid values: [8,4096]. By default, the width of the source video is used. Unit: pixels.
Height	Integer	No	The height of each snapshot. Valid values: [8,4096]. By default, the height of the source video is used. Unit: pixels.
SpriteSnapshotConfig	JSON	No	The snapshot configurations for image sprites. This parameter is required if you set SnapshotType to SpriteSnapshot. For more information, see SpriteSnapshotConfig.
Format	String	No	The format of the output file. Set the value to vtt. This parameter only takes effect when the SnapshotType parameter is set to WebVttSnapshot.
SubOut	JSON	No	Specifies how snapshots are displayed. This parameter only takes effect when the SnapshotType parameter is set to WebVttSnapshot. For more information, see SubOut.

SpriteSnapshotConfig

Parameter	Type	Required	Description
CellWidth	String	No	The width of the original snapshots that compose the image sprite. Default value: the width of a normal snapshot. Unit: pixels.
CellHeight	String	No	The height of the original snapshots that compose the image sprite. Default value: the height of a normal snapshot. Unit: pixels.
Padding	String	Yes	The padding of the original snapshots that compose the image sprite. Unit: pixels.
Margin	String	Yes	The margin of the original snapshots that compose the image sprite. Unit: pixels.
Color	String	Yes	The background color of the image sprite. For more information, see Color setting parameters. Note You cannot set background colors by using RGB values.
Columns	String	Yes	The number of columns for the original snapshots that compose the image sprite. Valid values: [1,10000].
Lines	String	Yes	The number of rows for the original snapshots that compose the image sprite. Valid values: [1,10000].
KeepCellPic	String	Yes	Specifies whether to retain the original snapshots that compose the image sprite. Valid values: keep delete

SubOut

Parameter

Type

Required

Description

IsSptFrag

String

Yes

Valid values:

false: separately stores each snapshot.
true: combines multiple snapshots to produce an image sprite and stores the image sprite.

Example of the SnapshotConfig parameter

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

Frame animation

Frame animation template configuration

DynamicImageTemplateConfig

Parameter	Type	Required	Description
Name	String	Yes	The name of the frame animation template.
Video	JSON	Yes	The display configurations of the animated sticker. For more information, see Video.
Container	JSON	Yes	The format of animated stickers. For more information, see Container.
Clip	JSON	Yes	The configurations used to generate an animated sticker from a video clip. For more information, see Clip.
SetDefaultCover	String	Yes	Specifies whether to automatically use the captured animated sticker as the video thumbnail. Valid values: true: uses the captured animated sticker as the video thumbnail. false: does not use the captured animated sticker as the video thumbnail.

Video

Note

If you do not specify Width or Height, the size of the source video is used.
If you specify only the Width parameter, the height of the animated sticker is resized based on the aspect ratio of the source video.
If you specify only the Height parameter, the width of the animated sticker is resized based on the aspect ratio of the source video.

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

Container

Parameter

Type

Required

Description

Format

String

Yes

The format of the animated sticker. Valid values:

webp
gif

Clip

Parameter	Type	Required	Description
TimeSpan	JSON	Yes	The timeline configurations of the animated sticker. For more information, see TimeSpan.

TimeSpan

Note

If you want to capture an animated sticker based on the duration, specify the Seek and Duration parameters. If you want to capture a specific part of the video to generate an animated sticker, you must specify the Seek and End parameters.
If you specify the Seek, Duration, and End parameters at the same time, the Seek and End parameters take effect.

Parameter	Type	Required	Description
Seek	String	Yes	The start time of the captured video clip. Values in the following formats are supported: 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 video clip. Values in the following formats are supported: 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 remaining part of the video after the video clip is cropped. If you specify this parameter, the Duration parameter does not take effect. Values in the following formats are supported: 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.

Example of the DynamicImageTemplateConfig parameter

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