阿里云首页 智能媒体生产

高级模板 WebSDK 接入指南

aliyun-advanced-template-websdk 是一个快速搭建高级模板剪辑 web 端界面的 SDK,本文将介绍如何接入这个 SDK

一、准备工作

在 html 的 head 标签中引入 SDK 的 CSS 文件,如下所示:

<head>
  <link rel="stylesheet" href="https://g.alicdn.com/thor-server/advanced-template-websdk/x.x.x/index.css">
</head>

其中 x.x.x 为版本号,当前最新版本为 1.0.0

然后在 html 的 body 标签中创建一个用以挂载剪辑界面的节点,在 body 标签的尾部引入 SDK 的 JS 文件,再引用一个 script 用以调用 WebSDK,如下所示:

<body>
  <div id="aliyun-advanced-template" style="height:100vh"></div> // 您可以根据需要改变 container 高度
  <script src="https://g.alicdn.com/thor-server/advanced-template-websdk/x.x.x/index.js"></script>
  <script>
    // 调用 SDK 的代码放在这里
  </script>
</body>

二、初始化

WebSDK 目前只提供单独 JS 引入的方式,后续会考虑提供 npm 包。该单独 JS 会在 window 上挂载 AliyunAdvancedTemplate 对象。

WebSDK 调用方式如下:

window.AliyunAdvancedTemplate.init(config);

config 是一个对象,对象的 key-value 说明见下一节

三、config 参数说明

注意:这里列出了参考链接的 config 参数,都是希望调用 OpenAPI 对应的接口,在大部分情况下,前端不需要关心参数及返回值,只需要透传函数参数给 OpenAPI,再将 OpenAPI 的响应返回给 WebSDK 即可,具体可参考第四节的示例代码

参数名

参数说明

是否必选

参数类型

参数类型说明

引入版本

locale

界面语言

'zh-CN' | 'en-US'

语言代码,默认展示中文

1.0.0

container

WebSDK 生成界面挂载的 DOM 节点

Element

DOM 节点

1.0.0

projectId

高级模板工程的 id

string

1.0.0

onBackButtonClick

一个函数,用户点击左上角返回按钮后被调用,如不传,则不展示返回按钮

() => void;

1.0.0

updateEditingProject

一个函数,用户修改工程标题或点击保存按钮后被调用

(req: { ProjectId: string; Title?: string; TemplateId?: string; ClipsParam?: string }) => Promise<void>;

参数及返回值请参考:修改云剪辑工程

1.0.0

getEditingProject

获取高级模板工程的元信息,如工程标题、模板 id 等

(req: { ProjectId: string }) => Promise<Response<GetEditingProjectRsp>>;

参数及返回值请参考:获取单个云剪辑工程

1.0.0

getTemplateMaterials

获取模板的原始素材

(req: { TemplateId: string; FileList: string }) => Promise<Response<GetTemplateMaterialsRsp>>;

参数及返回值请参考:获取模板素材地址

1.0.0

batchGetMediaInfos

批量获取媒资信息

(req: { AdditionType: 'FileInfo'; MediaIds: string }) => Promise<Response<BatchGetMediaInfosRsp>>;

参数及返回值请参考:批量获取媒资内容信息

1.0.0

onChangeMaterial

一个函数,用户点击更换素材按钮后被调用

() => Promise<MediaInfo>;

返回一个 Promise,该 Promise 应该 resolve 被选中媒资的信息,MediaInfo 请参考:数据类型

1.0.0

onConfirmPreview

一个函数,用户确定预览视频后被调用

(req: { ProjectTitle: string; TemplateId: string; TemplateSize: [number, number]; ClipsParam: string; }) => Promise<Response<{ MediaId: string }>>;

参数为工程当前的标题、模板 id、模板宽高、ClipsParam,返回一个 Promise,该 Promise 应该 resolve 生成的预览视频的 mediaId

1.0.0

