@volcengine/amk-editor 0.0.1 → 0.0.2-beta.1

package/dist/local-upload-modal.d.ts

@@ -6,7 +6,7 @@ export interface CreateLocalUploadModalOptions {
     onConfirm: (files: File[]) => void;
 }
 export interface LocalUploadModalController {
-    open: (files: File[]) => void;
+    open: (files?: File[]) => void;
     close: () => void;
     destroy: () => void;
 }

package/dist/public-types.d.ts

@@ -65,6 +65,10 @@ export interface VeVeditorMaterialOptions<TMaterialItem = VeVeditorMaterialItem>
 }
 export interface VeVeditorOptions<TMaterialOptions = VeVeditorMaterialOptions, TI18nOptions = VeVeditorI18nOptions, TResourceOptions extends VeVeditorResourceOptionTypes = VeVeditorResourceOptionTypes> {
     container: HTMLElement;
+    /** 埋点来源标识，用于区分业务接入方。 */
+    source?: string;
+    /** 埋点账号 ID；上报时写入事件 params.AccountID（对齐 master）。 */
+    accountId?: string;
     theme?: VeVeditorTheme;
     material?: TMaterialOptions;
     i18n?: TI18nOptions;
@@ -101,6 +105,7 @@ export interface VeVeditorOptions<TMaterialOptions = VeVeditorMaterialOptions, T
         item?: unknown;
     }) => void;
     onNodePreviewError?: (type: 'video' | 'audio', node: unknown) => void;
+    onPreviewNodeRefresh?: (type: 'video' | 'audio', node: unknown) => void | Promise<void>;
     onBeforeUndo?: (payload: unknown) => boolean | void;
     onBeforeRedo?: (payload: unknown) => boolean | void;
     onBeforeTimestampMount?: (params: Record<string, unknown>) => boolean | Promise<boolean>;

package/dist/tos-upload.d.ts

@@ -0,0 +1,46 @@
+import type { AmkEditorStorageConfig, AmkEditorUploadSTSCredentials, MaterialItem } from './types';
+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;
+/** 签名最长 24 小时，但不能超过本次 STS 凭证的剩余有效期。 */
+export declare function resolveSignedUrlExpiresSeconds(credentials: AmkEditorUploadSTSCredentials, now?: number): number;
+/** 解析 TOS V4 签名 URL 的绝对过期时间；非 TOS 签名链返回 null。 */
+export declare function resolveTosSignedUrlExpiresAt(urlValue: unknown): number | null;
+interface TosClientLike {
+    putObject(input: {
+        bucket: string;
+        key: string;
+        body: File;
+        contentType?: string;
+    }): Promise<unknown>;
+    getPreSignedUrl(input: {
+        bucket: string;
+        key: string;
+        method?: 'GET' | 'PUT';
+        expires?: number;
+    }): string;
+}
+interface UploadFilesToTosOptions {
+    files: File[];
+    projectId: string;
+    storage: AmkEditorStorageConfig;
+    createClient?: (credentials: AmkEditorUploadSTSCredentials, region: string) => TosClientLike;
+}
+interface RefreshTosMaterialUrlsOptions {
+    materials: MaterialItem[];
+    storage: AmkEditorStorageConfig;
+    createClient?: UploadFilesToTosOptions['createClient'];
+}
+/** 使用宿主下发的临时 STS 将本地文件直传客户 TOS，并转换为编辑器素材。 */
+export declare function uploadFilesToTos(options: UploadFilesToTosOptions): Promise<MaterialItem[]>;
+/** 为已持久化的私有 TOS 素材重新生成播放签名，供初始化和按需刷新使用。 */
+export declare function refreshTosMaterialUrls(options: RefreshTosMaterialUrlsOptions): Promise<Array<Partial<MaterialItem> & {
+    material_id: string;
+}>>;
+/** 为资产库导入的 TOS 素材签发播放 URL；稳定身份仍保留在 source_material_id。 */
+export declare function signTosImportedMaterialUrls(options: {
+    materials: MaterialItem[];
+    storage: AmkEditorStorageConfig;
+    createClient?: UploadFilesToTosOptions['createClient'];
+}): Promise<MaterialItem[]>;
+export {};

package/dist/types.d.ts

