@volcengine/amk-editor 0.0.1-beta.4

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

@@ -0,0 +1,12 @@
+import React from 'react';
+import type { AmkI18nInstance } from './i18n';
+export interface LocalUploadModalViewProps {
+    visible: boolean;
+    initialFiles: File[];
+    accept?: string;
+    t: AmkI18nInstance['t'];
+    /** 确认后弹窗立即关闭；上传过程由外部 Message 提示 */
+    onConfirm: (files: File[]) => void;
+    onClose: () => void;
+}
+export declare function LocalUploadModalView({ visible, initialFiles, accept, t, onConfirm, onClose, }: LocalUploadModalViewProps): React.ReactElement;

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

@@ -0,0 +1,13 @@
+import type { AmkI18nInstance } from './i18n';
+export interface CreateLocalUploadModalOptions {
+    container: HTMLElement;
+    accept?: string;
+    t: AmkI18nInstance['t'];
+    onConfirm: (files: File[]) => void;
+}
+export interface LocalUploadModalController {
+    open: (files: File[]) => void;
+    close: () => void;
+    destroy: () => void;
+}
+export declare function createLocalUploadModal(options: CreateLocalUploadModalOptions): LocalUploadModalController;

package/dist/project-bootstrap.d.ts

@@ -0,0 +1,11 @@
+import type { AmkProjectSnapshot, MaterialItem } from './types';
+/** 预览与导出统一使用 NativeRender 的多语言断行规则。 */
+export declare function addForceMultilingualLineBreak(editParam: Record<string, unknown>): Record<string, unknown>;
+export declare function normalizeLoadedProject(input: AmkProjectSnapshot | undefined): Required<Pick<AmkProjectSnapshot, 'materials' | 'editParam'>> & {
+    projectName?: string;
+};
+export declare function toEditorInitialData(params: {
+    projectName?: string;
+    materials: MaterialItem[];
+    editParam: Record<string, unknown>;
+}): AmkProjectSnapshot;

