@agrhub/engine-pixi 0.0.0-stage → 1.4.0

package/dist/json-serialization.d.ts

@@ -0,0 +1,312 @@
+import { IClip, ITransitionInfo, ClipContext, IChromaKeyOpts } from './clips';
+import { ColorAdjustment } from './utils/color-adjustment';
+import { ShapeType } from '@agrhub/core';
+export interface ClipTimingJSON {
+    display: {
+        from: number;
+        to: number;
+    };
+    trim?: {
+        from: number;
+        to: number;
+    };
+    duration: number;
+    playbackRate: number;
+    fadeIn?: {
+        duration: number;
+        curve?: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+    };
+    fadeOut?: {
+        duration: number;
+        curve?: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+    };
+}
+export interface ClipTransformJSON {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    angle: number;
+    opacity: number;
+    zIndex: number;
+    flip?: {
+        x: boolean;
+        y: boolean;
+    } | null;
+}
+interface BaseClipJSON {
+    id?: string;
+    name?: string;
+    metadata?: Record<string, any>;
+    effects?: Array<{
+        id: string;
+        key: string;
+        startTime: number;
+        duration: number;
+        targets?: number[];
+    }>;
+    src?: string;
+    timing?: ClipTimingJSON;
+    transform?: ClipTransformJSON;
+    display?: {
+        from: number;
+        to: number;
+    };
+    playbackRate?: number;
+    duration?: number;
+    trim?: {
+        from: number;
+        to: number;
+    };
+    transition?: ITransitionInfo;
+    style?: any;
+    locked?: boolean;
+    muted?: boolean;
+    colorAdjustment?: ColorAdjustment;
+    chromaKey?: IChromaKeyOpts;
+    animation?: {
+        keyFrames: Record<string, Partial<{
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+            angle: number;
+            opacity: number;
+        }>>;
+        options: {
+            duration: number;
+            delay?: number;
+            iterCount?: number;
+        };
+    };
+    animations?: Array<{
+        type: string;
+        options: any;
+        params?: any;
+    }>;
+    main?: boolean;
+}
+export interface ClipVisualStyleJSON {
+    borderRadius?: number;
+    stroke?: {
+        color: string;
+        width: number;
+    };
+    shadow?: {
+        color?: string;
+        alpha?: number;
+        blur?: number;
+        offsetX?: number;
+        offsetY?: number;
+    };
+}
+export interface VideoJSON extends BaseClipJSON {
+    type: "Video";
+    audio?: boolean;
+    volume?: number;
+    style?: ClipVisualStyleJSON;
+}
+export interface AudioJSON extends BaseClipJSON {
+    type: "Audio";
+    loop?: boolean;
+    volume?: number;
+    style?: ClipVisualStyleJSON;
+}
+export interface ImageJSON extends BaseClipJSON {
+    type: "Image";
+    style?: ClipVisualStyleJSON;
+}
+export interface TextStyleJSON {
+    fontSize?: number;
+    fontFamily?: string;
+    fontWeight?: string | number;
+    fontStyle?: string;
+    color?: string | number | {
+        type: "gradient";
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+        colors: Array<{
+            ratio: number;
+            color: string | number;
+        }>;
+    };
+    align?: "left" | "center" | "right";
+    fontUrl?: string;
+    stroke?: {
+        color: string | number;
+        width: number;
+        join?: "miter" | "round" | "bevel";
+        cap?: "butt" | "round" | "square";
+        miterLimit?: number;
+    };
+    shadow?: {
+        color?: string | number;
+        alpha?: number;
+        blur?: number;
+        offsetX?: number;
+        offsetY?: number;
+    };
+    wordWrap?: boolean;
+    wordWrapWidth?: number;
+    lineHeight?: number;
+    letterSpacing?: number;
+    textCase?: "none" | "uppercase" | "lowercase" | "title";
+    wordsPerLine?: "single" | "multiple";
+    verticalAlign?: "top" | "center" | "bottom";
+    wordAnimation?: ICaptionWordAnimation;
+    textBoxStyle?: TextBoxStyleJSON;
+    appeared?: string;
+    active?: string;
+    activeFill?: string;
+    captionBackground?: string;
+    keyword?: string;
+    background?: {
+        color?: string;
+        opacity?: number;
+        borderRadius?: number;
+        paddingX?: number;
+        paddingY?: number;
+    };
+}
+export interface ICaptionWordAnimation {
+    type: "scale" | "opacity";
+    application: "active" | "keyword" | "none";
+    value: number;
+    mode?: "static" | "dynamic";
+}
+export interface TextBoxStyleJSON {
+    style?: "tiktok" | "none";
+    textAlign?: "left" | "center" | "right" | "";
+    maxLines?: number;
+    borderRadius?: number;
+    horizontalPadding?: number;
+    verticalPadding?: number;
+}
+export interface TextJSON extends BaseClipJSON {
+    type: "Text";
+    text: string;
+    style?: TextStyleJSON;
+}
+export interface CaptionWordStyleJSON {
+    color?: string;
+    border?: {
+        color?: string;
+        width?: number;
+    };
+    background?: string;
+}
+export interface CaptionColorsJSON {
+    /** Currently spoken word */
+    active?: CaptionWordStyleJSON;
+    /** Upcoming / future words */
+    future?: CaptionWordStyleJSON;
+    /** Keyword words */
+    keyword?: {
+        color?: string;
+        preserveAfterSpoken?: boolean;
+    };
+}
+export interface CaptionPositioningJSON {
+    bottomOffset?: number;
+    videoWidth?: number;
+    videoHeight?: number;
+}
+export interface CaptionDataJSON {
+    words?: Array<{
+        text: string;
+        from: number;
+        to: number;
+        isKeyWord?: boolean;
+        paragraphIndex?: number;
+    }>;
+    colors?: CaptionColorsJSON;
+    positioning?: CaptionPositioningJSON;
+    wordAnimation?: ICaptionWordAnimation;
+    textBoxStyle?: TextBoxStyleJSON;
+}
+export interface CaptionJSON extends BaseClipJSON {
+    type: "Caption";
+    text: string;
+    style?: TextStyleJSON;
+    caption?: CaptionDataJSON;
+    fontUrl?: string;
+    mediaId?: string;
+    wordsPerLine?: "single" | "multiple";
+    textBoxStyle?: TextBoxStyleJSON;
+}
+export interface EffectJSON extends BaseClipJSON {
+    type: "Effect";
+    effectKey: string;
+    values?: Record<string, any>;
+}
+export interface TransitionJSON extends BaseClipJSON {
+    type: "Transition";
+    transitionKey: string;
+    fromClipId?: string | null;
+    toClipId?: string | null;
+}
+export interface PlaceholderJSON extends BaseClipJSON {
+    type: "Placeholder";
+}
+export interface ShapeJSON extends BaseClipJSON {
+    type: "Shape";
+    shapeType: ShapeType;
+}
+export interface GlobalTransitionJSON {
+    key: string;
+    duration: number;
+    clips: string[];
+}
+export type ClipJSON = VideoJSON | AudioJSON | ImageJSON | TextJSON | CaptionJSON | EffectJSON | TransitionJSON | PlaceholderJSON | ShapeJSON;
+export interface StudioTrackJSON {
+    id: string;
+    name: string;
+    type: string;
+    clipIds: string[];
+    muted?: boolean;
+}
+export interface ProjectJSON {
+    tracks?: StudioTrackJSON[];
+    clips: Record<string, ClipJSON>;
+    transition?: GlobalTransitionJSON[];
+    transitions?: GlobalTransitionJSON[];
+    globalEffects?: Array<{
+        id: string;
+        key: string;
+        startTime: number;
+        duration: number;
+    }>;
+    settings?: {
+        width?: number;
+        height?: number;
+        fps?: number;
+        duration?: number;
+        backgroundColor?: string;
+        format?: string;
+        videoCodec?: string;
+        bitrate?: number;
+        audio?: boolean;
+        audioCodec?: string;
+        audioSampleRate?: number;
+        metaDataTags?: Record<string, string>;
+    };
+}
+/**
+ * Normalize a clip's JSON structure to ensure compatibility and migrate old property structures
+ */
+export declare function normalizeClipJSON(json: ClipJSON): ClipJSON;
+export declare function normalizeClipStyleJSON(style: any, type: string): any;
+/**
+ * Serialize a clip to JSON format
+ * @param clip The clip to serialize
+ * @param main Whether this is the main clip (for Compositor)
+ */
+export declare function clipToJSON(clip: IClip, main?: boolean): ClipJSON;
+/**
+ * Deserialize JSON to a clip instance
+ * Uses fromObject static method if available (fabric.js pattern), otherwise falls back to manual construction
+ */
+export declare function jsonToClip(json: ClipJSON, context?: ClipContext): Promise<IClip>;
+export {};

