文档

接入预览组件Web SDK

更新时间:

智能生产制作提供单独预览Timeline的能力,您可以根据实际需求在前端页面文件中引入。通过阅读本文,您可以了解如何接入预览组件Web SDK。

使用说明

预览组件Web SDK版本号同视频剪辑Web SDK,本文中引入的预览组件Web SDK的版本号5.0.1仅供参考,从5.0.1开始,你需要申请License授权才能使用剪辑websdk。获取最新的版本及License信息,请参见视频剪辑工程——帮助信息

操作步骤

  1. 引入预览组件Web SDK。

    在项目前端页面文件中的<head>标签处引入预览组件Web SDK的CSS文件。

    <head>
      <link rel="stylesheet" href="https://g.alicdn.com/thor-server/video-editing-websdk/5.0.1/player.css">
    </head>

    <body>标签处添加一个用以挂载预览界面的<div>节点,并在<body>标签末尾添加引入Web SDK的JS文件,同时添加一个用以调用Web SDK的<script>节点。

    <body>
      <div id="player-wrapper" style="height:500px"></div> // 您可以根据需要改变 container 高度
      <script src="https://g.alicdn.com/thor-server/video-editing-websdk/5.0.1/player.js"></script>
      <script>
        // 调用 SDK 的代码放在这里
      </script>
    </body>
  2. 初始化预览组件Web SDK。

    const player = new window.AliyunTimelinePlayer({
      container: document.querySelector('#player-wrapper'),
      licenseConfig: {
        rootDomain: "", // license使用的根域名,例如abc.com
        licenseKey: "", // 申请的licenseKey,没有配置licenseKey,在预览时会出现水印,没有配置license的情况下,只能在localhost的域名下预览
      },
      timeline: {
        VideoTracks: [], // 省略 VideoTracks 的内容
        AudioTracks: [], // 省略 AudioTracks 的内容
        AspectRatio: '16:9',
      },
      getMediaInfo: (mediaId) => {
        return Promise.resolve('https://example.com/url/for/this/media.mp4');
      },
    });
    • 初始化实例new window.AliyunTimelinePlayer(PlayerInitConfig)中的参数PlayerInitConfig说明如下:

      interface PlayerInitConfig {
        licenseConfig?: {
          rootDomain?: string;
          licenseKey?: string;
        }; // license配置
        getTimelineMaterials?: (params: TimelineMaterial[]) => Promise<InputMedia[]>; // timeline媒资素材
        mode?: 'component' | 'player'; // 播放器组件样式:component为纯组件
        componentClass?: string;
        container: Element;// 预览组件的容器,HTML 元素
        locale?: Locales;// 界面语言,可选 'zh-CN' | 'en-US',默认 'zh-CN'
        controls?: boolean; // 是否显示底部的播控栏,默认 true
        timeline?: AliyunTimeline; // WebSDK 生成的 timeline 对象,需要注意与 OpenAPI 的 timeline 不完全一致
        playbackRate?: number;// 初始化时的播放速度,默认是 1。注意,该值的范围与浏览器本身对 video 的 playbackRate 限制有关
        aspectRatio?: string;// 初始化时的画面比例,默认是 '16:9'。可自定义宽高比,以英文冒号相连。建议与制作 AliyunTimeline 时的画面比例一致
        minWidth?: number | string;// 指定播放器最小宽度
        customFontList?: CustomFontItem[]; // 自定义字体列表
        getMediaInfo?: (
          mediaId: string,
          mediaType: MediaType,
          mediaOrigin?: MediaOrigin | undefined,
          inputUrl?: string | undefined,
        ) => Promise<string | DynamicSrcObj>;
      }// 与 https://help.aliyun.com/document_detail/453478.html 中的 getDynamicSrc 一样,通过 mediaId 返回其对应的带鉴权的播放 URL
      
    • AliyunTimelinePlayer类的定义如下:

      class AliyunTimelinePlayer {
        static parseTimeline(
          timeline: string | IServerTimeline,
          // 需要传入画布的大小,一般是Timeline中FECanvas的Width,Height的值
          options: { outputWidth: number; outputHeight: number } = { outputWidth: 800, outputHeight: 450 },
        ):ParsedResult; // 后端Timeline在前端进行预览转换
        constructor(config: PlayerInitConfig); // 见前述
        play(): void; // JS 控制播放
        pause(): void; // JS 控制暂停
        destroy(): boolean; // 销毁实例
        on(eventName: string, callback: Function): void; // 监听事件
        once(eventName: string, callback: Function): void; // 监听事件一次
        off(eventName: string): void; // 取消监听事件
        get event$():Observable<EventData<any>>; //事件流,通过subscribe订阅所有事件,参考rxjs订阅逻辑
        get version(): string; // 获取版本号
        get duration(): number; // 获取总时长,单位为秒
        get timeline(): AliyunTimeline; // 获取当前的 AliyunTimeline
        set timeline(timeline: AliyunTimeline); // 设置 AliyunTimeline
        get currentTime(): number; // 获取当前时刻,与 video 元素相同,单位为秒
        set currentTime(currentTime: number); // 跳转到某个时刻
        get controls(): boolean; // 获取当前是否展示播控条
        set controls(controls: boolean); // 设置是否展示播控条
        get aspectRatio(): string; // 获取当前的画面比例
        set aspectRatio(aspectRatio: string); // 设置画面比例。注意,修改画面比例可能会导致预览画面与制作 AliyunTimeline 时所看到的不一致,不建议修改
        get playbackRate(): number; // 获取当前的播放速度
        set playbackRate(playbackRate: number); // 设置播放速度。注意,该值的范围与浏览器本身对 video 的 playbackRate 限制有关
        get state():number; // 当前播放器状态,
        async setFontList(value: CustomFontItem[]); //设置自定义字体
      }
      // 自定义字体接口
       interface CustomFontItem {
        key: string; // 字体唯一标识
        name?: string; // 展示的名字
        url: string; // 字体地址
          urlType?: 'dynamic' | 'static'; // 如果url需要动态从getMedinfo中获取,填写dynamic否则填static
      }
      // 播放器状态
      enum PLAYER_STATE {
          PLAYING = 0,
          PAUSED = 1,
          STALLED = 2,
          ENDED = 3,
          BROKEN = 4
      }
      //前端解析Timeline结果
       interface ParsedResult {
        success: boolean; // 解析是否成功
        logs: any[];
        timeline: IServerTimeline; // Timeline解析结果
        toBackendTimeline: (fTimeline: IServerTimeline) => IServerTimeline; //前端Timeline转换为服务端Timeline
        mediaMap: ParsedMediaMap;
        output: {
          width: number;
          height: number;
        };
        fontList: Array<{ key: string; url: string }>;
      }
      
      type ParsedMediaMap = {
        [key: string]: {
          mediaType: string;
          mediaId: string;
          mediaUrl?: string;
          width?: number;
          height?: number;
          duration: number;
        };
      }
      
       type InputMedia = (InputVideo | InputAudio | InputImage);
      
       interface InputVideo {
        mediaId: string;
        mediaIdType?: MediaIdType;
        mediaType: 'video';
        video: {
          duration: number;
        };
      }
       interface InputAudio   {
        mediaId: string;
        mediaIdType?: MediaIdType;
        mediaType: 'audio';
        audio: {
          duration: number;
        };
      }
       interface InputImage   {
        mediaId: string;
        mediaIdType?: MediaIdType;
        mediaType: 'image';
        image: {
          coverUrl?: string;
        };
      }
      
      type MediaIdType = 'mediaId' | 'mediaURL';
  3. 释放实例。

    使用destroy方法可以释放实例,释放后容器为空元素。

    player.destroy();

