集成视频剪辑 Web SDK--视频点播-火山引擎

文档中心

视频点播

视频剪辑 Web SDK

集成视频剪辑 Web SDK

本文为您介绍如何将视频剪辑 Web SDK 集成到您的 Web 应用中，并结合视频点播的云端服务，构建一个功能强大的在线视频剪辑器。

整体架构和工作流

Web 视频剪辑解决方案包含以下三个核心部分：

视频剪辑 Web SDK：负责提供可视化的视频剪辑界面，包括时间轴、素材库、预览窗口等。它不直接与视频点播服务通信，而是通过您在 actions 中实现的接口与您的后端服务进行指令交互。
您的后端服务：作为桥梁，连接 Web SDK 和视频点播服务。您的后端负责调用火山引擎 API 完成剪辑工程管理和任务管理等操作，并为前端获取媒体文件的安全访问地址。
视频点播服务：提供底层的基础设施，包括媒资存储、云端剪辑工程和丰富的服务端 API。

典型工作流如下：

您的后端服务调用 CreateProject 创建一个云端剪辑工程，并获取 ProjectId 和 GroupId。
您的后端服务将 ProjectId 和 GroupId 传递给前端页面。
前端页面使用 ProjectId 和 GroupId 初始化 Web SDK，加载剪辑器界面。
用户在剪辑器中进行拖拽、裁剪等操作，SDK 会调用您后端封装的 UpdateProject 接口，实时将草稿保存到云端。
用户点击“导出”，SDK 调用您后端封装的 SubmitEditTaskAsync 接口，提交云端剪辑合成任务。

支持的剪辑素材格式

在将素材添加至剪辑工程前，请确保其格式符合以下要求：

素材类型	支持格式
视频	MP4, WebM, MOV
音频	MP3
图片	JPEG, PNG

说明

暂不支持导入字幕文件（如 SRT，VTT）作为剪辑素材。
所有的剪辑素材（视频、音频、图片）及剪辑产物都必须存储在视频点播服务中，并通过 Vid 模式进行管理。暂不支持 DirectUrl 模式和挂载 TOS。
- 音视频文件上传后，将存储在视频管理中。
- 图片上传后，将存储在素材管理中。

前提条件

在开始前端集成之前，请确保您已完成以下准备工作：

已注册火山引擎账号。如果您是首次登录火山引擎控制台，请先完成实名认证。
已开通视频点播服务。
已在视频点播控制台创建空间，用于存储剪辑素材和最终产物。
已在视频点播控制台配置点播加速域名，用于预览视频。请注意以下事项：
- 开启 HTTPS：为保障数据安全，请确保您的域名已配置 SSL 证书。
- 配置跨域访问：配置配置跨域访问，允许您的 Web 应用前端页面访问视频资源。
- 回源地址一致：确保您域名的回源存储地址与您的点播空间所绑定的存储地址保持一致。
服务端准备：您需要部署一个后端服务来调用视频点播的服务端 API，为前端 SDK 提供数据接口和鉴权。您可以参考体验 Demo 中的 Node.js 部分的代码实现。在加载前端剪辑器之前，您必须通过后端服务调用 CreateProject 接口，预先创建一个云端的视频剪辑工程，获取后续初始化 SDK 所需的 ProjectId 和GroupId。
注意
调用 CreateProject 时：
- 必须同时设置 Space 和 EditParam.Upload.SpaceName 两个参数，且取值相同，确保剪辑工程、剪辑素材和最终产物都归属于同一个点播空间。
- 请确保 EditParam.Canvas 的尺寸为 1920x1080 (16:9) 或 1080x1920 (9:16)，SDK 当前仅支持这两种画布尺寸。
前端开发环境：
- Node.js: v14.x 或更高版本（推荐使用 LTS 版本）。
- npm: 通常会随 Node.js 一同安装。

集成步骤

步骤 1：引入 SDK 资源

在您的前端项目 HTML 文件中，通过 CDN 链接引入 SDK 的 CSS 和 JS 文件。

在 <head> 标签内引入 CSS 文件：

<head>
  <link rel="stylesheet" href="https://lf-unpkg.volccdn.com/obj/vcloudfe/sdk/@byted/veveditor/1.0.4/veveditor.css">
</head>

在 <body> 标签内添加一个用于挂载剪辑器的容器 <div>，并在 </body> 标签前引入 JS 文件：

