All Products
Search
Document Center

ApsaraVideo VOD:Parameters for media processing

Last Updated:Jan 04, 2024

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"
}