@byteplus/amk-editor 0.0.0-beta.1

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates. All Rights Reserved.
+
+The AMK Editor SDK was developed by Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates (hereinafter “Volcano Engine”). Any rights, including but not limited to any copyrights or patent rights, are owned by and proprietary material of the Volcano Engine.
+
+The AMK Editor SDK is licensed solely for integration within AI MediaKit which shall be used under a valid commercial license. Customers can contact service@volcengine.com for such commercial license. Here is also a link to AI MediaKit: https://www.volcengine.com/docs/6448/69e744e0d6af160501b2d70b?lang=zh.
+
+Without Volcano Engine's prior written permission, any use of the AMK Editor SDK beyond its incorporation into AI MediaKit, in particular any use for commercial purposes, is strictly prohibited. This includes, without limitation, incorporation in a commercial product, use in a commercial service, or production of other artefacts for commercial purposes.
+
+Without Volcano Engine's prior written permission, you shall not reproduce, modify, decompile, disassemble, reverse-engineer, or create derivative works of the AMK Editor SDK, nor access, extract, or obtain its source code by any means, or make it available in any form to any third party in any form. Any unauthorized modifications, derivative works, or adaptations of the AMK Editor SDK, along with all associated intellectual property rights, shall automatically and exclusively vest in Volcano Engine.
+
+Except otherwise provided by Volcano Engine, the AMK Editor SDK is provided “AS IS” without any warranties. Volcano Engine disclaims all liability for damages arising from its use.

package/README.md