<body>
  <div id="editor-container" style="height: 100vh; width: 100vw;"></div>
  <script src="https://lf-unpkg.volccdn.com/obj/vcloudfe/sdk/@byted/veveditor/1.0.4/veveditor.umd.js"></script>
  <script>
    // SDK 初始化代码将写在这里
  </script>
</body>

步骤 2：初始化 SDK 实例

在 <script> 标签中，通过 new window.VeVEditor(param) 来实例化剪辑器。您需要传入在前提条件中获取的 projectId 和 groupId。param 对象是初始化的核心，包含挂载点、基础配置、API 代理和事件回调等所有必需信息。详情请见参数说明。

注意

仅支持单实例。在重新实例化之前，需调用 veveditor.destroy() 销毁旧实例。

// 从服务端获取或在 URL 参数中获取
const projectId = 'your-project-id'; 
const groupId = 'your-group-id';   

// 构造初始化参数对象
const param = {
  container: document.getElementById('editor-container'),
  config: {
    projectId: projectId,
    groupId: groupId,
    region: 'cn-north-1',
    material: {
      showClassification: true, // 开启素材分类功能
      defaultClassificationId: '1762937331', // (可选) 指定默认分类 ID
    },
    // ... 其他基础配置
  },
  actions: {
    // 关键：在此实现所有与您后端服务通信的 API 调用
    describeProject: async (params) => { /* ... */ },
    updateProject: async (params) => { /* ... */ },
    listVideoClassifications: async (params) => { /* ... 实现对 ListVideoClassifications 的调用 ... */ },
    // ... 其他必须实现的 actions
  },
  handlers: {
    // 关键：在此实现事件回调处理
    onNavBack: () => { /* ... */ },
    onProjectSubmit: () => { /* ... */ },
    // ...
  }
};

const veveditor = new window.VeVEditor(param);

参数说明

VeVEditor 的初始化对象由多个模块组成，用于控制剪辑器的行为、外观和数据通信。

Param（顶层参数）

参数	类型	必填	描述
`container`	`HTMLElement`	是	用于挂载剪辑器 UI 的 DOM 容器节点。SDK 将在此节点内部渲染整个剪辑器界面。
`config`	`object`	是	基础配置，包含 `projectId`、`groupId` 以及控制剪辑器各功能模块 UI 和行为的参数。详见 Config（基础配置）。
`actions`	`object`	是	API 代理配置。SDK 内部所有对视频点播服务端 API 的请求，都会通过您在此处定义的函数发起。您需要在此实现对您后端服务的请求封装。详见 Actions（API 代理）。
`handlers`	`object`	是	事件回调配置。用于处理剪辑器内部触发的用户行为或状态变化，如点击返回按钮、提交导出任务等。详见 Handlers（事件回调）。

Config（基础配置）

配置剪辑器的基础信息和各功能模块。

参数	类型	必填	描述
`projectId`	`string`	是	剪辑工程 ID。通过服务端调用 `CreateProject` 接口获取，详见前提条件。
`groupId`	`string`	是	剪辑工程所属的组 ID。通过服务端调用 `CreateProject` 接口获取，详见前提条件。
`region`	`string`	是	服务地域。当前仅支持 `cn-north-1`。
`defaultClassificationId`	`string`	否	分类ID。不填或填 `null` 表示默认「未分类」。
`autoPublish`	`boolean`	否	本地上传媒资后，是否自动调用 UpdateMediaPublishStatus 接口将媒资状态设置为“已发布”。默认为 `true`。
`header`	`object`	否	配置剪辑器顶部导航栏 UI 的显示/隐藏。详见 Header（顶部导航栏配置）。
`material`	`object`	否	配置素材库页面的功能和行为。详见 Material（素材库页面）。
`text`	`object`	否	配置文字页面。详见 Text（文字页面）。
`effect`	`object`	否	配置特效页面。详见 Effect（特效页面）。
`transition`	`object`	否	配置转场页面。详见 Transition（转场页面）。
`filter`	`object`	否	配置滤镜页面。详见 Filter（滤镜页面）。

Actions（API 代理）

actions 对象中的每一个函数，都对应一个 SDK 需要调用的视频点播服务端 API。您必须实现所有标记为“是”的函数，在函数内部完成对您自己后端服务的网络请求，并返回服务端 API 响应中的 Result 部分。

