@volcengine/amk-editor

@volcengine/amk-editor

火山引擎 AI MediaKit 官方 Web 视频编辑器 SDK。

安装

npm install @volcengine/amk-editor

需要 React 18 或 19。使用本 SDK 须获得有效的火山引擎商业授权，条款见 LICENSE。 本 SDK 使用的第三方开源组件仍分别适用其各自的许可证。

快速开始

import { AmkEditor } from '@volcengine/amk-editor';
const editor = new AmkEditor({
  container,
  projectId: 'your-project-id',
  endpoint: 'https://your-backend.example.com',
  // 可选：每次请求前动态获取，SDK 不解析或改写返回的 Header。
  getHeaders: async () => ({
    Authorization: `Bearer ${await getLatestToken()}`,
    'X-Customer-Id': 'your-customer-id',
  }),
  material: {
    onUploadMaterial: async files => {
      // 上传到业务存储后返回素材列表，每项必须带 source_material_id
      return [];
    },
    onUploadUrlMaterial: async urls => {
      return [];
    },
    onRefreshPlayInfo: async materials =>
      materials.map(item => ({
        material_id: item.material_id, // 仅用于匹配，不要改写
        url: '...',
        poster: item.poster,
        sprite: item.sprite,
      })),
  },
});


// 外部工具栏可复用素材面板的同一套导入弹窗与入库链路。
editor.requestMaterialImport('local'); // 本地文件选择 + 本地上传确认弹窗
editor.requestMaterialImport('url'); // URL 上传弹窗
editor.requestMaterialImport('system'); // 业务资产库回调

// 只有这个外部调用触发的导入成功后才回调；编辑器自身的导入按钮不会触发它。
editor.requestMaterialImport('local', {
  onMaterialsImported: materials => {
    console.log('本次已入库素材', materials);
  },
});

// 从服务端重新拉取当前工程，并热更新素材与 Track（不写入撤销历史）。
await editor.refreshProject();

// 从外部保存工程标题；保存成功后同步顶栏，并触发 header.onTitleUpdateSuccess。
await editor.updateTitle('新的工程标题');

// 查询由编辑器操作创建的异步任务；复用相同的 endpoint 和 getHeaders。
const exportTask = await editor.getTask('your-task-id');

页面卸载时销毁：

editor.destroy();

接入说明

• projectId、endpoint 必填。endpoint 指向你的业务代理。
• theme 默认 light。未传或传入其他值时按浅色渲染；只有显式 theme: 'dark' 才走暗色。
• 产物是面向浏览器的单文件 ESM。依赖里的 AMD define(["./core"]) 和 Node require('crypto') 兜底已在构建时剔除，避免 Next.js / webpack / Rspack 误解析依赖或报告动态 require 警告；浏览器加密仍使用 Web Crypto。
• getHeaders 可选，每次请求前都会重新调用；SDK 不解析、不缓存、不改写返回值，仅将其合并到发往 endpoint 的工程、素材、tools、tasks、导出等请求中。闭包内 Token 更新会自动用于下一次请求。
• 本地上传、URL 导入由业务回调完成。返回的素材必须带业务主键 source_material_id，不必填写 material_id。
• 播放地址、封面、雪碧图可能有时效。通过 onRefreshPlayInfo 返回新的访问地址；补丁按 material_id、source_material_id、无标识时数组顺序依次匹配，未返回的字段保持原值。
• 可选实现 onMaterialsImported：素材成功入库后回调已合并 material_id 的列表；可用于把新素材挂到对话草稿。失败或取消不会触发。
• 可选实现 onPersistExtractUrls：把抽帧得到的临时地址转存为业务长期地址，并随 materialPatch 写回自定义存储字段。
• 可选配置 export.qualityEnhancement: true 以在导出弹窗展示「视频画质增强」；默认不展示。
• 可选配置 header.mount 为外部 DOM 节点，将顶栏渲染到该节点（而不是编辑器内部），便于宿主做全宽顶栏；header.show: false 仍可完全隐藏顶栏。
• 可选配置 header.onTitleUpdateSuccess：工程名 PATCH 成功后回调 { projectId, title }。保存成功前编辑器继续展示旧名称；保存失败不会修改编辑器标题，也不会触发回调。
• 可选配置 header.exportTaskList: false 隐藏导出任务列表入口；默认开启。关闭后不会展示任务列表按钮，也不会启动导出任务列表查询与轮询。
• requestMaterialImport(type, options?) 返回是否成功触发已配置入口；local、url、system 分别要求存在本地上传能力、onUploadUrlMaterial、onUploadFromSystem。外部入口不会复制上传逻辑，仍走素材面板相同的回调、TOS 签名、素材入库与元信息处理。可选的 options.onMaterialsImported 只对这一次外部触发有效，编辑器自身的导入按钮不会调用它。
• updateTitle(title) 复用顶栏标题保存链路：先 PATCH 工程名，成功后更新编辑器标题/工程快照并触发 header.onTitleUpdateSuccess；校验失败或保存失败会 reject，且不会触发成功回调。
• toolbar.customItems 的只读态不会自动置灰。需要禁用时在该项 disabled({ readonly }) 里自行返回 true（例如 disabled: ({ readonly }) => readonly）。录音中仍会全局锁定自定义项。内置 ASR 按钮在只读时仍会禁用。
• refreshProject() 会等待当前保存队列结束，再重新拉取工程、刷新临时播放地址并热更新素材与 Track；远端 Track 不会写入本地撤销历史，也不会被自动保存回服务端。
• getTask(taskId, options?) 查询 GET /api/v1/tasks/{task_id}，复用编辑器初始化时的 endpoint 与 getHeaders；options.signal 可在宿主任务卡卸载时取消轮询请求。
• 配置 projectId 后，API Client 会把 invokeTool、invokeSyncTool 的成功响应以及 getTask 的轮询结果，以 schema v2 best-effort 上报到 POST /api/v1/editing/projects/{project_id}/tasks。记录包含 task_id、tool_name、同步/异步模式、状态、原始请求和响应；台账写入失败只输出 warning，不会让已经成功的 AMK 调用失败。轮询上报会省略 request.input，避免覆盖首次提交保存的请求参数。
• mediakit-studio dev 当前只提供上述任务台账写接口，尚无任务列表/详情 GET 接口。因此编辑器顶栏的导出记录仍只保留当前页面会话；如需刷新后读取历史导出列表，需要服务端补充按工程查询任务的接口。

样式隔离

SDK 会随 import '@volcengine/amk-editor' 自动注入样式，导航栏、左侧分类、素材网格的布局由 SDK 自己负责。接入方不必再写补丁 CSS 才能让界面正常显示。 编辑器挂在普通 DOM（#track-video-editor）里，不是 Shadow DOM。宿主页面里针对 section / nav / aside 的全局布局重置会穿透进来，把顶栏或左侧分类挤扁。 请避免：

• 对 section、nav、aside 写全局 display / flex / height / margin 规则。
• 用 #track-video-editor nav { ... } 这类按标签名锁定内部节点。同名标签在编辑器里用途不同，一条规则会同时打到顶栏和分类栏。 如需约束编辑器尺寸，只设置挂载容器或 #track-video-editor 本身的 width / height / min-height。