@volcengine/amk-editor 0.0.5-beta.1 → 0.0.5

package/dist/public-types.d.ts

@@ -88,6 +88,10 @@ export interface VeVeditorOptions<TMaterialOptions = VeVeditorMaterialOptions, T
     /** 埋点账号 ID；上报时写入事件 params.AccountID（对齐 master）。 */
     accountId?: string;
     theme?: VeVeditorTheme;
+    /** 项目加载页配置；默认展示 SDK 内置 loading，设为 false 后由宿主自行渲染。 */
+    loading?: {
+        show?: boolean;
+    };
     material?: TMaterialOptions;
     i18n?: TI18nOptions;
     decode?: VeVeditorDecodeOptions;

package/dist/refresh-play-info.d.ts

@@ -15,5 +15,20 @@ export declare function resolveMaterialId(material: Pick<MaterialItem, 'material
 /** 业务侧 / Editing API 主键：source_material_id */
 export declare function resolveSourceMaterialId(material: MaterialItem | MaterialPlayInfoPatch | Record<string, unknown>): string;
 export declare function mergePlayInfoOverrides(materials: MaterialItem[], overrides: MaterialPlayInfoPatch | MaterialPlayInfoPatch[]): MaterialItem[];
+/**
+ * 将异步播放信息刷新结果变基到最新素材列表。
+ * 刷新期间新写入的 sprite/poster 等字段会被保留；只有相对刷新前快照
+ * 确实发生变化的字段才会覆盖最新值，保证后完成的刷新不会回滚并发更新。
+ */
+export declare function mergeRefreshedPlayInfoIntoLatest(latestMaterials: MaterialItem[], baseMaterials: MaterialItem[], refreshedTargets: MaterialPlayInfoPatch | MaterialPlayInfoPatch[]): MaterialItem[];
 /** 从当前素材库按 material_id 选出待刷新列表；未传则全量有 material_id 的素材。 */
 export declare function pickMaterialsForRefresh(materials: MaterialItem[], materialIdOrIds?: string | string[]): MaterialItem[];
+/**
+ * 初始化刷新分组：轨道实际引用的素材进入首屏关键路径，其余素材留到
+ * 编辑器挂载后刷新。两个分组都保持素材库原有顺序，且忽略无 material_id
+ * 的条目（它们本身无法参与播放信息刷新）。
+ */
+export declare function partitionMaterialsByTrack(materials: MaterialItem[], track: unknown): {
+    trackMaterials: MaterialItem[];
+    remainingMaterials: MaterialItem[];
+};

package/dist/remote-edit-param-schema.d.ts

@@ -0,0 +1,29 @@
+export declare const REMOTE_MEDIA_SPEED_MIN = 0.1;
+export declare const REMOTE_MEDIA_SPEED_MAX = 4;
+export declare const REMOTE_MEDIA_SPEED_DEFAULT = 1;
+export declare const REMOTE_MEDIA_VOLUME_MIN = 0;
+export declare const REMOTE_MEDIA_VOLUME_MAX = 4;
+export declare const REMOTE_TRANSFORM_ALPHA_MIN = 0;
+export declare const REMOTE_TRANSFORM_ALPHA_MAX = 1;
+export declare const REMOTE_COLOR_ADJUSTMENT_MIN = 0;
+export declare const REMOTE_COLOR_ADJUSTMENT_MAX = 1;
+export declare const REMOTE_MEDIA_FADE_MIN_MS = 0;
+export declare const REMOTE_MEDIA_FADE_MAX_MS = 2000;
+export type RemoteEditParamSchemaIssue = {
+    path: string;
+    rule: 'media_speed' | 'media_volume' | 'transform_alpha' | 'color_adjustment' | 'media_fade';
+    reason: 'invalid_number' | 'coerced_number' | 'below_minimum' | 'above_maximum';
+    received: unknown;
+    normalized: number;
+};
+export type RemoteEditParamSchemaResult = {
+    value: Record<string, unknown>;
+    issues: RemoteEditParamSchemaIssue[];
+};
+/**
+ * 远端 editor document 进入 SDK 前的统一 schema 边界。
+ *
+ * 规则采用兼容式清洗：保留未知字段，只修正已声明且会影响 SDK 稳定性的字段。
+ * 新规则应加入 REMOTE_EDIT_PARAM_SCHEMA_RULES，禁止散落到本地编辑/保存链路。
+ */
+export declare function parseRemoteEditParam(input: unknown): RemoteEditParamSchemaResult;

package/dist/tos-upload.d.ts

@@ -25,7 +25,12 @@ interface UploadFilesToTosOptions {
     projectId: string;
     storage: AmkEditorStorageConfig;
     createClient?: (credentials: AmkEditorUploadSTSCredentials, region: string) => TosClientLike;
+    /** 单个文件完成 TOS 上传后回调；批量 Promise 会等待该文件的回调完成。 */
+    onFileUploaded?: (material: MaterialItem, index: number) => void | Promise<void>;
 }
+type UploadFileToTosOptions = Omit<UploadFilesToTosOptions, 'files' | 'onFileUploaded'> & {
+    file: File;
+};
 interface RefreshTosMaterialUrlsOptions {
     materials: MaterialItem[];
     storage: AmkEditorStorageConfig;
@@ -36,8 +41,15 @@ export declare function parseTosResourceUrl(value: unknown): {
     bucket: string;
     key: string;
 } | null;
+/** 与素材 TOS 上传保持一致，保留配置的产物存储目录。 */
+export declare function resolveTosOutputDestination(destination: string | undefined): string | undefined;
 /** 使用宿主下发的临时 STS 将本地文件直传客户 TOS，并转换为编辑器素材。 */
 export declare function uploadFilesToTos(options: UploadFilesToTosOptions): Promise<MaterialItem[]>;
+/**
+ * 内置 TOS 的单文件上传实现。本地多选时仍由上层 SDK 调度，
+ * 使 TOS 和业务自定义 onUploadFile 共用同一条逐项回写链路。
+ */
+export declare function uploadFileToTos(options: UploadFileToTosOptions): Promise<MaterialItem>;
 /** 为已持久化的私有 TOS 素材重新生成播放签名，供初始化和按需刷新使用。 */
 export declare function refreshTosMaterialUrls(options: RefreshTosMaterialUrlsOptions): Promise<Array<Partial<MaterialItem> & {
     material_id: string;

package/dist/types.d.ts

@@ -45,11 +45,27 @@ export interface PersistExtractUrlsResult {
 export interface MaterialConfig {
     emptyIcon?: string;
     uploadAccept?: string;
+    /** Fires when any material import flow enters or leaves its uploading phase. */
+    onUploadStatusChange?: (uploading: boolean) => void;
+    /**
+     * 上传单个本地文件并返回一条待入库素材。
+     * 多文件选择时由 SDK 并发调用；每个文件完成后会立即入库并替换对应占位卡。
+     * 单项失败不会回滚已成功的其他文件。
+     * 视频缺 duration / width / height、音频缺 duration、图片缺 width / height 时，
+     * SDK 会在入库前使用返回素材中的 HTTP(S) 地址自动探测并补齐。
+     */
+    onUploadFile?: (file: File) => Promise<MaterialItem> | MaterialItem;
+    /**
+     * @deprecated 请使用 onUploadFile。旧回调仍可用，但只能在整批返回后统一入库。
+     * 返回素材缺少必需元信息时，SDK 同样会在入库前自动探测并补齐。
+     */
     onUploadMaterial?: (files: File[]) => Promise<MaterialItem[]> | MaterialItem[];
+    /** 返回素材缺少必需元信息时，SDK 会在入库前按媒体类型自动探测并补齐。 */
     onUploadUrlMaterial?: (urls: string[]) => Promise<MaterialItem[]> | MaterialItem[];
     /**
      * 从业务资产库选择素材。业务方自行实现弹窗、列表查询与勾选，只返回选中数组。
      * `tos://bucket/key` 条目会由 SDK 用 storage.getUploadSTS 自动签名和补齐元信息。
+     * 非 TOS 条目缺少必需元信息时，也会使用其 HTTP(S) 地址自动探测并补齐。
      * 返回 `undefined` / `null` / `[]` 视为取消或未选择，不提示失败。
      */
     onUploadFromSystem?: () => Promise<SystemMaterialItem[] | undefined | null> | SystemMaterialItem[] | undefined | null;
@@ -106,6 +122,8 @@ export interface AmkEditorExportConfig {
      * 默认 false（不展示）；设为 true 后用户可在弹窗内开关增强。
      */
     qualityEnhancement?: boolean;
+    /** 每次导出任务成功创建后触发。 */
+    onTaskCreated?: (event: AmkExportTaskCreatedEvent) => void | Promise<void>;
 }
 /** 浏览器直传 TOS 使用的临时凭证；字段可直接用于初始化 TOS Browser SDK。 */
 export interface AmkEditorUploadSTSCredentials {
@@ -124,6 +142,7 @@ export interface AmkEditorUploadSTSCredentials {
 export interface AmkEditorStorageConfig {
     /**
      * 处理产物存储目标。支持 `vod://<空间名>` 或 `tos://<桶名>/<可选子目录>`。
+     * TOS 本地上传及自动封面/雪碧图产物使用配置的目录，不自动追加项目 ID。
      * 配置后任务结果中的 url 为对应资源地址，而不是临时下载链；当返回
      * `tos://bucket/key` 且同时配置 getUploadSTS 时，SDK 会自动签成 HTTP 播放地址。
      */
@@ -131,7 +150,7 @@ export interface AmkEditorStorageConfig {
     /**
      * 配置后，本地上传会优先使用 TOS Browser SDK 直传
      * `media_output_destination` 指定的 TOS Bucket；未配置时沿用
-     * `material.onUploadMaterial`。业务服务端应返回最小权限、短有效期凭证，
+     * `material.onUploadFile` / `material.onUploadMaterial`。业务服务端应返回最小权限、短有效期凭证，
      * 浏览器端不得保存客户长期 AK/SK。
      */
     getUploadSTS?: () => AmkEditorUploadSTSCredentials | Promise<AmkEditorUploadSTSCredentials>;
@@ -165,6 +184,16 @@ export interface VeVeditorInstance {
     on?: (eventName: string, handler: (...args: any[]) => void) => void;
     off?: (eventName: string, handler: (...args: any[]) => void) => void;
     getTrack?: () => any[];
+    /** 获取当前合成画布的 data URL；未初始化时返回 null，native 渲染模式下抛错。 */
+    getFrame?: (options?: {
+        type?: string;
+        quality?: number;
+    }) => string | null;
+    setCanvas?: (canvas: {
+        Width: number;
+        Height: number;
+        BackgroundColor?: string;
+    }) => Promise<void>;
     setTrack?: (track: any[], options?: {
         recordHistory?: boolean;
     }) => Promise<void>;
@@ -225,7 +254,7 @@ export interface AmkEditorOptions extends AmkInheritedVeVeditorOptions {
     getHeaders?: AmkEditorGetHeaders;
     header?: AmkEditorHeaderConfig;
     export?: AmkEditorExportConfig;
-    /** 每次导出任务成功创建后触发。 */
+    /** @deprecated 请改用 export.onTaskCreated。 */
     onExportTaskCreated?: (event: AmkExportTaskCreatedEvent) => void | Promise<void>;
     getLicenseUrl?: string | (() => string | Promise<string>);
     decode?: AmkEditorDecodeOptions;

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

@@ -1,4 +1,20 @@
 import type { MaterialItem } from '../types';
+export declare const VIDEO_POSTER_EXTRACT_PARAMS: {
+    readonly snapshot_type: "SpecifiedFrames";
+    readonly specified_frames: readonly [0];
+    readonly scale_long: 1280;
+    readonly scale_short: 720;
+};
+export declare function resolveSpriteTimeInterval(duration: unknown): number;
+export declare function buildSpriteExtractParams(duration: unknown): {
+    snapshot_type: string;
+    time_interval: number;
+    snapshot_limit: number;
+    scale_long: number;
+    enable_sprite: boolean;
+    sprite_rows: number;
+    sprite_cols: number;
+};
 export type SpriteState = {
     ready: boolean;
     pendingTaskId?: string;