示例代码

本文中的示例为完整示例,实现一个功能:创建一个带自定义字体,转场,特效的Timeline预览器。

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <link rel="icon" type="image/svg+xml" href="/vite.svg" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <link rel="stylesheet" href="https://g.alicdn.com/thor-server/video-editing-websdk/4.12.2/player.css">
  <script src="https://g.alicdn.com/thor-server/video-editing-websdk/4.12.2/player.js"></script>
  <title>云剪预览播放器</title>
</head>

<body>
  <div id="root">

    <div id="player" style="width: 800px;height: 450px;"></div>
  </div>
  <script type="text/javascript">

    const timelineDemo = {
      "Version": 1,
      "SdkVersion": "4.12.2",
      "VideoTracks": [
        { // 视频轨道
          "Id": 1,
          "Type": "Video",
          "Visible": true,
          "Disabled": false,
          "Count": 1,
          "VideoTrackClips": [
            { // 图片
              "Id": 3,
              "TrackId": 1,
              "Type": "Image",
              "MediaURL": "https://img.alicdn.com/imgextra/i4/O1CN01TDN7Gw1SCgVv61T4s_!!6000000002211-0-tps-1920-1046.jpg",
              "Title": "test.png",
              "X": 0,
              "Y": 0,
              "Width": 1,
              "Height": 1,
              "TimelineIn": 0,
              "TimelineOut": 5,
              "Duration": 5,
              "VirginDuration": 5
            }, {
              // 视频
              "Id": 4,
              "TrackId": 1,
              "Type": "Video",
              "MediaURL": "https://ice-pub-media.myalicdn.com/vod-demo/%E6%9C%80%E7%BE%8E%E4%B8%AD%E5%9B%BD%E7%BA%AA%E5%BD%95%E7%89%87-%E6%99%BA%E8%83%BD%E5%AD%97%E5%B9%95.mp4",
              "X": 0,
              "Y": 0,
              "Width": 1,
              "Height": 1,
              "TimelineIn": 4, // 转场的入点(TimelineIn)需要在上一个片段出点(TimelineOut)以前
              "TimelineOut": 9,
              "Duration": 5,
              "VirginDuration": 5,
              "Effects": [
                { // 转场
                  "Type": "Transition",
                  "Id": 13,
                  "Name": "transitions.directional",
                  "SubType": "directional",
                  "Duration": 1, // 转场时长=上一个片段出点(TimelineOut)-这个片段的入点(TimelineIn)
                  "From": 3 // 上一个片段的ID
                }
              ]
            }
          ]
        },
        { // 特效轨道
          "Id": 2,
          "Type": "Effect",
          "Visible": true,
          "Disabled": false,
          "Count": 1,
          "VideoTrackClips": [
            {
              "Type": "VFX",
              "Id": 2,
              "TrackId": 1,
              "SubType": "heartfireworks",
              "TimelineIn": 0,
              "TimelineOut": 5,
              "Duration": 5,
              "X": 0,
              "Y": 0,
              "Width": 0,
              "Height": 0
            }
          ]
        }
      ],
      "AudioTracks": [],
      "SubtitleTracks": [
        {
          "Id": 2,
          "Type": "Text",
          "Visible": true,
          "Disabled": false,
          "Count": 1,
          "SubtitleTrackClips": [
            {
              "Id": 1,
              "TrackId": 2,
              "Type": "Text",
              "X": 0,
              "Y": 0,
              "TimelineIn": 0,
              "TimelineOut": 2,
              "Duration": 2,
              "VirginDuration": 2,
              "FontSize": 30,
              "FontColor": "#333333",
              "FontColorOpacity": 1,
              "Content": 'FontUrl自定义字体',
              "Alignment": "BottomCenter",
              // 自定义字体
              "FontUrl": "https://ice-pub-media.myalicdn.com/mts-fonts/%E7%AB%99%E9%85%B7%E6%96%87%E8%89%BA%E4%BD%93.ttf"
            }
          ]
        }
      ],
      "AspectRatio": "16:9",
      "From": "websdk",
      "FECanvas": {
        "Width": 800,
        "Height": 450
      },
      "FEConfig": {
        "AutoProportion": "681:383"
      }
    };
    // 前端解析Timeline数据
    const parsedData = window.AliyunTimelinePlayer.parseTimeline(timelineDemo,
      {
        outputWidth: timelineDemo.FECanvas.Width,
        outputHeight: timelineDemo.FECanvas.Height
      });

    console.log('PARSED DEATA', parsedData);

    const player = new window.AliyunTimelinePlayer({
      container: document.getElementById('player'),
      getMediaInfo: async (mediaId) => {
        const mediaMap = parsedData.mediaMap;
        if (mediaMap[mediaId]) {
          return mediaMap[mediaId].mediaUrl;
        }
        return '';
        // 如果使用mediaId,通过GetMediaInfo的方式获取数据,参考一下代码
        // return request('GetMediaInfo', { // https://help.aliyun.com/document_detail/197842.html
        //   MediaId: mediaId
        // }).then((res) => {
        //   // 注意,这里仅作为示例,实际中建议做好错误处理,避免如 FileInfoList 为空数组时报错等异常情况
        //   const fileInfoList = get(res, 'data.MediaInfo.FileInfoList', []);
        //   let mediaUrl, maskUrl;
        //   let sourceFile = fileInfoList.find((item) => {
        //     return item?.FileBasicInfo?.FileType === 'source_file';
        //   })
        //   if (!sourceFile) {
        //     sourceFile = fileInfoList[0]
        //   }
        //   const maskFile = fileInfoList.find((item) => {
        //     return (
        //       item.FileBasicInfo &&
        //       item.FileBasicInfo.FileUrl &&
        //       item.FileBasicInfo.FileUrl.indexOf('_mask') > 0
        //     );
        //   });
        //   if (maskFile) {
        //     maskUrl = get(maskFile, 'FileBasicInfo.FileUrl');
        //   }
        //   mediaUrl = get(sourceFile, 'FileBasicInfo.FileUrl');
        //   if (!maskUrl) {
        //     return mediaUrl;
        //   }
        //   return {
        //     url: mediaUrl,
        //     maskUrl
        //   }
        // })
      }
    });
    // 设置自定义字体
    player.setFontList(parsedData.fontList);
    // 预览前端Timeline,前端Timeline不能直接提交合成
    player.timeline = parsedData.timeline;
    // 可以通过toBackendTimeline转换为后端Timeline
    console.log('toBackendTimeline', parsedData.toBackendTimeline(parsedData.timeline));
  </script>