@@ -5,6 +5,23 @@ export interface MaterialItem extends VeVeditorMaterialItem {
     source_material_id: string;
     /** Editing API 生成的服务端 id；业务方不必传，传了也不会入库。 */
     material_id?: string;
+    /** poster 抽帧任务 ID；任务完成或不再使用时显式写回 null。 */
+    poster_task_id?: string | null;
+    /** sprite 抽帧任务 ID；任务完成或不再使用时显式写回 null。 */
+    sprite_task_id?: string | null;
+}
+export type SystemMaterialItem = Omit<Partial<MaterialItem>, 'source_material_id' | 'source'> & {
+    source_material_id: string;
+    source?: string;
+    type: NonNullable<MaterialItem['type']>;
+    name?: string;
+};
+/** 可由外部工具栏复用的素材导入入口。 */
+export type AmkMaterialImportType = 'local' | 'url' | 'system';
+/** Optional callbacks scoped to one externally triggered material import. */
+export interface AmkMaterialImportRequestOptions {
+    /** Called with persisted materials only for this request. */
+    onMaterialsImported?: (materials: MaterialItem[]) => void | Promise<void>;
 }
 /**
  * 抽帧产物存储 key 的推荐命名，仅用于提供接入提示，不属于强制素材 Schema。
@@ -30,7 +47,17 @@ export interface MaterialConfig {
     uploadAccept?: string;
     onUploadMaterial?: (files: File[]) => Promise<MaterialItem[]> | MaterialItem[];
     onUploadUrlMaterial?: (urls: string[]) => Promise<MaterialItem[]> | MaterialItem[];
-    onUploadFromSystem?: () => Promise<MaterialItem[]> | MaterialItem[];
+    /**
+     * 从业务资产库选择素材。业务方自行实现弹窗、列表查询与勾选，只返回选中数组。
+     * `tos://bucket/key` 条目会由 SDK 用 storage.getUploadSTS 自动签名和补齐元信息。
+     * 返回 `undefined` / `null` / `[]` 视为取消或未选择，不提示失败。
+     */
+    onUploadFromSystem?: () => Promise<SystemMaterialItem[] | undefined | null> | SystemMaterialItem[] | undefined | null;
+    /**
+     * 素材成功入库后回调（已合并 Editing API 返回的 `material_id`）。
+     * 本地 / URL / 资产库三条导入链路都会走到这里；失败或用户取消不会触发。
+     */
+    onMaterialsImported?: (materials: MaterialItem[]) => void | Promise<void>;
     /**
      * 刷新播放信息。未配置时用素材库已有字段；
      * 配置后：入参为待刷新素材列表（按服务端 material_id 区分，支持批量），
@@ -52,10 +79,22 @@ export interface MaterialConfig {
         material: MaterialItem;
     }) => Promise<PersistExtractUrlsResult | string[]> | PersistExtractUrlsResult | string[];
 }
+export interface AmkEditorHeaderTitleUpdateSuccess {
+    readonly projectId: string;
+    /** Project title persisted successfully by the Editing API. */
+    readonly title: string;
+}
 export interface AmkEditorHeaderConfig {
     show?: boolean;
+    /**
+     * When set, the header is rendered into this element instead of inside the
+     * editor root. Use this to place a full-width header above a host split layout.
+     */
+    mount?: HTMLElement;
     onBack?: () => void;
     onClose?: () => void;
+    /** Fired only after the project title is persisted successfully. */
+    onTitleUpdateSuccess?: (change: AmkEditorHeaderTitleUpdateSuccess) => void;
 }
 export interface AmkEditorExportConfig {
     /**
@@ -64,6 +103,34 @@ export interface AmkEditorExportConfig {
      */
     qualityEnhancement?: boolean;
 }