函数名	对应服务端 API	必填	描述
`describeProject`	DescribeProject	是	SDK 初始化时调用，用于获取剪辑工程的初始数据结构。
`updateProject`	UpdateProject	是	在编辑过程中（如拖拽、删减素材）自动或手动调用，用于保存工程草稿。
`submitEditTaskAsync`	SubmitEditTaskAsync	是	用户点击“导出”按钮时调用，用于提交视频剪辑任务。
`searchVideo`	SearchVideo	是	用户在“从系统导入 > 视频库”中浏览或搜索视频时调用，用于拉取点播空间中的视频列表。
`mGetMaterial`	MGetMaterial	是	用户在“从系统导入 > 素材库”中浏览或选择素材时调用，用于拉取点播空间中的素材列表。
`searchEditMaterial`	SearchEditMaterial	是	SDK 初始化或切换工程时调用，用于获取当前工程已引用的所有素材列表。
`deleteEditMaterial`	DeleteEditMaterial	是	用户从工程中移除素材时调用。
`createEditMaterial`	CreateEditMaterial	是	用户向工程中添加素材时调用。默认不会刷新素材库，可以通过调用`refreshMaterialList`实现更新。
`getEffectList`	GetEffectList	是	加载特效、转场、滤镜、贴纸、花字等资源列表时调用。
`updateMediaPublishStatus`	UpdateMediaPublishStatus	是	当 `autoPublish` 为 `true` 时，在本地上传成功后自动调用，用于发布媒资。
`getVideoInfo`	`(media:{Vid:string;Space:string})=> Promise<MediaInfo>`	是	预览轨道上的视频素材时调用，用于获取播放地址、视频时长等信息。SDK 会传入包含 `Vid` 和 `Space` 的对象，您的函数需要返回符合 MediaInfo 结构的对象。
`listVideoClassifications`	ListVideoClassifications	否	当 `config.material.showClassification` 为 `true` 时，此函数为必填。用于获取媒资分类列表以在素材库中展示。

MediaInfo

actions.getVideoInfo 函数必须返回一个包含以下字段的 MediaInfo 对象。您需要从服务端 GetVideoPlayInfo 接口的响应中提取并组装这些数据。

参数	类型	必填	描述	来源
`PlayUrl`	`string`	是	音视频资源的播放地址	从 GetVideoPlayInfo 响应中的 `VideoDetail.VideoDetailInfo.PlayInfo.MainPlayUrl` 字段获取。
`PosterUrl`	`string`	是	音视频资源的封面图地址	从 GetVideoPlayInfo 响应中的`VideoDetail.VideoDetailInfo.PosterUrl`字段获取。
`Duration`	`number`	是	音视频资源的时长	从 GetVideoPlayInfo 响应中的`VideoDetail.VideoDetailInfo.Duration`字段获取。
`Width`	`number`	是	视频宽度	从 GetVideoPlayInfo 响应中的 `VideoDetail.VideoDetailInfo.Width` 字段获取。
`Height`	`number`	是	视频高度	从 GetVideoPlayInfo 响应中的 `VideoDetail.VideoDetailInfo.Height` 字段获取。

Handlers（事件回调）

handlers 对象用于监听并响应剪辑器内部的特定事件。

函数名	类型	必填	描述
`onUploadMaterial`	`(params: { type: 'video' \| 'material'; Space: string }) => void`	否	当 `config.material.enableLocalUpload` 为 `true` 时，此函数为必填。用户点击素材库页面中的“确定上传”按钮时触发。您可以在此回调中唤起您自定义的上传组件或页面。
`onProjectSubmit`	`(Space: string) => void`	是	用户点击剪辑器右上角的“导出”按钮、成功执行 `submitEditTaskAsync` 动作后触发。您可以在此提示用户“剪辑中，请稍候”或执行页面跳转。
`uploadMaterial`	`function`	否	当 `config.material.enableLocalUpload` 为 `true` 时，此函数必须实现，负责处理本地文件的上传逻辑。您需要在此函数中集成 Web 上传 SDK 完成上传，并返回上传成功后的媒资信息。
`onNavBack`	`(Space: string) => void`	否	用户点击剪辑器左上角的“返回”按钮时触发。您可以在此实现页面返回、弹窗确认等自定义逻辑。
`onNodePreviewError`	`(type: 'video' \| 'audio') => void`	否	当轨道上的视频或音频素材因 URL 失效等原因预览失败时触发。您可以在此进行错误上报或给出自定义提示。