package/dist/mp4-utils/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Quick concatenate multiple MP4 file streams, requires all MP4s to have consistent properties,
+ * properties include (but not limited to): audio/video codec format, resolution, sample rate
+ *
+ * @param streams An array of readable streams containing Uint8Array.
+ * @returns Returns a Promise that resolves to a readable stream containing merged MP4 data.
+ * @throws Will throw error if unable to generate file from streams.
+ *
+ * @example
+ * const streams = [stream1, stream2, stream3];
+ * const resultStream = await fastConcatMP4(streams);
+ */
+export declare function fastConcatMP4(streams: ReadableStream<Uint8Array>[]): Promise<ReadableStream<Uint8Array>>;
+/**
+ * Set correct duration value for fMP4 files generated
+ */
+export declare function fixFMP4Duration(stream: ReadableStream<Uint8Array>): Promise<ReadableStream<Uint8Array>>;
+/**
+ * Video dubbing; mix MP4 with audio file, only re-encode audio, video track unchanged
+ * @param mp4Stream - MP4 stream
+ * @param audio - Audio information
+ * @param audio.stream - Audio data stream
+ * @param audio.volume - Audio volume
+ * @param audio.loop - When audio duration is less than video, whether to loop audio stream
+ * @returns Output mixed audio stream
+ */
+export declare function mixinMP4AndAudio(mp4Stream: ReadableStream<Uint8Array>, audio: {
+    stream: ReadableStream<Uint8Array>;
+    volume: number;
+    loop: boolean;
+}): ReadableStream<Uint8Array<ArrayBufferLike>>;

