All Products
Search

This Product

    Intelligent Media Services:Timeline configuration

    Document Center

    Intelligent Media Services:Timeline configuration

    Last Updated:Apr 12, 2025

    A timeline is created when you add materials and configure special effects to create a video. A timeline primarily consists of tracks, materials, and effects. For more information, see Best practices.

    Name

    Type

    Required

    Description

    VideoTracks

    VideoTrack[]

    No. The video and audio tracks cannot be empty at the same time.

    The video tracks are overlaid based on the sequence of MediaId array elements. For example, the track that corresponds to the first MediaId array element is placed below the track that corresponds to the second MediaId array element.

    AudioTracks

    AudioTrack[]

    No. The video and audio tracks cannot be empty at the same time.

    The audio tracks.

    ImageTracks (The image track feature has been merged into the VideoTracks feature. The image track feature will no longer be maintained.)

    ImageTrack[]

    No. If an image track exists, the video track cannot be empty.

    The image tracks. Note:

    1) Image tracks are overlaid on video tracks. If you want to add images to a video, use VideoTracks.

    2) The image tracks are overlaid based on the sequence of MediaId array elements. For example, the track that corresponds to the first MediaId array element is placed below the track that corresponds to the second MediaId array element.

    SubtitleTracks

    SubtitleTrack[]

    No

    The subtitle tracks.

    EffectTracks

    EffectTrack[]

    No

    The special effect tracks.

    VideoTrack

    VideoTrack is used to arrange videos and images.

    Name

    Type

    Required

    Description

    Type

    String

    No

    The default value is a regular video track.

    If you set Type to Effect, the current track can be used as an effect track. You can add EffectTrackItem to VideoTrackClips.

    MainTrack

    Boolean

    No

    Indicates whether the current video track is the primary track. Default value: False. For more information and examples, see Set the primary track.

    TrackShortenMode

    String

    No

    If the duration of the current video track is longer than that of the primary track, the current track is automatically shortened to align with the primary track. Valid values:

    • AutoSpeed: automatically accelerates the video.

    TrackExpandMode

    String

    No

    If the duration of the current video track is shorter than that of the primary track, the current track is automatically extended to align with the primary track. Valid values:

    • AutoSpeed: automatically decelerates the video.

    VideoTrackClips

    VideoTrackClip[]

    Yes

    The video clips.

    AudioTrack

    AudioTrack is used to arrange audio-only materials and video materials that contain audio.

    Name

    Type

    Required

    Description

    MainTrack

    Boolean

    No

    Indicates whether the current audio track is the primary track. Default value: False. For more information and examples, see Set the primary track.

    TrackShortenMode

    String

    No

    If the duration of the current audio track is longer than that of the primary track, the current track is automatically shortened to align with the primary track. Valid values:

    • AutoSpeed: automatically accelerates the audio.

    TrackExpandMode

    String

    No

    If the duration of the current audio track is shorter than that of the primary track, the current track is automatically extended to align with the primary track. Valid values:

    • AutoSpeed: automatically decelerates the audio.

    AudioTrackClips

    AudioTrackClip[]

    Yes

    The audio clips.

    ImageTrack

    Important

    The image track feature has been merged into the VideoTrack feature. The image track feature will no longer be maintained.

    ImageTrack is used to arrange images.

    Name

    Type

    Required

    Description

    ImageTrackClips (The image track feature has been merged into the VideoTrackClips feature. The image track feature will no longer be maintained.)

    ImageTrackClip[]

    Yes

    The image clips.

    Subtitletrack

    SubtitleTrack is used to arrange subtitles, including banner text and external subtitles.

    Name

    Type

    Required

    Description

    SubtitleTrackClips

    SubtitleTrackClip[]

    Yes

    The subtitle clips.

    Effecttrack

    EffectTrack is used to add special effects to a video. You can add filters and visual effects to an effect track.

    Name

    Type

    Required

    Description

    EffectTrackItems

    EffectTrackItem[]

    Yes

    The filters and effects that are added to the special effect track.

    VideoTrackClip

    You can add videos and images to a video track.

    You can use the In, Out, TimelineIn, and TimelineOut parameters to specify the position from which the material is cut and added to the timeline. For example, if you set In to 5, Out to 10, TimelineIn to 15 and TimelineOut to 20, the material from the 5th to 10th second is cut and played in a loop from the 15th to 20th second in the timeline.

    Name

    Type

    Required

    Description

    MediaId

    String

    No

    The ID of the media asset in the IMS content library or VOD.

    Note: You must specify either MediaId or MediaURL.

    MediaURL

    String

    No

    The OSS URL of the video clip. Format:

    https://your-bucket.oss-cn-shanghai.aliyuncs.com/your-object.mp4

    Note:

    • You must specify either MediaId or MediaURL.

    • You can set MediaURL to a public OSS endpoint or another public URL.

    Type

    String

    No

    The type of the material. Default value: Video.

    Valid values:

    • Video

    • Image

    • GlobalImage (The duration of the image is calculated based on the duration of the longest video track. )

    X

    Float

    No

    The horizontal distance between the upper-left corner of the image or video 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.

    Y

    Float

    No

    The vertical distance between the upper-left corner of the image or video 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.

    Width

    Float

    No

    The width of the image 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

    No

    The height of the image 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.

    AdaptMode

    String

    No

    The mode in which a material is automatically resized. This parameter takes effect only when you specify the width and height of the view. The material is scaled based on the width and height of the view. Valid values:

    • Contain: resizes the material based on the original aspect ratio and fills in the view.

    • Cover: resizes the material based on the original aspect ratio and fills in the entire view. If the aspect ratio of the material does not match that of the view, the material is cropped to fit the view.

    • Fill (default): resizes the material based on the original aspect ratio and stretch the material to fill in the view. The entire material fills in the view. If the aspect ratio of the material does not match that of the view, the material is stretched to fit the view.

    In

    Float

    No

    The start time of the video clip in the video. This parameter takes effect only if the source file is an audio file or a video file. Unit: seconds. The value is accurate to four decimal places. If you do not specify In, 0 is used by default.

    Out

    Float

    No

    The end time of the video clip in the video. This parameter takes effect only if the source file is an audio file or a video file. Unit: seconds. The value is accurate to four decimal places. If you do not specify Out, the duration of the material is used by default.

    MaxOut

    Float

    No

    The maximum end time of the video clip in the video. If you specify this parameter, the end time of the video clip in the video is the smaller value between the duration of the material and the value of this parameter. This parameter takes effect only if the source file is an audio file or a video file. Unit: seconds. The value is accurate to four decimal places. If you specify the Out parameter, the MaxOut parameter does not take effect. Example: Set MaxOut in a video track.

    Duration

    Float

    No

    The duration of the material. This parameter is generally used for images. Unit: seconds. The value is accurate to four decimal places.

    DyncFrames

    Int

    No

    The number of frames in the animated image. This parameter is used when the material is an animated image. Example: Use a GIF sticker.

    TimelineIn

    Float

    No

    The start time of the video clip in the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineIn, the material is displayed when the display of the previous material in the timeline ends.

    TimelineOut

    Float

    No

    The end time of the video clip in the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineOut, the material stops to be displayed when the display of the next material in the timeline starts.

    Speed

    Float

    No

    The playback speed of the material. Valid values: 0.1 to 100. For example, if you set this parameter to 2, the material is played at twice the original speed in the output video. In this case, the duration of the material is reduced to half.

    Opacity

    Float

    No

    The opacity of the video. Valid values: 0 to 1. For example, if you set Opacity to 0, the video is completely transparent. If you set Opacity to 1, the video is completely opaque.

    MaskVideoUrl

    String

    No

    The URL of the mask video. The mask video is generally a video with an alpha channel. The mask video is used to add a transparent channel effect to the original video.

    • You can set this parameter to a public OSS endpoint or another public URL.

    ClipId

    String

    No

    The track alignment parameter. If materials in other audio or video tracks have the same ReferenceClipId, the start and end times of the materials in the timeline are aligned with those of the current clip.

    References: Automatically align materials based on the duration of materials

    ReferenceClipId

    String

    No

    The track alignment parameter. If materials in other audio or video tracks have the same ClipId, the start and end times of the current clip in the timeline are aligned with those of the materials in other tracks.

    References: Automatically align materials based on the duration of materials

    Effects

    Effect[]

    No

    The special effects that are used on the material.

    Generate a video clip in a video track by using the digital human (AI_Avatar) feature

    You can add a VideoTrackClip of the AI_Avatar type to directly generate a digital human video for editing. For more information, see Process timeline intelligent tasks in parallel.

    Note

    This feature is available only in the China (Beijing), China (Shanghai), and China (Hangzhou) regions.

    Name

    Type

    Required

    Meaning

    Description

    Type

    String

    Yes

    The type of the current clip

    • Fixed value: AI_Avatar

    MediaId

    String

    No

    The ID of the audio asset that is used to render the digital human

    • Note: You must specify one of the MediaId, MediaURL, and Content parameters.

    MediaURL

    String

    No

    The URL of the audio file that is used to render the digital human

    • Note: You must specify one of the MediaId, MediaURL, and Content parameters.

    • You can set this parameter to a public OSS endpoint or another public URL.

    Content

    String

    No

    The text that is used to render the digital human

    • Note: You must specify one of the MediaId, MediaURL, and Content parameters.

    • The text must contain at least five characters.

    AvatarId

    String

    No

    The ID of the digital human image

    Voice

    String

    No

    The voice type

    CustomizedVoice

    String

    No

    The personalized voice

    • You can specify the VoiceId that you obtain after you train a voice by using the voice cloning feature. Then, the audio is generated by using your personalized voice.

    • If you specify this parameter, the Voice parameter does not take effect.

    LoopMotion

    Boolean

    No

    Same frame at the beginning and end

    • If you set this parameter to true, the first frame and the last frame of the generated digital human video are the same. When the digital human video is played in a loop or spliced with other digital human videos, the actions and expressions of the digital human do not change abruptly.

    • Valid values: true and false

    • Default value: false

    SpeechRate

    Integer

    No

    The speech rate

    • If you use Content as the input, you can use this parameter to set the speech rate. Valid values: -500 to 500. Default value: 0.

      • The values -500, 0, and 500 correspond to the speech rate multipliers 0.5, 1.0, and 2.0.

    Note

    The total data size can be calculated by using one of the following formulas:

    • 0.8× speech rate: (1-1/0.8)/0.002 = -125

    • 1.2× speech rate: (1-1/1.2)/0.001 = 166

    If the speech rate multiplier is less than 1, the coefficient 0.002 is used.

    If the speech rate multiplier is greater than 1, the coefficient 0.001 is used.

    The approximate value of the calculation result is used.

    PitchRate

    Integer

    No

    The pitch

    • If you use Content as the input, you can use this parameter to set the pitch.

    • Valid values: -500 to 500

    • Default value: 0

    Note

    Other timeline parameters for generating a video clip in a video track by using the digital human (AI_Avatar) feature are the same as those for a regular VideoTrackClip. For more information about the parameters, see the preceding VideoTrackClip parameters.

    AudioTrackClip

    The audio clips in an audio track can be audio-only materials, video materials that contain audio streams, or audio that is directly generated from text.

    You can use In, Out, TimelineIn, and TimelineOut to specify the position from which a material is cut and added to the timeline. For example, if you set In to 5, Out to 10, TimelineIn to 15, and TimelineOut to 20, the material from the 5th to 10th second is cut and played from the 15th to 20th second in the timeline.

    Note

    Make sure that audio materials in the same audio track do not overlap in the timeline. Otherwise, audio exceptions may occur.

    Audio-only materials or video materials that contain audio streams in an audio track

    Name

    Type

    Required

    Description

    MediaId

    String

    No

    The ID of the media asset in the IMS content library or VOD.

    Note: You must specify either MediaId or MediaURL.

    MediaURL

    String

    No

    The OSS URL of the audio clip. Format:

    https://your-bucket.oss-cn-shanghai.aliyuncs.com/your-object.mp4

    Note:

    • You must specify either MediaId or MediaURL.

    • You can set MediaURL to a public OSS endpoint or another public URL.

    In

    Float

    No

    The start time of the video clip in the video. Unit: seconds. The value is accurate to four decimal places. If you do not specify In, 0 is used by default.

    Out

    Float

    No

    The end time of the video clip in the video. Unit: seconds. The value is accurate to four decimal places. If you do not specify Out, the duration of the material is used by default.

    TimelineIn

    Float

    No

    The start time of the video clip in the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineIn, the material is displayed when the display of the previous material in the timeline ends.

    TimelineOut

    Float

    No

    The end time of the video clip in the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineOut, the material stops to be displayed when the display of the next material in the timeline starts.

    Speed

    Float

    No

    The playback speed of the material. Valid values: 0.1 to 100. For example, if you set this parameter to 2, the material is played at twice the original speed in the output video. In this case, the duration of the material is reduced to half.

    Effects

    Effect[]

    No

    The special effects that are used on the material

    LoopMode

    Boolean

    No

    The loop effect of the material in the timeline. True indicates that the material is played in a loop and False indicates that no loop effect is configured for the material. Default value: False.

    Example: Loop audio playback

    ClipId

    String

    No

    The track alignment parameter. If materials in other audio or video tracks have the same ReferenceClipId, the start and end times of the materials in the timeline are aligned with those of the current clip.

    References: Automatically align materials based on the duration of materials

    ReferenceClipId

    String

    No

    The track alignment parameter. If materials in other audio or video tracks have the same ClipId, the start and end times of the current clip in the timeline are aligned with those of the materials in other tracks.

    References: Automatically align materials based on the duration of materials

    Audio in an audio track that is directly generated from text

    For timeline examples, see the best practices: Convert text to speech by using AI_TTS and merge the speech into a video. This feature is available only in the China (Beijing), China (Shanghai), and China (Hangzhou) regions.

    Name

    Type

    Required

    Description

    Type

    String

    Yes

    Fixed value: AI_TTS

    Content

    String

    Yes

    Text content

    Voice

    String

    No

    Examples of intelligent voice effects

    CustomizedVoice

    String

    No

    • Personalized voice

    • You can specify the VoiceId that you obtain after you train a voice by using the voice cloning feature. Then, the audio is generated by using your personalized voice.

    • If you specify this parameter, the Voice parameter does not take effect.

    Format

    String

    No

    The file format. Default value: mp3.

    The PCM, WAV, and MP3 formats are supported.

    SpeechRate

    Int

    No

    The speech rate. Valid values: -500 to 500. Default value: 0.

    • The values -500, 0, and 500 correspond to the speech rate multipliers 0.5, 1.0, and 2.0. A speech rate multiplier of 1 indicates the default speech rate of the model. The speech rate varies based on the voice. The speech rate is about four characters per second.

    Note

    The total data size can be calculated by using one of the following formulas:

    • 0.8× speech rate: (1-1/0.8)/0.002 = -125

    • 1.2× speech rate: (1-1/1.2)/0.001 = 166

    If the speech rate multiplier is less than 1, the coefficient 0.002 is used.

    If the speech rate multiplier is greater than 1, the coefficient 0.001 is used.

    The approximate value of the calculation result is used.

    PitchRate

    Int

    No

    The pitch. Valid values: -500 to 500. Default value: 0.

    TimelineIn

    Float

    No

    The start time of the video clip in the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineIn, the material is displayed when the display of the previous material in the timeline ends.

    TimelineOut

    Float

    No

    The end time of the video clip in the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineOut, the material stops to be displayed when the display of the next material in the timeline starts.

    Effects

    Effect[]

    No

    The special effects that are used on the material

    ClipId

    String

    No

    The track alignment parameter. If materials in other audio or video tracks have the same ReferenceClipId, the start and end times of the materials in the timeline are aligned with those of the current clip.

    References: Automatically align materials based on the duration of materials

    ReferenceClipId

    String

    No

    The track alignment parameter. If materials in other audio or video tracks have the same ClipId, the start and end times of the current clip in the timeline are aligned with those of the materials in other tracks.

    References: Automatically align materials based on the duration of materials

    Imagetrackclip

    Important

    The image track feature has been merged into the VideoTrackClip feature. The image track feature will no longer be maintained.

    ImageTrackClip is used to add images to an image track.

    Name

    Type

    Required

    Description

    MediaId

    String

    No

    The ID of the image in the media library or VOD.

    Note: You must specify either MediaId or MediaURL.

    MediaURL

    String

    No

    The OSS URL of the image clip. Format: https://your-bucket.oss-cn-shanghai.aliyuncs.com/your-object.mp4

    Note:

    • You must specify either MediaId or MediaURL.

    • You can set MediaURL only to a public OSS endpoint.

    X

    Float

    No

    The horizontal distance between the upper-left corner of the image 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.

    Y

    Float

    No

    The vertical distance between the upper-left corner of the image 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.

    Width

    Float

    No

    The width of the image 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

    No

    The height of the image 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.

    TimelineIn

    Float

    No

    The start time of the image in the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineIn, 0 is used by default.

    TimelineOut

    Float

    No

    The end time of the image in the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineOut, the maximum duration of the video track is used by default.

    DyncFrames

    Int

    No

    The number of frames in the animated image. This parameter is required if the material is an animated image. Example: Use a GIF sticker.

    Effects

    Effect[]

    No

    The special effects that are used on the material

    Subtitletrackclip

    SubtitleTrackClip is used to add subtitles to a subtitle track.

    Note

    Make sure that subtitle clips in the same subtitle track do not overlap in the timeline. Otherwise, the positions of the subtitles may be incorrect.

    Name

    Type

    Required

    Description

    Type

    String

    Yes

    The type of the subtitle. Valid values:

    SubType

    String

    No

    The subtype of the subtitle. Valid values:

    • srt: external SRT subtitle

    • ass: external ASS subtitle

    You can ignore this parameter if the subtitle type is banner text.

    FileURL

    String

    No

    The OSS URL of the subtitle file. This parameter is required if the subtitle type is external subtitle. Format:

    https://your-bucket.oss-cn-shanghai.aliyuncs.com/your-object.srt

    Note:

    • You can set FileURL to a public OSS endpoint or another public URL.

    Example: External subtitle

    X

    Float

    No

    The horizontal distance between the text and the upper-left corner of the output video. This parameter takes effect if you set Type to Text. 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.

    Y

    Float

    No

    The vertical distance between the text and the upper-left corner of the output video. This parameter takes effect if you set Type to Text. 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.

    TimelineIn

    Float

    No

    The start time of the text in the timeline. This parameter takes effect if you set Type to Text. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineIn, the material is displayed when the display of the previous material in the timeline ends.

    TimelineOut

    Float

    No

    The end time of the text in the timeline. This parameter takes effect if you set Type to Text. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineOut, the material stops to be displayed when the display of the next material in the timeline starts.

    ClipId

    String

    No

    The track alignment parameter. If materials in other audio, video, or subtitle tracks have the same ReferenceClipId, the start and end times of the materials in the timeline are aligned with those of the current clip.

    • You must specify the TimelineIn and TimelineOut parameters for the subtitle clip or use the automatic subtitle scrolling duration feature.

    ReferenceClipId

    String

    No

    The track alignment parameter. If materials in other audio, video, or subtitle tracks have the same ClipId, the start and end times of the current clip in the timeline are aligned with those of the materials in other tracks.

    Content

    String

    No

    The text content. This parameter is required if the subtitle type is banner text.

    Font

    String

    No

    The font of the text. This parameter takes effect if you set Type to Text. Default value: SimSun. For more information about the supported fonts, see Font list.

    FontSize

    Int

    No

    The size of the text. This parameter takes effect if you set Type to Text. Default value: 0. Maximum value: 5000.

    SizeRequestType

    String

    No

    The method that is used to calculate the actual rendering size of the text based on the font size. This parameter takes effect if you set Type to Text. Default value: RealDim.

    • Nominal: The rendering height of the subtitle in pixels is equal to the font size.

    • RealDim: For some fonts, the rendering height of the subtitle in pixels may be less than the font size.

    FontColor

    String

    No

    The color of the text. The value is in the format of a number sign (#) and a hexadecimal value. This parameter takes effect if you set Type to Text. Example: #ffffff.

    FontColorOpacity

    Float

    No

    The transparency of the font. This parameter takes effect if you set Type to Text. Valid values: 0 to 1. Default value: 1. 1 indicates that the font is not transparent and 0 indicates that the font is completely transparent.

    FontFace

    FontFace

    No

    The appearance of the font. This parameter takes effect when you set Type to Text.

    Spacing

    Int

    No

    The word spacing of the text. This parameter takes effect when you set Type to Text. Unit: pixels. Default value: 0.

    LineSpacing

    Int

    No

    The line spacing of the banner text. This parameter takes effect when you set Type to Text. Unit: pixels. Default value: 0.

    Angle

    Float

    No

    The rotation angle of the text in the counterclockwise direction. This parameter takes effect when you set Type to Text. Unit: degrees. Default value: 0.

    BorderStyle

    Int

    No

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

    Outline

    Int

    No

    The stroke width of the text. This parameter takes effect when you set Type to Text. Unit: pixels. Default value: 0.

    OutlineColour

    String

    No

    The stroke color of the text in the hexadecimal format. The value starts with a number sign (#). This parameter takes effect when you set Type to Text. Example: #ffffff.

    Shadow

    Int

    No

    The shadow size of the text. This parameter takes effect when you set Type to Text. Unit: pixels. Default value: 0.

    BackColour

    String

    No

    The shadow color of the text in the hexadecimal format. The value starts with a number sign (#). This parameter takes effect when you set Type to Text. Example: #ffffff.

    Alignment

    String

    No

    The alignment mode of the banner text. This parameter takes effect when you set Type to Text. Default value: TopLeft. Valid values:

    • TopLeft: upper-left corner of the video

    • TopCenter: upper side of the vertical axis of the video

    • TopRight: upper-right corner of the video

    • CenterLeft: left side of the horizontal axis of the video

    • CenterCenter: center of the video

    • CenterRight: right side of the horizontal axis of the video

    • BottomLeft: lower-left corner of the video

    • BottomCenter: lower side of the vertical axis of the video

    • BottomRight: lower-right corner of the video

    If you want to locate the accurate positions of subtitles in different alignment modes, we recommend that you set this parameter to one of the following values:

    • Left: left alignment. The value specifies the coordinates of the upper-left vertex of the subtitle in the upper-left corner of the video for X and Y.

    • Center: center alignment. The value specifies the coordinates of the boundary intersection on the central axis of the subtitle in the upper-left corner of the video for X and Y.

    • Right: right alignment. The value specifies the coordinates of the upper-right vertex of the subtitle in the upper-left corner of the video for X and Y.

    AdaptMode

    String

    No

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

    • AutoWrap: enables automatic line breaking.

    • AutoScale: enables automatic scaling.

    • AutoWrapAtSpaces: automatically wraps text only at spaces. This option is applicable only to all English subtitles.

    TextWidth

    Float

    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 you do not specify this parameter, the video width is used for automatic line breaking or automatic scaling. When the value is greater than 0 and less than or equal to 1, the value indicates the percentage of the width of the text box to the width of the output video. When the value is greater than 1, the value indicates the number of pixels.

    FontUrl

    String

    No

    The URL of the font file in OSS. The following formats of font files are supported: ttf, otf, and woff. This parameter takes effect when you set Type to Text. Example: https://your-bucket.oss-cn-shanghai.aliyuncs.com/example-font.ttf

    • You can set this parameter to a public OSS endpoint or another public URL.

    EffectColorStyle

    String

    No

    The word art effect of the text. This parameter takes effect when you set Type to Text. For more information about the types and effects of word art, see Examples of word art effects.

    SubtitleEffects

    SubtitleEffect[]

    No

    The multilayer effects of the text. This parameter takes effect when you set Type to Text. You can configure multilayer describes, multilayer shadows, Gaussian blurs, and subtitle background effects. Gaussian blurs are supported only if the subtitle text is set to have a shadow.

    Note:

    • If you specify the SubtitleEffects parameter, the Outline and Shadow parameters in the subtitle track do not take effect.

    • If you configure multilayer describes, shadows, or background effects, the order of the SubtitleEffects array elements indicates the order of the layers. The first SubtitleEffect in the array is rendered at the bottom layer, and the last SubtitleEffect in the array is rendered at the top layer.

    ScrollStartY

    Float

    No

    The Y coordinate of the starting point for the subtitle to scroll up or down when you configure the subtitle scrolling effect. Unit: pixels. If the value is less than 1, the value indicates a percentage of the height of the output video.

    ScrollEndY

    Float

    No

    The Y coordinate of the ending point for the subtitle to scroll up or down when you configure the subtitle scrolling effect. Unit: pixels. If the value is less than 1, the value indicates a percentage of the height of the output video.

    ScrollSpeed

    Float

    No

    The speed at which the subtitle scrolls up or down per second when you configure the subtitle scrolling effect. Unit: pixels/s.

    ScrollStartShift

    Float

    No

    The offset of the subtitle scrolling position from the starting point when you configure vertical subtitle scrolling. Unit: pixels. If the value is less than 1, the value indicates a percentage of the height of the output video.

    ScrollEndShift

    Float

    No

    The offset of the subtitle scrolling position from the ending point when you configure vertical subtitle scrolling. Unit: pixels. If the value is less than 1, the value indicates a percentage of the height of the output video.

    ScrollStartFreeze

    Float

    No

    The duration for which the subtitle stays at the starting point when you configure vertical subtitle scrolling. Unit: seconds.

    ScrollStartFreeze

    Float

    No

    The duration for which the subtitle stays at the ending point when you configure vertical subtitle scrolling. Unit: seconds.

    ScrollDirection

    String

    No

    The scrolling direction of the subtitle when you configure horizontal subtitle scrolling. Valid values:

    • Left: scrolls to the left

    • Right: scrolls to the right

    ScrollStartX

    Float

    No

    The X coordinate of the starting point for the subtitle to scroll left or right when you configure horizontal subtitle scrolling. Unit: pixels. If the value is less than 1, the value indicates a percentage of the height of the output video.

    ScrollEndX

    Float

    No

    The X coordinate of the ending point for the subtitle to scroll left or right when you configure horizontal subtitle scrolling. Unit: pixels. If the value is less than 1, the value indicates a percentage of the height of the output video.

    ScrollLoop

    Boolean

    No

    Specifies whether to enable loop scrolling when you configure horizontal subtitle scrolling.

    AaiMotionInEffect

    String

    No

    The entrance effect of the banner text. This parameter takes effect if you set the type to Text. For more information about the types and effects of subtitle entrance effects, see Examples of subtitle 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. This parameter takes effect if you set the type to Text. For more information about the types and effects of subtitle exit effects, see Examples of subtitle effects.

    AaiMotionOut

    Float

    No

    The duration of the exit effect of the banner text. This parameter takes effect if you set the type to Text. 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. This parameter takes effect if you set the type to Text. The loop effect cannot take effect together with the entrance effect or the exit effect. For more information about the types and effects of loop effects, see Examples of subtitle effects.

    Ratio

    Float

    No

    The speed of the loop effect of the banner text. This parameter takes effect if you set the type to Text. The value is accurate to four decimal places. If you do not specify this parameter, 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.

    TextureURL

    String

    No

    The URL of the texture of the banner text. This parameter takes effect if you set the type to Text. Only OSS objects in the PNG, JPG, JPEG, or BMP format are supported. Example: https://your-bucket.oss-cn-shanghai.aliyuncs.com/your-image.png

    BubbleStyleId

    String

    No

    The bubble effect ID of the banner text. This parameter takes effect if you set the type to Text. For more information about the types and effects of bubble effects, see Examples of bubble effects.

    BubbleWidth

    Float

    No

    The width of the bubble basemap in the output video. This parameter takes effect only if bubble subtitles are used. A value greater than 1 indicates an absolute pixel value. A value less than or equal to 1 indicates a percentage.

    BubbleHeight

    Float

    No

    The height of the bubble basemap in the output video. This parameter takes effect only if bubble subtitles are used. A value greater than 1 indicates an absolute pixel value. A value less than or equal to 1 indicates a percentage.

    Effecttrackitem

    You can add visual effects and filters to an effect track.

    Name

    Type

    Required

    Description

    Type

    String

    Yes

    The type of the special effect. Valid values: VFX and Filter.

    SubType

    String

    Yes

    The subtype of the special effect. For more information, see:

    Examples of special effects

    Examples of filter effects

    TimelineIn

    Float

    No

    The start time of the special effect in the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineIn, 0 is used by default.

    TimelineOut

    Float

    No

    The end time of the special effect in the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify TimelineOut, the special effect ends when the video ends.

    Duration

    Float

    No

    The duration of the special effect in the timeline. Unit: seconds. The value is accurate to four decimal places. If you do not specify Duration, the duration of the video is used by default.

    You can specify either Duration or TimelineOut.

    X

    Float

    No

    This parameter takes effect only if you set the SubType parameter 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 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.

    Y

    Float

    No

    This parameter takes effect only if you set the SubType parameter to mosaic_rect/blur.

    The vertical distance between the upper-left corner of the effect 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.

    Width

    Float

    No

    This parameter takes effect only if you set the SubType parameter to mosaic_rect/blur. The width of the effect 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

    No

    This parameter takes effect only if you set the SubType parameter to mosaic_rect/blur. The height of the visual effect 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.

    Subtitleeffect

    Subtitle outline/shadow effect

    Name

    Type

    Required

    Description

    Type

    String

    Yes

    -Outline: outline

    -Shadow: shadow

    -Box: subtitle background

    Bord

    Float

    No

    The width or height of the outline or shadow. If the value is greater than 1, the value indicates the number of pixels. If the value is greater than 0 and less than 1, the value indicates the width or height relative to the text size.

    XBord

    Float

    No

    The width of the outline or shadow. If the value is greater than 1, the value indicates the number of pixels. If the value is greater than 0 and less than 1, the value indicates the width relative to the text size. This parameter has a higher priority than the Bord parameter.

    YBord

    Float

    No

    The height of the outline or shadow. If the value is greater than 1, the value indicates the number of pixels. If the value is greater than 0 and less than 1, the value indicates the height relative to the text size. This parameter has a higher priority than the Bord parameter.

    Shift

    Float

    No

    The horizontal or vertical offset of the outline or shadow. If the absolute value is greater than 1, the value indicates the number of pixels. If the absolute value is greater than 0 and less than 1, the value indicates the offset relative to the text size. You can set this parameter to a negative value. A negative value indicates an upward or leftward offset.

    XShift

    Float

    No

    The horizontal offset of the outline or shadow. If the absolute value is greater than 1, the value indicates the number of pixels. If the absolute value is greater than 0 and less than 1, the value indicates the horizontal offset relative to the text size. This parameter has a higher priority than the Shift parameter.

    YShift

    Float

    No

    The vertical offset of the outline or shadow. If the absolute value is greater than 1, the value indicates the number of pixels. If the absolute value is greater than 0 and less than 1, the value indicates the vertical offset relative to the text size. This parameter has a higher priority than the Shift parameter.

    Color

    String

    No

    The RGB color in the hexadecimal format. The value starts with a number sign (#). Example: #ffffff.

    Opacity

    String

    No

    The opacity. The value of 1 indicates that the text is not transparent, and the value of 0 indicates that the text is completely transparent.

    Blur

    Float

    No

    The range of the Gaussian blur in pixels. This parameter takes effect only if Type is set to Shadow. You can use this parameter to implement the glow effect for subtitles.

    Radius

    Float

    No

    The radius of the rounded corners of the solid-color text background. This parameter takes effect only if Type is set to Box. You can use this parameter to implement the rounded corner effect for the subtitle background.

    ImageUrl

    String

    No

    The URL of the custom subtitle background image. This parameter takes effect only if Type is set to Box. You can use this parameter to implement the custom bubble subtitle effect. You can use the BubbleWidth or BubbleHeight parameter to adjust the subtitle size. Only OSS objects in the PNG, JPG, JPEG, or BMP format are supported. Example: https://your-bucket.oss-cn-shanghai.aliyuncs.com/your-image.png.

    Width

    Float

    No

    The width of the source file of the bubble basemap. This parameter is required if you use custom bubble subtitles.

    Height

    Float

    No

    The height of the source file of the bubble basemap. This parameter is required if you use custom bubble subtitles.

    TextArea

    String

    No

    The area of the text in the bubble basemap. This parameter is required if you use custom bubble subtitles. The value consists of four floating-point numbers in the range of [0, 1] that are separated by commas. For example, if you set this parameter to "0.1,0.2,0.8,0.6", the coordinates of the upper-left corner of the subtitle text box relative to the bubble are 0.1 and 0.2, and the width and height of the subtitle text box relative to the bubble are 0.8 and 0.6.

    FontFace

    Font style FontFace

    Name

    Type

    Required

    Description

    Bold

    Boolean

    No

    Bold

    Italic

    Boolean

    No

    Italic

    Underline

    Boolean

    No

    Underline

    Effect

    Material effect Effect

    Different effects have different parameters. Specific parameters are used for multiple effects.

    For more information about the independent parameters of each type of Effect, see Effect configuration.

    The following table describes the common parameters of Effect:

    Name

    Type

    Required

    Description

    Type

    String

    Yes

    The type of the effect. Valid values:

    • Text (banner text: video track material)

    • DeWatermark (blur: video track material)

    • Crop (crop: video track material)

    • Pad (padding: video track material)

    • Scale (scaling: video track material)

    • Transition (transition: video track material)

    • VFX (special effect: video track material)

    • Volume (volume adjustment: audio track material)

    • AFade (audio fade in and fade out: audio track)

    • AI_ASR (recognize audio to generate subtitles: video track and audio track materials)

    SubType

    String

    No

    The subtype of the effect

    • If you set Type to Transition, this parameter indicates the subtype of the transition effect. For more information about the valid values, see Examples of transition effects

    • If you set Type to VFX, this parameter indicates the subtype of the visual effect. For more information about the valid values, see Examples of special effects

    • If you set Type to Filter, this parameter indicates the subtype of the filter. For more information about the valid values, see Examples of filter effects