Timeline text overlay configuration examples - ApsaraVideo VOD

Common Timeline configuration examples for text overlays in OpenAPI-based video editing, covering full-duration overlays, specified-region overlays, external subtitles, and word art styles.

Related APIs

Parameters

Parameter	Description
Text coordinates	X: The horizontal distance from the upper-left corner of the text to the upper-left corner of the output video. Y: The vertical distance from the upper-left corner of the text to the upper-left corner of the output video. The value can be a percentage or a pixel value: If the value is in the range of 0 to 0.9999, it represents a ratio of the output video's width or height. X is relative to the width, and Y is relative to the height. If the value is an integer greater than or equal to 8, it indicates an absolute pixel value.
Text properties	Content: The text content. Font: The font of the text. The default font is SimSun. The following fonts are supported: SimSun is a Song typeface. WenQuanYi Zen Hei WenQuanYi Zen Hei Mono is also known as WenQuanYi Equal-Width Zen Hei. WenQuanYi Zen Hei Sharp is an alias for WenQuanYi Dot Matrix Zheng Hei. Yuanti SC Bold: Yuanti-Simplified (Bold). Yuanti SC Light: A lightweight, rounded font for Simplified Chinese. Yuanti SC Regular: Simplified Round. Regular. FontSize: The font size in pixels. The default value is 20. FontColor: The font color in a hexadecimal value. The value must start with a number sign (#), such as #FFFFFF. The default value is #FFFFFF. ColorOpacity: The font color opacity. Valid values: 0 (fully transparent) to 1 (fully opaque). Default value: 1. FontFace: The font style. Bold: Specifies whether to bold the font. The default value is false. Italic: Specifies whether to italicize the font. The default value is false. Underline: Specifies whether to underline the font. The default value is false.
Time range for the text overlay	TimelineIn: The start time of the text relative to the timeline. TimelineOut: The end time of the text relative to the timeline.

Timeline examples

Full-duration text overlay

A full-duration text overlay appears throughout the entire video. You do not need to specify TimelineIn and TimelineOut. The text position in the output video is determined by X and Y. Example:

{
    "VideoTracks": [
        {
            "VideoTrackClips": [
                {
                    "MediaId": "ea9a6f9bdb68419abfd36a7113cf****",
                    "Effects": [
                        {
                            "Type": "Text",
                            "X": 31,
                            "Y": 93,
                            "Font": "WenQuanYi Zen Hei Mono",
                            "Content": "Test text",
                            "FontSize": 26,
                            "FontColorOpacity": 0.2,
                            "FontColor": "#000000",
                            "FontFace": {
                                "Bold": true,
                                "Italic": false,
                                "Underline": false
                            }
                        },
                        {
                            "Type": "Text",
                            "X": 30,
                            "Y": 92,
                            "Font": "WenQuanYi Zen Hei Mono",
                            "Content": "Test text",
                            "FontSize": 26,
                            "FontColorOpacity": 1,
                            "FontColor": "#FFFFFF"
                        },
                        {
                            "Type": "Text",
                            "X": 0.8123,
                            "Y": 0.7896,
                            "Font": "WenQuanYi Zen Hei Mono",
                            "Content": "Test text",
                            "FontSize": 26,
                            "FontColorOpacity": 0.2,
                            "FontColor": "#000000"
                        },
                        {
                            "Type": "Text",
                            "X": 0.8223,
                            "Y": 0.7796,
                            "Font": "WenQuanYi Zen Hei Mono",
                            "Content": "Test text",
                            "FontSize": 26,
                            "FontColorOpacity": 1,
                            "FontColor": "#FFFFFF"
                        }
                    ]
                }
            ]
        }
    ]
}

Specified-region text overlay

A specified-region text overlay displays text within a specific time range. The text position in the output video is determined by X and Y. The following example overlays text from 0 to 5 seconds and from 5 to 10 seconds:

If TimelineIn is not set, the default value is 0.
If you do not set TimelineOut, the overlay continues to the end of the video by default.
If the value of TimelineOut exceeds the video duration, the overlay ends at the end of the video track.

{
    "VideoTracks": [
        {
            "VideoTrackClips": [
                {
                    "MediaId": "ea9a6f9bdb68419abfd36a7113cf****",
                    "Effects": [
                        {
                            "Type": "Text",
                            "X": 31,
                            "Y": 93,
                            "TimelineIn": 0,
                            "TimelineOut": 5,
                            "Font": "WenQuanYi Zen Hei Mono",
                            "Content": "Test text",
                            "FontSize": 26,
                            "FontColorOpacity": 0.2,
                            "FontColor": "#000000",
                            "FontFace": {
                                "Bold": true,
                                "Italic": false,
                                "Underline": false
                            }
                        },
                        {
                            "Type": "Text",
                            "X": 30,
                            "Y": 92,
                            "TimelineIn": 0,
                            "TimelineOut": 5,
                            "Font": "WenQuanYi Zen Hei Mono",
                            "Content": "Test text",
                            "FontSize": 26,
                            "FontColorOpacity": 1,
                            "FontColor": "#FFFFFF"
                        },
                        {
                            "Type": "Text",
                            "X": 1124,
                            "Y": 516,
                            "TimelineIn": 5,
                            "TimelineOut": 10,
                            "Font": "WenQuanYi Zen Hei Mono",
                            "Content": "Test text",
                            "FontSize": 26,
                            "FontColorOpacity": 0.2,
                            "FontColor": "#000000"
                        },
                        {
                            "Type": "Text",
                            "X": 1123,
                            "Y": 515,
                            "TimelineIn": 5,
                            "TimelineOut": 10,
                            "Font": "WenQuanYi Zen Hei Mono",
                            "Content": "Test text",
                            "FontSize": 26,
                            "FontColorOpacity": 1,
                            "FontColor": "#FFFFFF"
                        }
                    ]
                }
            ]
        }
    ]
}

Word art styles

Word art is a special text caption style based on banner text effects. Example:

{
  "VideoTracks": [
    {
      "VideoTrackClips": [
        {
          "MediaId": "MediaId1",
          "Effects": [
            {
              "Type": "Text",
              "X": 33,
              "Y": 34,
              "Font": "WenQuanYi Zen Hei Mono",
              "Content": "Word art with shadow and outline - First line of test text",
              "OutlineColour": "#ee00ff",
              "BackColour": "#CE1212",
              "EffectColorStyle": "skyline",
              "Angle": 300,
              "Outline": 2,
              "Shadow": 3,
              "FontSize": 42,
              "FontColorOpacity": 1,
              "FontColor": "#000000",
              "FontFace": {
                "Bold": true,
                "Italic": false,
                "Underline": false
              }
            },
            {
              "Type": "Text",
              "X": 66,
              "Y": 256,
              "Font": "WenQuanYi Zen Hei Mono",
              "Content": "Second line of text",
              "EffectColorStyle": "golden",
              "Angle": 60,
              "FontSize": 38,
              "FontColorOpacity": 0.8,
              "FontColor": "#d60e0e"
            },
            {
              "Type": "Text",
              "X": 0.7123,
              "Y": 0.7896,
              "TimelineIn": 5,
              "TimelineOut": 20,
              "Font": "WenQuanYi Zen Hei Mono",
              "Content": "Third line of text",
              "FontSize": 26,
              "FontColor": "#000000"
            }
          ]
        }
      ]
    }
  ]
}

Word art parameters

Parameters	Type	Description
EffectColorStyle	string	The type of the word art style. For more information about word art styles and effects, see Word art effect examples.
OutlineColour	string	The outline color. The color is a 6-digit hexadecimal RGB value in the #xxyyzz format.
BackColour	string	The shadow color. The color is a 6-digit hexadecimal RGB value in the #xxyyzz format.
Shadow	int	The shadow depth in pixels for the word art. Default value: 0. The recommended ratio of shadow depth to font size is 2:25. For example, if the font size is 25, set the shadow depth to 2.
Outline	int	The outline width in pixels for the word art. Default value: 0. The recommended ratio of outline width to font size is 2:25. For example, if the font size is 25, set the outline width to 2.
Spacing	int	The spacing between characters, in pixels.
Angle	float	The pre-rotation angle of the subtitle line, in degrees. Valid values: 0 to 360.