package/dist/mp4-utils/mp4box-utils.d.ts

@@ -0,0 +1,44 @@
+import { AudioTrackOpts, MP4File, MP4Info, MP4Sample, VideoTrackOpts } from 'wrapbox';
+import { file } from 'opfs-tools';
+interface ExtractedConfig {
+    videoTrackConf?: VideoTrackOpts;
+    videoDecoderConf?: VideoDecoderConfig;
+    audioTrackConf?: AudioTrackOpts;
+    audioDecoderConf?: AudioDecoderConfig;
+}
+/**
+ * Extracts video and audio configurations from an MP4 file.
+ */
+export declare function extractFileConfig(file: MP4File, info: MP4Info): ExtractedConfig;
+/**
+ * Quick parse mp4 file, prioritizing header parsing to save memory.
+ */
+export declare function quickParseMP4File(reader: Awaited<ReturnType<ReturnType<typeof file>["createReader"]>>, onReady: (data: {
+    mp4boxFile: MP4File;
+    info: MP4Info;
+}) => void, onSamples: (id: number, sampleType: "video" | "audio", samples: MP4Sample[]) => void): Promise<void>;
+/**
+ * Parses transformation matrix to extract scale, rotation, and translation.
+ */
+export declare function parseMatrix(matrix?: Int32Array): {
+    scaleX?: undefined;
+    scaleY?: undefined;
+    rotationRad?: undefined;
+    rotationDeg?: undefined;
+    translateX?: undefined;
+    translateY?: undefined;
+    perspective?: undefined;
+} | {
+    scaleX: number;
+    scaleY: number;
+    rotationRad: number;
+    rotationDeg: number;
+    translateX: number;
+    translateY: number;
+    perspective: number;
+};
+/**
+ * Creates a function to rotate VideoFrames using Canvas.
+ */
+export declare function createVFRotater(width: number, height: number, rotationDeg: number): (vf: VideoFrame | null) => VideoFrame | null;
+export {};

package/dist/mp4-utils/sample-transform.d.ts

@@ -0,0 +1,26 @@
+import { MP4File, MP4Info, MP4Sample } from 'wrapbox';
+export type TransformChunk = {
+    chunkType: "ready";
+    data: {
+        info: MP4Info;
+        file: MP4File;
+    };
+} | {
+    chunkType: "samples";
+    data: {
+        id: number;
+        type: "video" | "audio";
+        samples: MP4Sample[];
+    };
+};
+/**
+ * Transforms a raw byte stream into an MP4Sample stream using mp4box.js.
+ */
+export declare class SampleTransform {
+    readonly readable: ReadableStream<TransformChunk>;
+    readonly writable: WritableStream<Uint8Array>;
+    private inputBufOffset;
+    private isStreamCancelled;
+    constructor();
+    private initMP4Box;
+}