+/** 浏览器直传 TOS 使用的临时凭证；字段可直接用于初始化 TOS Browser SDK。 */
+export interface AmkEditorUploadSTSCredentials {
+    accessKeyId: string;
+    accessKeySecret: string;
+    /** 临时凭证必填；使用长期 AK/SK 做本地联调时可省略。 */
+    stsToken?: string;
+    /** 凭证过期时间，支持 ISO 8601、秒时间戳或毫秒时间戳；用于限制签名 URL 有效期。 */
+    expiration?: string | number;
+}
+/**
+ * 产物 / 主动上传的存储目标。
+ * `media_output_destination` 用于 TOS 直传的 Bucket 定位；当前不会自动写入 AMK tools 请求体。
+ * @see https://docs.volcengine.com/docs/6448/2386113
+ */
+export interface AmkEditorStorageConfig {
+    /**
+     * 处理产物存储目标。支持 `vod://<空间名>` 或 `tos://<桶名>`。
+     * 配置后任务结果中的 url 为对应资源地址，而不是临时下载链。
+     */
+    media_output_destination?: string;
+    /**
+     * 配置后，本地上传会优先使用 TOS Browser SDK 直传
+     * `media_output_destination` 指定的 TOS Bucket；未配置时沿用
+     * `material.onUploadMaterial`。业务服务端应返回最小权限、短有效期凭证，
+     * 浏览器端不得保存客户长期 AK/SK。
+     */
+    getUploadSTS?: () => AmkEditorUploadSTSCredentials | Promise<AmkEditorUploadSTSCredentials>;
+}
 export interface ExportVideoParams {
     videoName: string;
     qualityEnhancement: boolean;
@@ -73,12 +140,24 @@ export interface ExportVideoParams {
     format: 'mp4' | 'mp3';
     codec: 'h264' | 'h265' | 'vp9' | 'mp3';
 }
+/** Result of {@link AmkEditor.requestExport} for Agent/frontend-tool callers. */
+export type AmkExportRequestResult = {
+    status: 'success';
+    taskId: string;
+} | {
+    status: 'cancel';
+} | {
+    status: 'failed';
+    error: string;
+};
 export interface VeVeditorInstance {
     destroy: () => void;
     on?: (eventName: string, handler: (...args: any[]) => void) => void;
     off?: (eventName: string, handler: (...args: any[]) => void) => void;
     getTrack?: () => any[];
-    setTrack?: (track: any[]) => Promise<void>;
+    setTrack?: (track: any[], options?: {
+        recordHistory?: boolean;
+    }) => Promise<void>;
     setTrackElementMarker?: (elementId: string, marker: {
         key?: string;
         content: string;
@@ -124,15 +203,22 @@ type AmkResourceOptionTypes = {
     filter: boolean;
     effect: boolean;
 };
-type AmkInheritedVeVeditorOptions = Omit<VeVeditorOptions<MaterialConfig, VeVeditorI18nOptions, AmkResourceOptionTypes>, 'initialData' | 'recording' | 'onSketchItemsChange' | 'onNodePreviewError' | 'onBeforeUndo' | 'onBeforeRedo' | 'onBeforeTimestampMount' | 'onBeforeKeyframeMount' | 'onTrackChanged' | 'onRecordingUpload' | 'decode'>;
+type AmkInheritedVeVeditorOptions = Omit<VeVeditorOptions<MaterialConfig, VeVeditorI18nOptions, AmkResourceOptionTypes>, 'initialData' | 'recording' | 'onSketchItemsChange' | 'onNodePreviewError' | 'onPreviewNodeRefresh' | 'onBeforeUndo' | 'onBeforeRedo' | 'onBeforeTimestampMount' | 'onBeforeKeyframeMount' | 'onTrackChanged' | 'onRecordingUpload' | 'decode'>;
 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 {
     projectId: string;
+    /** AMK Editing API 的业务代理地址。 */
     endpoint: string;
+    /** 每次请求前调用；返回值不解析、不改写，仅透传给 endpoint。 */
+    getHeaders?: AmkEditorGetHeaders;
     header?: AmkEditorHeaderConfig;
     export?: AmkEditorExportConfig;
     getLicenseUrl?: string | (() => string | Promise<string>);
     decode?: AmkEditorDecodeOptions;
+    /** 产物 / 主动上传的存储目标，包括 TOS / VOD。 */
+    storage?: AmkEditorStorageConfig;
 }
 export interface AmkEditorInternalConfig {
     projectId: string;

package/dist/utils/material-extract.d.ts

@@ -6,7 +6,7 @@ export type SpriteState = {
 /**
  * 素材 `sprite`：
  * - object `{ storeurls, capturenum }`：已完成；链接是否失效由实际网络请求判断
- * - string：抽帧 taskId（进行中）
+ * - 进行中任务放在 `sprite_task_id`；旧 `sprite` 字符串仅用于一次性迁移
  * - 缺省：需要新建任务
  */
 export declare function resolveSpriteState(material: MaterialItem): SpriteState;
@@ -16,18 +16,21 @@ export declare function isPersistablePosterUrl(value: unknown): boolean;
 export declare function isRuntimeOnlyPosterUrl(value: unknown): boolean;
 /** http poster；有效性由实际网络请求判断 */
 export declare function isPosterAssetReady(material: MaterialItem): boolean;
+/** poster 任务只能存在独立字段；旧 poster 非 http/dataURL 字符串仅用于一次性迁移。 */
+export declare function resolvePosterTaskId(material: MaterialItem): string | undefined;
 export declare function isExtractableVideoMaterial(material: MaterialItem): boolean;
 export declare function resolveMaterialMediaUrl(material: MaterialItem): string;
 export type MaterialExtractActions = {
     url: string;
-    /** 需要新建 sprite 抽帧任务，完成后 PUT sprite=taskId */
+    /** 需要新建 sprite 抽帧任务，任务 ID 写入 sprite_task_id */
     createSpriteTask: boolean;
-    /** 已有 taskId，继续轮询，完成后 PUT sprite 结果 */
+    /** 已有 taskId，从 sprite_task_id 继续轮询 */
     resumeSpriteTaskId?: string;
+    /** 已有 poster 任务，从 poster_task_id 继续轮询。 */
+    resumePosterTaskId?: string;
     /**
-     * 需要抓封面：
-     * - 接口模式：缺有效 http poster（含 auth_key 过期）时抓取，http 结果 PUT 落盘
-     * - 前端解码模式：无运行时缓存时也可抓取（dataURL 不落盘）
+     * 需要抓封面：缺有效 http poster，或需恢复进行中的 poster_task_id。
+     * 前端 DataURL 仅作会话预览，不单独驱动 capturePoster。
      */
     capturePoster: boolean;
 };