package/dist/public-types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 公网包的自包含类型契约。
+ *
+ * 这些类型与底层编辑器的公开 Options 保持结构兼容，但不引用底层内部包，
+ * 避免公网用户安装 amk-editor 时还需要访问内网依赖。
+ */
+export type VeVeditorTheme = 'light' | 'dark';
+export interface VeVeditorMaterialItem {
+    id?: string;
+    type?: 'video' | 'audio' | 'image' | string;
+    source: string;
+    material_id?: string;
+    source_material_id?: string;
+    url?: string;
+    poster?: string;
+    sprite?: string | Record<string, unknown>;
+    waveform?: string | Record<string, unknown>;
+    duration?: number;
+    width?: number;
+    height?: number;
+    kid?: string;
+    bizMeta?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface VeVeditorI18nOptions {
+    locale?: string;
+    messages?: Record<string, Record<string, string>>;
+    messageOverrides?: Record<string, string>;
+}
+export interface VeVeditorDecodeOptions {
+    enableAudioFrontendDecode?: boolean;
+    enableVideoFrontendDecode?: boolean;
+    decodeConcurrency?: number;
+    decodeTopK?: number;
+    enableThumbnailDecode?: boolean;
+}
+export type VeVeditorResourceOptionTypes = {
+    font: unknown;
+    wordArt: unknown;
+    textAnimation: unknown;
+    transition: unknown;
+    filter: unknown;
+    effect: unknown;
+};
+export type VeVeditorResourceSource<T = unknown> = T[] | {
+    resources: T[];
+    categories?: Array<Record<string, unknown>>;
+} | (() => Promise<T[] | {
+    resources: T[];
+    categories?: Array<Record<string, unknown>>;
+}>) | false;
+export interface VeVeditorMaterialOptions<TMaterialItem = VeVeditorMaterialItem> {
+    show?: boolean;
+    emptyIcon?: string;
+    showClassification?: boolean;
+    defaultClassificationId?: string | null;
+    showExportVideoClassification?: boolean;
+    sketchItems?: TMaterialItem[];
+    sketchShowAdd?: boolean;
+    sketchShowDelete?: boolean;
+    showProductCategory?: boolean;
+    renderChannels?: () => unknown;
+    renderImportActions?: (container: HTMLElement) => void | (() => void);
+    onDeleteMaterial?: (material: TMaterialItem) => boolean | void | Promise<boolean | void>;
+}
+export interface VeVeditorOptions<TMaterialOptions = VeVeditorMaterialOptions, TI18nOptions = VeVeditorI18nOptions, TResourceOptions extends VeVeditorResourceOptionTypes = VeVeditorResourceOptionTypes> {
+    container: HTMLElement;
+    theme?: VeVeditorTheme;
+    material?: TMaterialOptions;
+    i18n?: TI18nOptions;
+    decode?: VeVeditorDecodeOptions;
+    track?: Record<string, unknown>;
+    toolbar?: Record<string, unknown>;
+    navigationBar?: Record<string, unknown>;
+    videoOperationBar?: Record<string, unknown>;
+    layout?: Record<string, unknown>;
+    ui?: Record<string, unknown>;
+    shortcut?: Record<string, boolean | undefined>;
+    interaction?: {
+        readonly?: boolean;
+    };
+    frameRate?: {
+        type?: 'source' | 'target';
+        frameRate?: number;
+    };
+    timeDisplayFormat?: 'hms' | 'msms' | 'msf';
+    crashedFallback?: string;
+    debug?: boolean;
+    renderMode?: 'webgl' | 'native';
+    initialData?: Record<string, unknown>;
+    font?: TResourceOptions['font'];
+    wordArt?: TResourceOptions['wordArt'];
+    textAnimation?: TResourceOptions['textAnimation'];
+    transition?: TResourceOptions['transition'];
+    filter?: TResourceOptions['filter'];
+    effect?: TResourceOptions['effect'];
+    recording?: Record<string, unknown>;
+    onSketchItemsChange?: (params: {
+        sketchItems?: VeVeditorMaterialItem[];
+        action?: 'delete' | 'add';
+        item?: unknown;
+    }) => void;
+    onNodePreviewError?: (type: 'video' | 'audio', node: unknown) => void;
+    onBeforeUndo?: (payload: unknown) => boolean | void;
+    onBeforeRedo?: (payload: unknown) => boolean | void;
+    onBeforeTimestampMount?: (params: Record<string, unknown>) => boolean | Promise<boolean>;
+    onBeforeKeyframeMount?: (params: Record<string, unknown>) => boolean | Promise<boolean>;
+    onTrackChanged?: (payload: unknown) => unknown;
+    onRecordingUpload?: (params: Record<string, unknown>) => Promise<boolean | {
+        success: boolean;
+        url?: string;
+        name?: string;
+        userDataPatch?: Record<string, unknown>;
+    }> | boolean | {
+        success: boolean;
+        url?: string;
+        name?: string;
+        userDataPatch?: Record<string, unknown>;
+    };
+}

package/dist/react-mount.d.ts

@@ -0,0 +1,10 @@
+import type { ReactElement } from 'react';
+/**
+ * React 18/19 挂载封装：createRoot + render / unmount。
+ * 避免 ReactDOM.render / unmountComponentAtNode（React 18 弃用，19 已移除）。
+ * 命令式 modal 宿主需要同步刷 DOM，故 render 包一层 flushSync。
+ */
+export declare function createReactMount(container: HTMLElement): {
+    render: (element: ReactElement) => void;
+    unmount: () => void;
+};

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

@@ -0,0 +1,17 @@
+import type { MaterialItem } from './types';
+/**
+ * 业务方回写的播放信息补丁；未返回的字段保持原样。
+ * 按 SDK 内部 material_id 匹配目标素材；可更新 url / poster / sprite / source_material_id 等。
+ * material_id 为 SDK 内部字段，补丁中的同名字段会被忽略。
+ */
+export type MaterialPlayInfoPatch = Partial<MaterialItem> & {
+    material_id?: string;
+    source_material_id?: string;
+};
+/** SDK 内部素材关联键：material_id（不暴露给业务改写） */
+export declare function resolveMaterialId(material: Pick<MaterialItem, 'material_id'> | MaterialPlayInfoPatch): string;
+/** 业务侧 / 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[];
+/** 从当前素材库按 material_id 选出待刷新列表；未传则全量有 material_id 的素材。 */
+export declare function pickMaterialsForRefresh(materials: MaterialItem[], materialIdOrIds?: string | string[]): MaterialItem[];

package/dist/runtime/veveditor.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 构建占位模块：发布构建由 build.mjs 替换为内联的 VeVeditor UMD。
+ * 测试环境通过 Vitest mock 此模块注入编辑器实例。
+ */
+declare const VeVeditor: any;
+export default VeVeditor;

package/dist/task-polling.d.ts

@@ -0,0 +1,9 @@
+export declare function getTaskPollDelayMs(attempt: number): number;
+export type TaskPollingController = {
+    cancel: () => void;
+};
+export declare function startTaskPolling(options: {
+    poll: () => Promise<boolean>;
+    onError?: (error: unknown) => void;
+    getDelayMs?: (attempt: number) => number;
+}): TaskPollingController;

package/dist/toast.d.ts

@@ -0,0 +1,24 @@
+export type AmkMessageType = 'info' | 'warning' | 'error' | 'success' | 'loading';
+export interface ShowAmkMessageOptions {
+    durationMs?: number;
+    type?: AmkMessageType;
+}
+type MessageCloser = () => void;
+/**
+ * 轻量 Message（对齐常见 Message 用法）：上传中 / 成功 / 失败提示。
+ * 不依赖外部 UI 库，避免把 Arco Message 整包打进 AMK。
+ */
+export declare const Message: {
+    loading(content: string): MessageCloser;
+    success(content: string): MessageCloser;
+    error(content: string): MessageCloser;
+    warning(content: string): MessageCloser;
+    info(content: string): MessageCloser;
+    clear(): void;
+};
+/** @deprecated 使用 Message.* */
+export declare function showAmkToast(message: string, options?: {
+    type?: Exclude<AmkMessageType, 'loading'>;
+    durationMs?: number;
+}): void;
+export {};

package/dist/types.d.ts

@@ -0,0 +1,138 @@
+import type { VeVeditorI18nOptions, VeVeditorMaterialItem, VeVeditorOptions, VeVeditorTheme, VeVeditorDecodeOptions } from './public-types';
+export type Theme = VeVeditorTheme;
+export interface MaterialItem extends VeVeditorMaterialItem {
+    /** 业务侧素材主键；上传 / 更新 / 删除必填。 */
+    source_material_id: string;
+    /** Editing API 生成的服务端 id；业务方不必传，传了也不会入库。 */
+    material_id?: string;
+}
+/**
+ * 抽帧产物存储 key 的推荐命名，仅用于提供接入提示，不属于强制素材 Schema。
+ * 业务可以直接使用这两个字段，也可以把 key 放进任意自定义字段或嵌套对象。
+ */
+export interface RecommendedExtractStorageFields {
+    /** 推荐字段：封面图业务存储 key；业务也可以使用自定义字段。 */
+    poster_storage_key?: string;
+    /** 推荐字段：与 sprite.storeurls 对应的业务存储 key；也可自定义。 */
+    sprite_storage_keys?: string[];
+}
+export interface PersistExtractUrlsResult {
+    /** 转存后的长期可访问 URL，须与回调入参 urls 等长。 */
+    urls: string[];
+    /**
+     * 随转存结果写回素材的业务字段，SDK 原样合并并持久化。
+     * 字段名和结构完全由业务决定；SDK 不读取推荐字段，也不限制自定义嵌套结构。
+     */
+    materialPatch?: Partial<MaterialItem>;
+}
+export interface MaterialConfig {
+    emptyIcon?: string;
+    uploadAccept?: string;
+    onUploadMaterial?: (files: File[]) => Promise<MaterialItem[]> | MaterialItem[];
+    onUploadUrlMaterial?: (urls: string[]) => Promise<MaterialItem[]> | MaterialItem[];
+    onUploadFromSystem?: () => Promise<MaterialItem[]> | MaterialItem[];
+    /**
+     * 刷新播放信息。未配置时用素材库已有字段；
+     * 配置后：入参为待刷新素材列表（按服务端 material_id 区分，支持批量），
+     * 返回单条或数组补丁覆盖原素材的播放字段（url / poster / sprite / source_material_id 等）。
+     * 补丁不得改写 material_id（服务端字段，业务传了也不入库）。
+     */
+    onRefreshPlayInfo?: (materials: MaterialItem[]) => Partial<MaterialItem> | Partial<MaterialItem>[] | Promise<Partial<MaterialItem> | Partial<MaterialItem>[]>;
+    /**
+     * 抽帧得到的临时 http（约 24h）转存成长效地址。
+     * SDK 会先用临时链上屏/落盘，再后台调用本回调换链；失败则保留临时链。
+     * 未配置则只落盘临时链；若带 auth_key 且过期，SDK 会自动重抽。
+     * 推荐返回 urls + materialPatch，把刷新 URL 所需的 storage key 或其他业务字段写入素材。
+     * SDK 不限定 materialPatch 的字段名；poster_storage_key / sprite_storage_keys 仅为推荐命名。
+     * 兼容只返回 string[]，但该形式无法附带业务字段。
+     */
+    onPersistExtractUrls?: (params: {
+        kind: 'poster' | 'sprite';
+        urls: string[];
+        material: MaterialItem;
+    }) => Promise<PersistExtractUrlsResult | string[]> | PersistExtractUrlsResult | string[];
+}
+export interface AmkEditorHeaderConfig {
+    show?: boolean;
+    onBack?: () => void;
+    onClose?: () => void;
+}
+export interface ExportVideoParams {
+    videoName: string;
+    qualityEnhancement: boolean;
+    enhancementVersion: 'standard' | 'professional' | 'large-model';
+    resolution: 'original' | '720p' | '1080p' | '2k' | '4k';
+    frameRate: number;
+    format: 'mp4' | 'mp3';
+    codec: 'h264' | 'h265' | 'vp9' | 'mp3';
+}
+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>;
+    setTrackElementMarker?: (elementId: string, marker: {
+        key?: string;
+        content: string;
+        position?: number;
+        loading?: boolean;
+    } | null, options?: {
+        clearKey?: string;
+    }) => void;
+    getTrackElementMarkers?: (elementId: string) => Array<{
+        key?: string;
+        content: string;
+        position?: number;
+        loading?: boolean;
+    }>;
+    setTrackElementBadge?: (elementId: string, badge: {
+        type: 'spinner';
+        content?: string;
+        position?: number;
+    } | null) => void;
+    getTrackElementBadge?: (elementId: string) => unknown;
+    getSketchItems?: () => MaterialItem[];
+    getEditParam?: () => Record<string, unknown>;
+    decodeVideoPoster?: (url: string, options?: {
+        signal?: AbortSignal;
+        imageWidth?: number;
+    }) => Promise<Blob | null>;
+    addSketchItems?: (items: MaterialItem[]) => void;
+    setSketchItems?: (items: MaterialItem[]) => void;
+    [key: string]: unknown;
+}
+/** 内置 get/update 工程快照（不导出给宿主配置） */
+export type AmkProjectSnapshot = {
+    projectName?: string;
+    materials?: MaterialItem[];
+    editParam?: Record<string, unknown>;
+};
+/** AMK 资源面板开关：false=关闭（不透传）；true/不传=展示（透传 AMK 内置资源）。 */
+type AmkResourceOptionTypes = {
+    font: boolean;
+    wordArt: boolean;
+    textAnimation: boolean;
+    transition: boolean;
+    filter: boolean;
+    effect: boolean;
+};
+type AmkInheritedVeVeditorOptions = Omit<VeVeditorOptions<MaterialConfig, VeVeditorI18nOptions, AmkResourceOptionTypes>, 'initialData' | 'recording' | 'onSketchItemsChange' | 'onNodePreviewError' | 'onBeforeUndo' | 'onBeforeRedo' | 'onBeforeTimestampMount' | 'onBeforeKeyframeMount' | 'onTrackChanged' | 'onRecordingUpload' | 'decode'>;
+export type AmkEditorDecodeOptions = VeVeditorDecodeOptions;
+export interface AmkEditorOptions extends AmkInheritedVeVeditorOptions {
+    projectId: string;
+    endpoint: string;
+    header?: AmkEditorHeaderConfig;
+    getLicenseUrl?: string | (() => string | Promise<string>);
+    decode?: AmkEditorDecodeOptions;
+}
+export interface AmkEditorInternalConfig {
+    projectId: string;
+    endpoint: string;
+}
+/** 挂载 veveditor 用的内部配置（含组装后的 initialData 等，不作为宿主 API） */
+export interface AmkEditorConfig extends AmkEditorOptions {
+    initialData?: AmkProjectSnapshot;
+    __amkEditor: AmkEditorInternalConfig;
+}
+export {};

