Parameters for media processing - ApsaraVideo VOD - Alibaba Cloud Documentation Center

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

EncryptConfig: specifies 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: specifies 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 configurations. To replace a subtitle file, 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 the "SubtitleConfig" section of the Basic structures topic. 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 the subtitle package. 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: specifies 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.

Notice

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

SubtitleSetting: specifies the subtitle files

Parameter	Type	Required	Description
SubtitleList	Subtitle	Yes	The subtitle files.

Subtitle: specifies 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

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: specifies the subtitle package

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

PackageSubtitle: specifies the configurations for a subtitle package

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: specifies 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 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.
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 width of the watermark 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 height of the watermark 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.
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.

Notice

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.
FontColor	String	No	The color of the font.
FontAlpha	String	No	The transparency of the text. Valid values: (0,1]. Default value: 1.0.
BorderColor	String	No	The color of the font outline.
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: specifies 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.

Notice

This parameter is valid only for image watermarks.

SnapshotTemplateConfig: specifies the configurations for a snapshot template

Parameter	Type	Required	Description
SnapshotType	String	Yes	The snapshot type. Valid values: NormalSnapshot: normal snapshot SpriteSnapshot: image sprite WebVttSnapshot: WebVTT-based snapshot
SnapshotConfig	SnapshotConfig	Yes	The snapshot configurations, which vary with the snapshot type. The value is a JSON string.

SnapshotConfig: specifies the configurations for 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 to be captured.
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 video source is used. Unit: pixels.
Height	Integer	No	The height of each snapshot. Valid values: [8,4096]. By default, the height of the video source is used. Unit: pixels.
SpriteSnapshotConfig	SpriteSnapshotConfig	No	The snapshot configurations for image sprites. To capture image sprites, you must set this parameter.
Format	String	No	The file format. Set the value to vtt. This parameter only takes effect when the SnapshotType parameter is set to WebVttSnapshot.
SubOut	SubOut	No	Specifies how snapshots are displayed. This parameter only takes effect when the SnapshotType parameter is set to WebVttSnapshot.

Note

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

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.

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.

SpriteSnapshotConfig: specifies the configurations for capturing image sprites

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

Note

Note: You cannot set background colors by using RGB values.

Parameter values for font names

Font name	Description
SimSun	SimSum
WenQuanYi Zen Hei	WenQuanYi Zen Hei
WenQuanYi Zen Hei Mono	WenQuanYi Zen Hei Mono
WenQuanYi Zen Hei Sharp	WenQuanYi Zen Hei Sharp
Yuanti SC	Yuanti SC Regular