@vvfx/artis 0.0.1-alpha.0

package/dist/core/types/page.d.ts

@@ -0,0 +1,40 @@
+import type { ItemSchema } from './item-schema';
+import type { ArtisItem } from '../item';
+import type { GlobalLayoutMode } from '../../utils';
+import type { ViewportFitShiftParam } from './view';
+export type PageOptions = {
+    asyncMode: boolean;
+    safeAreaPreview: boolean;
+    adsorption: boolean;
+};
+export type ArtisData = {
+    items: ArtisItem[];
+};
+export type InitArtisData = {
+    items: ItemSchema[];
+};
+export type PageAutoLayoutParam = {
+    mode?: GlobalLayoutMode;
+    ids?: string[];
+    focus?: boolean;
+    gap?: number;
+    padding?: ViewportFitShiftParam;
+};
+export type ArtisPageConfig = {
+    safeAreaPreview: boolean;
+    zoom: number;
+    adsorption: boolean;
+    asyncMode: boolean;
+    translation: [number, number];
+};
+export type PageProperty = {
+    safeAreaPreview: boolean;
+    zoom: number;
+    translation: [number, number];
+    adsorption: boolean;
+    asyncMode: boolean;
+};
+export type ActiveData = {
+    selectedItems: string[];
+    loadingItems: string[];
+};

package/dist/core/types/sdk.d.ts

@@ -0,0 +1,28 @@
+import type { spec } from '../../shared';
+import type { ViewParam } from './view';
+import type { PageOptions } from './page';
+export declare enum SDKBackgroundType {
+    COLOR = "color",
+    IMAGE = "image",
+    CHESS_BOARD = "chess-board",
+    DOT_BOARD = "dot-board"
+}
+export type SDKOptions = {
+    /** 导出视频时，是否开启转码日志 */
+    loggerInExportVideoTranscoding?: boolean;
+};
+export type SDKTemplateInputParam = {
+    scene: string | spec.JSONScene;
+    mode: 'template';
+    viewParams?: ViewParam[];
+    options: PageOptions;
+};
+export type SDKEditorInputParam = {
+    mode: 'editor';
+};
+export type SDKInputParam = SDKTemplateInputParam | SDKEditorInputParam;
+export type SDKInitParam = {
+    scene: spec.JSONScene;
+    viewParams: ViewParam[];
+    options: PageOptions;
+};

package/dist/core/types/view.d.ts

@@ -0,0 +1,39 @@
+import type { SizeAdaptDirection, ExportMediaItemOptions } from '../../helper';
+/** 聚焦偏移参数 */
+export type ViewportFitShiftParam = {
+    /** 左偏移 */
+    left?: number;
+    /** 右偏移 */
+    right?: number;
+    /** 上偏移 */
+    top?: number;
+    /** 下偏移 */
+    bottom?: number;
+    /** 包围盒整体缩放 */
+    scale?: number;
+};
+export type ExportParam = {
+    name?: string;
+} & Omit<ExportMediaItemOptions, 'scene' | 'size'>;
+export type PreviewSafeAreaParam = {
+    box: [number, number, number, number];
+    color?: [number, number, number, number];
+    url?: string;
+    visible?: boolean;
+};
+export type ViewParam = {
+    size?: [number, number];
+    safeArea?: [number, number, number, number];
+    adaptionDirection?: SizeAdaptDirection;
+    previewSafeAreas?: PreviewSafeAreaParam[];
+    export: ExportParam;
+};
+export type ViewProperty = {
+    id: number;
+    size: [number, number];
+    safeArea: [number, number, number, number];
+    previewSafeAreas: PreviewSafeAreaParam[];
+    scene: unknown;
+    export: ExportParam;
+    ignoreInteraction: boolean;
+};

package/dist/helper/exporter/config.d.ts