用于控制剪辑器顶部导航栏各元素的可见性。

参数	类型	必填	默认值	描述
`show`	`boolean`	否	`true`	是否整体显示顶部导航栏。
`isNavBackVisible`	`boolean`	否	`true`	是否显示左上角的“返回”按钮。
`isProjectSubmitVisible`	`boolean`	否	`true`	是否显示右上角的“导出”按钮。
`isProjectNameEditable`	`boolean`	否	`true`	是否允许用户点击并编辑工程名称。

Material（素材库页面）

用于配置素材库页面的行为。

参数	类型	必填	默认值	描述
`show`	`boolean`	否	`true`	是否整体显示素材库页面。
`showClassification`	`boolean`	否	`false`	是否在素材库页面启用分类筛选功能。若设置为 `true`，您必须实现 `actions.listVideoClassifications` 函数。
`defaultClassificationId`	`string`	否	`''`	当 `showClassification` 为 `true` 时生效。用于指定进入素材库时默认选中的分类 ID。
`enableLocalUpload`	`boolean`	否	`true`	是否在素材库页面中启用“从本地上传”功能。若为 `true`，则您必须实现 `handlers.uploadMaterial` 函数。
`uploadAccept`	`string`	否	`'image/*,.mp3,.mp4,.webm,.mov'`	用于限制从本地上传的文件类型。图片支持 png、jpeg 音频支持 mp3 视频支持 mp4、webm、mov
`videoAccept`	`string`	否	`'.mp4,.webm,.mov'`	用于限制从系统导入的视频文件类型。支持 mp4、webm、mov。
`emptyIcon`	`string`	否	`''`	素材库为空状态时显示的自定义图标的 URL。

Text（文字页面）

用于配置文字页面的行为。

参数	类型	必填	默认值	描述
`show`	`boolean`	否	`true`	是否整体显示文字页面入口。
`enableAnimation`	`boolean`	否	`false`	是否启用文字动画功能。

Effect（特效页面）

参数	类型	必填	默认值	描述
`show`	`boolean`	否	`true`	是否整体显示特效页面。

Transition（转场页面）

参数	类型	必填	默认值	描述
`show`	`boolean`	否	`true`	是否整体显示转场页面。

Filter（滤镜页面）

参数	类型	必填	默认值	描述
`show`	`boolean`	否	`true`	是否整体显示滤镜页面。

完整示例代码

var projectId = 'your-project-id'; // 剪辑工程ID
var groupId = 'your-group-id';   // 分组 ID

var veveditor = new window.VeVEditor({
  container: document.getElementById('editor-container'),
  config: {
    projectId: projectId,
    groupId: groupId,
    region: 'cn-north-1',
    autoPublish: true,
    material: {
      show: true,
      enableLocalUpload: true,
      showClassification: true, // 开启素材分类功能
      defaultClassificationId: '1762937331', // (可选) 指定默认分类
      uploadAccept: 'image/*,.mp3,.mp4,.webm',
      videoAccept: '.mp4,.webm',
    },
    // ... 其他 UI 配置
  },
  actions: {
    listVideoClassifications: async (params) => {
      // 获取分类列表
      var res = await request('api/ListVideoClassifications', params);
      return res.Result;
    },
    searchVideo: async (params) => {
      // 搜索音视频素材。注意：当用户在 UI 上选择分类后，分类 ID 会通过 params.ClassificationIds 传入
      var res = await request('api/SearchVideo', params);
      return res.Result;
    },
    // ... 其他 actions 实现
  },
  handlers: {
    uploadMaterial: async (file, options) => {
      // 此处为本地上传逻辑，需集成 Web 上传 SDK
      // 如果 UI 上选择了分类，分类 ID 会在 options.classificationId 中
      const classificationId = options.classificationId;
      
      // 在上传 SDK 的 processAction 中，将 classificationId 作为 AddOptionInfo 的参数传入
      // 参考示例：
      // {
      //   name: 'AddOptionInfo',
      //   input: {
      //     ...,
      //     ...(classificationId ? { ClassificationId: Number(classificationId) } : {}),
      //   },
      // },
    },
    // ... 其他 handlers 实现
  }
});

常见问题

轨道上的素材预览报错或显示黑屏？

