All Products
Search
Document Center

ApsaraVideo VOD:Effect configurations

Last Updated:May 13, 2024

The structure of the Effect parameter varies based on effect types. This topic describes the structure of the Effect parameter.

Banner text

For more information about the timeline example, see Text overlay.

Parameter

Type

Required

Description

X

Float

No

The horizontal distance between the upper-left corner of the text and the upper-left corner of the output video.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates a number of pixels. Default value: 0. The coordinates are scaled based on the size of the source and the output video.

Y

Float

No

The vertical distance between the upper-left corner of the text and the upper-left corner of the output video.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates a number of pixels. Default value: 0. The coordinates are scaled based on the size of the source and the output video.

TimelineIn

Float

No

The time when the text is displayed in the timeline. Unit: seconds. The value is accurate to four decimal places. If this parameter is not specified, the TimelineIn value of the clip is used.

TimelineOut

Float

No

The time when the text stops to be displayed in the timeline. Unit: seconds. The value is accurate to four decimal places. If this parameter is not specified, the TimelineOut value of the clip is used.

Content

String

Yes

The content of the banner text.

Font

String

No

The font of the banner text. Default value: SimSun.

For more information about the supported fonts, see Fonts.

FontSize

Int

Yes

The font size of the banner text. The font size is scaled based on the size of the material and the output video.

Note

You can specify either FontSize or FixedFontSize. If you specify FontSize and FixedFontSize, only FontSize takes effect.

FixedFontSize

Int

Yes

The font size of the banner text. The font size is not scaled based on the size of the material and the output video.

Note

You can specify either FontSize or FixedFontSize. If you specify FontSize and FixedFontSize, only FontSize takes effect.

FixedX

Float

No

The horizontal distance between the upper-left corner of the text and the upper-left corner of the output video.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates a number of pixels. Default value: 0. The coordinates are not scaled based on the size of the material and the output video.

FixedY

Float

No

The horizontal distance between the upper-left corner of the text and the upper-left corner of the output video.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates a number of pixels. Default value: 0. The coordinates are not scaled based on the size of the material and the output video.

FontColor

String

No