@@ -0,0 +1,18 @@
+export declare const HELPER_CONFIG: {
+    WEBP: {
+        SCRIPT: string;
+        WASM: string;
+    };
+    FFMPEG: {
+        CLASSWORKER: string;
+        DEFAULT: {
+            CORE: string;
+            WASM: string;
+        };
+        MT: {
+            CORE: string;
+            WASM: string;
+            WORKER: string;
+        };
+    };
+};

package/dist/helper/exporter/const.d.ts

@@ -0,0 +1,71 @@
+export declare const STATUS_MAP: {
+    readonly READY: "ready";
+    readonly EXECUTABLE: "executable";
+    readonly DISPOSE: "dispose";
+};
+export declare const MEDIA_TYPE: {
+    readonly APNG: "APNG";
+    readonly MP4: "MP4";
+    readonly WebM: "WebM";
+    readonly Images: "Images";
+    readonly WebP: "WebP";
+    readonly GIF: "GIF";
+    readonly AlphaMaskVideo: "AlphaMaskVideo";
+};
+export declare const STAGE_MAP: {
+    readonly IDLE: "idle";
+    readonly CONVERT_IMAGE: "convertImage";
+    readonly TRANSCODING: "transcoding";
+    readonly AUDIO: "audio";
+};
+export declare const EXPORT_NEED_TRANS_IMAGES_MAP: {
+    JPEG: string;
+    WEBP: string;
+    PNG: string;
+};
+export declare const FORMAT_BUFFER_DOWNLOAD_SUFFIX: {
+    MP4: string;
+    WebP: string;
+    APNG: string;
+    GIF: string;
+    AlphaMaskVideo: string;
+    Images: string;
+};
+export declare const FORMAT_BUFFER_DOWNLOAD_MIMETYPE: {
+    MP4: string;
+    WebP: string;
+    APNG: string;
+    GIF: string;
+    AlphaMaskVideo: string;
+    Images: string;
+};
+export declare const EXPORT_STATUS_MAP: {
+    DEFAULT: string;
+    EXPORTING: string;
+    SUCCESS: string;
+    ERROR: string;
+};
+/**
+ * GIF 压缩参数
+ * 核心通过参数 flags + palettegen + paletteuse 实现
+ * highest: lanczos + max_colors=256 + dither=bayer
+ * high: bicubic + max_colors=200 + dither=bayer
+ * medium: bilinear + max_colors=64 + dither=bayer
+ * low: neighbor + max_colors=32 + dither=none
+ */
+export declare const GIF_QUALITY_TO_FFMPEG_ARGS: {
+    highest: string;
+    high: string;
+    medium: string;
+    low: string;
+};
+/**
+ * APNG 压缩参数
+ * 核心通过参数 compression_level 实现，压缩等级分为 1/3/6/9
+ */
+export declare const APNG_QUALITY_TO_FFMPEG_ARGS: {
+    highest: string;
+    high: string;
+    medium: string;
+    low: string;
+};

package/dist/helper/exporter/export-media.d.ts