package/dist/url-upload-modal-view.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import type { AmkI18nInstance } from './i18n';
+export interface UrlUploadModalViewProps {
+    visible: boolean;
+    t: AmkI18nInstance['t'];
+    /** 确认后弹窗立即关闭；上传过程由外部 Message 提示 */
+    onConfirm: (urls: string[]) => void;
+    onClose: () => void;
+}
+/** 支持逗号 / 换行分隔，得到回调给业务方的 url 数组 */
+export declare function splitUrls(input: string): string[];
+export declare function UrlUploadModalView({ visible, t, onConfirm, onClose, }: UrlUploadModalViewProps): React.ReactElement;

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

@@ -0,0 +1,12 @@
+import type { AmkI18nInstance } from './i18n';
+export interface CreateUrlUploadModalOptions {
+    container: HTMLElement;
+    t: AmkI18nInstance['t'];
+    onConfirm: (urls: string[]) => void;
+}
+export interface UrlUploadModalController {
+    open: () => void;
+    close: () => void;
+    destroy: () => void;
+}
+export declare function createUrlUploadModal(options: CreateUrlUploadModalOptions): UrlUploadModalController;

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

@@ -0,0 +1,43 @@
+import type { MaterialItem } from '../types';
+export type SpriteState = {
+    ready: boolean;
+    pendingTaskId?: string;
+};
+/**
+ * 素材 `sprite`：
+ * - object `{ storeurls, capturenum }`：已完成；链接是否失效由实际网络请求判断
+ * - string：抽帧 taskId（进行中）
+ * - 缺省：需要新建任务
+ */
+export declare function resolveSpriteState(material: MaterialItem): SpriteState;
+/** 可落盘的封面：接口返回的 http(s) URL */
+export declare function isPersistablePosterUrl(value: unknown): boolean;
+/** 仅会话内使用的封面：前端解码 dataURL，不落盘 */
+export declare function isRuntimeOnlyPosterUrl(value: unknown): boolean;
+/** http poster；有效性由实际网络请求判断 */
+export declare function isPosterAssetReady(material: MaterialItem): boolean;
+export declare function isExtractableVideoMaterial(material: MaterialItem): boolean;
+export declare function resolveMaterialMediaUrl(material: MaterialItem): string;
+export type MaterialExtractActions = {
+    url: string;
+    /** 需要新建 sprite 抽帧任务，完成后 PUT sprite=taskId */
+    createSpriteTask: boolean;
+    /** 已有 taskId，继续轮询，完成后 PUT sprite 结果 */
+    resumeSpriteTaskId?: string;
+    /**
+     * 需要抓封面：
+     * - 接口模式：缺有效 http poster（含 auth_key 过期）时抓取，http 结果 PUT 落盘
+     * - 前端解码模式：无运行时缓存时也可抓取（dataURL 不落盘）
+     */
+    capturePoster: boolean;
+};
+/**
+ * 纯判断：单个素材要不要建 sprite 任务 / 恢复轮询 / 抓封面。
+ * - enableThumbnailDecode（前端缩略图）开启时不发起 sprite 接口任务
+ * - poster / sprite 缺省时触发重抽；已有 URL 的有效性由实际网络请求判断
+ */
+export declare function planMaterialExtractActions(params: {
+    material: MaterialItem;
+    useFrontendThumbnails: boolean;
+    hasPosterCache: boolean;
+}): MaterialExtractActions | null;