@volcengine/amk-editor 0.0.5 → 0.0.7-beta.7

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

@@ -0,0 +1,7 @@
+import type { ExportVideoParams } from './types';
+type RecordValue = Record<string, any>;
+export declare function buildExportSubmission(editParam: RecordValue, params: Pick<ExportVideoParams, 'resolution' | 'format' | 'frameRate' | 'codec'>, legacy?: boolean): {
+    toolName: string;
+    params: Record<string, unknown>;
+};
+export {};

package/dist/material-source.d.ts

@@ -0,0 +1,5 @@
+/** 媒体资源身份在入库时确定；url 独立保存 HTTP(S) 播放地址。 */
+export declare function resolveMaterialSource(material: {
+    source?: unknown;
+    source_material_id?: unknown;
+}): string;

package/dist/tos-upload.d.ts

@@ -2,6 +2,8 @@ import type { AmkEditorStorageConfig, AmkEditorUploadSTSCredentials, MaterialIte
 export declare const DEFAULT_TOS_REGION = "cn-beijing";
 export declare const DEFAULT_SIGNED_URL_EXPIRES_SECONDS: number;
 export declare const TOS_SIGNED_URL_REFRESH_AHEAD_MS: number;
+/** 配置隔离的短期凭证缓存；未知有效期仅合并在途请求，不猜测 TTL。 */
+export declare function getCachedTosCredentials(storage: AmkEditorStorageConfig): Promise<AmkEditorUploadSTSCredentials>;
 /** 签名最长 24 小时，但不能超过本次 STS 凭证的剩余有效期。 */
 export declare function resolveSignedUrlExpiresSeconds(credentials: AmkEditorUploadSTSCredentials, now?: number): number;
 /** 解析 TOS V4 签名 URL 的绝对过期时间；非 TOS 签名链返回 null。 */
@@ -41,6 +43,11 @@ export declare function parseTosResourceUrl(value: unknown): {
     bucket: string;
     key: string;
 } | null;
+/** 业务 ID 可独立于存储地址，优先有效 source_material_id，否则使用 source。 */
+export declare function resolveTosMaterialSource(material: {
+    source_material_id?: unknown;
+    source?: unknown;
+}): string | undefined;
 /** 与素材 TOS 上传保持一致，保留配置的产物存储目录。 */
 export declare function resolveTosOutputDestination(destination: string | undefined): string | undefined;
 /** 使用宿主下发的临时 STS 将本地文件直传客户 TOS，并转换为编辑器素材。 */

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { VeVeditorI18nOptions, VeVeditorMaterialItem, VeVeditorOptions, VeVeditorTheme, VeVeditorDecodeOptions } from './public-types';
+import type { VeVeditorI18nOptions, VeVeditorMaterialItem, VeVeditorMaterialOptions, VeVeditorOptions, VeVeditorTheme, VeVeditorDecodeOptions } from './public-types';
 export type Theme = VeVeditorTheme;
 export interface MaterialItem extends VeVeditorMaterialItem {
     /** 业务侧素材主键；上传 / 更新 / 删除必填。 */
@@ -30,7 +30,7 @@ export interface AmkMaterialImportRequestOptions {
 export interface RecommendedExtractStorageFields {
     /** 封面图稳定身份；内置 TOS 链路保存 `tos://bucket/key`。 */
     poster_storage_key?: string;
-    /** 与 sprite.storeurls 等长的稳定身份数组；内置 TOS 链路保存 tos:// 地址。 */
+    /** 与 sprite.storeurls 等长的稳定身份数组；内置链路保存 tos:// 或 vod:// 地址。 */
     sprite_storage_keys?: string[];
 }
 export interface PersistExtractUrlsResult {
@@ -42,8 +42,14 @@ export interface PersistExtractUrlsResult {
      */
     materialPatch?: Partial<MaterialItem>;
 }
-export interface MaterialConfig {
-    emptyIcon?: string;
+export interface MaterialConfig extends VeVeditorMaterialOptions<MaterialItem> {
+    /**
+     * 本地单文件上传流程的并发上限（正整数）；未配置时保持不限并发。
+     * 同一编辑器跨批次共享；覆盖上传、元信息补齐及入库，不含后台抽帧。
+     * 适用于 onUploadFile、内置上传和临时 URL 素材转存，不控制旧 onUploadMaterial 的内部并发。
+     * 此值不是每秒请求数，也不控制单文件分片并发。
+     */
+    uploadConcurrency?: number;
     uploadAccept?: string;
     /** Fires when any material import flow enters or leaves its uploading phase. */
     onUploadStatusChange?: (uploading: boolean) => void;
@@ -60,11 +66,23 @@ export interface MaterialConfig {
      * 返回素材缺少必需元信息时，SDK 同样会在入库前自动探测并补齐。
      */
     onUploadMaterial?: (files: File[]) => Promise<MaterialItem[]> | MaterialItem[];
-    /** 返回素材缺少必需元信息时，SDK 会在入库前按媒体类型自动探测并补齐。 */
-    onUploadUrlMaterial?: (urls: string[]) => Promise<MaterialItem[]> | MaterialItem[];
+    /**
+     * URL 素材上传回调。普通导入可批量传入；服务端素材标记为 MediaKit 临时存储时，
+     * SDK 会跳过播放地址刷新，并按单 URL 调用本回调转存后原位替换 material_id。
+     * 临时转存并发数使用 uploadConcurrency，未配置时为 5。
+     * 临时地址可先抽帧并展示，抽帧字段等待素材替换成功后再写回客户存储身份。
+     * SDK 只扫描初始化已加载的素材和 refreshMaterials() 的结果，不轮询素材列表。
+     * 临时素材转存时，第二参数按 URL 顺序提供原素材，可用于识别无后缀 URL 的 type/name；
+     * 用户手动输入 URL 时不提供第二参数。
+     */
+    onUploadUrlMaterial?: (urls: string[], context?: {
+        readonly materials: readonly MaterialItem[];
+    }) => Promise<MaterialItem[]> | MaterialItem[];
     /**
      * 从业务资产库选择素材。业务方自行实现弹窗、列表查询与勾选，只返回选中数组。
-     * `tos://bucket/key` 条目会由 SDK 用 storage.getUploadSTS 自动签名和补齐元信息。
+     * 同时配置 TOS `storage.media_output_destination` 与 `storage.getUploadSTS` 时，
+     * `tos://bucket/key` 条目会由 SDK 自动签名和补齐元信息；否则使用业务提供的
+     * HTTP(S) 长期地址，缺少地址时交给 `onRefreshPlayInfo` 补齐。
      * 非 TOS 条目缺少必需元信息时，也会使用其 HTTP(S) 地址自动探测并补齐。
      * 返回 `undefined` / `null` / `[]` 视为取消或未选择，不提示失败。
      */
@@ -85,7 +103,7 @@ export interface MaterialConfig {
     /**
      * 抽帧得到的临时 http（约 24h）转存成长效地址。
      * SDK 会先用临时链上屏/落盘，再后台调用本回调换链；失败则保留临时链。
-     * 未配置则只落盘临时链；若带 auth_key 且过期，SDK 会自动重抽。
+     * 未配置则只落盘临时链；签名明确过期且图片加载失败时，SDK 最多刷新一次播放地址，不重抽。
      * 推荐返回 urls + materialPatch，把刷新 URL 所需的 storage key 或其他业务字段写入素材。
      * SDK 不限制其他 materialPatch 字段；poster_storage_key / sprite_storage_keys
      * 中的 `tos://` 地址会作为后续自动重签依据。
@@ -117,6 +135,8 @@ export interface AmkEditorHeaderConfig {
     onTitleUpdateSuccess?: (change: AmkEditorHeaderTitleUpdateSuccess) => void;
 }
 export interface AmkEditorExportConfig {
+    /** 临时兼容旧 vibe-editing-common 导出；默认 false，后续可移除。 */
+    legacy?: boolean;
     /**
      * 导出弹窗是否展示「视频画质增强」。
      * 默认 false（不展示）；设为 true 后用户可在弹窗内开关增强。
@@ -134,30 +154,78 @@ export interface AmkEditorUploadSTSCredentials {
     /** 凭证过期时间，支持 ISO 8601、秒时间戳或毫秒时间戳；用于限制签名 URL 有效期。 */
     expiration?: string | number;
 }
+/** 点播 Web 上传及 OpenAPI 发布/播放查询共用的短期 STS 凭证。 */
+export interface AmkEditorVodUploadToken {
+    AccessKeyId: string;
+    SecretAccessKey: string;
+    SessionToken: string;
+    ExpiredTime: string;
+    CurrentTime: string;
+}
+/** 按 Vid 解析的可播放信息。 */
+export interface AmkEditorVodPlayInfo {
+    url: string;
+    poster?: string;
+    duration?: number;
+    width?: number;
+    height?: number;
+}
+/** SDK 内部点播上传与播放地址解析配置，由 storage 目标和临时凭证回调生成。 */
+export interface AmkEditorVodUploadConfig {
+    /** 应用云平台分配的 appId，仅用于上传质量监控。 */
+    appId: number;
+    /** 火山引擎点播空间名。 */
+    spaceName: string;
+    /** 当前用户稳定标识，用于上传任务隔离与断点续传。 */
+    userId: string;
+    /** 由宿主服务端签发短期点播 STS。 */
+    getUploadToken: () => AmkEditorVodUploadToken | Promise<AmkEditorVodUploadToken>;
+    /**
+     * 由宿主服务端发布媒资（如需要）并按 Vid 返回 HTTP(S) 播放地址。
+     * SDK 会用该回调处理新上传素材、已入库 VOD 素材和 VOD 导出结果的播放地址。
+     */
+    getPlayInfo: (vid: string, kind?: 'vid') => AmkEditorVodPlayInfo | Promise<AmkEditorVodPlayInfo>;
+}
 /**
  * 产物 / 主动上传的存储目标。
- * `media_output_destination` 用于 TOS 直传的 Bucket 定位，并默认写入会产生媒体产物的 AMK tools 请求体。
+ * `media_output_destination` 用于 SDK 内置上传的目标定位。火山版会默认将其写入会产生媒体产物的
+ * AMK tools 请求体以启用产物转存；BytePlus AMK 暂不支持产物转存，因此 BytePlus 构建不会把
+ * 该字段发送给 AMK 接口；该配置仍用于内置 BytePlus VOD 上传与播放地址解析，
+ * 并作为后续 BytePlus TOS 接入入口。
  * @see https://docs.volcengine.com/docs/6448/2386113
  */
 export interface AmkEditorStorageConfig {
     /**
      * 处理产物存储目标。支持 `vod://<空间名>` 或 `tos://<桶名>/<可选子目录>`。
      * TOS 本地上传及自动封面/雪碧图产物使用配置的目录，不自动追加项目 ID。
+     * 必须与 `getUploadSTS` 同时配置；只配置其中任意一个都会在初始化时报错。
      * 配置后任务结果中的 url 为对应资源地址，而不是临时下载链；当返回
-     * `tos://bucket/key` 且同时配置 getUploadSTS 时，SDK 会自动签成 HTTP 播放地址。
+     * `tos://bucket/key` 或 `vod://space/Vid` 时，SDK 会分别通过 TOS 签名或
+     * VOD 播放信息接口换取 HTTP(S) 预览地址。
      */
     media_output_destination?: string;
     /**
-     * 配置后，本地上传会优先使用 TOS Browser SDK 直传
-     * `media_output_destination` 指定的 TOS Bucket；未配置时沿用
-     * `material.onUploadFile` / `material.onUploadMaterial`。业务服务端应返回最小权限、短有效期凭证，
+     * TOS 目标返回 TOS STS，VOD 目标返回含上传、发布和播放查询权限的短期 STS；
+     * 必须与 media_output_destination 同时配置；只配置其中任意一个都会在初始化时报错。
+     * SDK 按目标协议选择内置上传与播放地址刷新链路。
+     * TOS 凭证按 expiration 缓存至过期前 5 分钟，并合并并发获取；
+     * expiration 缺失或无效时只合并在途请求，不缓存已完成的结果。
+     * VOD 同样按 ExpiredTime 缓存至过期前 5 分钟并合并并发获取，不缓存播放查询结果。
+     * 本地上传优先使用业务配置的 `material.onUploadFile` / `material.onUploadMaterial`；
+     * 两者均未配置时，SDK 才按目标协议使用内置 VOD / TOS 上传。
+     * 业务服务端应返回最小权限、短有效期凭证，
      * 浏览器端不得保存客户长期 AK/SK。
+     * 未同时配置 TOS `media_output_destination` 时，SDK 不会仅凭素材
+     * `source_material_id` 或兜底 `source` 的 `tos://` 前缀接管播放地址；业务长期 URL 会原样使用，
+     * 缺少 URL 时可由 `material.onRefreshPlayInfo` 补齐。
      */
-    getUploadSTS?: () => AmkEditorUploadSTSCredentials | Promise<AmkEditorUploadSTSCredentials>;
+    getUploadSTS?: () => AmkEditorUploadSTSCredentials | AmkEditorVodUploadToken | Promise<AmkEditorUploadSTSCredentials | AmkEditorVodUploadToken>;
 }
 export interface ExportVideoParams {
     videoName: string;
     qualityEnhancement: boolean;
+    /** 画质增强完成后是否同时保留未增强的原始导出成片。 */
+    keepOriginal?: boolean;
     enhancementVersion: 'standard' | 'professional' | 'large-model';
     resolution: 'original' | '720p' | '1080p' | '2k' | '4k';
     frameRate: number;
@@ -228,7 +296,15 @@ export interface VeVeditorInstance {
     [key: string]: unknown;
 }
 /** 内置 get/update 工程快照（不导出给宿主配置） */
+/** 工程接口返回的元信息；保留服务端扩展字段，供宿主及后续 UI 使用。 */
+export type AmkProjectInfo = {
+    project_id: string;
+    name: string;
+    description?: string;
+    [key: string]: unknown;
+};
 export type AmkProjectSnapshot = {
+    projectInfo?: AmkProjectInfo;
     projectName?: string;
     materials?: MaterialItem[];
     editParam?: Record<string, unknown>;
@@ -247,9 +323,17 @@ export type AmkEditorDecodeOptions = VeVeditorDecodeOptions;
 /** 每次 AMK 请求前动态获取、原样透传给 endpoint 的业务请求头。 */
 export type AmkEditorGetHeaders = () => Readonly<Record<string, string>> | undefined | Promise<Readonly<Record<string, string>> | undefined>;
 export interface AmkEditorOptions extends AmkInheritedVeVeditorOptions {
+    toolbar?: AmkInheritedVeVeditorOptions['toolbar'] & {
+        /** 字幕识别后端：火山默认 asr-subtitles，BytePlus 默认 maas。 */
+        asr?: {
+            provider?: import('./asr-provider').AmkAsrProvider;
+        };
+    };
     projectId: string;
     /** AMK Editing API 的业务代理地址。 */
     endpoint: string;
+    /** 接入方标识，用于埋点来源和问题归因；缺省时使用 sdk。 */
+    source?: string;
     /** 每次请求前调用；返回值不解析、不改写，仅透传给 endpoint。 */
     getHeaders?: AmkEditorGetHeaders;
     header?: AmkEditorHeaderConfig;

package/dist/upload-queue.d.ts

@@ -0,0 +1,6 @@
+/** 文件级 FIFO 队列；一个名额覆盖上传、元信息补齐和入库。 */
+export declare function createUploadQueue(concurrency?: number): {
+    run<T>(task: () => Promise<T> | T): Promise<T>;
+    destroy(): void;
+};
+export type UploadQueue = ReturnType<typeof createUploadQueue>;

package/dist/utils/signed-media-url-expiration.d.ts

@@ -0,0 +1,2 @@
+/** 只根据签名参数判断明确过期；图片 onerror 本身无法可靠区分 403/404/CORS。 */
+export declare function isSignedMediaUrlExpired(urlValue: unknown, now?: number): boolean;