@volcengine/amk-editor 0.0.6 → 0.0.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/refresh-play-info.d.ts

@@ -4,7 +4,7 @@ import type { MaterialItem } from './types';
  * 优先按 SDK 内部 material_id 匹配，随后按业务 source_material_id 兜底；
  * 两个标识都没有的补丁才按数组下标兜底。
  * 可更新 url / poster / sprite / source_material_id 等。
- * material_id 为 SDK 内部字段，补丁中的同名字段会被忽略。
+ * material_id 与抽帧任务 ID 由 SDK 维护，补丁中的同名字段会被忽略。
  */
 export type MaterialPlayInfoPatch = Partial<MaterialItem> & {
     material_id?: 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,20 +30,27 @@ 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 {
     /** 转存后的长期可访问 URL，须与回调入参 urls 等长。 */
     urls: string[];
     /**
-     * 随转存结果写回素材的业务字段，SDK 原样合并并持久化。
-     * 字段名和结构完全由业务决定；SDK 不读取推荐字段，也不限制自定义嵌套结构。
+     * 随转存结果写回素材的业务字段；material_id、poster_task_id、
+     * sprite_task_id 由 SDK 维护，即使传入 null 也会被忽略。
+     * 其他字段名和结构由业务决定，SDK 不限制自定义嵌套结构。
      */
     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 +67,20 @@ export interface MaterialConfig {
      * 返回素材缺少必需元信息时，SDK 同样会在入库前自动探测并补齐。
      */
     onUploadMaterial?: (files: File[]) => Promise<MaterialItem[]> | MaterialItem[];
-    /** 返回素材缺少必需元信息时，SDK 会在入库前按媒体类型自动探测并补齐。 */
+    /**
+     * URL 素材上传回调。普通导入可批量传入；服务端素材标记为 MediaKit 临时存储时，
+     * SDK 会跳过播放地址刷新，并按单 URL 调用本回调转存后原位替换 material_id。
+     * 临时转存并发数使用 uploadConcurrency，未配置时为 5。
+     * 临时地址可先抽帧并展示，抽帧字段等待素材替换成功后再写回客户存储身份。
+     * SDK 只扫描初始化已加载的素材和 refreshMaterials() 的结果，不轮询素材列表。
+     * 回调只接收 URL 数组；临时素材的类型、名称等元信息由 SDK 从素材库原记录保留。
+     */
     onUploadUrlMaterial?: (urls: string[]) => 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` / `[]` 视为取消或未选择，不提示失败。
      */
@@ -79,16 +95,19 @@ export interface MaterialConfig {
      * 配置后：入参为待刷新素材列表，支持批量；返回补丁优先按 material_id 匹配，
      * source_material_id 次之，两者都未返回时才按数组顺序兜底，
      * 返回单条或数组补丁覆盖原素材的播放字段（url / poster / sprite / source_material_id 等）。
-     * 补丁不得改写 material_id（服务端字段，业务传了也不入库）。
+     * 补丁不得改写 material_id（服务端字段）及 poster_task_id / sprite_task_id
+     *（SDK 抽帧任务状态）；即使业务返回 null，也保留 SDK 当前值。
      */
     onRefreshPlayInfo?: (materials: MaterialItem[]) => Partial<MaterialItem> | Partial<MaterialItem>[] | Promise<Partial<MaterialItem> | Partial<MaterialItem>[]>;
     /**
      * 抽帧得到的临时 http（约 24h）转存成长效地址。
      * SDK 会先用临时链上屏/落盘，再后台调用本回调换链；失败则保留临时链。
-     * 未配置则只落盘临时链；若带 auth_key 且过期，SDK 会自动重抽。
+     * 未配置时仍会落盘临时 HTTP 链；若同时没有有效的 storage 配置，初始化会提示 warning，不阻止启动。
+     * 已存链接下次打开工程时直接复用；加载失败且明确过期时先尝试换链，未恢复则每种素材本会话最多重抽一次。
      * 推荐返回 urls + materialPatch，把刷新 URL 所需的 storage key 或其他业务字段写入素材。
-     * SDK 不限制其他 materialPatch 字段；poster_storage_key / sprite_storage_keys
-     * 中的 `tos://` 地址会作为后续自动重签依据。
+     * materialPatch 可更新其他业务字段，但 material_id、poster_task_id、
+     * sprite_task_id 由 SDK 维护，回调返回的值（包括 null）会被忽略。
+     * poster_storage_key / sprite_storage_keys 中的 `tos://` 地址会作为后续自动重签依据。
      * 兼容只返回 string[]，但该形式无法附带业务字段。
      */
     onPersistExtractUrls?: (params: {
@@ -117,6 +136,8 @@ export interface AmkEditorHeaderConfig {
     onTitleUpdateSuccess?: (change: AmkEditorHeaderTitleUpdateSuccess) => void;
 }
 export interface AmkEditorExportConfig {
+    /** 临时兼容旧 vibe-editing-common 导出；默认 false，后续可移除。 */
+    legacy?: boolean;
     /**
      * 导出弹窗是否展示「视频画质增强」。
      * 默认 false（不展示）；设为 true 后用户可在弹窗内开关增强。
@@ -134,26 +155,76 @@ 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;
+    /** 点播媒资的实际类型；纯音频 MP4 产物也应返回 audio。 */
+    mediaType?: 'video' | 'audio';
+    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 分钟并合并并发获取，不缓存播放查询结果。
+     * 内置 VOD 通过 GetPlayInfo 请求不超过 STS 剩余时长和 24 小时的播放 URL；
+     * 对带 auth_key 到期时间的 URL 在到期前 5 分钟自动刷新，届时按需重新获取 STS。
+     * 本地上传优先使用业务配置的 `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;
@@ -230,7 +301,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>;
@@ -249,9 +328,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;