@agrhub/engine-pixi 0.0.0-stage → 1.3.3

package/LICENSE

@@ -0,0 +1,47 @@
+# OpenVideo License
+
+Depending on the type of your legal entity, you are granted permission to use OpenVideo for your project. Individuals and small companies are allowed to use OpenVideo for free (even commercially), while a company license is required for for-profit organizations of a certain size. This two-tier system was designed to ensure funding for this project while still allowing the source code to be available and the program to be free for most. Read below for the exact terms of use.
+
+- [Free License](#free-license)
+- [Company License](#company-license)
+
+## Free License
+
+Copyright © 2026 [OpenVideo](https://openvideo.dev)
+
+### Eligibility
+
+You are eligible to use OpenVideo for free if you are:
+
+- an individual
+- a for-profit organization with up to 3 employees
+- a non-profit or not-for-profit organization
+- evaluating whether OpenVideo is a good fit, and are not yet using it in a commercial way
+
+### Allowed use cases
+
+Permission is hereby granted, free of charge, to any person eligible for the "Free License", to use the software non-commercially or commercially for the purpose of creating videos and images and to modify the software to their own liking, for the purpose of fulfilling their custom use case or to contribute bug fixes or improvements back to OpenVideo.
+
+This license applies to all packages, applications, and services within the OpenVideo monorepo.
+
+### Disallowed use cases
+
+It is not allowed to copy or modify OpenVideo code for the purpose of selling, renting, licensing, relicensing, or sublicensing your own derivative of OpenVideo.
+
+### Warranty notice
+
+The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. In no event shall the author or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.
+
+### Support
+
+Support is provided on a best-we-can-do basis via GitHub Issues and Discord.
+
+## Company License
+
+You are required to obtain a Company License to use OpenVideo if you are not within the group of entities eligible for a Free License. This license will enable you to use OpenVideo for the allowed use cases specified in the Free License.
+
+Contact hello@openvideo.dev for pricing and to buy a license.
+
+### FAQs
+
+Are you not sure whether you need a Company License because of an edge case? Contact hello@openvideo.dev with your situation.

package/NOTICE.md

@@ -0,0 +1,19 @@
+# Notice
+
+`@agrhub/engine-pixi` is a modified fork of [`@openvideo/engine-pixi`](https://www.npmjs.com/package/@openvideo/engine-pixi) (based on 1.3.2),
+part of OpenVideo by OpenVideoDev (https://openvideo.dev).
+
+It is distributed under the **OpenVideo License** — see [LICENSE](./LICENSE). That license applies to
+this fork as well: in particular, organisations that are not eligible for the Free License need an
+OpenVideo Company License, and the code may not be copied or modified to sell, rent, license,
+relicense or sublicense a derivative of OpenVideo.
+
+## Changes in this fork
+
+- Renamed to @agrhub/engine-pixi; source rebuilt from OpenVideo 1.3.0 with the 1.3.2 changes ported (Backdrop clip, BlockRevealAnimation, text/caption layout, effect and bridge fixes).
+- Dependencies are external (single PixiJS/@agrhub/core instance in the app); a self-contained build is published at "@agrhub/engine-pixi/standalone".
+- Video: the first decodable frame is held before its timestamp (no black frames at clip start); stale overlapping updateFrame calls no longer hide frames.
+- Captions/Text: glyph atlases are not cached before the web font loads; refreshes resolve after the final pass; track/clip styles (background, lineHeight, letterSpacing, textCase) are applied.
+- Shared MediaCache: one download per URL (in-flight dedupe + memory LRU + atomic OPFS persistence).
+- StudioBridge: patches applied in order, rebuilds coalesced, latest-wins seeking, listener-safe dispose.
+- Export: falls back to an encodable audio codec (AAC -> 44.1 kHz -> Opus) instead of failing; long audio decodes no longer abort the export.

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# @agrhub/engine-pixi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fork of `@openvideo/engine-pixi` for the AgrHub video editor. See [NOTICE.md](./NOTICE.md) for the changes and licensing.
+
+```bash
+npm install @agrhub/engine-pixi
+```

package/dist/animation/block-reveal-animation.d.ts

@@ -0,0 +1,33 @@
+import { AnimationOptions, AnimationTransform, IAnimation } from './types';
+export type BlockRevealDirection = "left" | "right" | "top" | "bottom";
+/**
+ * "reveal": a solid block grows across the text, then retracts the other way, uncovering it.
+ * Any other mode: a block of `blockSize` sweeps across the text.
+ */
+export type BlockRevealMode = "reveal" | "sweep";
+export interface BlockRevealParams {
+    /** Block colour (default white) */
+    blockColor?: string | number;
+    /** Colour of the text where the block covers it (default black) */
+    textColorInside?: string | number;
+    direction?: BlockRevealDirection;
+    mode?: BlockRevealMode;
+    /** Sweep mode: block size as a fraction of the line (default 0.3) */
+    blockSize?: number;
+}
+/**
+ * BlockRevealAnimation (text/caption clips)
+ *
+ * A coloured block wipes across each text line; where it covers the text, the text is drawn in
+ * `textColorInside`. Draws directly on the clip's text container in apply().
+ */
+export declare class BlockRevealAnimation implements IAnimation {
+    readonly id: string;
+    readonly type = "blockReveal";
+    readonly options: Required<AnimationOptions>;
+    readonly params: BlockRevealParams;
+    constructor(params: BlockRevealParams, options: AnimationOptions);
+    getTransform(_time: number): AnimationTransform;
+    apply(target: any, time: number): void;
+    cleanup(target: any): void;
+}

package/dist/animation/easings.d.ts

@@ -0,0 +1,4 @@
+import { EasingFunction } from './types';
+export declare const easings: Record<string, EasingFunction>;
+export declare function createSlowMo(linearRatio?: number, power?: number, yoyoMode?: boolean): EasingFunction;
+export declare function getEasing(easing: string | EasingFunction | undefined): EasingFunction;

package/dist/animation/gsap-animation.d.ts

@@ -0,0 +1,32 @@
+import { AnimationOptions, AnimationTransform, IAnimation } from './types';
+export interface GsapAnimationParams {
+    /**
+     * Animation presets or custom GSAP vars
+     */
+    type: "character" | "word" | "line";
+    from: gsap.TweenVars;
+    to: gsap.TweenVars;
+    stagger?: number | gsap.StaggerVars;
+}
+export declare class GsapAnimation implements IAnimation {
+    readonly id: string;
+    readonly type: string;
+    readonly options: Required<AnimationOptions>;
+    readonly params: GsapAnimationParams;
+    private timeline;
+    private lastTarget;
+    private originalProperties;
+    constructor(params: GsapAnimationParams, options: AnimationOptions, type?: string);
+    getTransform(_time: number): AnimationTransform;
+    get isOutAnimation(): boolean;
+    restoreOriginals(): void;
+    getTargetCount(target: any): number;
+    apply(target: any, time: number): void;
+    /**
+     * Get current animation targets from the container based on animation type.
+     * Used to compare against GSAP's cached targets to detect when children are recreated.
+     */
+    private getCurrentTargets;
+    private initTimeline;
+    destroy(): void;
+}

package/dist/animation/index.d.ts

@@ -0,0 +1,9 @@
+export * from './types';
+export * from './easings';
+export * from './registry';
+export * from './keyframe-animation';
+export * from './wipe-animation';
+export * from './block-reveal-animation';
+export * from './mask-animation';
+export * from './gsap-animation';
+export * from './pixi-animation-utils';

package/dist/animation/keyframe-animation.d.ts

@@ -0,0 +1,11 @@
+import { AnimationOptions, AnimationTransform, IAnimation, KeyframeData } from './types';
+export declare class KeyframeAnimation implements IAnimation {
+    readonly id: string;
+    readonly type: string;
+    readonly options: Required<AnimationOptions>;
+    readonly params: any;
+    private frames;
+    constructor(data: KeyframeData | any[], options: AnimationOptions, type?: string);
+    getTransform(time: number): AnimationTransform;
+    private interpolateProps;
+}

package/dist/animation/mask-animation.d.ts

@@ -0,0 +1,145 @@
+import { AnimationOptions, AnimationTransform, IAnimation, MaskTransform } from './types';
+/**
+ * Base class for all mask animations.
+ * Subclasses override `buildMask(progress)` to define the mask shape.
+ */
+declare abstract class BaseMaskAnimation implements IAnimation {
+    readonly id: string;
+    abstract readonly type: string;
+    readonly options: Required<AnimationOptions>;
+    readonly params: any;
+    constructor(params: any, options: AnimationOptions);
+    getTransform(time: number): AnimationTransform;
+    protected abstract buildMask(progress: number): MaskTransform;
+}
+export interface CircleRevealParams {
+    mode?: "reveal" | "conceal";
+    /** Origin of expansion. Default: "center" */
+    origin?: MaskTransform["origin"];
+    /** Feather (soft edge) in pixels */
+    feather?: number;
+}
+/**
+ * CircleReveal / CircleConceal
+ *
+ * An ellipse mask that expands from an origin point outward (or contracts inward).
+ * Works on any clip type.
+ *
+ * ```ts
+ * clip.addAnimation("circleReveal", { duration: 1_000_000, easing: "easeOutCubic" }, {
+ *   mode: "reveal",
+ *   origin: "center",
+ *   feather: 10,
+ * });
+ * ```
+ */
+export declare class CircleRevealAnimation extends BaseMaskAnimation {
+    readonly type = "circleReveal";
+    constructor(params: CircleRevealParams, options: AnimationOptions);
+    protected buildMask(progress: number): MaskTransform;
+}
+export interface RectExpandParams {
+    mode?: "reveal" | "conceal";
+    /** Origin of expansion. Default: "center" */
+    origin?: MaskTransform["origin"];
+    /** Feather in pixels */
+    feather?: number;
+}
+/**
+ * RectExpand / RectShrink
+ *
+ * A rectangle mask that grows outward from an origin (or shrinks inward).
+ * Useful for "iris box" style reveals.
+ *
+ * ```ts
+ * clip.addAnimation("rectExpand", { duration: 1_000_000, easing: "easeInOutQuad" }, {
+ *   mode: "reveal",
+ *   origin: "center",
+ * });
+ * ```
+ */
+export declare class RectExpandAnimation extends BaseMaskAnimation {
+    readonly type = "rectExpand";
+    constructor(params: RectExpandParams, options: AnimationOptions);
+    protected buildMask(progress: number): MaskTransform;
+}
+export interface CenterExpandParams {
+    mode?: "reveal" | "conceal";
+    /**
+     * Axis of expansion:
+     *   "vertical"   → starts full-width, expands top + bottom (default)
+     *   "horizontal" → starts full-height, expands left + right
+     *   "both"       → expands in all directions simultaneously (true center iris)
+     */
+    axis?: "vertical" | "horizontal" | "both";
+}
+/**
+ * CenterExpand
+ *
+ * Reveals the clip from the center outward.
+ * Default: starts as a full-width zero-height bar, expands up and down.
+ *
+ * ```ts
+ * clip.addAnimation("centerExpand", { duration: 1_000_000, easing: "easeOutCubic" }, {
+ *   mode: "reveal",
+ *   axis: "vertical",
+ * });
+ * ```
+ */
+export declare class CenterExpandAnimation extends BaseMaskAnimation {
+    readonly type = "centerExpand";
+    constructor(params: CenterExpandParams, options: AnimationOptions);
+    protected buildMask(progress: number): MaskTransform;
+}
+export interface AngleWipeParams {
+    mode?: "reveal" | "conceal";
+    /** Wipe angle in degrees. 0 = left→right, 90 = top→bottom, 45 = diagonal */
+    angle?: number;
+    /** Feather in pixels */
+    feather?: number;
+}
+/**
+ * AngleWipe
+ *
+ * A wipe that sweeps at an arbitrary angle (diagonal, rotated, etc.).
+ * The `angle` param rotates the sweep direction from the default left→right.
+ *
+ * ```ts
+ * clip.addAnimation("angleWipe", { duration: 1_000_000, easing: "linear" }, {
+ *   mode: "reveal",
+ *   angle: 45, // diagonal
+ * });
+ * ```
+ */
+export declare class AngleWipeAnimation extends BaseMaskAnimation {
+    readonly type = "angleWipe";
+    constructor(params: AngleWipeParams, options: AnimationOptions);
+    protected buildMask(progress: number): MaskTransform;
+}
+export interface StarRevealParams {
+    mode?: "reveal" | "conceal";
+    /** Number of star points. Default: 5 */
+    points?: number;
+    /** Inner radius ratio relative to outer (0–1). Default: 0.4 */
+    innerRatio?: number;
+}
+/**
+ * StarReveal
+ *
+ * Reveals the clip through a star-shaped mask that grows from the center.
+ * Demonstrates the custom `painter` pattern — no renderer changes needed.
+ *
+ * ```ts
+ * clip.addAnimation("starReveal", { duration: 1_000_000, easing: "easeOutBack" }, {
+ *   mode: "reveal",
+ *   points: 5,
+ *   innerRatio: 0.4,
+ * });
+ * ```
+ */
+export declare class StarRevealAnimation extends BaseMaskAnimation {
+    readonly type = "starReveal";
+    constructor(params: StarRevealParams, options: AnimationOptions);
+    protected buildMask(progress: number): MaskTransform;
+}
+export {};

package/dist/animation/pixi-animation-utils.d.ts

@@ -0,0 +1,10 @@
+export declare const pixiProps: string[];
+export declare const hasPixiProp: (obj: any) => any;
+export declare const prepareVars: (vars: any) => any;
+export declare function resolveValue(val: any, baseVal: number): number;
+export declare function resolveVars(from: any, to: any, baseSource: Record<string, any>, isOut: boolean): {
+    resolvedFrom: Record<string, any>;
+    resolvedTo: Record<string, any>;
+};
+export declare function getAnimatedKeys(from: any, to: any): string[];
+export declare function getPixiProperty(t: any, key: string): number;

package/dist/animation/registry.d.ts

@@ -0,0 +1,11 @@
+import { AnimationOptions, IAnimation } from './types';
+export type AnimationFactory = (options: AnimationOptions, params?: any) => IAnimation;
+declare class AnimationRegistry {
+    private factories;
+    constructor();
+    register(name: string, factory: AnimationFactory): void;
+    create(name: string, options: AnimationOptions, params?: any): IAnimation;
+    has(name: string): boolean;
+}
+export declare const animationRegistry: AnimationRegistry;
+export {};

package/dist/animation/types.d.ts

@@ -0,0 +1,205 @@
+export type EasingFunction = (t: number) => number;
+export interface AnimationProps {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    scale?: number;
+    scaleX?: number;
+    scaleY?: number;
+    opacity?: number;
+    angle?: number;
+    blur?: number;
+    brightness?: number;
+    mirror?: number;
+    motionBlur?: number;
+}
+export interface AnimationOptions {
+    duration: number;
+    delay?: number;
+    easing?: string | EasingFunction;
+    iterCount?: number;
+    id?: string;
+    disableGlobalEasing?: boolean;
+}
+export interface IAnimation {
+    readonly id: string;
+    readonly type: string;
+    readonly options: Required<AnimationOptions>;
+    readonly params?: any;
+    /**
+     * Calculate offsets and multipliers for the given time
+     * @param time Relative time from the start of the clip in microseconds
+     * @returns Partial state containing offsets/multipliers
+     */
+    getTransform(time: number): AnimationTransform;
+    /**
+     * Apply complex animations (like GSAP character animations) directly to a target
+     * @param target The target object (e.g., PixiJS Container)
+     * @param time Relative time in microseconds
+     */
+    apply?(target: any, time: number): void;
+}
+export interface AnimationTransform {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    scale?: number;
+    scaleX?: number;
+    scaleY?: number;
+    opacity?: number;
+    angle?: number;
+    blur?: number;
+    brightness?: number;
+    mirror?: number;
+    motionBlur?: number;
+    mask?: MaskTransform;
+}
+/**
+ * Custom mask painter function.
+ * Called by PixiSpriteRenderer when shape === "custom".
+ * Receives a cleared Graphics object; draw your shape into it using Pixi's
+ * Graphics API. Fill with white (0xffffff) — alpha determines mask opacity.
+ *
+ * @param g        The cleared Graphics object to draw into
+ * @param width    Clip's logical width in pixels
+ * @param height   Clip's logical height in pixels
+ * @param progress Normalized reveal progress 0→1
+ */
+export type MaskPainter = (g: {
+    rect: any;
+    circle: any;
+    ellipse: any;
+    fill: any;
+    poly: any;
+    [key: string]: any;
+}, width: number, height: number, progress: number) => void;
+export interface MaskTransform {
+    /** Mask shape. Use "custom" and provide a `painter` for arbitrary paths. */
+    shape: "rect" | "circle" | "ellipse" | "custom";
+    /**
+     * Normalized progress 0–1 controlling how much of the clip is revealed.
+     * 0 = fully hidden, 1 = fully visible.
+     */
+    progress: number;
+    /** For rect: which edge the wipe sweeps from. For circle/ellipse: ignored. */
+    direction?: "left" | "right" | "top" | "bottom";
+    /** For angled wipe: rotation of the mask edge in degrees (0 = vertical sweep) */
+    angle?: number;
+    /** Origin point for expand masks (circle/ellipse/rectExpand). Default: "center" */
+    origin?: "center" | "topLeft" | "topRight" | "bottomLeft" | "bottomRight";
+    /** Soft edge width in pixels. 0 = hard edge. */
+    feather?: number;
+    /**
+     * Normalized starting size of the mask (0–1). Default: 0.
+     * e.g. 0.2 means the mask starts at 20% size and grows to 100%.
+     * The painter receives a `progress` value already remapped from
+     * initialProgress→1 so individual painters don't need to handle this.
+     */
+    initialProgress?: number;
+    /**
+     * Custom painter for shape === "custom".
+     * Draw any path into the provided Graphics object.
+     * The renderer calls this instead of its built-in shape dispatch.
+     */
+    painter?: MaskPainter;
+}
+export interface KeyframeData {
+    [key: string]: Partial<AnimationProps & {
+        easing?: string | EasingFunction;
+    }>;
+}
+export declare const ANIMATABLE_PROPERTIES: {
+    readonly x: {
+        readonly label: "X Position";
+        readonly min: -2000;
+        readonly max: 2000;
+        readonly step: 1;
+        readonly default: 0;
+    };
+    readonly y: {
+        readonly label: "Y Position";
+        readonly min: -2000;
+        readonly max: 2000;
+        readonly step: 1;
+        readonly default: 0;
+    };
+    readonly width: {
+        readonly label: "Width";
+        readonly min: -1000;
+        readonly max: 1000;
+        readonly step: 1;
+        readonly default: 0;
+    };
+    readonly height: {
+        readonly label: "Height";
+        readonly min: -1000;
+        readonly max: 1000;
+        readonly step: 1;
+        readonly default: 0;
+    };
+    readonly scale: {
+        readonly label: "Scale";
+        readonly min: 0;
+        readonly max: 3;
+        readonly step: 0.1;
+        readonly default: 1;
+    };
+    readonly scaleX: {
+        readonly label: "Scale X";
+        readonly min: 0;
+        readonly max: 3;
+        readonly step: 0.1;
+        readonly default: 1;
+    };
+    readonly scaleY: {
+        readonly label: "Scale Y";
+        readonly min: 0;
+        readonly max: 3;
+        readonly step: 0.1;
+        readonly default: 1;
+    };
+    readonly opacity: {
+        readonly label: "Opacity";
+        readonly min: 0;
+        readonly max: 1;
+        readonly step: 0.01;
+        readonly default: 1;
+    };
+    readonly angle: {
+        readonly label: "Rotation";
+        readonly min: -360;
+        readonly max: 360;
+        readonly step: 1;
+        readonly default: 0;
+    };
+    readonly blur: {
+        readonly label: "Blur";
+        readonly min: 0;
+        readonly max: 100;
+        readonly step: 1;
+        readonly default: 0;
+    };
+    readonly brightness: {
+        readonly label: "Brightness";
+        readonly min: 0;
+        readonly max: 5;
+        readonly step: 0.1;
+        readonly default: 1;
+    };
+    readonly mirror: {
+        readonly label: "Mirror";
+        readonly min: 0;
+        readonly max: 1;
+        readonly step: 1;
+        readonly default: 0;
+    };
+    readonly motionBlur: {
+        readonly label: "Motion Blur";
+        readonly min: 0;
+        readonly max: 500;
+        readonly step: 1;
+        readonly default: 0;
+    };
+};

package/dist/animation/wipe-animation.d.ts

@@ -0,0 +1,53 @@
+import { AnimationOptions, AnimationTransform, IAnimation } from './types';
+/**
+ * Direction the wipe edge travels FROM:
+ *   "left"   → wipe sweeps left-to-right  (mask grows from left)
+ *   "right"  → wipe sweeps right-to-left  (mask grows from right)
+ *   "top"    → wipe sweeps top-to-bottom  (mask grows from top)
+ *   "bottom" → wipe sweeps bottom-to-top  (mask grows from bottom)
+ */
+export type WipeDirection = "left" | "right" | "top" | "bottom";
+/**
+ * "reveal" = wipe IN  (mask expands, more of the clip becomes visible)
+ * "conceal"= wipe OUT (mask shrinks, clip disappears progressively)
+ */
+export type WipeMode = "reveal" | "conceal";
+export interface WipeAnimationParams {
+    direction: WipeDirection;
+    mode: WipeMode;
+    /** Optional angle offset for diagonal wipes (degrees) */
+    angle?: number;
+    /** Soft edge feather width in pixels. 0 = hard edge. */
+    feather?: number;
+    /** Starting mask size 0–1. Default: 0 (starts from nothing). */
+    initialProgress?: number;
+}
+/**
+ * WipeAnimation
+ *
+ * Rectangular edge-sweep mask animation. Emits a MaskTransform via
+ * getTransform() so it composes cleanly with other animations.
+ * The actual mask drawing is handled by PixiSpriteRenderer's unified
+ * mask compositor, which reads renderTransform.mask each frame.
+ *
+ * Example (AI usage):
+ *
+ * ```ts
+ * clip.addAnimation("wipe", {
+ *   duration: 1_000_000, // 1 second in microseconds
+ *   easing: "easeInOutCubic",
+ * }, {
+ *   direction: "left",
+ *   mode: "reveal",
+ *   feather: 0,        // hard edge (default)
+ * });
+ * ```
+ */
+export declare class WipeAnimation implements IAnimation {
+    readonly id: string;
+    readonly type = "wipe";
+    readonly options: Required<AnimationOptions>;
+    readonly params: WipeAnimationParams;
+    constructor(params: WipeAnimationParams, options: AnimationOptions);
+    getTransform(time: number): AnimationTransform;
+}