@volcengine/amk-editor 0.0.6 → 0.0.7

package/README.md

@@ -1,5 +1,55 @@
 # @volcengine/amk-editor
 火山引擎 AI MediaKit 官方 Web 视频编辑器 SDK。
+
+BytePlus 包的接入说明见 [README.byteplus.md](./README.byteplus.md)。
+
+## 字幕识别后端
+
+现有工具栏的字幕识别入口支持通过初始化配置切换后端：
+
+```ts
+const editor = new AmkEditor({
+  container, projectId, endpoint,
+  toolbar: {
+    asr: { provider: 'maas' }, // 可选；火山默认 'asr-subtitles'
+  },
+});
+```
+
+- `asr-subtitles`：火山默认，沿用原来的字幕识别工具及参数。
+- `maas`：视频先调用 `extract-audio`（`format: 'mp3'`），再调用 `call-maas-proxy`（`api: 'doubao.asr'`）。HTTP(S) MP3/WAV/OGG 音频直接识别；其他或无法从 URL 确认格式的音频先调用 `transcode-audio` 转为 MP3。
+- 新链路不传 `media_output_destination`，中间音频使用临时 HTTP(S) 地址供模型读取，不写入工程素材库；所有请求仍经过配置的 `endpoint` / `getHeaders`。
+- 返回 `utterances` 的毫秒时间戳会转换为原字幕逻辑使用的秒，并继续按素材裁剪范围、变速和时间线位置映射。`toolbar.builtInVisibility.asrSubtitle` 仍控制原入口显隐。
+- 取消/关闭识别弹窗或销毁编辑器会停止本地等待、阻止后续阶段及字幕写入；已提交的远端任务不会因此撤销，仍可能产生费用。
+
+业务代理需允许 `extract-audio`、`transcode-audio`、`call-maas-proxy` 和任务查询。使用 MaaS 前需开通对应语音识别能力并完成 AMK 跨服务授权；源 URL 必须在任务执行期间可被服务端访问。BytePlus 默认使用 `maas`，不支持选择 `asr-subtitles`，海外接口和账号能力需单独联调。
+
+接口参考：[MaaS 模型代理](https://docs.volcengine.com/docs/Intelligentprocessing/call-maas-proxy-api?lang=zh)、[音频提取](https://docs.volcengine.com/docs/Intelligentprocessing/SubmitAudioExtractionTaskAPI?lang=zh)。
+
+## 素材 Source 与播放地址
+
+素材入库时，AMK 返回的 `tos://bucket/key`、`vod://space/id` 保留在 `source` 中；稳定的 `source_material_id` 也可用于补齐该资源身份。`url` 始终使用可播放的 HTTP(S) 地址，播放地址刷新不会覆盖资源 `source`。普通 HTTP(S) 素材沿用原来的 URL 处理逻辑。
+
+拖入时间线后，元素 `Source` 直接沿用素材 `source`，保存工程保留该值。导出使用工程中已保存的 `Source`，不再通过 `source_material_id` 或存储空间配置转换 TOS/VOD 协议；已有 HTTP(S) 轨道仍按原逻辑刷新播放地址，不自动迁移旧工程。
+
+## 素材上传并发
+
+通过 `material.uploadConcurrency` 设置同一编辑器的本地文件与临时 URL 转存并发上限：
+
+```ts
+material: {
+  uploadConcurrency: 3,
+  // 可选；未提供自定义回调时，按现有规则使用内置上传。
+  onUploadFile: async file => uploadToYourService(file),
+}
+```
+
+选择 10 个文件时先启动 3 个，每项上传、元信息补齐和入库完成或失败后再启动下一项；后台抽帧不占名额。连续选择多批文件也共用上限，已成功项立即显示，单项失败不阻塞后续文件。仅接受正整数（1 为串行），未配置保持原不限并发行为。销毁编辑器后排队任务不再启动，已开始的自定义请求不会被强制取消。
+
+该配置作用于 `onUploadFile`、SDK 内置本地上传，以及服务端标记为临时存储的 URL 素材转存；临时转存会按单 URL 调用 `onUploadUrlMaterial([url])`，未配置并发数时默认最多同时处理 5 条。普通 URL 导入仍按整批调用 `onUploadUrlMaterial(urls)`；临时素材转存也只传 URL 数组，原素材的 `type`、`name` 等元信息由 SDK 从素材库保留，业务回调不必再返回 `type`；旧版 `onUploadMaterial(files)` 与系统素材导入的内部并发仍由宿主控制。本配置不是每秒 QPS 限速，也不改变单个文件内部的分片并发。
+
+配置并发上限后，本地上传与临时转存共用同一队列。临时素材跳过客户侧播放信息刷新，但可立即使用临时 HTTP(S) 地址抽帧并展示结果。每条转存成功后立即进入与封面/雪碧图素材更新相同的 100 ms 合并窗口，窗口内多个成功项合并 PUT，不等待整轮上传结束；写回与其它素材更新串行。抽帧任务状态和结果先缓存在内存，替换 PUT 成功后再按当前客户存储身份批量写回；转存失败时保留缓存等待后续重试。SDK 只扫描初始化已加载的素材和 `refreshMaterials()` 的结果，不会为等待临时素材重复请求素材列表。后续陈旧读取保留已提交绑定和抽帧结果，避免重复上传或抽帧。转存后的素材刷新不重建当前时间线预览节点。
+
 ## 获取当前合成画面
 ```ts
 await amkEditor.whenReady();
@@ -20,6 +70,7 @@ const editor = new AmkEditor({
   container,
   projectId: 'your-project-id',
   endpoint: 'https://your-backend.example.com',
+  source: 'your-app-name',
   // 可选：每次请求前动态获取，SDK 不解析或改写返回的 Header。
   getHeaders: async () => ({
     Authorization: `Bearer ${await getLatestToken()}`,
@@ -60,6 +111,13 @@ editor.requestMaterialImport('local', {
 // 从服务端重新拉取当前工程，并热更新素材与 Track（不写入撤销历史）。
 await editor.refreshProject();
 
+// 只重新拉取全部素材（自动分页），刷新播放地址并更新素材面板；不刷新轨道或工程名。
+const materials = await editor.refreshMaterials();
+
+// 只读取工程接口并更新工程信息；当前同步名称/Header，并保留其他元信息。
+const projectInfo = await editor.refreshProjectInfo();
+console.log(projectInfo.name, projectInfo.description);
+
 // 从外部保存工程标题；保存成功后同步顶栏，并触发 header.onTitleUpdateSuccess。
 await editor.updateTitle('新的工程标题');
 
@@ -70,13 +128,63 @@ const exportTask = await editor.getTask('your-task-id');
 ```ts
 editor.destroy();
 ```
+
+### 内置 VOD 本地上传
+
+SDK 可通过 `tt-uploader` 将本地视频、音频和图片直传火山引擎点播。长期
+AK/SK 保留在宿主服务端，浏览器通过统一回调获取短期 Token；SDK 自动按
+Vid 获取播放地址：
+
+```ts
+const editor = new AmkEditor({
+  container,
+  projectId: 'your-project-id',
+  endpoint: 'https://your-backend.example.com',
+  source: 'your-app-name',
+  storage: {
+    media_output_destination: 'vod://your-space',
+    getUploadSTS: () => fetch('/api/vod/upload-token', {
+      method: 'POST',
+    }).then(response => response.json()),
+  },
+});
+```
+
+服务端需返回带 `Vod:ApplyUploadInfo`、`Vod:CommitUploadInfo`、
+`Vod:UpdateMediaPublishStatus` 和 `Vod:GetPlayInfo` 权限的短期 STS，不应下发长期 AK/SK。
+签发接口须由业务服务端鉴权、限流；发布权限不应向未授权访客开放。
+SDK 使用该 STS 直传点播，仅在上传成功后发布 Vid，然后获取播放地址；
+普通播放地址刷新不再发布媒资，一批 VOD 素材刷新共用一次 STS，并按 Vid 去重查询。
+内置 VOD 取链通过 `GetPlayInfo.ForceExpire` 请求不超过 STS 剩余有效期和 24 小时的播放地址；
+当返回 URL 带有可识别的 `auth_key` 到期时间时，SDK 会提前 5 分钟刷新素材、封面和雪碧图的播放地址。
+刷新时若 STS 距过期不足 5 分钟，SDK 会重新调用 `getUploadSTS`。实际可播放时长仍取决于点播域名的鉴权配置。
+不再需要服务端播放地址代理。视频、音频和图片都通过点播 media
+通道取得 Vid；仅返回 Mid 的上传结果会报错，
+不会写入 AMK 工程。SDK 将 `vod://<spaceName>/<Vid>` 保存为稳定的
+`source_material_id`，并在素材接口的 `source`、`url`、可识别的 poster/sprite 字段中
+写入稳定 VOD 身份；HTTP(S) 播放地址仅在编辑器运行时使用，初始化和预览失败时自动重新获取。
+导出结果若返回 `vod://<spaceName>/<Vid>`，任务列表同样通过点播 OpenAPI 换取
+HTTP(S) 地址，再显示「预览」和「下载」；TOS 导出结果仍按原有 STS 签名逻辑处理。
+提交多轨剪辑任务时仅在请求副本中转换媒体轨道 `Source`：点播素材使用
+`vod://<spaceName>/<Vid>`，TOS 素材使用 `tos://<bucket>/<key>`。
+优先使用素材中已有的完整 `source_material_id`；旧工程轨道中的
+`vid://<Vid>` 若没有完整素材身份，使用
+`storage.media_output_destination` 配置的 VOD 空间补成 `vod://` 地址；缺少空间时在提交前报错。
+普通 URL 素材仍使用刷新后的 HTTP(S) 地址；工程持久化及页面预览中的
+`Source` 不随此转换改写。
+
 ## 接入说明
-- `projectId`、`endpoint` 必填。`endpoint` 指向你的业务代理。
+- `container`、`projectId`、`endpoint` 必填。`container` 是编辑器挂载元素；`projectId` 用于加载和保存工程；`endpoint` 是工程、素材和任务请求的业务代理地址，支持 HTTP(S) 地址或以 `/` 开头的路径。`source` 是可选的接入方标识，用于区分埋点来源和问题归因；未配置时 SDK 会提示 warning，并使用默认值 `sdk`。
+- 构造时会在挂载页面和发起请求前汇总校验错误，错误文案会说明字段用途和修复方式。`storage.media_output_destination` 仅支持 `vod://<space>` 或 `tos://<bucket>[/prefix]`，并且必须和函数 `storage.getUploadSTS` 同时配置；只配置其中任意一个都会初始化失败。两者均不配置时不启用内置存储上传，可继续使用自定义上传回调；自定义上传也未配置时不展示本地上传入口。凭证内容及远端桶权限仍需在实际请求时验证，错误信息不会回显配置值。
 - `theme` 默认 `light`。未传或传入其他值时按浅色渲染；只有显式 `theme: 'dark'` 才走暗色。
 - 产物是面向浏览器的单文件 ESM。依赖里的 AMD `define(["./core"])`、`define(["dayjs"])` 和 Node `require('crypto')` 兜底已在构建时剔除或中和，避免 Next.js / webpack / Rspack 误解析依赖或报告动态 require 警告；浏览器加密仍使用 Web Crypto。
 - `getHeaders` 可选，每次请求前都会重新调用；SDK 不解析、不缓存、不改写返回值，仅将其合并到发往 `endpoint` 的工程、素材、tools、tasks、导出等请求中。闭包内 Token 更新会自动用于下一次请求。
 - SDK 发往 `endpoint` 的全部 AMK 服务请求都会固定携带 `X-Amk-Task-Source: vibe-editing`，用于任务来源和用量归因；该字段不会被 `getHeaders` 或单次请求 Header 覆盖。跨域代理需在 CORS 配置中允许此请求头。成片 CDN 下载、TOS 直传等非 AMK 服务请求不携带该字段。
-- 本地上传通过 `onUploadFile(file)` 实现单文件上传；SDK 负责多文件并发、逐项入库和部分失败收口。旧 `onUploadMaterial(files)` 仍兼容，但只能整批完成后入库。URL 导入仍由 `onUploadUrlMaterial` 完成。返回素材必须带业务主键 `source_material_id`，不必填写 `material_id`。
+- AMK 服务请求不再由 SDK 自动注入版本请求头，避免因此触发额外的跨域预检限制。预设资源请求保留已有的 `sdk_version` 查询参数。
+- 本地上传优先使用业务自定义回调：`onUploadFile(file)` > 旧版 `onUploadMaterial(files)` > SDK 内置 VOD / TOS 上传。也就是说，同时配置 `storage` 和自定义上传时一定走自定义链路；只有两个自定义回调均未配置时，SDK 才按 `media_output_destination` 协议使用内置上传。`onUploadFile` 模式下 SDK 负责多文件并发、逐项入库和部分失败收口；旧 `onUploadMaterial` 只能整批完成后入库。URL 导入仍由 `onUploadUrlMaterial` 完成。返回素材必须带业务主键 `source_material_id`，不必填写 `material_id`。
+- 配置 `vod://<space>` 与 `storage.getUploadSTS` 可启用内置点播直传；配置 `tos://<bucket>[/prefix]` 与 `storage.getUploadSTS` 可启用内置 TOS 直传。两种 storage 目标都不会覆盖业务自定义上传回调。
+- `storage.media_output_destination` 的服务端转存行为按发行版区分：火山版会将该字段传给支持产物转存的 AMK tools；BytePlus AMK 当前不支持 TOS/VOD 产物转存，因此 BytePlus 构建不会向 AMK 接口发送该字段（包括调用参数中显式传入的同名字段），避免请求失败。此限制不影响浏览器本地上传：`vod://` 目标在火山包中使用 `tt-uploader`，在 BytePlus 包中使用 `@byteplus/uploader`；BytePlus TOS 内置上传仍待后续接入。自定义上传回调始终优先于内置上传。
+- 配置 `tos://` 格式的 `storage.media_output_destination` 时必须同时配置 `storage.getUploadSTS`。只有两者都存在时，SDK 才接管 `source_material_id` 为 `tos://bucket/key` 的资产库素材并生成临时播放地址；该字段不是有效 TOS 地址时兜底读取 `source`，不改写业务 `source_material_id`。VOD 刷新同样优先解析 `source_material_id`，无有效 VOD 地址时读取 `source`，且仍校验空间匹配。同批非 TOS 素材继续使用业务 URL。两者都未配置时，`tos://` 只作为业务稳定 ID：已有 HTTP(S) 长期 URL 会原样使用且不触发刷新；缺少播放地址时调用 `onRefreshPlayInfo` 补齐，刷新后仍无地址则拒绝入库。
 - 播放地址、封面、雪碧图可能有时效。通过 `onRefreshPlayInfo` 返回新的访问地址；补丁按 `material_id`、`source_material_id`、无标识时数组顺序依次匹配，未返回的字段保持原值。
 - 可选实现 `onMaterialsImported`：素材成功入库后回调已合并 `material_id` 的列表；可用于把新素材挂到对话草稿。失败或取消不会触发。
 - 可选实现 `onPersistExtractUrls`：把抽帧得到的临时地址转存为业务长期地址，并随 `materialPatch` 写回自定义存储字段。
@@ -88,6 +196,10 @@ editor.destroy();
 - `updateTitle(title)` 复用顶栏标题保存链路：先 PATCH 工程名，成功后更新编辑器标题/工程快照并触发 `header.onTitleUpdateSuccess`；校验失败或保存失败会 reject，且不会触发成功回调。
 - `toolbar.customItems` 的只读态不会自动置灰。需要禁用时在该项 `disabled({ readonly })` 里自行返回 true（例如 `disabled: ({ readonly }) => readonly`）。录音中仍会全局锁定自定义项。内置 ASR 按钮在只读时仍会禁用。
 - `refreshProject()` 会等待当前保存队列结束，再重新拉取工程、刷新临时播放地址并热更新素材与 Track；远端 Track 不会写入本地撤销历史，也不会被自动保存回服务端。
+- `refreshMaterials(): Promise<MaterialItem[]>` 只读取当前工程 `/materials` 全部分页，并复用已配置的播放地址刷新、封面展示和后台抽帧处理；结果替换素材面板，空列表会清空面板。不调用工程或 editor 查询，不重新设置 Track/Canvas。
+- `refreshProjectInfo(): Promise<AmkProjectInfo>` 只 GET 当前工程接口，返回并保存完整元信息（包含 `project_id`、`name`、`description` 及服务端扩展字段），可通过 `getProject().projectInfo` 读取；目前名称同步到 `projectName` 和 Header，后续其他工程字段也由该入口处理。不会刷新素材或轨道，不会 PATCH 工程或触发 `onTitleUpdateSuccess`。
+- `refreshEditParam()` 只拉取 editor 文档并更新轨道、画布。`refreshProject()` 一次获取工程信息、素材和 editor 三部分，更新完整工程；局部刷新方法各自只负责对应部分。
+- 两个刷新方法都会等待初始化及已有保存完成，与 `refreshProject()` / `refreshEditParam()` 共用串行刷新队列；同一方法的并发调用合并。读取或播放地址刷新失败时保留原状态并 reject，后续可重试。
 - `whenReady()` 完成后会每 5 秒拉取一次 Editing 工程；服务端 `editor.revision` 高于当前版本，或素材数量 / 素材 ID 集合发生变化时，都会复用 `refreshProject()` 的无撤销热更新链路。素材 ID 优先使用 `material_id`，缺失时回退 `source_material_id`，仅返回顺序变化不会触发刷新。页面进入后台时暂停轮询，重新可见后立即检查一次，`destroy()` 会停止后续轮询。相同 ID 的素材字段更新或纯标题变更仍需宿主主动调用 `refreshProject()`。
 - 轮询会额外检查相同素材后补的封面和雪碧图：当前页面对应字段为空且服务端已返回有效链接时，仅刷新素材面板展示，不重建 Track，也不调用素材或 editor 保存；当前页面已有链接时保持不变。其他相同 ID 的素材字段变化仍不会触发热更新。
 - 素材同步兼容尚未产生轨道的空工程：服务端 `editor.document` 为 `{}`、缺少 `Track` 时按空轨道处理，不会阻断新素材写入面板；显式返回非数组 `Track` 仍视为非法工程数据。

package/dist/amk-editor.d.ts

@@ -1,5 +1,5 @@
 import './veveditor.css';
-import type { AmkMaterialImportType, AmkMaterialImportRequestOptions, AmkEditorOptions, AmkExportRequestResult, AmkProjectSnapshot, MaterialItem, VeVeditorInstance } from './types';
+import type { AmkMaterialImportType, AmkMaterialImportRequestOptions, AmkEditorOptions, AmkExportRequestResult, AmkProjectSnapshot, AmkProjectInfo, MaterialItem, VeVeditorInstance } from './types';
 import { type AmkI18nInstance } from './i18n';
 import { type AmkInvokeToolParams } from './api/client';
 export declare class AmkEditor {
@@ -16,6 +16,7 @@ export declare class AmkEditor {
     private exportTaskListLoaded;
     private exportTaskListRequest?;
     private readonly message;
+    private readonly notifiedToolErrors;
     private importActions?;
     /** 完整 VeVeditor 挂载前承载外部素材导入入口的隐藏节点。 */
     private bootstrapImportHost?;
@@ -27,6 +28,8 @@ export declare class AmkEditor {
     private readonly bootstrapAbortController;
     private destroyed;
     private projectName?;
+    private projectInfo?;
+    private vodConfig?;
     private editorRevision;
     private projectHydrated;
     private lastKnownTrack;
@@ -39,6 +42,8 @@ export declare class AmkEditor {
     private saveQueue;
     /** 初始化 URL refresh 的远端回写；允许先挂载 UI，但 whenReady 仍等待它完成。 */
     private bootstrapRefreshSync;
+    /** 初始化 GET 的素材基线，用于两段刷新结束后只写回原有且变化的素材。 */
+    private bootstrapMaterialBaseline?;
     /** 非轨道素材刷新必须在 VeVeditor 挂载后才启动，避免继续阻塞预览首帧。 */
     private bootstrapRemainingMaterialRefresh?;
     /** 初始化素材播放地址是否刷新成功；失败时禁止用工程旧 URL 新建抽帧任务。 */
@@ -51,11 +56,15 @@ export declare class AmkEditor {
     /** 完整工程与轻量 editor 刷新共用队列，保证后发请求最后应用。 */
     private runtimeRefreshQueue;
     private projectRefreshInFlight?;
+    private materialsRefreshInFlight?;
+    private materialsRefreshTransferRequested;
+    private projectInfoRefreshInFlight?;
     private editParamRefreshInFlight?;
     private pendingSaveCount;
     private readonly asrPollingControllers;
     /** 当前前台 ASR 会话；取消、关闭或销毁后直接丢弃，不写入工程 JSON。 */
     private activeAsrElementId?;
+    private asrSession?;
     /** 提交 ASR 前的同步锁，防止连点在任务创建前重复提交 */
     private readonly asrStartingElementIds;
     /** sprite 抽帧任务轮询：key = material_id / source */
@@ -63,6 +72,13 @@ export declare class AmkEditor {
     private readonly posterPollingControllers;
     /** 同一素材的抽帧检查共享一条 Promise，避免初始化与热刷新重复建任务。 */
     private readonly materialExtractInFlight;
+    /** 每个素材在本次会话只检查一次抽帧；新导入的素材仍会获得自己的首次检查。 */
+    private readonly materialExtractChecked;
+    /** 同一素材的过期图片只刷新一次地址；并发失败共享同一请求。 */
+    private readonly thumbnailErrorHandled;
+    /** 图片确实加载失败时，每个素材的封面/雪碧图各只补抽一次。 */
+    private readonly thumbnailReextractHandled;
+    private readonly thumbnailErrorInFlight;
     /** TOS 上传完成前的素材面板占位：key = source_material_id。 */
     private readonly tosUploadPlaceholders;
     /** URL 上传完成前的素材面板占位：按本次导入批次暂存占位卡片 id。 */
@@ -76,12 +92,10 @@ export declare class AmkEditor {
     private materialPatchBatchTimer?;
     /** 批次串行提交，避免先发批次晚返回后覆盖更新批次。 */
     private materialPatchFlushQueue;
-    /** 同一素材的 sprite 失败只处理一次，避免多个缩略图同时 403 重复建任务。 */
-    private readonly thumbnailErrorInFlight;
     /** 前端抽帧封面缓存（不落盘）：key = materialKey，value = dataURL */
     private readonly posterCache;
-    /** 本次会话签名 URL 对应的原始 TOS 身份，供产物落盘时保留重签依据。 */
-    private readonly tosIdentityBySignedUrl;
+    /** 本次会话展示 URL 对应的原始 TOS/VOD 身份，供产物落盘后续签。 */
+    private readonly taskOutputIdentityByDisplayUrl;
     /** 同一 URL 的封面抽帧只执行一次，避免初始化与上传回调重复请求。 */
     private readonly posterCaptureInFlight;
     /** 销毁编辑器时中断尚未完成的前端抽帧或 AMK 首帧轮询。 */
@@ -90,14 +104,30 @@ export declare class AmkEditor {
     private presetLibrary;
     /** 所有 TOS 素材共用一个刷新定时器，避免按素材创建大量 timer。 */
     private tosSignedUrlRefreshTimer?;
+    /** 同一组未变化的 TOS 签名 URL 只自动重签一次，避免失败后固定间隔空转。 */
+    private readonly tosSignedUrlRefreshAttempted;
     private tosSignedUrlRefreshInFlight?;
+    private vodSignedUrlRefreshTimer?;
+    private readonly vodSignedUrlRefreshAttempted;
+    private vodSignedUrlRefreshInFlight?;
     /** 同一轮播放地址刷新合并 materialId，并串行执行各批次，避免并发覆盖轨道和 revision。 */
     private readonly pendingPlayInfoRefreshes;
     private playInfoRefreshBatchScheduled;
     private playInfoRefreshQueue;
     private readonly handleVisibilityChange;
+    private readonly handleMaterialUploadStatusChange;
     private readonly handleTrackChanged;
     private readonly handleEditParamChanged;
+    private readonly uploadQueue;
+    private activeUploadBatches;
+    private temporaryMaterialTransferPromise?;
+    private temporaryMaterialScanRequested;
+    private readonly committedTemporaryMaterialReplacements;
+    private readonly pendingTemporaryMaterialReplacements;
+    private readonly queuedTemporaryMaterialReplacements;
+    private temporaryMaterialReplacementTimer?;
+    private readonly temporaryMaterialExtractPatches;
+    private readonly deferredTemporaryMaterialExtracts;
     constructor(options: AmkEditorOptions);
     /** 等待工程拉取 / canvas 校正 / 挂载完成 */
     whenReady(): Promise<this>;
@@ -105,6 +135,7 @@ export declare class AmkEditor {
     getI18n(): AmkI18nInstance;
     /** 通用工具调用：POST /api/v1/tools/{toolName} */
     invokeTool<T = unknown>(options: AmkInvokeToolParams): Promise<T>;
+    private wasToolErrorNotified;
     /**
      * Queries an asynchronous AMK task through the editor's configured endpoint
      * and headers. Intended for host UI cards that track tasks created by editor
@@ -148,6 +179,24 @@ export declare class AmkEditor {
      * 适合素材引用面板等必须包含最新导出产物的场景。
      */
     fetchProjectMaterials(): Promise<MaterialItem[]>;
+    /** 重新拉取全部素材并更新素材面板；不重新拉取或替换 Track、工程名。 */
+    refreshMaterials(): Promise<MaterialItem[]>;
+    private refreshMaterialsInternal;
+    private enqueueTemporaryMaterialTransfers;
+    private runTemporaryMaterialTransfers;
+    private reconcileTemporaryMaterials;
+    private findTemporaryMaterialUploadInputs;
+    private applyCommittedMaterialReplacements;
+    private applyCommittedMaterialBindings;
+    private applyTemporaryMaterialExtractPatches;
+    private reconcileTemporaryMaterialExtractPatches;
+    private flushDeferredTemporaryMaterialExtracts;
+    private queueTemporaryMaterialReplacement;
+    private flushTemporaryMaterialReplacements;
+    private resolveTemporaryMaterialReplacements;
+    private uploadTemporaryMaterials;
+    /** 拉取完整工程元信息并应用相关字段；不刷新素材或 Track，也不回写工程。 */
+    refreshProjectInfo(): Promise<AmkProjectInfo>;
     /**
      * 重新拉取服务端工程，并把最新素材与 Track 热更新到当前编辑器。
      * 用于 Agent 完成远端编辑后刷新右侧预览；不会产生撤销记录，也不会把回灌事件再次保存到服务端。
@@ -164,8 +213,9 @@ export declare class AmkEditor {
     /**
      * 刷新素材播放信息（按需触发，如播放前 / 初始化）。
      * - TOS 直传素材会先使用临时 STS 重签私有对象 URL
+     * - VOD 直传素材按 Vid 换取最新播放地址
      * - 配置 `material.onRefreshPlayInfo` 后，宿主可继续覆盖播放字段
-     * - 两者都未配置时直接返回当前素材，不发请求
+     * - 三者都未配置时直接返回当前素材，不发请求
      * @param materialIdOrIds 单个 material_id、material_id 列表；省略则刷新当前全部有 material_id 的素材
      */
     refreshPlayInfo(materialIdOrIds?: string | string[]): Promise<MaterialItem | MaterialItem[] | undefined>;
@@ -178,18 +228,17 @@ export declare class AmkEditor {
     private bootstrap;
     /** 内置拉取工程：project + materials + editor → 归一化 → 组装 initialData。 */
     private resolveAndApplyProject;
+    /** 轨道与非轨道素材全部刷新后，一次批量同步最新 URL 与素材字段。 */
+    private persistBootstrapRefreshedMaterials;
     /**
      * 初始化时批量 refresh 指定素材（未指定时保持全量刷新），
      * 再把轨道元素里的 URL 回填到当前运行时。UserData 与素材媒体 HTTP Source
      * 的变化都不作为主动回写 editor 文档的理由；其他剪辑变化保存时可附带最新 Source。
      */
     private refreshProjectOnInit;
-    /**
-     * 首屏编辑器已经挂载后再刷新非轨道素材。刷新成功先热更新素材面板，
-     * 再后台持久化；失败只保留旧地址，不影响预览与 whenReady 收敛。
-     */
+    /** 首屏挂载后刷新非轨道素材；统一 PUT 在两段刷新完成后执行。 */
     private refreshRemainingMaterialsOnInit;
-    /** TOS 私有桶签名刷新优先，宿主刷新回调随后可继续覆盖播放信息。 */
+    /** 临时素材保留现有 HTTP 地址；其余素材依次经过 TOS、VOD 与宿主播放信息刷新。 */
     private refreshMaterialTargets;
     /**
      * 将重签后的素材 URL 按 material_id 同步到轨道节点并重建媒体节点。
@@ -197,9 +246,15 @@ export declare class AmkEditor {
      */
     private applyTrackMaterialUrls;
     private resolveTosSignedResourceUrls;
+    private isTosSignedUrlRefreshAttempted;
     private getExpiringTosMaterialIds;
     private scheduleTosSignedUrlRefresh;
     private refreshExpiringTosUrls;
+    private resolveVodSignedResourceUrls;
+    private isVodSignedUrlRefreshAttempted;
+    private getExpiringVodMaterialIds;
+    private scheduleVodSignedUrlRefresh;
+    private refreshExpiringVodUrls;
     private readonly handlePreviewNodeRefresh;
     private resolveAndApplyPresetLibrary;
     mount(): VeVeditorInstance;
@@ -278,6 +333,10 @@ export declare class AmkEditor {
     private uploadFileWithPlaceholder;
     private uploadCustomFile;
     private uploadTosFile;
+    private uploadVodFile;
+    private hasVodStorage;
+    private hasTosStorage;
+    private getVodConfig;
     private extractToolResult;
     private requirePositiveNumber;
     private waitForToolTask;
@@ -285,7 +344,7 @@ export declare class AmkEditor {
     private resolveMetadataProbeUrl;
     private isPositiveNumber;
     /**
-     * 自定义本地 / URL / 资产库导入的统一元信息兜底。
+     * 单文件、批量、URL 与资产库导入的统一元信息兜底。
      * 只探测当前缺失的必需字段，业务已经返回的合法值保持不变。
      */
     private ensureImportedMaterialMetadata;
@@ -293,10 +352,10 @@ export declare class AmkEditor {
     /** 将业务资产库的原始条目归一化为 SDK 素材；TOS 地址随后由 SDK 自行签发。 */
     private normalizeSystemMaterial;
     /**
-     * 资产库选择的 TOS 条目：同步签发播放 URL 并补齐基础元信息。
-     * 入参应为已 normalize 的素材；poster/sprite 在正式素材入库后后台处理。
+     * 资产库条目按项准备：启用 SDK TOS 存储时仅为 tos:// 条目签名；
+     * 未启用时保留业务长期 URL，缺少播放地址的条目交给业务刷新回调补齐。
      */
-    private prepareSystemTosMaterials;
+    private prepareSystemMaterials;
     private ingestTosImportedMaterials;
     /**
      * 本地 / URL 上传入库后的统一收口：
@@ -313,6 +372,8 @@ export declare class AmkEditor {
      * 才写入素材面板（业务不用传 material_id；不覆盖本地 source / kid / 预览字段）。
      */
     private persistUploadedMaterials;
+    /** 所有上传方式共用的入库边界：仅补探测缺失元信息，再创建远端素材。 */
+    private createImportedMaterials;
     private rememberPreMountImportedMaterials;
     private isHttpUrl;
     private resolveDisplayPoster;
@@ -349,8 +410,8 @@ export declare class AmkEditor {
      */
     private schedulePersistExtractUrlsAndSwap;
     /**
-     * 统一入口：初始化 / 本地上传 / URL 上传拿到素材后，按 sprite/poster 判断是否抽帧。
-     * - sprite / poster 缺失或 auth_key 过期：重新抽帧
+     * 统一入口：初始化 / 新素材入库后，每个素材在本次会话只检查一次抽帧。
+     * - sprite / poster 缺失时创建任务；图片加载失败不再触发重抽
      * - http 结果：先临时链上屏/PUT；若配置 onPersistExtractUrls 则后台转存换链
      * - 封面：浏览器可并行解一帧作会话预览（DataURL 不落盘）；正式封面始终走 AMK 接口 URL 落库
      * - enableThumbnailDecode=true：跳过 sprite 接口，轨道缩略图走前端解码
@@ -360,22 +421,21 @@ export declare class AmkEditor {
     private ensureTrackMaterialExtractTasks;
     private ensureMaterialExtractTasksInBackground;
     private createExtractFramesTask;
-    /** AMK 转存到私有 TOS 后，任务产物需先重签才能用于浏览器预览。 */
+    /** 导出结果是资源身份时，先换取浏览器可访问的播放地址。 */
+    private resolveExportOutputUrl;
+    /** 任务产物的 TOS/VOD 身份先换成浏览器可访问的 HTTP URL。 */
     private signTaskOutputUrls;
     private startSpritePolling;
     private startPosterPolling;
     private buildSpriteFromExtractResult;
     private extractFirstSnapshotUrl;
-    /**
-     * 时间轴 sprite / 素材库 poster 真实请求失败后的兜底：不解析 URL 的签名格式，直接以 Image.onerror 为准。
-     * 先让业务通过 onRefreshPlayInfo 更新素材；刷新后仍没有新地址，再重新抽帧。
-     */
+    /** 图片真实加载失败时先换一次过期签名，仍不可用则每类图片最多补抽一次。 */
     private handleThumbnailError;
-    /** 兼容时间轴元素与素材库 sketch 项，定位失败资源所属素材。 */
     private resolveMaterialFromThumbnailError;
     private findMaterialByKey;
     private applyMaterialToPanel;
     private enqueueMaterialPatch;
+    private patchMaterialExtraction;
     private patchMaterialRemote;
     private flushPendingMaterialPatches;
     private clearSpriteTimer;

package/dist/api/project.d.ts

@@ -1,6 +1,12 @@
 import type { AmkApiClient } from './client';
-import type { AmkProjectSnapshot, MaterialItem } from '../types';
+import type { AmkProjectSnapshot, AmkProjectInfo, MaterialItem } from '../types';
 type EditingApiClient = Pick<AmkApiClient, 'requestJson'>;
+export interface AmkMaterialReplacement {
+    material_id: string;
+    source_material_id: string;
+    source: string;
+    url?: string;
+}
 export type LoadedAmkProject = AmkProjectSnapshot & {
     editorRevision: number;
 };
@@ -15,6 +21,10 @@ export type SavedAmkEditor = {
 export declare function fetchAmkProjectMaterials(client: EditingApiClient, projectId: string, options?: {
     signal?: AbortSignal;
 }): Promise<MaterialItem[]>;
+/** 只读取工程元信息，不请求素材列表和 editor 文档。 */
+export declare function fetchAmkProjectInfo(client: EditingApiClient, projectId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<AmkProjectInfo>;
 export declare function fetchAmkProject(client: EditingApiClient, projectId: string, options?: {
     signal?: AbortSignal;
 }): Promise<LoadedAmkProject>;
@@ -34,6 +44,8 @@ export declare function createAmkMaterials(client: EditingApiClient, projectId:
  * PUT 语义：已存在覆盖，不存在新增；适合本地上传/URL上传完成后写回。
  */
 export declare function upsertAmkMaterials(client: EditingApiClient, projectId: string, materials: MaterialItem[]): Promise<void>;
+/** Rebinds existing materials to durable customer storage without changing material_id. */
+export declare function replaceAmkMaterials(client: EditingApiClient, projectId: string, materials: AmkMaterialReplacement[]): Promise<void>;
 /**
  * 删除 AMK 工程素材。Editing API DELETE body 为 source_material_ids，
  * 值为业务 source_material_id；这里统一按 100 条分批。

package/dist/asr-provider.d.ts

@@ -0,0 +1,17 @@
+import type { AmkInvokeToolParams } from './api/client';
+export type AmkAsrProvider = 'asr-subtitles' | 'maas';
+export declare function resolveAsrProvider(provider?: AmkAsrProvider): AmkAsrProvider;
+/** 中间音频不转存，以获得下游模型可直接读取的临时 HTTP(S) URL。 */
+export declare function submitMaasAsr(options: {
+    mediaType: 'video' | 'audio';
+    mediaUrl: string;
+    signal?: AbortSignal;
+    invoke: (params: AmkInvokeToolParams) => Promise<any>;
+    query: (taskId: string) => Promise<any>;
+}): Promise<string>;
+/** 旧字幕接口使用秒；MaaS 的分句时间是毫秒，在入口统一为秒。 */
+export declare function extractMaasUtterances(payload: any): {
+    text: any;
+    start_time: number;
+    end_time: number;
+}[] | undefined;

package/dist/byteplus-export-source-adapter.d.ts

@@ -0,0 +1,9 @@
+type JsonRecord = Record<string, unknown>;
+/**
+ * TEMP: BP 导出接口尚不支持元素 Source 的 vod:// / tos:// 地址。
+ * 服务端工程不保存 UserData，优先使用刚刷新的素材 URL；运行时副本可回退 UserData.url。
+ * 只遍历 Track 元素，不处理 Extra；返回副本供提交，绝不改动工程。
+ * 服务端支持协议地址后，删除本文件及 amk-editor.ts 中的调用即可。
+ */
+export declare function replaceBytePlusExportElementSources(editParam: JsonRecord, materialUrlById?: ReadonlyMap<string, string>): JsonRecord;
+export {};

package/dist/config-validation.d.ts

@@ -0,0 +1,3 @@
+import type { AmkEditorOptions } from './types';
+/** 仅校验初始化时可确定的配置错误，不请求凭证或远端服务。 */
+export declare function validateAmkEditorOptions(options: AmkEditorOptions): string[];

package/dist/distribution.d.ts

@@ -0,0 +1,16 @@
+export declare const distribution: "volcengine" | "byteplus";
+export declare const distributionDefaults: {
+    locale: string;
+    region: string;
+    videoHost: string;
+};
+/**
+ * 发行版对应的服务端能力开关。
+ *
+ * BytePlus AMK 当前不支持通过 media_output_destination 配置产物转存。
+ * 该限制只作用于 AMK 接口请求，不影响 SDK 使用 @byteplus/uploader
+ * 完成 BytePlus VOD 直传与播放地址解析；BytePlus TOS 仍可后续独立接入。
+ */
+export declare const distributionCapabilities: {
+    readonly forwardsMediaOutputDestination: boolean;
+};

package/dist/export-project-adapter.d.ts

@@ -1,4 +1,6 @@
 import type { ExportVideoParams } from './types';
+/** 复用 master 导出语义：忽略无效文字后，所有元素均为音频则关闭视频合成。 */
+export declare function isOnlyAudioTrack(track: unknown): boolean;
 /**
  * 开启画质增强时，把增强任务参数交给代理层（callback_args，JSON 字符串）。
  * - large-model → POST .../tools/enhance-video-generative

package/dist/header.d.ts

@@ -39,6 +39,8 @@ export type AmkExportTaskListItem = {
     /** 是否已在当前页面触发过浏览器下载。 */
     downloaded?: boolean;
     outputUrl?: string;
+    /** 产物的实际媒体类型；可能与用户选择的容器格式不同。 */
+    mediaType?: 'video' | 'audio';
 };
 export interface AmkEditorLayout {
     root: HTMLDivElement;

package/dist/i18n/keys.d.ts

@@ -30,6 +30,7 @@ export declare const AMK_I18N_KEYS: {
         readonly exportTaskEmptyDescription: "amk.header.exportTaskEmptyDescription";
         readonly exportTaskLoading: "amk.header.exportTaskLoading";
         readonly exportTaskDownloadReady: "amk.header.exportTaskDownloadReady";
+        readonly exportTaskUrlUnavailable: "amk.header.exportTaskUrlUnavailable";
         readonly exportTaskDownload: "amk.header.exportTaskDownload";
         readonly exportTaskDownloadAgain: "amk.header.exportTaskDownloadAgain";
         readonly exportTaskDownloading: "amk.header.exportTaskDownloading";

package/dist/import-actions.d.ts

@@ -1,6 +1,8 @@
+import { type UploadQueue } from './upload-queue';
 import type { AmkMaterialImportType, AmkMaterialImportRequestOptions, MaterialItem, SystemMaterialItem } from './types';
 import type { AmkI18nInstance } from './i18n';
 interface MountImportActionsOptions {
+    uploadQueue?: UploadQueue;
     /** AMKEditor 自己的浮层容器；按钮仍挂在 VeVeditor 提供的工具栏插槽中。 */
     modalContainer: HTMLElement;
     uploadAccept?: string;

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export declare const version: string;
+export type { AmkAsrProvider } from './asr-provider';
 export { AmkEditor, createAmkEditor } from './amk-editor';
 export { AmkApiClient, createAmkApiClient } from './api/client';
 export type { AmkApiClientOptions, AmkInvokeToolParams } from './api/client';
 export type { PresetLibrary, PresetLibraryItem, PresetLibraryResourceKey, } from './api/preset-library';
 export { AMK_I18N_KEYS, createAmkI18n, tAmk, getGlobalAmkI18n, setGlobalAmkI18n, } from './i18n';
 export type { AmkI18nInstance, AmkI18nOptions, Locale, LocaleMessages, Messages, } from './i18n';
-export type { AmkEditorOptions, AmkEditorStorageConfig, AmkEditorUploadSTSCredentials, AmkEditorConfig, AmkEditorDecodeOptions, AmkEditorExportConfig, AmkEditorGetHeaders, AmkEditorHeaderConfig, AmkEditorHeaderTitleUpdateSuccess, AmkEditorInternalConfig, AmkMaterialImportType, AmkMaterialImportRequestOptions, AmkExportRequestResult, AmkExportTaskCreatedEvent, AmkProjectSnapshot, ExportVideoParams, MaterialConfig, MaterialItem, PersistExtractUrlsResult, RecommendedExtractStorageFields, SystemMaterialItem, Theme, VeVeditorInstance, } from './types';
+export type { AmkEditorOptions, AmkEditorStorageConfig, AmkEditorUploadSTSCredentials, AmkEditorVodPlayInfo, AmkEditorVodUploadToken, AmkEditorConfig, AmkEditorDecodeOptions, AmkEditorExportConfig, AmkEditorGetHeaders, AmkEditorHeaderConfig, AmkEditorHeaderTitleUpdateSuccess, AmkEditorInternalConfig, AmkMaterialImportType, AmkMaterialImportRequestOptions, AmkExportRequestResult, AmkExportTaskCreatedEvent, AmkProjectSnapshot, AmkProjectInfo, ExportVideoParams, MaterialConfig, MaterialItem, PersistExtractUrlsResult, RecommendedExtractStorageFields, SystemMaterialItem, Theme, VeVeditorInstance, } from './types';