预览失败通常与素材的播放地址或网络环境有关。可按以下步骤排查：

检查视频播放地址可用性：
- 播放域名配置：在视频点播控制台域名管理页面检查播放域名的配置情况。确保域名配置准确无误，DNS 解析正常，并且该域名已被启用。
- 域名 SSL 配置：在视频点播控制台域名管理页面确认域名已配置有效的 SSL证书。
- 域名回源存储配置：核实域名回源存储配置，保证素材在火山引擎存储的地址与域名回源存储的设置一致。
- 主分发协议设置：在视频点播控制台分发设置页面确认主分发协议设置为 https。
- 域名CORS配置：在视频点播控制台域名管理页面确认已正确配置 Header，允许跨域访问，使不同来源的请求能顺利获取视频资源。
检查视频文件完整性：检查视频文件是否因上传失误、存储故障等原因导致损坏。
确认网络连接稳定性：检查网络稳定性，避免因网络波动影响视频预览。
尝试调整视频参数：若上述检查均无问题，可尝试降低视频分辨率或码率。

如何管理素材分类？如何在上传或搜索时使用分类？

您可以通过服务端 API 和视频点播控制台进行分类管理。

创建和管理分类：详见媒资分类。
注意
当前仅支持对音视频素材进行分类管理，暂不支持对图片素材进行分类。
在剪辑器中使用分类：
- 展示分类列表：当您在初始化 SDK 时设置 config.material.showClassification: true，剪辑器会自动调用您实现的 actions.listVideoClassifications 函数来获取并展示分类列表。
- 按分类搜索素材：当用户在剪辑器 UI 中搜索某个分类时，该分类的 ID 会自动通过 params.ClassificationIds 参数，在 actions.searchVideo 函数中传递给您的后端。您的后端在调用 SearchVideo 接口时，需携带 ClassificationIds 参数指定分类 ID。
- 上传到指定分类：当用户在启用了分类的上传界面从本地上传素材时，所选分类的 ID 会通过 options.classificationId 在 handlers.uploadMaterial 函数中提供。您需要在集成 Web 上传 SDK 时，将此 classificationId 作为 AddOptionInfo 的一个参数传入，即可将新上传的素材自动归入指定分类。
```
// 在 Web 上传 SDK 的初始化配置中
const uploader = new VodUpload({
  // ... 其他上传配置
  videoConfig: {
    spaceName: 'your-space-name',
    processAction: [
      {
        name: 'AddOptionInfo',
        input: {
          Title: file.name,
          // ... 其他元信息
          // 核心逻辑：如果文件对象中包含 ClassificationId, 则将其添加到 input 中
          ...(file.ClassificationId ? { ClassificationId: Number(file.ClassificationId) } : {}),
        },
      },
    ],
  },
  // ...
});
```

参考信息

SDK 发布历史

日期	版本号	说明
2026-03-27	1.0.6	修复同种花字多轨道下渲染的 bug。
2026-03-23	1.0.5	新增导出视频分类功能。
2026-02-10	1.0.4	修复删除素材失败的 bug。新增 refreshMaterialList 接口实现服务端重新拉取素材列表。新增 AccountID 和 source 字段上报。
2025-12-25	1.0.3	新增媒资分类管理功能：素材库（系统导入和本地上传）现已支持按分类展示和筛选音视频素材。支持从本地上传素材时，将其直接归入指定分类。素材库中所有音视频的时长展示精度提升至毫秒级。
2025-10-24	1.0.1	首次发布。

最近更新时间：2026.03.27 18:07:04

这个页面对您有帮助吗？

有用

无用

视频点播

整体架构和工作流 #

支持的剪辑素材格式 #

前提条件 #

集成步骤 #

步骤 1：引入 SDK 资源 #

步骤 2：初始化 SDK 实例 #

参数说明 #

Param（顶层参数） #

Config（基础配置） #

Actions（API 代理） #

MediaInfo

Handlers（事件回调） #

Header（顶部导航栏配置） #

Material（素材库页面） #

Text（文字页面） #

Effect（特效页面） #

Transition（转场页面） #

Filter（滤镜页面） #

完整示例代码 #

常见问题 #

轨道上的素材预览报错或显示黑屏？ #

如何管理素材分类？如何在上传或搜索时使用分类？ #

参考信息 #

SDK 发布历史 #