The color of the text in the hexadecimal format. The value starts with a number sign (#).

Example: #ffffff.

FontColorOpacity

String

No

The transparency of the banner text. Valid values: 0 to 1. 1 indicates that the text is not transparent and 0 indicates that the text is completely transparent. Default value: 1.

FontFace

FontFace

No

The appearance of the banner text.

Spacing

Integer

No

The word spacing of the banner text. Unit: pixels. Default value: 0.

Angle

Float

No

The rotation angle of the banner text in the counterclockwise direction. Unit: degrees. Default value: 0.

BorderStyle

Int

No

The border style of the banner text. Valid values: 1 and 3. 1 indicates that the text has a border and a shadow and 3 indicates that the text has a background. Default value: 1.

Outline

Int

No

The stroke width of the banner text. Unit: pixels. Default value: 0.

OutlineColour

String

No

The stroke color of the banner text in the hexadecimal format. The value starts with a number sign (#). Example: #ffffff.

Shadow

Int

No

The shadow size of the banner text. Unit: pixels. Default value: 0.

BackColour

String

No

The shadow color of the banner text in the hexadecimal format. The value starts with a number sign (#). Example: #ffffff.

Alignment

String

No

The location of the banner text. Default value: TopLeft. Valid values:

  • TopLeft

  • TopCenter

  • TopRight

  • CenterLeft

  • CenterCenter

  • CenterRight

  • BottomLeft

  • BottomCenter

  • BottomRight

AdaptMode

String

No

Indicates whether to enable automatic line breaking or automatic scaling when the width of the banner text exceeds the video width or the specified TextWidth. Valid values:

  • AutoWrap: enables automatic line breaking

  • AutoScale: enables automatic scaling

  • AutoWrapAtSpaces: automatically wraps text by using the white space only when the text is displayed in English.

TextWidth

String

No

The width of the text box. This parameter takes effect when AdaptMode is specified. This parameter is used when you enable automatic line breaking or automatic scaling. If this parameter is not specified, automatic line breaking or automatic scaling is performed based on the video width. Unit: pixels.

FontUrl

String

No

The URL of the font file in Object Storage Service (OSS). The following formats of font files are supported: ttf, otf, and woff.

Example: https://your-bucket.oss-cn-shanghai.aliyuncs.com/example-font.ttf.

EffectColorStyle

String

No

The word art effect of the banner text.

For more information about the word art effects, see Word art effect examples.

AaiMotionInEffect

String

No

The entrance effect of the banner text.

For more information about the entrance effects, see Entrance effects.

AaiMotionIn

Float

No

The duration of the entrance effect. Unit: seconds. The value is accurate to four decimal places. If AaiMotionIn is not specified, the default value of this parameter is 0.5 seconds. If the banner text is displayed for less than 0.5 seconds, the duration of the entrance effect is the total duration of the banner text minus the duration of the exit effect.

AaiMotionOutEffect

String

No

The exit effect of the banner text.

For more information about the exit effects, see Exit effects.

AaiMotionOut

Float

No

The duration of the exit effect. Unit: seconds. The value is accurate to four decimal places. If AaiMotionOut is not specified, the default value of this parameter is 0.5 seconds. If the banner text is displayed for less than 0.5 seconds, the duration of the exit effect is the total duration of the banner text.

AaiMotionLoopEffect

String

No

The loop effect of the banner text. The loop effect cannot take effect together with the entrance effect or the exit effect.

For more information about the loop effects, see Loop effects.

Ratio

Float

No

The speed of the loop effect. The value is accurate to four decimal places. If this parameter is not specified, 1 is used by default. A value greater than 1 indicates a higher loop speed and a value less than 1 indicates a slower loop speed.

Masking

Parameter

Type

Required

Description

X

Float

No

The horizontal distance between the upper-left corner of the blurred area and the upper-left corner of the output video. You can set the value to a percentage or the number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates the number of pixels. Default value: 0.

Y

Float

No

The vertical distance between the upper-left corner of the blurred area and the upper-left corner of the output video. You can set the value to a percentage or the number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates the number of pixels. Default value: 0.

Width

Float

Yes

The width of the blurred area in the output video. You can set the value to a percentage or the number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates the number of pixels.

Height

Float

Yes

The height of the blurred area in the output video. You can set the value to a percentage or the number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates a number of pixels.

TimelineIn

Float

No

The time at which the area is blurred in the timeline. Unit: seconds. The value is accurate to four decimal places. If this parameter is not specified, the TimelineIn value of the clip is used.

TimelineOut

Float

No

The time at which the area stops being blurred in the timeline. Unit: seconds. The value is accurate to four decimal places. If this parameter is not specified, the TimelineOut value of the clip is used.

Cropping

For more information about the timeline example, see Remove black bars.

Parameter

Type

Required

Description

X

Float

No

The horizontal distance between the upper-left corner of the video image after cropping and the upper-left corner of the output video.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates a number of pixels. Default value: 0.

Y

Float

No

The vertical distance between the upper-left corner of the video image after cropping and the upper-left corner of the output video.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates a number of pixels. Default value: 0.

Width

Float

Yes

The width of the video image in the output video after cropping.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates a number of pixels.

Height

Float

Yes

The height of the video image in the output video after cropping.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates a number of pixels.

Scaling

For more information about the timeline example, see Configure picture-in-picture.

Note

If the width or height of the material is different from those of the output video and scaling is not configured, the system automatically scales the material width or height to the width or height of the video, centers the material, and adds black bars to fill the view.

Parameter

Type

Required

Description

Width

Float

Yes

The width of the video image in the output video after scaling.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 1, the value indicates a number of pixels.

Height

Float

Yes

The height of the video image in the output video after scaling.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 1, the value indicates a number of pixels.

Padding

Note

If the aspect ratio of the material is different from that of the output video and padding is not configured, the system automatically scales the material width or height to the width or height of the video, centers the material, and adds paddings to fill the view.

Parameter

Type

Required

Description

Left

Float

No

The distance between the left side of the material and the left side of the output video.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 1, the value indicates a number of pixels.

Right

Float

No

The distance between the right side of the material and the right side of the output video.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 1, the value indicates a number of pixels.

Top

Float

No

The distance between the top of the material and the top of the output video.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 1, the value indicates a number of pixels.

Bottom

Float

No

The distance between the bottom of the material and the bottom of the output video.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 1, the value indicates a number of pixels.

Color

String

No

The color of the paddings in the hexadecimal format. The value must start with a number sign (#). Example: #000000. The default color is black.

Background settings

If the size of the material is inconsistent with the size of the output video, you can specify to blur the blank area or fill the blank area with a specified color.

Background settings can be used together with effects such as cropping, scaling, and transition.

Parameter

Type

Required

Description

SubType

String

Yes

The type of the background setting. Valid values:

Blur

Color

Radius

Float

No

The blur radius. This parameter takes effect only when SubType is set to Blur. Valid values: [0.01,1].

Color

String

No

The RGB color value in the hexadecimal format. This parameter takes effect only when SubType is set to Color.

Example: #FFFFFF.

Transitions

A transition effect connects two materials. You need to specify the transition duration only for the previous material. Then, the transition effect connects the end of the previous material and the beginning of the next material by overlaying the video images. After you add a transition effect between two materials, the total duration of the materials is shortened by the duration of the transition effect.

For example, a video track has two materials Clip 1 and Clip 2, and the duration of Clip 1 is 10 seconds, the duration of Clip 2 is 8 seconds. If you add a 4-second transition effect between Clip 1 and Clip 2, the total duration of the video track is reduced from 18 seconds to 14 seconds.

Parameter

Type

Required

Description

SubType

String

Yes

The type of the transition effect. You can specify multiple transition effects and separate them with commas (,). Then the system randomly selects one of the transition effects. Alternatively, you can specify random to let the system randomly select a transition effect from all transition effects. For more information about the valid values and effects, see Transition effect examples.

Example: directional.

Duration

Float

No

The duration of the transition effect. Unit: seconds. The value is accurate to four decimal places. Default value: 1.

Visual effects

Parameter

Type

Required

Description

SubType

String

Yes

The type of the visual effect. You can specify multiple visual effects and separate them with commas (,). Then the system randomly selects one of the visual effects. Alternatively, you can specify random to let the system randomly select a visual effect from all visual effects. For more information about the valid values and effects, see Special effect examples.

Example: colorfulradial.

X

Float

No

This parameter takes effect only when SubType is set to mosaic_rect/blur. The horizontal distance between the upper-left corner of the visual effect area and the upper-left corner of the output video.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates a number of pixels.

Y

Float

No

This parameter takes effect only when SubType is set to mosaic_rect/blur.

The vertical distance between the upper-left corner of the visual effect area and the upper-left corner of the output video.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates a number of pixels.

Width

Float

No

This parameter takes effect only when SubType is set to mosaic_rect/blur. The width of the visual effect area in the output video.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates a number of pixels.

Height

Float

No

This parameter takes effect only when SubType is set to mosaic_rect/blur. The height of the visual effect area in the output video.

You can set the value to a percentage or a number of pixels. If the value ranges from 0 to 0.9999, the value indicates a percentage. If the value is an integer greater than or equal to 2, the value indicates a number of pixels.

Filters

Parameter

Type

Required

Description

SubType

String

Yes

The type of the filter. You can specify multiple filters and separate them with commas (,). Then the system randomly selects one of the filters. Alternatively, you can specify random to let the system randomly select a filter from all filters. For more information about the valid values and effects, see Filter effect examples.

Example: M1.

TimelineIn

Float

No

The time when the filter is applied in the timeline. Unit: seconds. The value is accurate to four decimal places. If this parameter is not specified, the TimelineIn value of the clip is used.

TimelineOut

Float

No

The time when the filter is lifted in the timeline. Unit: seconds. The value is accurate to four decimal places. If this parameter is not specified, the TimelineOut value of the clip is used.

ExtParams

String

No

The parameters related to filters. This parameter takes effect only when SubType is set to color. In this case, a color toning filter is applied. For more information about the configuration of ExtParams, see ExtParams.

ExtParams

For more information about the timeline example, see Use rendering filters.

Parameter

Type

Valid value

Description

Default value

brightness

int

[-255,255]

Brightness

0

contrast

int

[-100,100]

Contrast

0

saturation

int

[-100,100]

Saturation

0

kelvin_temperature

int

[1000,40000]

The color temperature. This parameter takes effect when temperature_ratio is specified.

temperature_ratio

6000

temperature_ratio

int

[0,100]

The color temperature ratio.

0

tint

int

[-100,100]

tint

0

dark_corner_ratio

int

[0,100]

Vignetting

0

Volume tuning

For more information about timeline examples, see Example of muting an entire video and Example of adjusting the volume of a video and dubbing the video with an audio resource whose volume is also adjusted.

Parameter

Type

Required

Description

Gain

Float

No

The volume. Valid values: 0 to 10. A smaller value indicates a lower volume. 0 indicates mute, 1 indicates the original volume. Default value: 1.

Audio fade-in and fade-out

For more information about timeline examples, see Example of configuring audio fade-in and fade-out for a video and Example of configuring audio fade-in and fade-out.

Parameter

Type

Required

Description

SubType

String

Yes

The type of audio fading. Valid values:

  • In

  • Out

Duration

Float

No

The duration of audio fading. Audio fade-in is applied at the beginning of a material and audio fade-out is applied at the end of a material. Default value: 0. 0 indicates that no audio fading is applied.

Curve

String

No

The volume curve of audio fading. Default value: exp.

Valid values:

  • exp: exponential curve

  • tri: linear curve

Rotation

You can rotate a material by 90, 180, or 270 degrees. You can specify a rotation angle in the video track or image track.

For more information about the timeline example, see Configure material rotation.

Parameter

Type

Required

Description

Degree

Integer

Yes

The rotation angle in the clockwise direction. You can rotate a material only by 90, 180, or 270 degrees.

Random clip capture

You can randomly capture a clip from the original material and add the clip to the timeline.

For more information about the timeline example, see Use a random effect.

Parameter

Type

Required

Description

SubType

String

Yes

The type of the capture. Valid value: RandomClip.

ClipDuration

Float

Yes

The duration of the video track clip.

Flipping

You can flip videos or images in a video track along the x-axis or y-axis.

Parameter

Type

Required

Description

Direction

String

Yes

  • horizontal: flips videos or images along the x-axis

  • vertical: flips videos or images along the y-axis

Ken Burns

You can add the Ken Burns effect to videos and images in the video track.

Limits:

  • You can apply this effect only to images and videos. You can use the Ken Burns effect together with visual effects, filters, and transitions.

  • You can specify the WindowW and WindowH parameters to configure the width and height of the output video. After you specify the WindowW and WindowH parameters, you cannot crop, scale, pad, or configure the background for the output video image.

Parameter

Type

Required

Description

Example

Duration

Float

No

The duration of the effect. Default value: the duration of the clip. Unit: seconds. Maximum value: 10.

5

WindowW

Float

No

The width of the clip. By default, the value equals to the width of the output video. Unit: pixels.

If the value of WindowW is in the range of (0,1], the value is a relative value. If the value is greater than 1, the value is an absolute value.

1

WindowH

Float

No

The height of the clip. By default, the value equals to the height of the output video. Unit: pixels.

If the value of WindowH is in the range of (0,1], the value is a relative value.

If the value is greater than 1, the value is an absolute value.

1

Start

String

No

The position of the effect area before the Ken Burns effect is applied. The position is determined by the x and y coordinates of the upper-left corner and the width and height of the effect area. The parameters are optional. The values must be separated by commas (,).

"StartX,StartY,StartW,StartH"

The following rules apply:

0 < StartX + StartW <=1

0 < StartY + StartH <=1

"0,0,0.9,0.9"

StartX

Float

No

The x coordinate of the upper-left corner of the effect area before the Ken Burns effect is applied. Unit: pixels.

If the value of StartX is in the range of [0,1), the value is a relative value.

If the value is greater than or equal to 1, the value is an absolute value.

0

StartY

Float

No

The y coordinate of the upper-left corner of the effect area before the Ken Burns effect is applied. Unit: pixels.

If the value of StartY is in the range of [0,1), the value is a relative value.

If the value is greater than or equal to 1, the value is an absolute value.

0

StartW

Float

No

The width of the effect area before the Ken Burns effect is applied. Unit: pixels.

If the value of StartW is in the range of (0,1], the value is a relative value.

If the value is greater than 1, the value is an absolute value.

0.9

StartH

Float

No

The height of the effect area before the Ken Burns effect is applied. Unit: pixels.

If the value of StartH is in the range of (0,1], the value is a relative value.

If the value is greater than 1, the value is an absolute value.

0.9

End

String

No

The position of the effect area after the Ken Burns effect is applied. The position is determined by the x and y coordinates of the upper-left corner and the width and height of the effect area. The parameters are optional. The values must be separated by commas (,).

"EndX,EndY,EndW,EndH"

The following rules apply:

0 < EndX + EndW <=1

0 < EndY + EndH <=1

"0,0,1,1"

EndX

Float

No

The x coordinate of the upper-left corner of the effect area after the Ken Burns effect is applied. Unit: pixels.

If the value of StartX is in the range of [0,1), the value is a relative value.

If the value is greater than or equal to 1, the value is an absolute value.

0

EndY

Float

No

The y coordinate of the upper-left corner of the effect area after the Ken Burns effect is applied. Unit: pixels.

If the value of StartY is in the range of [0,1), the value is a relative value.

If the value is greater than or equal to 1, the value is an absolute value.

0

EndW

Float

No

The width of the effect area after the Ken Burns effect is applied. Unit: pixels.

If the value of StartW is in the range of (0,1], the value is a relative value.

If the value is greater than 1, the value is an absolute value.

1

EndH

Float

No

The height of the effect area after the Ken Burns effect is applied. Unit: pixels.

If the value of StartH is in the range of (0,1], the value is a relative value.

If the value is greater than 1, the value is an absolute value.

1

Zooming

You can add zooming effects to clips.

Important

You can add zooming effects only to clips in the video track.

Parameter

Type

Required

Description

StartRate

Float

No

  • The current zoom value.

  • Default value: 1.0

  • Valid values: [1.0,5.0].

EndRate

Float

No

  • The desired zoom value.

  • Default value: The value of StartRate plus 0.3.

  • Valid values: [StartRate,5.0]

Duration

Float

No

  • The duration of the zooming effect.

  • Default value: the rendering duration of the clip.

  • Valid values: [0,clip rendering duration]