@agrhub/engine-pixi 0.0.0-stage → 1.3.3

package/dist/clips/clip-registry.d.ts

@@ -0,0 +1,56 @@
+import { IClip } from './iclip';
+export interface TrackCaptionConfig {
+    style?: Record<string, any>;
+    colors?: {
+        active?: {
+            color?: string;
+            background?: string;
+            border?: {
+                color?: string;
+                width?: number;
+            };
+        } | null;
+        future?: {
+            color?: string;
+            border?: {
+                color?: string;
+                width?: number;
+            };
+        } | null;
+        keyword?: {
+            color?: string;
+            preserveAfterSpoken?: boolean;
+        } | null;
+    };
+    positioning?: {
+        videoWidth?: number;
+        videoHeight?: number;
+        bottomOffset?: number;
+    };
+    wordsPerLine?: "single" | "multiple";
+}
+export interface ClipContext {
+    captionConfig?: TrackCaptionConfig;
+}
+export type ClipClass = {
+    fromObject(json: any, context?: ClipContext): Promise<IClip>;
+};
+/**
+ * Registry mapping clip type strings to their class constructors.
+ * Supports default core clips and dynamic registration of custom clip types.
+ */
+export declare class ClipRegistry {
+    private static registry;
+    /**
+     * Register a clip class under a type name.
+     */
+    static register(type: string, klass: ClipClass): void;
+    /**
+     * Retrieve the registered clip class for a type.
+     */
+    static get(type: string): ClipClass | undefined;
+    /**
+     * Get all registered clip types.
+     */
+    static getRegisteredTypes(): string[];
+}

package/dist/clips/effect-clip.d.ts