@@ -0,0 +1,189 @@
+import { EventEmitter } from '../../shared';
+import type { MediaType, ExportMediaInitOptions, ExportItemParams, ExportParams, Buffer, Extra, Buffers, Extras } from './types';
+export type ExportMediaEvent = {
+    /**
+     * 环境准备完成
+     */
+    ready: [mediaType: MediaType];
+    /**
+     * 总体进度
+     */
+    progress: [progress: number];
+    /**
+     * 单个任务完成
+     */
+    done: [item: ExportItemParams | undefined, success: boolean, buffer: Buffer, extra: Extra];
+    /**
+     * 全部任务完成
+     */
+    finish: [success: boolean, taskInfos: ExportParams, buffers: Buffers, extras: Extras];
+    /**
+     * 异常
+     */
+    error: [error: any];
+};
+export declare class ExportMedia extends EventEmitter<ExportMediaEvent> {
+    #private;
+    private status;
+    private stage;
+    private player?;
+    /**
+     * 构造导出器实例，合并默认选项并触发初始化
+     * @param options 导出初始化配置
+     */
+    constructor(options: ExportMediaInitOptions);
+    /**
+     * 切换导出媒体类型，类型变化时重置实例并重新初始化
+     * @param curMediaType 目标媒体类型
+     */
+    setMediaType(curMediaType: MediaType): void;
+    /**
+     * 合并更新导出选项，媒体类型变化时联动切换
+     * @param options 待合并的选项片段
+     */
+    setOptions(options: Partial<ExportMediaInitOptions>): void;
+    /** 当前是否已处于销毁（取消）态 */
+    get canceled(): boolean;
+    /** 基于当前任务与播放器合成信息组装出导出所需的运行配置 */
+    private get config();
+    /** 当前任务的 MP4 导出参数 */
+    private get mp4Config();
+    /** 当前任务的 GIF 导出参数 */
+    private get gifConfig();
+    /** 当前任务的 APNG 导出参数 */
+    private get apngConfig();
+    /** 按转帧与转码两段权重计算得到的总体进度（0-1） */
+    private get progress();
+    /** 根据当前媒体类型推导序列帧应使用的图片格式 */
+    private get transImageType();
+    /**
+     * 初始化导出环境，按媒体类型加载所需 helper 并抛出 ready 事件
+     * @returns 初始化后的状态
+     */
+    private onInit;
+    /** 重置运行态：清理定时器、动画帧、播放器与任务进度 */
+    private onReset;
+    /**
+     * 统一处理导出异常：结束流程并触发 error 事件后销毁实例
+     * @param error 抛出的异常对象
+     */
+    private onError;
+    /**
+     * 收尾流程：补满进度并对外抛出 finish 事件
+     * @param success 本次导出是否全部成功
+     * @param taskInfos 任务信息集合
+     * @param buffers 输出文件缓冲集合
+     * @param extras 额外输出文件缓冲集合
+     */
+    private onFinish;
+    /**
+     * 按媒体类型按需加载 WebP / FFmpeg helper，并为 ffmpeg 注册日志监听以更新转码帧进度
+     * @param mediaType 当前媒体类型
+     */
+    private loadHelper;
+    /**
+     * 累加所有任务的总帧数，用于全局进度计算
+     * @param options 全部导出任务配置
+     * @returns 所有任务总帧数
+     */
+    private getAllTaskFrames;
+    /**
+     * 更新进度相关内部字段并对外抛出 progress 事件
+     * @param options 需要更新的进度子字段
+     */
+    private setProgress;
+    /**
+     * 将播放器时间跳转到指定秒数，规避末帧回卷边界问题
+     * @param seconds 目标时间（秒）
+     * @param playing 是否以播放方式跳转
+     * @returns 实际生效的时间（秒）
+     */
+    private forwardPlayerTime;
+    /**
+     * 生成静音 wav 音轨并写入 ffmpeg 虚拟文件系统
+     * @param name 写入 ffmpeg 的文件名
+     */
+    private getWavAudio;
+    /**
+     * 将序列帧缓冲打包成zip并返回整体 ArrayBuffer
+     * @param folderName zip 内目录名
+     * @param imageBuffers 各帧图片缓冲
+     * @returns 打包后的 ArrayBuffer
+     */
+    private getImagesZip;
+    /**
+     * 调用 img2webp 将序列帧合成为 WebP 动图，处理后清理中间文件
+     * @returns 合成后的 WebP 文件字节
+     */
+    private getWebP;
+    /**
+     * 通过 ffmpeg 将序列帧合成为 APNG，失败抛出异常
+     * @returns 生成的 APNG 文件名
+     */
+    private getAPNG;
+    /**
+     * 通过 ffmpeg 将序列帧合成为 GIF，失败抛出异常
+     * @returns 生成的 GIF 文件名
+     */
+    private getGIF;
+    /**
+     * 通过 ffmpeg 合成 MP4，按需混入音频并可选输出末帧 JPEG，返回产物文件名
+     * @param oldTotalTime 原始总时长
+     * @param newTotalTime 目标总时长，用于变速
+     * @returns 视频文件名与可选末帧文件名
+     */
+    private getMP4;
+    /**
+     * 通过 ffmpeg 合成 AlphaMask 透明视频
+     * @param oldTotalTime 原始总时长
+     * @param newTotalTime 目标总时长，用于变速
+     * @returns 生成的视频文件名
+     */
+    private getAlphaMaskVideo;
+    /**
+     * 按当前媒体类型分派到具体合成方法，并读取/清理 ffmpeg 内的产物文件
+     * @param oldTotalTime 原始总时长
+     * @param newTotalTime 目标总时长
+     * @returns 主产物与额外产物的字节内容
+     */
+    private getVideoByType;
+    /**
+     * 启动 MediaRecorder 录制 canvas 流为 WebM 分片
+     * @param canvas 被录制的画布
+     */
+    private onRecordWebM;
+    /**
+     * 逐帧推进播放器并将序列帧写入对应产物通道（ffmpeg/webp/images），完成后抛出 done
+     * @param options 单帧导出参数
+     */
+    private onExportImageFrame;
+    /**
+     * 通过画布流录制方式逐帧采集 WebM，录制完成后抛出 done
+     * @param canvas 输出画布
+     */
+    private onExportWebMFrame;
+    /**
+     * 执行单个导出任务：配置画布尺寸并按媒体类型分派到帧导出流程
+     * @param options 单任务执行参数
+     */
+    private runTask;
+    /** 清空任务相关的全部进度与缓存字段 */
+    private clearTaskInfo;
+    /** 清理 ffmpeg 实例及其内部残留文件并终止 worker */
+    private clearFFMpegCore;
+    /** 关闭并释放 img2webp 内核实例 */
+    private clearImage2WebPCore;
+    /** 停止 MediaRecorder 并清空已录制分片 */
+    private clearMediaRecorder;
+    /** 移除当前实例对外抛出的全部事件监听 */
+    private clearAllListeners;
+    /** 取消导出：触发失败收尾、重置状态并释放全部资源 */
+    onCancel(): void;
+    /**
+     * 串行执行所有导出任务，逐任务加载场景并收集产物，最终触发 finish
+     * @param options 全部导出任务配置
+     */
+    onExport(options: ExportParams): Promise<void>;
+    /** 销毁实例：释放播放器、helper 与监听等全部资源 */
+    dispose(): void;
+}