@@ -0,0 +1,217 @@
+# @byteplus/amk-editor
+
+The official BytePlus AI MediaKit web video editor SDK.
+
+## Automatic subtitles
+
+The existing subtitle toolbar button uses the MaaS pipeline by default:
+
+```ts
+const editor = new AmkEditor({
+  container, projectId, endpoint,
+  toolbar: {
+    asr: { provider: 'maas' }, // Optional: this is the BytePlus default.
+  },
+});
+```
+
+Videos are processed by `extract-audio` with `format: 'mp3'`, followed by
+`call-maas-proxy` with `api: 'doubao.asr'` and `show_utterances: true`.
+HTTP(S) MP3/WAV/OGG audio is submitted directly; other or unknown audio
+formats are converted using `transcode-audio` with `container_format: 'MP3'`.
+The intermediate audio is not added to the project library. These requests
+omit `media_output_destination` to obtain temporary HTTP(S) audio URLs.
+All requests use your configured `endpoint` and `getHeaders`; no domestic
+endpoint or credential is embedded in the SDK.
+
+Sentence timestamps are converted from milliseconds and mapped to the
+existing trimmed/speed-adjusted timeline. The existing
+`toolbar.builtInVisibility.asrSubtitle` setting still controls visibility.
+Cancelling the modal or destroying the editor stops local waiting and prevents
+subsequent stages/subtitle insertion, but does not cancel already submitted
+remote jobs or their charges.
+
+Your proxy/account must support the above tools and task queries, with the
+required model service and cross-service permissions enabled. Source URLs
+must remain accessible to the backend. The pipeline has been verified on
+Volcengine; availability on your BytePlus endpoint/account must be verified
+separately. BytePlus rejects `toolbar.asr.provider: 'asr-subtitles'`, because that legacy
+tool is unavailable. Volcengine defaults to `asr-subtitles` and can opt into `maas`.
+
+## Installation
+
+```bash
+npm install @byteplus/amk-editor
+```
+
+React 18 and React 19 are supported. Use of this SDK requires a valid BytePlus
+commercial license. See [LICENSE](./LICENSE). Third-party open-source components
+remain subject to their respective licenses.
+
+## Quick start
+
+```ts
+import { AmkEditor } from '@byteplus/amk-editor';
+
+const editor = new AmkEditor({
+  container,
+  projectId: 'your-project-id',
+  endpoint: 'https://your-backend.example.com',
+  source: 'your-app-name',
+  // Called before every request. The SDK does not parse or persist the headers.
+  getHeaders: async () => ({
+    Authorization: `Bearer ${await getLatestToken()}`,
+  }),
+  // Optional. Custom uploads take priority over built-in storage uploads.
+  material: {
+    onUploadFile: async file => uploadOneFile(file),
+    onUploadUrlMaterial: async urls => uploadUrls(urls),
+    onRefreshPlayInfo: async materials => refreshPlayableUrls(materials),
+  },
+});
+
+await editor.whenReady();
+```
+
+Destroy the editor when the page is unmounted:
+
+```ts
+editor.destroy();
+```
+
+## Built-in VOD upload
+
+BytePlus AMK does not currently support TOS or VOD output transfer through
+`media_output_destination`. The BytePlus build therefore never sends this field
+to AMK tool APIs, including when the same field is supplied explicitly in tool
+parameters. This restriction applies only to AMK-side output transfer; it does
+not disable browser-side VOD upload.
+
+When `storage.media_output_destination` is `vod://<space>` and
+`storage.getUploadSTS` is configured, the SDK uploads local files with its
+distribution-specific VOD dependency:
+
+These two fields must be configured together. Supplying only one of them causes
+initialization to fail. If neither built-in storage nor a custom upload callback
+is configured, the local-upload entry is hidden.
+
+- `@byteplus/amk-editor` uses `@byteplus/uploader`, `ap-southeast-1`, and
+  `https://vod.byteplusapi.com`.
+- `@volcengine/amk-editor` uses `tt-uploader`, `cn-north-1`, and
+  `https://vod.volcengineapi.com`.
+
+The uploader is selected while building the SDK package. A BytePlus application
+does not need to import or pass an uploader instance.
+
+```ts
+const editor = new AmkEditor({
+  // ...required options
+  storage: {
+    media_output_destination: 'vod://your-byteplus-space',
+    getUploadSTS: () => fetch('/api/vod-upload-sts', {
+      method: 'POST',
+    }).then(response => response.json()),
+  },
+});
+```
+
+Playback URL refreshes do not publish media. Publishing happens only after a successful built-in upload. Each VOD refresh batch shares one STS request and deduplicates playback queries by Vid.
+
+`getUploadSTS` must return short-lived BytePlus VOD credentials containing
+`AccessKeyId`, `SecretAccessKey`, `SessionToken`, `ExpiredTime`, and
+`CurrentTime`. Keep permanent AK/SK credentials on your server. The SDK uploads
+the file, publishes the resulting Vid, obtains an HTTP(S) playback URL, and
+stores `vod://<space>/<Vid>` as the stable material identity.
+
+Built-in BytePlus TOS browser upload is not enabled yet. Use
+`material.onUploadFile` for TOS or another business storage service until the
+BytePlus TOS endpoint integration is available.
+
+## Custom upload priority
+
+To use a business-owned upload flow, provide a custom callback:
+
+```ts
+material: {
+  onUploadFile: async file => uploadToYourStorage(file),
+}
+```
+
+Upload selection priority is:
+
+1. `material.onUploadFile(file)`
+2. Legacy `material.onUploadMaterial(files)`
+3. SDK built-in VOD/TOS upload, when supported and configured
+
+This means a configured custom upload callback always takes precedence over
+`storage`.
+
+## Material identity and playable URLs
+
+`source_material_id` is the stable material identifier. A material may use a
+TOS/VOD-style identifier while its `url` remains a long-lived or temporary
+HTTP(S) playback URL.
+
+Without a supported and fully configured built-in storage integration, the SDK
+does not sign a material merely because `source_material_id` starts with
+`tos://` or `vod://`:
+
+- An existing HTTP(S) `url` is used as-is.
+- If the URL is missing or expires, implement `material.onRefreshPlayInfo` and
+  return a fresh HTTP(S) URL.
+- A material without a playable URL is not added to the editor.
+
+## Upload concurrency
+
+Use `material.uploadConcurrency` to limit concurrent local uploads in one editor:
+
+```ts
+material: {
+  uploadConcurrency: 3,
+  onUploadFile: async file => uploadToYourStorage(file),
+}
+```
+
+The limit applies to `onUploadFile` and built-in local uploads. It does not apply
+to URL imports or system-library imports.
+
+## Common APIs
+
+```ts
+editor.requestMaterialImport('local');
+editor.requestMaterialImport('url');
+editor.requestMaterialImport('system');
+
+await editor.refreshProject();
+const materials = await editor.refreshMaterials();
+const projectInfo = await editor.refreshProjectInfo();
+await editor.updateTitle('New project title');
+
+const task = await editor.getTask('your-task-id');
+```
+
+`container`, `projectId`, and `endpoint` are required. `getHeaders` is evaluated
+before each request, so refreshed business credentials are used automatically.
+All AMK service requests include `X-Amk-Task-Source: vibe-editing`; allow this
+header in the CORS configuration of your proxy.
+
+## Capture the current frame
+
+```ts
+await editor.whenReady();
+const image = editor.getEditor()?.getFrame?.({ type: 'image/png' });
+```
+
+The method returns a data URL, or `null` before the canvas is initialized. Native
+rendering mode does not support this API.
+
+## Styling and isolation
+
+Importing `@byteplus/amk-editor` automatically includes the SDK styles. The
+editor uses normal DOM rather than Shadow DOM, so broad host-page selectors such
+as `section`, `nav`, or `aside` can affect its layout. Size the mount container
+directly and avoid tag-level layout overrides inside the editor.
+
+## Temporary export Source compatibility
+
+当前 BP SDK 在提交导出时遍历 Track 元素：元素 Source 为 vod:// 或 tos:// 地址时，优先使用刚刷新的素材播放 URL；仅运行时副本回退 UserData.url，因为服务端工程不会保存 UserData。其他 Source（例如文本、特效的协议或业务 ID）原样保留。该转换仅作用于导出副本，不处理 Extra，也不改变上传或工程中保存的 vod:// / tos:// 地址。缺少有效素材播放 URL 时，错误会指出元素 ID 和类型。BP 接口支持协议地址后，可删除 `src/byteplus-export-source-adapter.ts` 和 `src/amk-editor.ts` 中的调用。