package/dist/sprite/base-sprite.d.ts

@@ -0,0 +1,273 @@
+import { default as EventEmitter } from '../event-emitter';
+import { IAnimation, AnimationTransform } from '../animation';
+import { IChromaKeyOpts } from '../clips/iclip';
+import { ColorAdjustment } from '../utils/color-adjustment';
+import { IClipTiming } from '@agrhub/core';
+type IRectBaseProps = any;
+interface IAnimationOptions {
+    duration: number;
+    delay?: number;
+    iterCount?: number;
+}
+type TAnimateProps = IRectBaseProps & {
+    opacity: number;
+};
+export type TAnimationKeyFrame = Array<[number, Partial<TAnimateProps>]>;
+type TKeyFrameOptions = Partial<Record<`${number}%` | "from" | "to", Partial<TAnimateProps>>>;
+export interface BaseSpriteEvents {
+    propsChange: Partial<{
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+        angle: number;
+        zIndex: number;
+        opacity: number;
+        volume: number;
+        animations: IAnimation[];
+        locked: boolean;
+        muted: boolean;
+    }>;
+    [key: string]: any;
+    [key: symbol]: any;
+}
+/**
+ * Sprite base class
+ *
+ * @see {@link OffscreenSprite}
+ */
+export declare abstract class BaseSprite<T extends BaseSpriteEvents = BaseSpriteEvents> extends EventEmitter<T> {
+    /**
+     * Unique identifier for the sprite/clip
+     */
+    id: string;
+    /**
+     * Name of the sprite/clip
+     */
+    name: string;
+    /**
+     * Nested timing property group (Phase 1 Refactoring)
+     */
+    timing: IClipTiming;
+    /**
+     * Control display time range of clips, commonly used in editing scenario timeline (track) module
+     * from: start time offset in microseconds
+     * to: end time (from + duration) in microseconds
+     */
+    get display(): {
+        from: number;
+        to: number;
+    };
+    set display(v: {
+        from: number;
+        to: number;
+    });
+    /**
+     * Duration of the clip in microseconds
+     * Cannot exceed the duration of the referenced {@link IClip}
+     */
+    get duration(): number;
+    set duration(v: number);
+    /**
+     * Playback rate of current clip, 1 means normal playback
+     * **Note**
+     *    1. When setting playbackRate, duration must be actively corrected
+     *    2. Audio uses the simplest interpolation algorithm to change rate, so changing rate will cause pitch variation, for custom algorithm please use {@link Video.tickInterceptor} to implement
+     */
+    get playbackRate(): number;
+    set playbackRate(v: number);
+    /**
+     * Trim range of the source media in microseconds
+     * from: start time in microseconds
+     * to: end time in microseconds
+     */
+    get trim(): {
+        from: number;
+        to: number;
+    };
+    set trim(v: {
+        from: number;
+        to: number;
+    });
+    constructor();
+    protected _left: number;
+    /**
+     * Left position (x coordinate)
+     */
+    get left(): number;
+    set left(v: number);
+    protected _top: number;
+    /**
+     * Top position (y coordinate)
+     */
+    get top(): number;
+    set top(v: number);
+    protected _width: number;
+    /**
+     * Width
+     */
+    get width(): number;
+    set width(v: number);
+    protected _height: number;
+    /**
+     * Height
+     */
+    get height(): number;
+    set height(v: number);
+    private _angle;
+    /**
+     * Rotation angle in degrees
+     */
+    get angle(): number;
+    set angle(v: number);
+    /**
+     * Center point calculated from position and dimensions
+     */
+    get center(): {
+        x: number;
+        y: number;
+    };
+    private _zIndex;
+    get zIndex(): number;
+    /**
+     * Control layering relationship between clips, clips with smaller zIndex will be occluded
+     */
+    set zIndex(v: number);
+    private _opacity;
+    /**
+     * Opacity (0.0 to 1.0)
+     */
+    get opacity(): number;
+    set opacity(v: number);
+    private _volume;
+    /**
+     * Audio volume level (0.0 to 1.0)
+     */
+    get volume(): number;
+    set volume(v: number);
+    private _locked;
+    /**
+     * Whether the sprite is locked (preventing interactions)
+     */
+    get locked(): boolean;
+    set locked(v: boolean);
+    private _muted;
+    /**
+     * Whether the clip's audio is muted (volume is kept, so unmuting restores it)
+     */
+    get muted(): boolean;
+    set muted(v: boolean);
+    private _trackMuted;
+    /**
+     * Set by Studio/Compositor when the clip's track is muted. Not serialized and does not emit
+     * propsChange, so it can be refreshed every frame.
+     */
+    get trackMuted(): boolean;
+    set trackMuted(v: boolean);
+    /** Called when the track-level mute flips (clip-level changes arrive via propsChange). */
+    protected onEffectiveVolumeChange(): void;
+    /** Volume actually applied to audio output: 0 when the clip or its track is muted. */
+    get effectiveVolume(): number;
+    /**
+     * Flip clip horizontally or vertically
+     */
+    flip: {
+        x: boolean;
+        y: boolean;
+    } | null;
+    effects: Array<{
+        id: string;
+        key: string;
+        startTime: number;
+        duration: number;
+        targets?: number[];
+    }>;
+    /**
+     * Chroma key settings (green screen removal)
+     */
+    chromaKey?: IChromaKeyOpts;
+    colorAdjustment?: ColorAdjustment;
+    /**
+     * Styling properties (e.g., stroke, dropShadow, borderRadius)
+     * This is a generic object to hold visual styles across different clip types
+     */
+    protected _style: any;
+    get style(): any;
+    set style(v: any);
+    private animatKeyFrame;
+    private animatOptions;
+    private _animations;
+    /**
+     * List of active animations.
+     * When setting this property, raw objects are automatically converted to IAnimation instances.
+     */
+    get animations(): IAnimation[];
+    set animations(v: IAnimation[]);
+    /**
+     * Current transform offsets/multipliers from animations
+     * Resets every frame in animate()
+     */
+    renderTransform: AnimationTransform;
+    /**
+     * @see {@link IClip.ready}
+     * For clips, this should be Promise<IClipMeta>, but for BaseSprite it's just Promise<void>
+     */
+    protected _render(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
+    /**
+     * Add animation to clip, usage reference CSS animation
+     *
+     * @example
+     * sprite.setAnimation(
+     *   {
+     *     '0%': { x: 0, y: 0 },
+     *     '25%': { x: 1200, y: 680 },
+     *     '50%': { x: 1200, y: 0 },
+     *     '75%': { x: 0, y: 680 },
+     *     '100%': { x: 0, y: 0 },
+     *   },
+     *   { duration: 4e6, iterCount: 1 },
+     * );
+     *
+     */
+    setAnimation(keyFrame: TKeyFrameOptions, options: IAnimationOptions): void;
+    /**
+     * If current sprite has animation set, set sprite's animation properties to state at specified time
+     */
+    animate(time: number, target?: any): void;
+    /**
+     * Add a modular animation to the clip
+     * @param name Preset name or 'keyframes'
+     * @param opts Animation options (duration, delay, etc.)
+     * @param params Preset-specific parameters or KeyframeData
+     */
+    addAnimation(name: string, options: any, params?: any): string;
+    /**
+     * Remove an animation by ID
+     */
+    removeAnimation(id: string): void;
+    /**
+     * Clear all modular animations
+     */
+    clearAnimations(): void;
+    /**
+     * Update an existing animation by ID
+     * @param id Animation ID to update
+     * @param type Animation type (preset name or 'keyframes')
+     * @param opts Animation options
+     * @param params Preset-specific parameters or KeyframeData
+     */
+    updateAnimation(id: string, type: string, options: any, params?: any): void;
+    /**
+     * Copy current sprite's properties to target
+     *
+     * Used for cloning or copying state between {@link OffscreenSprite} instances
+     */
+    copyStateTo<T extends BaseSprite>(target: T): void;
+    /**
+     * Update multiple properties at once
+     */
+    update(updates: Partial<this>): void;
+    protected destroy(): void;
+}
+export declare function linearTimeFn(time: number, keyFrame: TAnimationKeyFrame, options: Required<IAnimationOptions>): Partial<TAnimateProps>;
+export {};