@@ -0,0 +1,37 @@
+import { BaseClip } from './base-clip';
+import { IClip } from './iclip';
+import { EffectKey } from '../effect/glsl/gl-effect';
+export declare class Effect extends BaseClip {
+    readonly type = "Effect";
+    ready: IClip["ready"];
+    private _meta;
+    get meta(): {
+        duration: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * Unique identifier for this clip instance
+     */
+    id: string;
+    /**
+     * The effect key
+     */
+    effectKey: EffectKey;
+    /**
+     * Effect parameters / values
+     */
+    values: Record<string, any>;
+    constructor(effectKey: EffectKey);
+    clone(): Promise<this>;
+    tick(_time: number): Promise<{
+        video: ImageBitmap | undefined;
+        state: "success";
+    }>;
+    split(_time: number): Promise<[this, this]>;
+    toJSON(_main?: boolean): any;
+    /**
+     * Create an Effect instance from a JSON object
+     */
+    static fromObject(json: any): Promise<Effect>;
+}

package/dist/clips/iclip.d.ts

@@ -0,0 +1,231 @@
+import { BaseSprite, BaseSpriteEvents } from '../sprite/base-sprite';
+import { ColorAdjustment } from '../utils/color-adjustment';
+export interface IClipMeta {
+    width: number;
+    height: number;
+    duration: number;
+}
+export interface ITransitionInfo {
+    name: string;
+    duration: number;
+    textureUrl?: string;
+    prevClipId?: string;
+    fromClipId?: string;
+    toClipId?: string;
+    start?: number;
+    end?: number;
+}
+export interface IChromaKeyOpts {
+    enabled: boolean;
+    color: string;
+    similarity: number;
+    spill: number;
+}
+/**
+ * Interface that all clips must implement
+ *
+ * Clips are abstractions of different data types, providing data to other modules
+ *
+ *
+ * You only need to implement this interface to create custom clips, giving you maximum flexibility to generate video content such as animations and transition effects
+ *
+ */
+export interface IClip<T extends BaseSpriteEvents = BaseSpriteEvents> extends Omit<BaseSprite<T>, "destroy" | "ready"> {
+    destroy: () => void;
+    readonly ready: Promise<IClipMeta>;
+    /**
+     * Clip type (e.g., 'video', 'image', 'text', 'audio')
+     */
+    readonly type: string;
+    /**
+     * Name of this clip
+     */
+    name: string;
+    /**
+     * User-defined metadata
+     */
+    metadata: Record<string, any>;
+    /**
+     * Source URL or identifier for this clip
+     */
+    src: string;
+    /**
+     * Extract data from clip at specified time
+     * @param time Time in microseconds
+     */
+    tick: (time: number) => Promise<{
+        video?: VideoFrame | ImageBitmap | null;
+        audio?: Float32Array[];
+        state: "done" | "success";
+    }>;
+    /**
+     * Get video frame and audio at specified time
+     * This method is provided by BaseClip and used by Compositor
+     */
+    getFrame(time: number): Promise<{
+        video: VideoFrame | ImageBitmap | null;
+        audio: Float32Array[];
+        done: boolean;
+    }>;
+    /**
+     * Data metadata
+     */
+    readonly meta: IClipMeta;
+    /**
+     * When set, the clip's RenderTexture is larger than its logical bounds by this many pixels
+     * on each side (top, right, bottom, left). This provides transparent overflow room so that
+     * animations (e.g. slide, zoom) can move content outside the clip boundary without clipping.
+     * Selection handles, hit areas, and position sync all use the logical bounds, not the texture size.
+     */
+    renderTexturePadding?: number;
+    /**
+     * Clone and return a new clip
+     */
+    clone: () => Promise<this>;
+    /**
+     * Split at specified time, return two new clips before and after that moment, commonly used in editing scenarios to split clips by time
+     *
+     * This method will not corrupt original clip data
+     *
+     * @param time Time in microseconds
+     * @returns
+     */
+    split?: (time: number) => Promise<[this, this]>;
+    /**
+     * Serialize clip to JSON format
+     * Returns a plain object with only serializable data (no circular references)
+     * @param main Whether this is the main clip (for Compositor)
+     */
+    toJSON(main?: boolean): any;
+    /**
+     * Set an external renderer (e.g., from Studio)
+     * This is called by Studio when adding clips to provide a shared renderer
+     * @param renderer The PixiJS renderer to use
+     */
+    setRenderer?(renderer: any): void;
+    /**
+     * Transition info (optional)
+     */
+    transition?: ITransitionInfo;
+    /**
+     * Audio volume level (0-1)
+     */
+    volume: number;
+    /**
+     * Styling properties (e.g., stroke, dropShadow, borderRadius)
+     */
+    style: any;
+    /**
+     * Get the list of visible transformer handles for this clip type
+     * Similar to Fabric.js v6 controls visibility pattern
+     * @returns Array of handle kinds that should be visible
+     */
+    getVisibleHandles?: () => Array<"tl" | "tr" | "bl" | "br" | "ml" | "mr" | "mt" | "mb" | "rot">;
+    /**
+     * Scale clip to fit within the scene dimensions while maintaining aspect ratio
+     */
+    scaleToFit(sceneWidth: number, sceneHeight: number): Promise<void>;
+    /**
+     * Scale clip to fill the scene dimensions while maintaining aspect ratio
+     */
+    scaleToFill(sceneWidth: number, sceneHeight: number): Promise<void>;
+    /**
+     * Center the clip within the scene dimensions
+     */
+    centerInScene(sceneWidth: number, sceneHeight: number): 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;
+    /**
+     * List of active animations
+     */
+    readonly animations: any[];
+    /**
+     * Chroma key settings (green screen removal)
+     */
+    chromaKey?: IChromaKeyOpts;
+    /**
+     * Clip color adjustment settings
+     */
+    colorAdjustment?: ColorAdjustment;
+    /**
+     * Whether the clip is locked (preventing interactions)
+     */
+    locked: boolean;
+}
+/**
+ * Optional interface for clips that support HTML media element playback
+ * Used by Studio for interactive preview
+ */
+export interface IPlaybackCapable {
+    /**
+     * Create and initialize HTML media element for playback
+     * @returns Promise resolving to the media element and optional object URL for cleanup
+     */
+    createPlaybackElement(): Promise<{
+        element: HTMLVideoElement | HTMLAudioElement;
+        objectUrl?: string;
+    }>;
+    /**
+     * Start playback at a specific time
+     * @param element The HTML media element
+     * @param timeSeconds Time in seconds (relative to clip start)
+     */
+    play(element: HTMLVideoElement | HTMLAudioElement, timeSeconds: number): Promise<void>;
+    /**
+     * Pause playback
+     * @param element The HTML media element
+     */
+    pause(element: HTMLVideoElement | HTMLAudioElement): void;
+    /**
+     * Seek to a specific time
+     * @param element The HTML media element
+     * @param timeSeconds Time in seconds (relative to clip start)
+     */
+    seek(element: HTMLVideoElement | HTMLAudioElement, timeSeconds: number): Promise<void>;
+    /**
+     * Sync playback state during preview
+     * @param element The HTML media element
+     * @param isPlaying Whether playback should be active
+     * @param timeSeconds Current time in seconds (relative to clip start)
+     */
+    syncPlayback(element: HTMLVideoElement | HTMLAudioElement, isPlaying: boolean, timeSeconds: number): void;
+    /**
+     * Clean up playback element and resources
+     * @param element The HTML media element
+     * @param objectUrl Optional object URL to revoke
+     */
+    cleanupPlayback(element: HTMLVideoElement | HTMLAudioElement, objectUrl?: string): void;
+}
+/**
+ * Get the default audio configuration
+ * This function returns a promise that resolves to the best supported audio codec
+ */
+export declare function getDefaultAudioConf(): Promise<{
+    codec: string;
+    sampleRate: number;
+    channelCount: number;
+}>;
+/**
+ * Synchronous version that returns cached codec or a default fallback
+ * Use this only when you need synchronous access (e.g., in constants)
+ * Prefer getDefaultAudioConf() for async contexts
+ */
+export declare const DEFAULT_AUDIO_CONF: {
+    readonly codec: string;
+    readonly codecType: "aac" | "opus";
+    readonly sampleRate: number;
+    readonly channelCount: number;
+};

package/dist/clips/image-clip.d.ts

@@ -0,0 +1,116 @@
+import { Texture } from 'pixi.js';
+import { BaseClip } from './base-clip';
+import { IClip } from './iclip';
+import { ClipJSON, ImageJSON } from '../json-serialization';
+type AnimateImgType = "avif" | "webp" | "png" | "gif";
+/**
+ * Image clip supporting animated images
+ *
+ * Ordinary text can be converted to image clip using {@link renderTxt2ImgBitmap}
+ *
+ * @example
+ * // Load from URL using PixiJS Assets (optimized for Studio)
+ * const imgClip = await Image.fromUrl('path/to/image.png');
+ *
+ * @example
+ * // Traditional approach (for Compositor/export)
+ * new Image((await fetch('<img url>')).body);
+ *
+ * @example
+ * new Image(
+ *   await renderTxt2ImgBitmap(
+ *     'Watermark',
+ *    `font-size:40px; color: white; text-shadow: 2px 2px 6px red;`,
+ *   )
+ * )
+ *
+ */
+export declare class Image extends BaseClip implements IClip {
+    readonly type = "Image";
+    ready: IClip["ready"];
+    private _meta;
+    /**
+     * ⚠️ Static images have duration of Infinity
+     *
+     * When wrapping with Sprite, you need to set its duration to a finite number
+     *
+     */
+    get meta(): {
+        duration: number;
+        width: number;
+        height: number;
+    };
+    private img;
+    private pixiTexture;
+    private frames;
+    /**
+     * Unique identifier for this clip instance
+     */
+    id: string;
+    /**
+     * Array of effects to be applied to this clip
+     * Each effect specifies key, startTime, duration, and optional targets
+     */
+    effects: Array<{
+        id: string;
+        key: string;
+        startTime: number;
+        duration: number;
+    }>;
+    getVisibleHandles(): Array<"tl" | "tr" | "bl" | "br" | "ml" | "mr" | "mt" | "mb" | "rot">;
+    /**
+     * Load an image clip from a URL using PixiJS Assets
+     * This is optimized for Studio as it uses Texture directly
+     *
+     * @param url Image URL
+     * @param src Optional source identifier for serialization
+     * @returns Promise that resolves to an Image instance
+     *
+     * @example
+     * const imgClip = await Image.fromUrl('path/to/image.png');
+     */
+    static fromUrl(url: string, src?: string): Promise<Image>;
+    /**
+     * Get the PixiJS Texture (if available)
+     * This is used for optimized rendering in Studio
+     */
+    getTexture(): Texture | null;
+    /**
+     * Static images can be initialized using stream or ImageBitmap
+     *
+     * Animated images need to use VideoFrame[] or provide image type
+     */
+    constructor(dataSource: ReadableStream | ImageBitmap | VideoFrame[] | {
+        type: `image/${AnimateImgType}`;
+        stream: ReadableStream;
+    }, src?: string);
+    private initAnimateImg;
+    tickInterceptor: <T extends Awaited<ReturnType<Image["tick"]>>>(time: number, tickRet: T) => Promise<T>;
+    tick(time: number): Promise<{
+        video: ImageBitmap | VideoFrame;
+        state: "success";
+    }>;
+    split(time: number): Promise<[this, this]>;
+    clone(): Promise<this>;
+    addEffect(effect: {
+        id: string;
+        key: string;
+        startTime: number;
+        duration: number;
+    }): void;
+    editEffect(effectId: string, newEffectData: Partial<{
+        key: string;
+        startTime: number;
+        duration: number;
+    }>): void;
+    removeEffect(effectId: string): void;
+    destroy(): void;
+    toJSON(main?: boolean): ImageJSON;
+    /**
+     * Create an Image instance from a JSON object (fabric.js pattern)
+     * @param json The JSON object representing the clip
+     * @returns Promise that resolves to an Image instance
+     */
+    static fromObject(json: ClipJSON): Promise<Image>;
+}
+export {};

package/dist/clips/index.d.ts

@@ -0,0 +1,20 @@
+export * from './audio-clip';
+export * from './caption-clip';
+export * from './iclip';
+export * from './image-clip';
+export * from './video-clip';
+export { Video } from './video-clip';
+export type { IMP4ClipOpts } from './video-clip';
+export * from './base-text-clip';
+export * from './text-clip';
+export * from './effect-clip';
+export { Effect } from './effect-clip';
+export * from './placeholder-clip';
+export { Placeholder } from './placeholder-clip';
+export * from './transition-clip';
+export { Transition } from './transition-clip';
+export * from './shape-clip';
+export { ShapeClip } from './shape-clip';
+export * from './backdrop-clip';
+export { Backdrop } from './backdrop-clip';
+export * from './clip-registry';

package/dist/clips/placeholder-clip.d.ts

@@ -0,0 +1,22 @@
+import { BaseClip } from './base-clip';
+import { IClipMeta } from './iclip';
+export declare class Placeholder extends BaseClip {
+    type: string;
+    meta: IClipMeta;
+    constructor(src: string, meta?: Partial<IClipMeta>, type?: string);
+    private canvas;
+    private ctx;
+    private animationRafId;
+    private renderPending;
+    tick(_time: number): Promise<{
+        video: ImageBitmap | VideoFrame | null;
+        audio: Float32Array[];
+        state: "done" | "success";
+    }>;
+    clone(): Promise<this>;
+    split(time: number): Promise<[this, this]>;
+    /**
+     * Create a Placeholder instance from a JSON object
+     */
+    static fromObject(json: any): Promise<Placeholder>;
+}

package/dist/clips/shape-clip.d.ts

@@ -0,0 +1,59 @@
+import { Graphics, Application } from 'pixi.js';
+import { BaseClip } from './base-clip';
+import { ShapeType } from '@agrhub/core';
+import { IClipMeta } from './iclip';
+export interface ShapeClipOptions {
+    shapeType: ShapeType;
+    width?: number;
+    height?: number;
+    fill?: string;
+    fillOpacity?: number;
+    stroke?: {
+        color: string;
+        width: number;
+    };
+    borderRadius?: number;
+    renderer?: Application["renderer"];
+}
+/**
+ * ShapeClip renders rectangle shapes using Pixi.js Graphics
+ */
+export declare class ShapeClip extends BaseClip {
+    readonly type = "Shape";
+    shapeType: ShapeType;
+    graphics: Graphics;
+    private _meta;
+    private renderTexture;
+    private externalRenderer;
+    constructor(options: ShapeClipOptions);
+    private getRenderer;
+    /**
+     * Set an external renderer (e.g., from Studio)
+     */
+    setRenderer(renderer: Application["renderer"]): void;
+    /**
+     * Get or create the render texture for this shape
+     */
+    private getRenderTexture;
+    get meta(): IClipMeta;
+    private drawShape;
+    private drawRectangle;
+    private hexToNumber;
+    tick(_time: number): Promise<{
+        video: ImageBitmap;
+        state: "success";
+    }>;
+    clone(): Promise<this>;
+    split(_time: number): Promise<[this, this]>;
+    toJSON(main?: boolean): any;
+    set style(style: any);
+    get style(): any;
+    set width(width: number);
+    get width(): number;
+    set height(height: number);
+    get height(): number;
+    /**
+     * Create ShapeClip from JSON object
+     */
+    static fromObject(json: any): Promise<ShapeClip>;
+}

package/dist/clips/text-clip.d.ts

@@ -0,0 +1,148 @@
+import { Application, Container } from 'pixi.js';
+import { IClip } from './iclip';
+import { TextJSON } from '../json-serialization';
+import { BaseSpriteEvents } from '../sprite/base-sprite';
+import { BaseTextClip, IBaseTextOpts } from './base-text-clip';
+export interface ITextOpts extends IBaseTextOpts {
+    /**
+     * Text decoration ('none', 'underline', 'line-through', 'overline')
+     * @default 'none'
+     */
+    textDecoration?: "none" | "underline" | "line-through" | "overline";
+    /**
+     * Words per line mode ('single' or 'multiple')
+     * @default 'multiple'
+     */
+    wordsPerLine?: "single" | "multiple";
+}
+export interface ITextEvents extends BaseSpriteEvents {
+    propsChange: Partial<{
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+        angle: number;
+        zIndex: number;
+        opacity: number;
+        volume: number;
+        text: string;
+        style: any;
+    } & ITextOpts>;
+}
+/**
+ * Text clip using PixiJS Text for rendering
+ *
+ * @example
+ * const textClip = new Text('Hello World', {
+ *   fontSize: 48,
+ *   fill: '#ffffff',
+ *   stroke: '#000000',
+ *   strokeWidth: 2,
+ *   dropShadow: {
+ *     color: '#000000',
+ *     alpha: 0.5,
+ *     blur: 4,
+ *     distance: 2,
+ *   },
+ * });
+ * textClip.duration = 5e6; // 5 seconds
+ */
+export declare class Text extends BaseTextClip<ITextEvents> {
+    readonly type = "Text";
+    ready: IClip["ready"];
+    get width(): number;
+    set width(v: number);
+    get height(): number;
+    /**
+     * Flag to track if height was explicitly set by user (vs auto-calculated from content)
+     */
+    private _explicitHeight;
+    /**
+     * Get whether height was explicitly set by user
+     */
+    get isExplicitHeight(): boolean;
+    /**
+     * Reset height to auto-fit mode (height will adjust to content)
+     */
+    resetHeightToAuto(): void;
+    set height(v: number);
+    /**
+     * Text content (hybrid JSON structure)
+     */
+    get text(): string;
+    set text(v: string);
+    /**
+     * Text styling (hybrid JSON structure)
+     * Provides direct access to styling properties
+     */
+    /**
+     * Text styling (hybrid JSON structure)
+     * Provides direct access to styling properties
+     */
+    get style(): any;
+    set style(opts: Partial<ITextOpts>);
+    /**
+     * Text alignment proxy for compatibility with UI
+     */
+    get textAlign(): "left" | "center" | "right";
+    set textAlign(v: "left" | "center" | "right");
+    /**
+     * Vertical alignment or decoration proxy
+     */
+    get verticalAlign(): string;
+    set verticalAlign(v: string);
+    /**
+     * Text case proxy
+     */
+    get textCase(): string;
+    set textCase(v: "none" | "uppercase" | "lowercase" | "title");
+    /**
+     * Decoration proxies for UI compatibility (booleans)
+     */
+    get underline(): boolean;
+    set underline(v: boolean);
+    get overline(): boolean;
+    set overline(v: boolean);
+    get linethrough(): boolean;
+    set linethrough(v: boolean);
+    protected _targetWidth: number;
+    private _wordCache;
+    private _measuredTextHeight;
+    private _lineHeightMultiplier;
+    private _fontSize;
+    private _textOnlyContainer;
+    originalOpts: ITextOpts;
+    constructor(text: string, opts?: ITextOpts, renderer?: Application["renderer"]);
+    _onAfterRefresh(words: string[], textOnlyContainer: Container, spaceWidth: number, measuredTextHeight: number, lineHeightMultiplier: number, fontSize: number): void;
+    clone(): Promise<this>;
+    /**
+     * Update text styling options and refresh the texture
+     */
+    updateStyle(opts: Partial<ITextOpts>): Promise<void>;
+    private _populateWordCache;
+    /**
+     * Fast layout update for real-time transform operations.
+     * Re-calculates word wrapping and repositions existing text objects without
+     * re-creating them. Much faster than full refreshText() for resize operations.
+     *
+     * @param targetWidth - The new target width for wrapping
+     * @returns Object with new width and height
+     */
+    updateLayoutForWidth(targetWidth: number): {
+        width: number;
+        height: number;
+    };
+    toJSON(main?: boolean): TextJSON;
+    /**
+     * Create a Text instance from a JSON object (fabric.js pattern)
+     * @param json The JSON object representing the clip
+     * @returns Promise that resolves to a Text instance
+     */
+    static fromObject(json: TextJSON): Promise<Text>;
+    /**
+     * Override handle visibility for text clips
+     * Text clips should only show: mr (mid-right), mb (mid-bottom), br (bottom-right), and rot (rotation)
+     * This allows resizing width and height independently while preventing corner handles that might distort text
+     */
+    getVisibleHandles(): Array<"tl" | "tr" | "bl" | "br" | "ml" | "mr" | "mt" | "mb" | "rot">;
+}