package/dist/amk-editor.d.ts

@@ -0,0 +1,411 @@
+import './veveditor.css';
+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 {
+    private readonly options;
+    private config;
+    private readonly i18n;
+    private editor?;
+    private layout?;
+    private exportModal?;
+    private exportRequestInFlight?;
+    private readonly exportTaskPollingControllers;
+    private readonly exportTaskPollingTokens;
+    private exportTasks;
+    private exportTaskListLoaded;
+    private exportTaskListRequest?;
+    private readonly message;
+    private readonly notifiedToolErrors;
+    private importActions?;
+    /** 完整 VeVeditor 挂载前承载外部素材导入入口的隐藏节点。 */
+    private bootstrapImportHost?;
+    private asrProgressModal?;
+    private confirmModal?;
+    private emptyTrackConfirmInFlight?;
+    private readonly apiClient;
+    private readonly ready;
+    private readonly bootstrapAbortController;
+    private destroyed;
+    private projectName?;
+    private projectInfo?;
+    private editorRevision;
+    private projectHydrated;
+    private lastKnownTrack;
+    private intentionalEmptyTrackChange;
+    private emptyTrackSaveNeedsConfirmation;
+    private emptyTrackSaveBlocked;
+    private savedMaterials;
+    /** 工程初始化慢请求期间已完成的导入，防止最终快照将其覆盖。 */
+    private preMountImportedMaterials;
+    private saveQueue;
+    /** 初始化 URL refresh 的远端回写；允许先挂载 UI，但 whenReady 仍等待它完成。 */
+    private bootstrapRefreshSync;
+    /** 非轨道素材刷新必须在 VeVeditor 挂载后才启动，避免继续阻塞预览首帧。 */
+    private bootstrapRemainingMaterialRefresh?;
+    /** 初始化素材播放地址是否刷新成功；失败时禁止用工程旧 URL 新建抽帧任务。 */
+    private bootstrapMaterialRefreshSucceeded;
+    /** 最近一次 GET 或成功 PUT 后的服务端 editor 深比较基线。 */
+    private latestEditorFingerprint;
+    private latestEditorHasTrack;
+    /** 正在等待或执行的 editor 文档快照，用于合并高频重复事件。 */
+    private readonly pendingEditorSaveFingerprints;
+    /** 完整工程与轻量 editor 刷新共用队列，保证后发请求最后应用。 */
+    private runtimeRefreshQueue;
+    private projectRefreshInFlight?;
+    private materialsRefreshInFlight?;
+    private projectInfoRefreshInFlight?;
+    private editParamRefreshInFlight?;
+    private pendingSaveCount;
+    private readonly asrPollingControllers;
+    /** 当前前台 ASR 会话；取消、关闭或销毁后直接丢弃，不写入工程 JSON。 */
+    private activeAsrElementId?;
+    private asrSession?;
+    /** 提交 ASR 前的同步锁，防止连点在任务创建前重复提交 */
+    private readonly asrStartingElementIds;
+    /** sprite 抽帧任务轮询：key = material_id / source */
+    private readonly spritePollingControllers;
+    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。 */
+    private readonly urlUploadPlaceholders;
+    /** 同一素材的封面/雪碧图转存结果串行写回，避免自定义字段互相覆盖。 */
+    private readonly materialPatchQueues;
+    /** 等待批量落盘的素材；同一素材在窗口内只保留合并后的最新状态。 */
+    private readonly pendingMaterialPatches;
+    /** 包含等待中和提交中的最新本地状态，用于合并跨批次的并发字段。 */
+    private readonly latestMaterialPatches;
+    private materialPatchBatchTimer?;
+    /** 批次串行提交，避免先发批次晚返回后覆盖更新批次。 */
+    private materialPatchFlushQueue;
+    /** 前端抽帧封面缓存（不落盘）：key = materialKey，value = dataURL */
+    private readonly posterCache;
+    /** 本次会话展示 URL 对应的原始 TOS/VOD 身份，供产物落盘后续签。 */
+    private readonly taskOutputIdentityByDisplayUrl;
+    /** 同一 URL 的封面抽帧只执行一次，避免初始化与上传回调重复请求。 */
+    private readonly posterCaptureInFlight;
+    /** 销毁编辑器时中断尚未完成的前端抽帧或 AMK 首帧轮询。 */
+    private readonly posterCaptureControllers;
+    /** 启动时加载的内置预设资源，供编辑器面板和 ASR 字幕复用。 */
+    private presetLibrary;
+    /** 所有 TOS 素材共用一个刷新定时器，避免按素材创建大量 timer。 */
+    private tosSignedUrlRefreshTimer?;
+    /** 同一组未变化的 TOS 签名 URL 只自动重签一次，避免失败后固定间隔空转。 */
+    private readonly tosSignedUrlRefreshAttempted;
+    private tosSignedUrlRefreshInFlight?;
+    /** 同一轮播放地址刷新合并 materialId，并串行执行各批次，避免并发覆盖轨道和 revision。 */
+    private readonly pendingPlayInfoRefreshes;
+    private playInfoRefreshBatchScheduled;
+    private playInfoRefreshQueue;
+    private readonly handleVisibilityChange;
+    private readonly handleTrackChanged;
+    private readonly handleEditParamChanged;
+    private readonly uploadQueue;
+    private activeUploadBatches;
+    constructor(options: AmkEditorOptions);
+    /** 等待工程拉取 / canvas 校正 / 挂载完成 */
+    whenReady(): Promise<this>;
+    getEditor(): VeVeditorInstance | undefined;
+    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
+     * operations such as {@link requestExport}.
+     */
+    getTask<T = unknown>(taskId: string, options?: {
+        headers?: Record<string, string>;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    /**
+     * Opens the existing export modal and resolves after the user confirms or cancels.
+     * Intended for Agent frontend tools (`request_export_task`). Header export still
+     * uses `open()` + direct submit and is unchanged.
+     */
+    requestExport(): Promise<AmkExportRequestResult>;
+    /**
+     * 从外部工具栏打开 AMK Editor 已配置的素材导入入口。
+     * 本地、URL、资产库均复用素材面板中的同一套弹窗、回调和入库链路。
+     * @returns 当前入口存在且已触发时返回 true；未配置时返回 false。
+     */
+    requestMaterialImport(type: AmkMaterialImportType, options?: AmkMaterialImportRequestOptions): boolean;
+    /**
+     * 直接导入外部 URL 素材，不打开 URL 输入弹窗。
+     * 供 Agent / 宿主前端 Tool 复用 material.onUploadUrlMaterial，并继续走
+     * AMK Editor 的素材持久化、面板更新与 onMaterialsImported 链路。
+     */
+    uploadUrlMaterials(urls: string[]): Promise<MaterialItem[]>;
+    /**
+     * 从外部更新 AMK 工程标题。
+     * 保存成功后会同步编辑器顶栏与工程快照，并触发 header.onTitleUpdateSuccess。
+     */
+    updateTitle(title: string): Promise<void>;
+    /**
+     * 获取工程全量参数（materials + editParam + projectName）。
+     * 从 VeVeditor 当前素材/草稿快照读取；未挂载时回落内置拉取到的快照。
+     */
+    getProject(): AmkProjectSnapshot;
+    /**
+     * 从 Editing 工程接口重新拉取完整素材列表。
+     * 与 `getProject()` 的当前编辑器快照不同，该方法每次都会请求服务端，
+     * 适合素材引用面板等必须包含最新导出产物的场景。
+     */
+    fetchProjectMaterials(): Promise<MaterialItem[]>;
+    /** 重新拉取全部素材并更新素材面板；不重新拉取或替换 Track、工程名。 */
+    refreshMaterials(): Promise<MaterialItem[]>;
+    /** 拉取完整工程元信息并应用相关字段；不刷新素材或 Track，也不回写工程。 */
+    refreshProjectInfo(): Promise<AmkProjectInfo>;
+    /**
+     * 重新拉取服务端工程，并把最新素材与 Track 热更新到当前编辑器。
+     * 用于 Agent 完成远端编辑后刷新右侧预览；不会产生撤销记录，也不会把回灌事件再次保存到服务端。
+     */
+    refreshProject(): Promise<AmkProjectSnapshot>;
+    /**
+     * 只重新拉取服务端 editor 文档并热更新 Track。
+     * 不请求或替换工程名称、素材列表，适合 Agent 运行过程中的轻量预览刷新。
+     */
+    refreshEditParam(): Promise<Record<string, unknown>>;
+    private enqueueRuntimeRefresh;
+    private refreshEditParamFromServer;
+    private refreshProjectFromServer;
+    /**
+     * 刷新素材播放信息（按需触发，如播放前 / 初始化）。
+     * - TOS 直传素材会先使用临时 STS 重签私有对象 URL
+     * - VOD 直传素材按 Vid 换取最新播放地址
+     * - 配置 `material.onRefreshPlayInfo` 后，宿主可继续覆盖播放字段
+     * - 三者都未配置时直接返回当前素材，不发请求
+     * @param materialIdOrIds 单个 material_id、material_id 列表；省略则刷新当前全部有 material_id 的素材
+     */
+    refreshPlayInfo(materialIdOrIds?: string | string[]): Promise<MaterialItem | MaterialItem[] | undefined>;
+    private flushPlayInfoRefreshBatch;
+    private refreshPlayInfoInternal;
+    /**
+     * 异步初始化入口：并行加载工程与预设，完成数据归一化后再挂载编辑器，
+     * 最后注册运行期的 URL 刷新和页面可见性监听。destroy() 可随时中断该流程。
+     */
+    private bootstrap;
+    /** 内置拉取工程：project + materials + editor → 归一化 → 组装 initialData。 */
+    private resolveAndApplyProject;
+    /**
+     * 初始化时批量 refresh 指定素材（未指定时保持全量刷新），
+     * 再把轨道元素里的 URL 回填到当前运行时。UserData 与素材媒体 HTTP Source
+     * 的变化都不作为主动回写 editor 文档的理由；其他剪辑变化保存时可附带最新 Source。
+     */
+    private refreshProjectOnInit;
+    /**
+     * 首屏编辑器已经挂载后再刷新非轨道素材。刷新成功先热更新素材面板，
+     * 再后台持久化；失败只保留旧地址，不影响预览与 whenReady 收敛。
+     */
+    private refreshRemainingMaterialsOnInit;
+    /** TOS 私有桶签名刷新优先，宿主刷新回调随后可继续覆盖播放信息。 */
+    private refreshMaterialTargets;
+    /**
+     * 将重签后的素材 URL 按 material_id 同步到轨道节点并重建媒体节点。
+     * URL 是运行时数据：只更新 SDK 内存与渲染节点，不主动保存工程，也不产生撤销步骤。
+     */
+    private applyTrackMaterialUrls;
+    private resolveTosSignedResourceUrls;
+    private isTosSignedUrlRefreshAttempted;
+    private getExpiringTosMaterialIds;
+    private scheduleTosSignedUrlRefresh;
+    private refreshExpiringTosUrls;
+    private readonly handlePreviewNodeRefresh;
+    private resolveAndApplyPresetLibrary;
+    mount(): VeVeditorInstance;
+    /**
+     * 只挂载项目 header、弹窗和导入控制器，不创建重量级 VeVeditor。
+     * 该阶段只依赖工程基础 GET，可提前首屏可见与输入框上传响应。
+     */
+    private mountLayout;
+    private mountVeVeditor;
+    private destroyLayout;
+    /** 在重量级编辑器创建前提供外部上传入口；节点本身不展示按钮。 */
+    private mountBootstrapImportActions;
+    /** 素材面板按钮与输入框「+」共用同一导入控制器。 */
+    private mountConfiguredImportActions;
+    destroy(): void;
+    private assertNotDestroyed;
+    private resolveConfig;
+    /** 与 VeVeditor 同一套顶层扁平资源字段：boolean 面板开关 + 内部 xgplayer 组装 */
+    private resolveVeVeditorOptions;
+    private resolveInternalConfig;
+    private enqueueSave;
+    private queueProjectNameSave;
+    private updateProjectTitle;
+    /**
+     * VeVeditor 删除前置钩子：远端删除成功后返回 true，底层才清理本地素材和轨道；
+     * 请求失败返回 false，保留当前素材。
+     */
+    private deleteMaterial;
+    private queueEditorSave;
+    private setLatestEditorSnapshot;
+    private confirmAbnormalEmptyTrackSave;
+    private enqueueEditorSaveWithCurrentEditParam;
+    /**
+     * AMK 内部导出入口。
+     * 适配只作用于即将提交给导出接口的 editParam 副本，不写回工程或当前预览。
+     */
+    private submitExport;
+    private startExportTaskStatusPolling;
+    private refreshExportTasksAfterSubmission;
+    private refreshLatestExportTasks;
+    private loadLatestExportTasks;
+    private clearExportTaskPolling;
+    private attach;
+    private detach;
+    private clearAsrPollingTimers;
+    private isAsrMediaElement;
+    /** 前台 ASR 弹窗打开期间，只允许当前素材对应的一个任务运行。 */
+    private isAsrBusy;
+    private cancelActiveAsrTask;
+    private completeAsrTask;
+    private createId;
+    private getTrackSnapshot;
+    private setTrackSnapshot;
+    private findTrackElementIndexById;
+    private resolveAsrMediaUrl;
+    private extractTaskId;
+    private submitAsrTask;
+    private queryAsrTask;
+    private isTaskCompleted;
+    private isTaskFailed;
+    private extractUtterances;
+    private normalizeAsrRange;
+    private resolveAsrTimelineMapping;
+    private createAsrTextElement;
+    private finishAsrAndCreateTextTrack;
+    private startAsrPolling;
+    private startAsrTask;
+    private resolveLocalFileType;
+    private createTosUploadPlaceholder;
+    private createUrlUploadPlaceholder;
+    private removeUrlUploadPlaceholders;
+    /** 资产库选中后立即展示 0% 上传占位卡片，写入素材库成功后再切换为完成态。 */
+    private addSystemTosImportPlaceholders;
+    private removeTosUploadPlaceholders;
+    private hasTosUploadPlaceholders;
+    private uploadFileWithPlaceholder;
+    private uploadCustomFile;
+    private uploadTosFile;
+    private uploadVodFile;
+    private hasVodStorage;
+    private hasTosStorage;
+    private getVodConfig;
+    private extractToolResult;
+    private requirePositiveNumber;
+    private waitForToolTask;
+    private probeAsyncMetadata;
+    private resolveMetadataProbeUrl;
+    private isPositiveNumber;
+    /**
+     * 单文件、批量、URL 与资产库导入的统一元信息兜底。
+     * 只探测当前缺失的必需字段，业务已经返回的合法值保持不变。
+     */
+    private ensureImportedMaterialMetadata;
+    private prepareTosMaterial;
+    /** 将业务资产库的原始条目归一化为 SDK 素材；TOS 地址随后由 SDK 自行签发。 */
+    private normalizeSystemMaterial;
+    /**
+     * 资产库条目按项准备：启用 SDK TOS 存储时仅为 tos:// 条目签名；
+     * 未启用时保留业务长期 URL，缺少播放地址的条目交给业务刷新回调补齐。
+     */
+    private prepareSystemMaterials;
+    private ingestTosImportedMaterials;
+    /**
+     * 本地 / URL 上传入库后的统一收口：
+     * POST 远端素材库 → 按 sprite/poster 判断发起抽帧并 PUT 更新。
+     */
+    private ingestImportedMaterials;
+    /**
+     * 通知宿主素材已入库。抽帧仍在后台进行，不阻塞对话引用。
+     */
+    private notifyMaterialsImported;
+    /**
+     * 本地上传 / URL 上传完成后，将新素材 POST 到 Editing API。
+     * 先确保远端持久化并合并 Editing API 返回的 material_id；成功后调用方
+     * 才写入素材面板（业务不用传 material_id；不覆盖本地 source / kid / 预览字段）。
+     */
+    private persistUploadedMaterials;
+    /** 所有上传方式共用的入库边界：仅补探测缺失元信息，再创建远端素材。 */
+    private createImportedMaterials;
+    private rememberPreMountImportedMaterials;
+    private isHttpUrl;
+    private resolveDisplayPoster;
+    /**
+     * DataURL 已上屏时保留到本次会话结束，HTTP poster 只负责落库。
+     * 没有前端预览或当前缓存也是 HTTP 时，才切换到新的 HTTP 地址。
+     */
+    private cachePersistedPosterForDisplay;
+    private withDisplayPosters;
+    private blobToDataUrl;
+    /** AMK 视频抽帧：指定第 0 帧并轮询任务结果。 */
+    private captureVideoPosterFromAmk;
+    /** 前端 Range + WebCodecs 解第一张同步帧。 */
+    private captureVideoPosterFromFrontend;
+    private isThumbnailFrontendDecodeEnabled;
+    /**
+     * 浏览器先解一帧仅作会话展示（DataURL 不落库）。
+     * 正式封面仍由 AMK 接口返回的 HTTP URL 负责持久化。
+     */
+    private previewPosterFromFrontend;
+    /**
+     * 正式封面只走 AMK 抽帧接口；返回可落库的 HTTP URL。
+     * 前端预览由 {@link previewPosterFromFrontend} 并行触发。
+     */
+    private captureVideoPosterFromUrl;
+    /**
+     * 抽帧临时 http 转存；失败回落临时链。
+     * 调用方应先上屏临时链，再后台调用本方法换链。
+     */
+    private persistExtractUrls;
+    /**
+     * 后台转存：临时链已上屏/落盘后，换成长效地址再 PUT + 刷新面板。
+     * 未配置回调、转存失败或结果未变时不二次写盘。
+     */
+    private schedulePersistExtractUrlsAndSwap;
+    /**
+     * 统一入口：初始化 / 新素材入库后，每个素材在本次会话只检查一次抽帧。
+     * - sprite / poster 缺失时创建任务；图片加载失败不再触发重抽
+     * - http 结果：先临时链上屏/PUT；若配置 onPersistExtractUrls 则后台转存换链
+     * - 封面：浏览器可并行解一帧作会话预览（DataURL 不落盘）；正式封面始终走 AMK 接口 URL 落库
+     * - enableThumbnailDecode=true：跳过 sprite 接口，轨道缩略图走前端解码
+     */
+    private ensureMaterialExtractTasks;
+    private ensureMaterialExtractTasksUnchecked;
+    private ensureTrackMaterialExtractTasks;
+    private ensureMaterialExtractTasksInBackground;
+    private createExtractFramesTask;
+    /** 导出结果是资源身份时，先换取浏览器可访问的播放地址。 */
+    private resolveExportOutputUrl;
+    /** 任务产物的 TOS/VOD 身份先换成浏览器可访问的 HTTP URL。 */
+    private signTaskOutputUrls;
+    private startSpritePolling;
+    private startPosterPolling;
+    private buildSpriteFromExtractResult;
+    private extractFirstSnapshotUrl;
+    /** 图片真实加载失败时先换一次过期签名，仍不可用则每类图片最多补抽一次。 */
+    private handleThumbnailError;
+    private resolveMaterialFromThumbnailError;
+    private findMaterialByKey;
+    private applyMaterialToPanel;
+    private enqueueMaterialPatch;
+    private patchMaterialRemote;
+    private flushPendingMaterialPatches;
+    private clearSpriteTimer;
+    private clearSpritePollingTimers;
+    private clearPosterTimer;
+    private clearPosterPollingTimers;
+}
+export declare function createAmkEditor(options: AmkEditorOptions): AmkEditor;

package/dist/amk-modal.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+export interface AmkModalProps {
+    visible: boolean;
+    className: string;
+    width: number;
+    popupContainer: HTMLElement;
+    ariaLabelledBy: string;
+    ariaDescribedBy?: string;
+    onCancel: () => void;
+    children: React.ReactNode;
+}
+/**
+ * AMK 弹窗只复用 VEVEditor 的样式类，避免旧 Modal 运行时依赖 React 19
+ * 已移除的 ReactDOM.findDOMNode。
+ */
+export declare function AmkModal({ visible, className, width, popupContainer, ariaLabelledBy, ariaDescribedBy, onCancel, children, }: AmkModalProps): React.ReactPortal | null;