</body>

</html>

常见问题

如何更新timeline

在创建AliyunTimelinePlayer的实例后,通过赋值即可更新timeline

player.timeline = {....}

如果出现缓存导致的问题,可以尝试先赋空值,清空timeline的内容,再赋值为新的timeline。

player.timeline = {} // 赋空值,清空timeline的内容

预览字体大小和合成的视频不一致?

如果合成时字体变小,须确保timeline中包含FECanvas字段,FECanvas字段表示预览器的分辨率,在合成时服务端会根据这个分辨率及输出的分辨率对字体进行缩放,常见FECanvas分辨率如下:

//16:9
FECanvas: {Width: 800, Height: 450}
//9:16
FECanvas: {Width: 253.125, Height: 450}

预览播放器内置的字体列表?

[
"Alibaba PuHuiTi",  //阿里巴巴普惠体
"STFangsong", //仿宋字体
"KaiTi", // 楷体
"SimSun", //宋体
"Source Han Sans CN Normal", // 思源黑体
"思源宋体", //思源宋体
"WenQuanYi Zen Hei Mono", //文泉驿等宽正黑
"WenQuanYi Zen Hei Sharp", //文泉驿点阵正黑
"文泉驿微米黑", //文泉驿微米黑
"zcool-gdh", //站酷高端黑体
"HappyZcool-2016", //站酷快乐体
"zcoolwenyiti" //站酷文艺体
]
重要