package/dist/helper/exporter/exporter.d.ts

@@ -0,0 +1,58 @@
+import type { ExportMediaInitOptions, ExportItemParams, ExportParams, ExportMediaItemDownloadInfo, FileBuffer, Buffers, Extras } from './types';
+import { EventEmitter } from '../../shared';
+export type ExporterEvent = {
+    'progress': [progress: number];
+    'done': [item: ExportItemParams | undefined, success: boolean, buffer?: FileBuffer, extra?: FileBuffer | null];
+    'complete': [success: boolean, taskInfos: ExportParams, buffers: Buffers, extras: Extras];
+};
+export declare class Exporter extends EventEmitter<ExporterEvent> {
+    private _options;
+    private _status;
+    private _exportMedia;
+    /**
+     * 构造导出器，保存选项并创建内部媒体导出实例
+     * @param options 导出初始化配置
+     */
+    constructor(options: ExportMediaInitOptions);
+    /** 当前导出状态 */
+    get status(): string;
+    /**
+     * 合并更新导出选项并同步给内部媒体导出实例
+     * @param options 待合并的选项片段
+     */
+    setOptions(options: Partial<ExportMediaInitOptions>): void;
+    /**
+     * 将导出产物按文件名打包成 zip 并触发浏览器下载
+     * @param params 各任务的下载命名信息
+     * @param buffers 主产物缓冲集合
+     * @param extras 额外产物缓冲集合
+     */
+    downloadByMediaBuffers(params: ExportMediaItemDownloadInfo[], buffers: Buffers, extras: Extras): void;
+    /**
+     * 转发媒体导出进度事件
+     * @param progress 当前进度（0-1）
+     */
+    private onExportProgress;
+    /**
+     * 转发单任务完成事件
+     * @param current 当前任务信息
+     * @param success 是否成功
+     * @param buffer 产物缓冲
+     * @param extra 额外产物缓冲
+     */
+    private onExportDone;
+    /**
+     * 处理导出异常：置错误态并记录日志
+     * @param error 异常对象
+     */
+    private onExportError;
+    /**
+     * 启动导出流程：委托内部实例执行任务并桥接进度/完成/异常事件
+     * @param params 全部导出任务配置
+     */
+    onExport(params: ExportParams): void;
+    /** 取消导出：置错误态并对外抛出失败完成事件 */
+    onCancel(): void;
+    /** 释放内部媒体导出实例资源 */
+    dispose(): void;
+}