submitMediaProducingJob

提交合成任务

(req: { ProjectId: string; TemplateId: string; TemplateSize: [number, number]; ClipsParam: string; }) => Promise<void>;

参数为工程 id、模板 id,模板宽高、ClipsParam,返回一个 Promise,提交合成任务成功后,该 Promise 应该 resolve

1.0.0

注:ClipsParam 为 ICE 接口合成视频所需要的参数,开发者可直接透传给 ICE 接口,具体参考:提交剪辑合成作业

四、init 方法示例代码

WebSDK 本身只负责界面和交互,不会发起请求,您需要将请求的逻辑提供给 WebSDK 调用。请求本身应该先发送给您自己的服务端,您自己的服务端再根据自己的 AccessKeyId, AccessKeySecret 转发给相关的阿里云 OpenAPI

// 注意,WebSDK 本身并不提供 request 这个方法,这里仅作为示例,您可以使用您喜欢的网络请求库,如 axios 等

const projectId = 'exampleId';

window.AliyunAdvancedTemplate.init({
  locale: 'zh-CN',
  container: document.getElementById('aliyun-advanced-template'),
  projectId,
  onBackButtonClick: () => {
    // 跳转回列表页
    window.location.href = '/mediaEdit/list/advanced';
  },
  updateEditingProject: req => {
    return request('UpdateEditingProject', req);
  },
  getEditingProject: req => {
    return request('GetEditingProject', req);
  },
  getTemplateMaterials: req => {
    return request('GetTemplateMaterials', req);
  },
  batchGetMediaInfos: req => {
    return request('BatchGetMediaInfos', req);
  },
  onChangeMaterial: () => {
    return new Promise(resolve => {
      // 假设 showMediaModal 是您编写的一个函数,这个函数将展示一个 modal 组件,modal 中通过调用 ICE 的
      // ListMediaBasicInfos 接口展示媒资库中的媒资供用户进行选择,用户选择后点击确定按钮,触发 onOk 方法
      showMediaModal({
        onOk(media) {
          resolve(media);
        }
      });
    });
  },
  onConfirmPreview: ({ ProjectTitle, TemplateId, TemplateSize, ClipsParam }) => {
    const height = 360; // 假设按照 360P 进行预览
    let width = Math.floor((height / TemplateSize[1]) * TemplateSize[0]); // 根据模板的比例算出宽度

    if (width % 2 === 1) width += 1; // 保证宽度是偶数

    const filename = `${encodeURIComponent(
      ProjectTitle
    )}_preview_${new Date().toISOString()}.mp4`; // 预览视频文件名由您自定义,这里只是一种示例

    const outputMediaConfig = JSON.stringify({
      MediaURL: `https://exampleBucket.oss-exampleRegion.aliyuncs.com/examplePath/${filename}`,
      Width: width,
      Height: height
    });

    return request('SubmitMediaProducingJob', {
      ProjectId: projectId,
      TemplateId,
      ClipsParam,
      OutputMediaConfig: outputMediaConfig
    });
  },
  submitMediaProducingJob: ({ TemplateId, TemplateSize, ClipsParam }) => {
    return new Promise((resolve, reject) => {
      // 假设 showSubmitModal 是您编写的一个函数,这个函数将展示一个 modal 组件,modal 中提供表单供用户填写合成信息
      // 比如文件名、存储路径、格式、分辨率等,当用户提交表单时,这些填写的信息将被整理成 formValues 传入 onOk 里
      showSubmitModal({
        onOk: async (formValues) => {
          const res = await request('SubmitMediaProducingJob', {
            ...formValues,
            ProjectId: projectId,
            TemplateId,
            ClipsParam
          });
          if (res.code === '200') {
            console.log('success');
            resolve();
          } else {
            console.error('failed');
            reject();
          }
        }
      });
    });
  }
});

首页 智能媒体生产 WebSDK接入手册 高级模板 WebSDK 接入指南