传参时需要保留空格,例如"Font":"Alibaba PuHuiTi",

前端报错player.js:27 TypeError: Cannot read properties of undefined (reading 'GLctx')?

出现这种错误一般是没有打开浏览器硬件加速导致的,请确保浏览器内核版本为Chrome且版本号大于80,并在浏览器上打开硬件加速。

说明

当前Web SDK只支持Chrome内核浏览器。

预览播放器Timeline支持

后端Timeline支持情况请参考:Timeline配置说明

前端Timeline支持情况:

  • Track

    名称

    类型

    是否支持

    描述

    VideoTracks

    VideoTrack[]

    视频轨列表。多个轨道的层叠顺序与数组元素顺序一致,例如:数组的第一个元素图层的t在最底层,第二个元素的图层在其之上,以此类推。

    AudioTracks

    AudioTrack[]

    音频轨列表。

    ImageTracks(图片轨能力已兼容合并至视频轨 VideoTracks,图片轨将不再迭代维护)

    ImageTrack[]

    否, 建议合并到VideoTracks,Type="Image",或通过SDK的ParasedTimeline方法支持

    图片轨列表。

    1. 图片轨需叠加在视频轨之上,图片本身作为素材与视频混编时(如图片合成视频场景),请使用视频轨VideoTracks。

    2. 多个轨道的层叠顺序与数组元素顺序一致,如:数组的第一个元素图层的t在最底层,第二个元素的图层在其之上,以此类推。

    SubtitleTracks

    SubtitleTrack[]

    否, 建议合并到VideoTracks,Type="Subtitle",或通过SDK的ParasedTimeline方法支持

    字幕轨列表。

    EffectTracks

    EffectTrack[]

    否, 建议合并到VideoTracks,

    Type="Effects",或通过SDK的ParasedTimeline方法支持

    特效轨列表。

  • VideoTrackClip

    名称

    类型

    是否支持

    是否必填

    描述

    MediaId

    String

    视频轨素材片段对应的IMS内容库媒资ID,或VOD媒资ID。

    说明

    MediaId和MediaURL有且仅有一个不为空。

    MediaURL

    String

    否(可以通过paraseTimeline方法支持)

    视频轨素材片段对应的OSS地址,格式为:

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

    说明
    • MediaId和MediaURL有且仅有一个不为空。

    • MediaURL 仅支持OSS外网地址,不支持OSS加速地址、cdn地址或其他http url。

    示例:多视频混剪Timeline

    Type

    String

    部分,

    不支持

    GlobalImage,AI_Avatar

    素材片段类型,默认Video。

    取值:

    • Video(视频)

    • Image(图片)

    X

    Float

    表示图片或视频左上角距离输出视频左上角的横向距离。

    说明

    支持百分比和像素两种形式。当取值为[0~0.9999]时,表示相对输出视频宽的占比。当取值为>=2的整数时,表示绝对像素。

    Y

    Float

    表示图片或视频左上角距离输出视频左上角的纵向距离。

    说明

    支持百分比和像素两种形式。当取值为[0~0.9999]时,表示相对输出视频高的占比。当取值为>=2的整数时,表示绝对像素。

    Width

    Float

    取值为[0~1.9999],表示相对输出视频宽的占比,暂不支持绝对值。

    Height

    Float

    取值为[0~1.9999],表示相对输出视频宽的占比,暂不支持绝对值。

    AdaptMode

    String

    视频尺寸自适应模式类型,默认为Fill,必须同时设置视频轨道Width和Height,该模式才会生效,此时Width和Height为目标区域宽高,视频会在目标区域内自适应缩放。

    • Contain:被替换的内容将被缩放,在填充目标区域的同时保留其长宽比。

    • Cover:被替换的内容在保持其宽高比的同时填充整个目标区域。如果对象的宽高比与内容框不相匹配,该对象将被剪裁以适应目标区域。

    • Fill:默认逻辑,被替换的内容正好填充目标内容框。整个对象将完全填充此框。如果对象的宽高比与内容框不相匹配,那么该对象将被拉伸以适应目标区域。

    In

    Float

    素材片段相对于素材的入点,在素材类型是音视频时使用。单位:秒,精确到小数点后4位。如果In不填,默认为0。

    Out

    Float

    素材片段相对于素材的出点,在素材类型是音视频时使用。单位:秒,精确到小数点后4位。如果Out不填,默认为素材时长。

    MaxOut

    Float

    素材片段相对于素材的最大出点值。如果设置该值,素材片段相对于素材的出点将会设置为素材时长与该值中的较小者。在素材为音视频时使用。单位:秒,精确到小数点后4位。如果填入Out值,MaxOut值将失效。

    Duration

    Float

    素材片段的时长,一般在素材类型是图片时使用。单位:秒,精确到小数点后4位。

    DyncFrames

    Int

    动图的帧数,在素材类型是图片且为动图时使用。示例:使用gif贴纸

    TimelineIn

    Float

    素材片段相对于时间线的入点。单位:秒,精确到小数点后4位。如果TimelineIn不填,则会按照素材片段顺序相接的方式自动计算TimelineIn。

    TimelineOut

    Float

    素材片段相对于时间线的出点。单位:秒,精确到小数点后4位。如果TimelineOut不填,则会按照素材片段顺序相接的方式自动计算TimelineOut。

    Speed

    Float

    视频素材速率,取值范围0.1~100,如:Speed=2,则将视频做2倍速处理,Clip的Duration减半,并合成到成片中。

    参考示例:多视频混剪Timeline

    Opacity

    Float

    视频不透明度,取值范围0~1,如:Opacity=0,表示完全透明;Opacity=1,表示完全不透明。

    MaskVideoUrl

    String

    遮罩视频地址。一般为带 Alpha 通道的视频,用于为原视频添加透明通道效果。

    说明

    仅支持传入 OSS 外网地址

    ClipId

    String

    轨道对齐参数。其他音视频轨道的素材如果设置了相同的ReferenceClipId,则其时间线入出点与当前clip对齐。

    参考文档:素材与素材时长自动对齐

    ReferenceClipId

    String

    轨道对齐参数。其他音视频轨道的素材如果设置了相同的ClipId,则当前clip的时间线入出点与其他轨道的素材对齐。

    参考文档:素材与素材时长自动对齐

    Effects

    Effect[]

    素材片段的效果列表。

  • AudioTrackClip

    名称

    类型

    是否支持

    是否必填

    描述

    MediaId

    String

    音频轨素材片段对应的IMS内容库媒资ID,或VOD媒资ID。

    说明

    MediaId和MediaURL有且仅有一个不为空。

    MediaURL

    String

    否(可以通过paraseTimeline方法支持)

    音频轨素材片段对应的OSS地址,格式为:

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

    说明
    • MediaId和MediaURL有且仅有一个不为空。

    • MediaURL 仅支持OSS外网地址,不支持OSS加速地址、cdn地址或其他http url。

    示例:多视频混剪Timeline

    In

    Float

    素材片段相对于素材的入点。单位:秒,精确到小数点后4位。如果In不填,默认为0。

    Out

    Float

    素材片段相对于素材的出点。单位:秒,精确到小数点后4位。如果Out不填,默认为素材时长。

    TimelineIn

    Float

    素材片段相对于时间线的入点。单位:秒,精确到小数点后4位。如果TimelineIn不填,则会按照素材片段顺序相接的方式自动计算TimelineIn。

    TimelineOut

    Float

    素材片段相对于时间线的出点。单位:秒,精确到小数点后4位。如果TimelineOut不填,则会按照素材片段顺序相接的方式自动计算TimelineOut。

    Speed

    Float

    音频素材速率,取值范围0.1~100,如:Speed=2,则将音频做2倍速处理,Clip的Duration减半,并合成到成片中。

    参考示例:多视频混剪Timeline

    Effects

    Effect[]

    素材片段的效果列表

    LoopMode

    Boolean

    素材片段在时间线中循环播放效果。

    • True:循环播放;

    • False(默认值):正常不循环。

    参考示例:多视频混剪Timeline

    ClipId

    String

    轨道对齐参数。其他音视频轨道的素材如果设置了相同的ReferenceClipId,则其时间线入出点与当前clip对齐。

    参考文档:素材与素材时长自动对齐

    ReferenceClipId

    String

    轨道对齐参数。其他音视频轨道的素材如果设置了相同的ClipId,则当前clip的时间线入出点与其他轨道的素材对齐。

    参考文档:素材与素材时长自动对齐

  • ImageTrackClip

    名称

    类型

    是否支持

    是否必填

    描述

    MediaId

    String

    图片轨素材对应的媒资库图片资源MediaId,或VOD图片媒资Id。

    说明

    MediaId和MediaURL有且仅有一个不为空。

    MediaURL

    String

    否(可以通过paraseTimeline方法支持

    图片轨素材片段对应的OSS地址,格式为:https://your-bucket.oss-cn-shanghai.aliyuncs.com/your-object.mp4。

    说明
    • MediaId和MediaURL有且仅有一个不为空。

    • MediaURL 仅支持OSS外网地址,不支持OSS加速地址、cdn地址或其他http url。

    示例:多视频混剪Timeline

    X

    Float

    表示图片左上角距离输出视频左上角的横向距离。

    说明

    支持百分比和像素两种形式。当取值为[0~0.9999]时,表示相对输出视频宽的占比。当取值为>=2的整数时,表示绝对像素。

    Y

    Float

    表示图片左上角距离输出视频左上角的纵向距离。

    说明

    支持百分比和像素两种形式。当取值为[0~0.9999]时,表示相对输出视频高的占比。当取值为>=2的整数时,表示绝对像素。

    Width

    Float

    表示图片在输出视频中的宽度。

    说明

    支持百分比和像素两种形式。当取值为[0~0.9999]时,表示相对输出视频宽的占比。当取值为>=2的整数时,表示绝对像素。

    Height

    Float

    表示图片在输出视频中的高度。

    说明

    支持百分比和像素两种形式。当取值为[0~0.9999]时,表示相对输出视频高的占比。当取值为>=2的整数时,表示绝对像素。

    TimelineIn

    Float

    图片出现在时间线的起始位置。单位:秒,精确到小数点后4位。如果TimelineIn不填,默认值为0。

    TimelineOut

    Float

    图片出现在时间线的结束位置。单位:秒,精确到小数点后4位。如果TimelineOut不填,默认值为视频轨的最大时长。

    DyncFrames

    Int

    动图的帧数,在素材为动图时必填。示例:使用gif贴纸

    Effects

    Effect[]

    素材的效果列表。

  • SubtitleTrackClip

    名称

    类型

    是否支持

    是否必填

    描述

    Type

    String

    仅支持Text

    字幕素材类型。取值:

    • Subtitle 外挂字幕文件

    • Text 横幅文字

    SubType

    String

    字幕素材子类型。取值:

    • srt 外挂srt字幕

    • ass 外挂ass字幕

    字幕素材类型为横幅文字时,可忽略该字段。

    FileURL

    String

    字幕文件对应的OSS地址。当字幕类型为外挂字幕时必填。格式为:

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

    说明

    FileURL 仅支持OSS外网地址,不支持OSS加速地址、cdn地址或其他http url。

    示例:多视频混剪Timeline

    X

    Float

    当字幕类型为横幅文字时,表示文字左上角距离输出视频左上角的横向距离。

    说明

    支持百分比和像素两种形式。当取值为[0~0.9999]时,表示相对输出视频宽的占比。当取值为>=2的整数时,表示绝对像素。

    Y

    Float

    当字幕类型为横幅文字时,表示文字左上角距离输出视频左上角的纵向距离。

    说明

    支持百分比和像素两种形式。当取值为[0~0.9999]时,表示相对输出视频高的占比。当取值为>=2的整数时,表示绝对像素。

    TimelineIn

    Float

    当字幕类型为横幅文字时,表示文字出现在时间线的起始位置。单位:秒,精确到小数点后4位。如果TimelineIn不填,则会按照素材顺序相接的方式自动计算TimelineIn

    TimelineOut

    Float

    当字幕类型为横幅文字时,表示文字出现在时间线的结束位置。单位:秒,精确到小数点后4位。如果TimelineOut不填,则会按照素材顺序相接的方式自动计算TimelineOut。

    Content

    String

    当字幕类型为横幅文字时必填,表示文字内容。

    Font

    String

    支持字体:

    "Alibaba PuHuiTi", //阿里巴巴普惠体
    "STFangsong", //仿宋字体
    "KaiTi", // 楷体
    "SimSun", //宋体
    "Source Han Sans CN Normal", // 思源黑体
    "思源宋体", //思源宋体
    "WenQuanYi Zen Hei Mono", //文泉驿等宽正黑
    "WenQuanYi Zen Hei Sharp", //文泉驿点阵正黑
    "文泉驿微米黑", //文泉驿微米黑
    "zcool-gdh", //站酷高端黑体
    "HappyZcool-2016", //站酷快乐体
    "zcoolwenyiti" //站酷文艺体

    FontSize

    Int

    当字幕类型为横幅文字时,表示文字的字号。

    SizeRequestType

    String

    当字幕类型为横幅文字时,表示将文字字号到实际文字渲染大小的计算方式,默认处理方式为Nominal

    • Nominal:字幕渲染高度(像素值)等于字号FontSize

    • RealDim:在某些字体上,字幕渲染高度(像素)可能会小于字号FontSize

    FontColor

    String

    当字幕类型为横幅文字时,表示文字的颜色,格式为#后跟16进制值。例如:#ffffff。

    FontColorOpacity

    String

    当字幕类型为横幅文字时,表示文字的透明度,取值0-1,默认1。1为不透明,0为完全透明。

    FontFace

    FontFace

    当字幕类型为横幅文字时,表示文字的字体外观。

    Spacing

    Int

    当字幕类型为横幅文字时,表示横幅文字字间距。单位:像素值,默认为0。

    LineSpacing

    Int

    当字幕类型为横幅文字时,表示横幅文字行间距。单位:像素值,默认为0。

    Angle

    Float

    当字幕类型为横幅文字时,表示横幅文字逆时针旋转角度。单位:度,默认为0。

    BorderStyle

    Int

    设置横幅文字边框和阴影格式。取值1或3,1=边框+阴影,3=不透明底框。默认为1。

    Outline

    Int

    当字幕类型为横幅文字时,表示横幅文字描边宽度。单位:像素值,默认为0。

    OutlineColour

    String

    当字幕类型为横幅文字时,表示横幅文字描边颜色,格式为#后跟16进制值。例如:#ffffff。

    Shadow

    Int

    当字幕类型为横幅文字时,表示横幅文字投下阴影的深度,单位:像素值,默认为0。

    BackColour

    String

    当字幕类型为横幅文字时,表示横幅文字阴影颜色,格式为#后跟16进制值。例如:#ffffff。

    Alignment

    String

    当字幕类型为横幅文字时,用于设置定位对齐方式,默认为TopLeft,支持设置:

    • TopLeft:视频左上角

    • TopCenter:视频竖直中轴线上侧

    • TopRight:视频右上角

    • CenterLeft:视频水平中轴线左侧

    • CenterCenter:视频中心位置

    • CenterRight:视频水平中轴线右侧

    • BottomLeft:视频左下角

    • BottomCenter:视频竖直中轴线下侧

    • BottomRight:视频右下角

    AdaptMode

    String

    横幅文字当超出视频宽度或超出指定TextWidth时进行自动换行或缩放:

    • AutoWrap:自动换行

    • AutoScale:自动缩放

    • AutoWrapAtSpaces:只在空格位置自动换行(适用于纯英文字幕自动换行场景)

    TextWidth

    Float

    字幕文本框宽度,当设置AdaptMode时生效。将按照该值设置文本框宽度进行自动换行或缩放。不填写时,会按照视频宽度进行自动换行或缩放。当值大于0小于等于1时,表示相对输出视频的宽度,当值大于1时,表示绝对像素值。

    FontUrl

    String

    否,可以通过parseTimeline转换成key,url的方式进行设置

    当字幕类型为横幅文字时,支持使用用户OSS的字体文件路径来生成字幕,支持ttf、otf、woff三种格式的字体文件。例如:https://your-bucket.oss-cn-shanghai.aliyuncs.com/example-font.ttf

    EffectColorStyle

    String

    当字幕类型为横幅文字时,表示横幅文字花字样式类型。花字种类及效果见:花字效果示例

    SubtitleEffects

    SubtitleEffect[]

    当字幕类型为横幅文字时,表示文字多层效果。目前支持设置多层描边、多层阴影以及高斯模糊效果(高斯模糊仅支持在类型为阴影时使用)。

    说明
    • 如果设置SubtitleEffects时,字幕轨道中Outline、Shadow字段不会再生效;

    • 当设置多层描边/阴影效果时,SubtitleEffects数组的顺序表示层级顺序,数组中第一个SubtitleEffect会渲染在最底层,数组中最后一个SubtitleEffect会渲染在最上层;

    AaiMotionInEffect

    String

    当字幕类型为横幅文字时,表示横幅文字入场特效类型。字幕入场特效种类及效果见:字幕特效效果示例

    AaiMotionIn

    Float

    当字幕类型为横幅文字时,表示横幅文字入场特效时长。单位:秒,精确到小数点后4位,如果AaiMotionIn不填,默认0.5s,如果文本时长小于0.5,则为总时长减去出场时长。

    AaiMotionOutEffect

    String

    当字幕类型为横幅文字时,表示横幅文字出场特效类型。字幕出场特效种类及效果见:字幕特效效果示例

    AaiMotionOut

    Float

    当字幕类型为横幅文字时,表示横幅文字出场特效时长,单位秒,精确到小数点后4位,如果AaiMotionOut不填,默认0.5s,如果文本时长小于0.5,则为总文本时长。

    AaiMotionLoopEffect

    String

    当字幕类型为横幅文字时,表示横幅文字循环特效类型,不可与字幕入场或者出场特效同时生效。循环特效种类以及效果见:字幕特效效果示例

    Ratio

    Float

    当字幕类型为横幅文字时,表示横幅文字循环特效播放速度,精确到小数点后4位。不填默认为1,大于1表示加速循环,小于1表示慢速循环。

  • EffectTrackItem

    名称

    类型

    是否支持

    是否必填

    描述

    Type

    String

    特效轨片段类型,支持:VFX、Filter。

    SubType

    String

    特效轨片段子类型,请参见:

    特效效果示例滤镜效果示例

    TimelineIn

    Float

    特效片段出现在时间线的起始位置。单位:秒,精确到小数点后4位。如果TimelineIn不填,则默认为0。

    TimelineOut

    Float

    特效片段出现在时间线的结束位置。单位:秒,精确到小数点后4位。如果TimelineOut不填,则默认为视频结束时间。

    Duration

    Float

    特效片段出现在时间线的持续时长。单位:秒,精确到小数点后4位。如果Duration不填,则默认为视频时长。

    说明

    Duration和TimelineOut仅有一个生效。

    X

    Float

    该字段仅支持SubType为mosaic_rect/blur的情况。特效区域左上角距离输出视频左上角的横向距离。

    说明

    支持百分比和像素两种形式。当取值为[0~0.9999]时,表示相对输出视频宽的占比。当取值为>=2的整数时,表示绝对像素。

    Y

    Float

    该字段仅支持SubType为mosaic_rect/blur的情况。

    特效区域距离输出视频左上角的纵向距离。

    说明

    支持百分比和像素两种形式。当取值为[0~0.9999]时,表示相对输出视频高的占比。当取值为>=2的整数时,表示绝对像素。

    Width

    Float

    该字段仅支持SubType为mosaic_rect/blur的情况。特效区域在输出视频中的宽度。

    说明

    支持百分比和像素两种形式。当取值为[0~0.9999]时,表示相对输出视频宽的占比。当取值为>=2的整数时,表示绝对像素。

    Height

    Float

    该字段仅支持SubType为mosaic_rect/blur的情况。特效区域在输出视频中的高度。

    说明

    支持百分比和像素两种形式。当取值为[0~0.9999]时,表示相对输出视频高的占比。当取值为>=2的整数时,表示绝对像素。

  • VideoClips effect支持情况

    名称

    类型

    是否支持

    是否必填

    描述

    Type

    String

    支持类型

    Text,Crop,Scale,Transition,Filter,VFX,Volume,AFade

    效果类型。取值如下:

    • Text(横幅文字:视频轨素材)

    • DeWatermark(模糊:视频轨素材)

    • Crop(裁剪:视频轨素材)

    • Pad(贴边:视频轨素材)

    • Scale(缩放:视频轨素材)

    • Transition(转场:视频轨素材)

    • VFX(特效:视频轨素材)

    • Volume(音量调整:音频轨素材)

    • AFade(音频淡入淡出:音频轨)

    • AI_ASR(识别音频生成字幕:视频轨、音频轨素材)

    SubType

    String

    效果子类型

    • 当Type为Transition时,会进一步描述转场子类型。取值请参见:转场效果示例

    • 当Type为VFX时,会进一步描述特效子类型。取值请参见:特效效果示例

    • 当Type为Filter 时,会进一步描述滤镜子类型。取值请参见:滤镜效果示例

相关参考

常见问题