package/dist/helper/exporter/index.d.ts

@@ -0,0 +1,2 @@
+export type { ExportItemParams, ExportParams, ExportMediaInitOptions, ExportMediaItemDownloadInfo, ExportMediaItemOptions, FileBuffer, Buffers, Extras } from './types';
+export * from './exporter';

package/dist/helper/exporter/types.d.ts

@@ -0,0 +1,194 @@
+import { spec } from '../../shared';
+import { STATUS_MAP, MEDIA_TYPE, STAGE_MAP, EXPORT_STATUS_MAP, GIF_QUALITY_TO_FFMPEG_ARGS } from './const';
+declare global {
+    interface Window {
+        /**
+         * 创建 WebP Core 实例
+         */
+        createWebPCore: (config: any) => Promise<Img2WebPCore>;
+    }
+}
+export type FileBuffer = ArrayBuffer | Uint8Array;
+export type Status = typeof STATUS_MAP[keyof typeof STATUS_MAP];
+export type MediaType = typeof MEDIA_TYPE[keyof typeof MEDIA_TYPE];
+export type ExportImageFrameOptions = {
+    canvas: HTMLCanvasElement;
+    imageBuffers: ArrayBuffer[];
+    startTime: number;
+    oldTotalTime: number;
+    newTotalTime?: number;
+    backgroundCanvas?: HTMLCanvasElement;
+};
+export type RunExportTaskOptions = {
+    size: [number, number];
+    startTime: number;
+    containerCanvas: HTMLCanvasElement;
+    background?: {
+        backgroundCanvas?: HTMLCanvasElement;
+        backgroundImage?: HTMLImageElement;
+    };
+};
+export type FS = {
+    writeFile: (path: string, data: Uint8Array | string) => void;
+    unlink: (path: string) => void;
+    quit: () => void;
+    readFile(path: string, opts: {
+        encoding: 'binary';
+        flags?: string | undefined;
+    }): Uint8Array;
+    readFile(path: string, opts: {
+        encoding: 'utf8';
+        flags?: string | undefined;
+    }): string;
+    readFile(path: string, opts?: {
+        flags?: string | undefined;
+    }): Uint8Array;
+};
+type Pointer = number;
+export type Img2WebPCore = {
+    FS: FS;
+    run: (...args: string[]) => number;
+    cwrap: (ident: string, returnType: string, argTypes: string[]) => ((argc: number, argv: Pointer) => number);
+    _malloc: (size: number) => Pointer;
+    writeAsciiToMemory: (str: string, buffer: number, dontAddNull?: boolean) => void;
+    setValue: (ptr: number, value: any, type: string, noSafe?: boolean) => void;
+};
+export type Config = {
+    name: string;
+    oldTotalTime: number;
+    newTotalTime?: number;
+    startTime: number;
+    fps: number;
+    backgroundColor: string;
+    loop: boolean;
+    audioEnable: boolean;
+};
+export type Stage = typeof STAGE_MAP[keyof typeof STAGE_MAP];
+export type ExportStatus = typeof EXPORT_STATUS_MAP[keyof typeof EXPORT_STATUS_MAP];
+export type ExportMediaInitOptions = {
+    /**
+     * 导出类型
+     */
+    mediaType: MediaType;
+    /**
+     * 额外画布，导出透明视频时使用
+     */
+    extraCanvas?: HTMLCanvasElement | null;
+    /**
+     * 是否打印转码过程中的日志，仅在导出 MP4/AlphaMaskVideo 时有效， 默认 false
+     * 供开发调试使用
+     */
+    loggerInTranscoding?: boolean;
+    /**
+     * ffmpeg 转码是否开启多线程，默认 false，确保环境支持 SharedArrayBuffer
+     */
+    multiThreading?: boolean;
+    /**
+     * 是否输出 buffer，默认 false
+     */
+    isOutputBuffer?: boolean;
+};
+export type MP4Config = {
+    /**
+     * MP4 导出时是否需要导出最后一帧 PNG
+     */
+    isExportLastFrameJPEG?: boolean;
+};
+export type GifConfig = {
+    /**
+     * GIF 导出时的帧率
+     */
+    fps?: number;
+    /**
+     * GIF 导出时的缩放比例
+     * 默认 '-1:-1'， 表示不缩放
+     * 例如 '100:-1'， 表示宽度 100，高度自动
+     * 例如 '-1:100'， 表示宽度自动，高度 100
+     */
+    scale?: string;
+    /**
+     * GIF 导出时的质量
+     * 默认 'highest'
+     * 可选 'highest', 'high', 'medium', 'low'
+     */
+    quality?: keyof typeof GIF_QUALITY_TO_FFMPEG_ARGS;
+};
+export type ApngConfig = {
+    /**
+     * APNG 导出时的帧率
+     */
+    fps?: number;
+    /**
+     * APNG 导出时的缩放比例
+     * 默认 '-1:-1'， 表示不缩放
+     * 例如 '100:-1'， 表示宽度 100，高度自动
+     * 例如 '-1:100'， 表示宽度自动，高度 100
+     */
+    scale?: string;
+    /**
+     * APNG 导出时的质量
+     * 默认 'highest'
+     * 可选 'highest', 'high', 'medium', 'low'
+     */
+    quality?: keyof typeof GIF_QUALITY_TO_FFMPEG_ARGS;
+};
+export type ExportMediaItemOptions = {
+    /**
+     * 尺寸
+     */
+    size: [number, number];
+    /**
+     * 动效资源
+     */
+    scene: spec.JSONScene;
+    /**
+     * 视频时长，目前仅在导出 MP4 / AlphaMaskVideo 时有效，默认取动效资源时长
+     */
+    time?: number;
+    /**
+     * 是否生成音轨，默认 false，仅在导出 MP4 时有效
+     */
+    audioEnable?: boolean;
+    /**
+     * 帧率， 默认 30
+     */
+    fps?: number;
+    /**
+     * 是否循环，默认 true
+     */
+    loop?: boolean;
+    /**
+     * 视频背景颜色，默认 #000000
+     */
+    backgroundColor?: string;
+    /**
+     * 导出 MP4 时，设置的导出配置
+     */
+    mp4Config?: MP4Config;
+    /**
+     * 导出 GIF 时，设置的导出配置
+     */
+    gifConfig?: GifConfig;
+    /**
+     * 导出 APNG 时，设置的导出配置
+     */
+    apngConfig?: ApngConfig;
+};
+export type ExportOptions = ExportMediaItemOptions[];
+export type ExportMediaItemDownloadInfo = {
+    /**
+     * 导出文件夹名称
+     */
+    folderName: string;
+    /**
+     * 导出视频名称
+     */
+    name: string;
+};
+export type ExportItemParams = ExportMediaItemOptions & ExportMediaItemDownloadInfo;
+export type ExportParams = ExportItemParams[];
+export type Buffer = FileBuffer | undefined;
+export type Extra = FileBuffer | null | undefined;
+export type Buffers = FileBuffer[] | undefined;
+export type Extras = (FileBuffer | null)[] | null | undefined;
+export {};