pixi-effects 0.1.0 → 0.2.0

package/README.md

@@ -1,24 +1,107 @@
 # pixi-effects
 
-> **Status**: v0.1.0. API stable; semver from here.
+> **Status**: experimental — current release `0.2.0`. The API may still change between minor versions.
 
-**[Live demos →](https://yjmtmtk.github.io/pixi-effects/)** · 8 numbered examples + an in-browser playground.
+**[Live demos →](https://yjmtmtk.github.io/pixi-effects/)** · 12 numbered examples + an in-browser playground.
 
 Declarative composition and video rendering for the web. After Effects-style timelines on top of [PixiJS v8](https://pixijs.com/) and [GSAP](https://gsap.com/), with strict TypeScript types. Render to MP4 / WebM / MOV via [mediabunny](https://mediabunny.dev/).
 
-- **Declarative DSL** — describe your composition as a tree of typed sequences (text, image, video, audio, nested compositions). No imperative tween code.
+- **Declarative DSL** — describe your composition as a tree of typed sequences (text, image, video, audio, shapes, nested compositions). No imperative tween code.
 - **Expression language** — sprinkle `'GW * 0.5'` or `'min(W, H) / 2'` anywhere a number goes. Resolved at runtime against a sequence-relative scope.
-- **Filters** — chroma key, blur, color matrix. Animatable per-keyframe.
+- **Filters, masks, transitions** — chroma key, blur, color matrix (or any PixiJS filter); inline masks; seven scene transitions (`crossfade`, `wipe`, `iris`, `slide`, `dip`, `zoom`, `dissolve`).
+- **Presets** — `kenBurns` for stills, `withFade` for fade-in/out.
+- **2.5D layers & camera** — add `threeD: true`, `z`, `rotationX/Y` and a `{ type: 'camera' }` layer for parallax, flips and dolly zooms; no three.js needed.
+- **three.js layer** *(optional)* — drop a real three.js scene in as a layer via `pixi-effects/three`; keyframes drive its objects (`three.cube.rotation.y`).
 - **Built-in player UI** — drop-in HTML5-`<video>`-style overlay controller (play, scrub, mute, volume, fullscreen, export-to-file).
 - **MP4 / WebM / MOV export** — pick container and quality from the controller, or call `movie.render()` from code.
-- **Tiny dependency surface** — only `mediabunny` (runtime) plus PixiJS and GSAP (peer deps).
+- **Tiny dependency surface** — only `mediabunny` (runtime) plus PixiJS and GSAP (peer deps). three.js is an *optional* peer, needed only if you import `pixi-effects/three`.
 
 ## Install
 
 ```bash
 npm install pixi-effects pixi.js gsap
+npm install three        # optional — only if you import `pixi-effects/three`
 ```
 
+### Browser via CDN (no bundler)
+
+Drop the imports into an [importmap](https://developer.mozilla.org/docs/Web/HTML/Element/script/type/importmap) and you're done — see [`examples/`](./examples/) for full files.
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "pixi.js":                 "https://esm.sh/pixi.js@8.22.0?bundle-deps",
+    "gsap":                    "https://esm.sh/gsap@3.12.5",
+    "gsap/PixiPlugin":         "https://esm.sh/gsap@3.12.5/PixiPlugin",
+    "mediabunny":              "https://esm.sh/mediabunny",
+    "pixi-effects":            "https://cdn.jsdelivr.net/npm/pixi-effects@0.2.0/dist/index.js",
+    "pixi-effects/controller": "https://cdn.jsdelivr.net/npm/pixi-effects@0.2.0/dist/Controller.js"
+  }
+}
+</script>
+<script type="module">
+  import { Movie } from 'pixi-effects';
+  import { Controller } from 'pixi-effects/controller';
+  // ...
+</script>
+```
+
+Load the `dist/` files **as they are** (jsDelivr's `/npm/…/dist/…`, or unpkg's `https://unpkg.com/pixi-effects@0.2.0/dist/index.js`) rather than a CDN-rebundled build such as `esm.sh/pixi-effects` or jsDelivr's `+esm`: the entries (`pixi-effects`, `…/controller`, `…/three`) share internal chunks, which only works when each file is served untouched.
+
+> **Using three.js?** Add two more entries (`three` and `pixi-effects/three`) to this importmap — see [Adding three.js](#adding-threejs-optional) below.
+>
+> **Want the unreleased `main`?** Point the `pixi-effects*` entries at the GitHub Pages build instead: `https://yjmtmtk.github.io/pixi-effects/dist/index.js` (and `Controller.js`, `three.js`).
+
+#### Adding three.js (optional)
+
+Add two more entries to the importmap above: three.js itself, and the `pixi-effects/three` entry.
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "...":                     "(everything from the importmap above)",
+    "three":                   "https://esm.sh/three@0.178.0",
+    "pixi-effects/three":      "https://cdn.jsdelivr.net/npm/pixi-effects@0.2.0/dist/three.js"
+  }
+}
+</script>
+```
+
+Always route `three` through the importmap — both your code and `pixi-effects/three` then share **one** copy of three.js. Don't load a second copy from another URL (objects from one copy are not `instanceof` the other).
+
+```html
+<script type="module">
+  import { Movie } from 'pixi-effects';
+  import { registerThree, three } from 'pixi-effects/three';
+  import * as THREE from 'three';
+
+  registerThree();   // once, before movie.init()
+
+  // ...inside composition.sequences:
+  three({
+    type: 'three', name: 'knot',
+    width: 'GW * 0.6', height: 'GH * 0.6',
+    initial: { x: 'GW/2', y: 'GH/2', anchorX: 0.5, anchorY: 0.5 },
+    setup: (ctx) => {
+      const knot = new THREE.Mesh(
+        new THREE.TorusKnotGeometry(1, 0.35, 128, 32),
+        new THREE.MeshStandardMaterial({ color: 0x7fb4ff }),
+      );
+      ctx.scene.add(knot, new THREE.AmbientLight(0xffffff, 0.4));
+      ctx.camera.position.z = 6;
+      return { objects: { knot } };        // addressable from keyframes
+    },
+    keyframes: [{ at: 0, to: { 'three.knot.rotation.y': Math.PI * 2 }, duration: 6 }],
+  })
+</script>
+```
+
+The layer is a normal sprite once built, so 2D keyframes, masks and filters work on it. Full spec, rules and caveats (one WebGL context per layer, `update(t)` must be a pure function of `t`): [DSL reference § three](./docs/dsl.md#three) and [API reference](./docs/api.md#pixi-effectsthree). Runnable: [`examples/10-three.html`](./examples/10-three.html).
+
+With a bundler, `import { registerThree, three } from 'pixi-effects/three'` works the same once you've installed `three`.
+
 ## Quickstart
 
 ```ts
@@ -55,10 +138,24 @@ await movie.init({
 const blob = await movie.render({ format: 'mp4' });
 ```
 
+## 2.5D layers & camera
+
+Any layer can be placed in depth and viewed through a camera — no three.js involved:
+
+```ts
+sequences: [
+  { type: 'camera', keyframes: [{ at: 0, from: { x: 'GW/2 - 260' }, to: { x: 'GW/2 + 260' }, duration: 4, ease: 'sine.inOut' }] },
+  { type: 'shape', shape: 'rect', width: 300, height: 200, threeD: true, initial: { x: 'GW/2', y: 'GH/2', z: -400, fillColor: '#3a6ea5' } },
+  { type: 'shape', shape: 'rect', width: 300, height: 200, threeD: true, initial: { x: 'GW/2', y: 'GH/2', z: 250,  fillColor: '#d96a3a' } },
+]
+```
+
+`+z` is toward the viewer, rotations are degrees (CSS signs), and with `z = 0` and the default camera a `threeD` layer looks identical to a 2D one. See [DSL reference § 3D layers & camera](./docs/dsl.md#3d-layers--camera) and [`examples/11-depth.html`](./examples/11-depth.html).
+
 ## Documentation
 
-- [**DSL reference**](./docs/dsl.md) — composition, sequences, keyframes, expressions, filters
-- [**API reference**](./docs/api.md) — `Movie`, `Controller`, events, render options
+- [**DSL reference**](./docs/dsl.md) — composition, sequences, 3D layers & camera, three.js layer, keyframes, expressions, filters
+- [**API reference**](./docs/api.md) — `Movie`, `Controller`, `pixi-effects/three`, events, render options
 - [**Examples**](./examples/) — runnable HTML files (read in order):
   - `01-hello.html` — minimum viable composition
   - `02-keyframes.html` — keyframes, easings, expressions
@@ -69,6 +166,9 @@ const blob = await movie.render({ format: 'mp4' });
   - `07-transitions.html` — all seven transition kinds in one timeline
   - `08-presets-export.html` — `kenBurns` preset and `movie.render()` from code
   - `09-audio.html` — multi-track audio mixing with BGM ducking and SFX cues
+  - `10-three.html` — a three.js scene as a layer (`pixi-effects/three`)
+  - `11-depth.html` — 2.5D layers and camera: parallax, spin, dolly zoom
+  - `12-title-motion.html` — a staggered 2.5D title: letters fly in from depth, particles, orbiting camera
   - `playground.html` — in-browser editor with preset dropdown
 
 ## Browser support

package/dist/Base-B1Tdn0Cv.d.cts

@@ -0,0 +1,92 @@
+import { Filter, Container, RenderTexture, Matrix } from 'pixi.js';
+import { S as SequenceSpec, C as CompositionShape, t as AudioDescriptor } from './types-CNBilhpz.cjs';
+import { gsap } from 'gsap';
+
+/**
+ * Resolves a routed keyframe path to a concrete GSAP tween target.
+ * `path` is everything after the registered prefix + dot (for
+ * `three.cube.rotation.y` under prefix `three`, path = `cube.rotation.y`).
+ * Return null to skip the key (the router is expected to have warned).
+ */
+type PathRouter = (path: string) => {
+    target: object;
+    prop: string;
+} | null;
+type PathRouters = Record<string, PathRouter>;
+
+/** Variables available to expression evaluation. */
+interface Scope {
+    w: number;
+    h: number;
+    W: number;
+    H: number;
+    GW: number;
+    GH: number;
+    contain: number;
+    cover: number;
+    t: number;
+    d: number;
+    T: number;
+}
+
+/** Internal marker we set on filter instances so partition path resolution finds them. */
+interface NamedFilter extends Filter {
+    _name?: string;
+}
+
+/** The slice of a Pixi renderer Layer3D needs (also what tests fake). */
+interface SpaceHost {
+    render(options: {
+        container: Container;
+        target: RenderTexture;
+        transform: Matrix;
+        clear: boolean;
+        clearColor: number[];
+    }): void;
+}
+
+type Timeline = ReturnType<typeof gsap.timeline>;
+declare abstract class Sequence {
+    spec: SequenceSpec;
+    parent: CompositionShape | null;
+    root: CompositionShape;
+    target: Container | null;
+    intrinsicWidth: number;
+    intrinsicHeight: number;
+    at: number;
+    duration: number | undefined;
+    filters: NamedFilter[];
+    /**
+     * Mask sequence built from `spec.mask`, if any. Built and added to the
+     * scene graph by the parent CompositionSequence; rendered as a mask
+     * (not a normal child) by PIXI when `target.mask = maskSequence.target`.
+     */
+    maskSequence: Sequence | null;
+    /**
+     * Absolute start time on the global timeline (offset + at), recorded by
+     * bindTimeline. Movie._awaitVideoFrames uses it to determine the correct
+     * time to pass to awaitFrameAt. Subclasses that override bindTimeline
+     * without calling super must set this field themselves. Null until bound.
+     */
+    absoluteStart: number | null;
+    constructor(spec: SequenceSpec, parent: CompositionShape | null, root: CompositionShape);
+    abstract build(): Promise<void>;
+    buildFilters(): void;
+    scope(): Scope;
+    /**
+     * Prefix routers contributed to the keyframe pipeline (e.g. `three.` in
+     * pixi-effects/three). Base sequences route nothing extra.
+     */
+    protected pathRouters(): PathRouters;
+    bindTimeline(timeline: Timeline, offset?: number): void;
+    collectAudio(_out: AudioDescriptor[], _baseTime: number): void;
+    /**
+     * 2.5D hook. Runs once per rendered frame, after the timeline seek and the
+     * per-frame media sync, before the render. Compositions override it to
+     * project their `threeD` layers; everything else has nothing to do.
+     */
+    updateSpace(_t: number, _host: SpaceHost): void;
+    destroy(): void;
+}
+
+export { type PathRouters as P, Sequence as S };

package/dist/Base-Bh_VSusi.d.ts

@@ -0,0 +1,92 @@
+import { Filter, Container, RenderTexture, Matrix } from 'pixi.js';
+import { S as SequenceSpec, C as CompositionShape, t as AudioDescriptor } from './types-CNBilhpz.js';
+import { gsap } from 'gsap';
+
+/**
+ * Resolves a routed keyframe path to a concrete GSAP tween target.
+ * `path` is everything after the registered prefix + dot (for
+ * `three.cube.rotation.y` under prefix `three`, path = `cube.rotation.y`).
+ * Return null to skip the key (the router is expected to have warned).
+ */
+type PathRouter = (path: string) => {
+    target: object;
+    prop: string;
+} | null;
+type PathRouters = Record<string, PathRouter>;
+
+/** Variables available to expression evaluation. */
+interface Scope {
+    w: number;
+    h: number;
+    W: number;
+    H: number;
+    GW: number;
+    GH: number;
+    contain: number;
+    cover: number;
+    t: number;
+    d: number;
+    T: number;
+}
+
+/** Internal marker we set on filter instances so partition path resolution finds them. */
+interface NamedFilter extends Filter {
+    _name?: string;
+}
+
+/** The slice of a Pixi renderer Layer3D needs (also what tests fake). */
+interface SpaceHost {
+    render(options: {
+        container: Container;
+        target: RenderTexture;
+        transform: Matrix;
+        clear: boolean;
+        clearColor: number[];
+    }): void;
+}
+
+type Timeline = ReturnType<typeof gsap.timeline>;
+declare abstract class Sequence {
+    spec: SequenceSpec;
+    parent: CompositionShape | null;
+    root: CompositionShape;
+    target: Container | null;
+    intrinsicWidth: number;
+    intrinsicHeight: number;
+    at: number;
+    duration: number | undefined;
+    filters: NamedFilter[];
+    /**
+     * Mask sequence built from `spec.mask`, if any. Built and added to the
+     * scene graph by the parent CompositionSequence; rendered as a mask
+     * (not a normal child) by PIXI when `target.mask = maskSequence.target`.
+     */
+    maskSequence: Sequence | null;
+    /**
+     * Absolute start time on the global timeline (offset + at), recorded by
+     * bindTimeline. Movie._awaitVideoFrames uses it to determine the correct
+     * time to pass to awaitFrameAt. Subclasses that override bindTimeline
+     * without calling super must set this field themselves. Null until bound.
+     */
+    absoluteStart: number | null;
+    constructor(spec: SequenceSpec, parent: CompositionShape | null, root: CompositionShape);
+    abstract build(): Promise<void>;
+    buildFilters(): void;
+    scope(): Scope;
+    /**
+     * Prefix routers contributed to the keyframe pipeline (e.g. `three.` in
+     * pixi-effects/three). Base sequences route nothing extra.
+     */
+    protected pathRouters(): PathRouters;
+    bindTimeline(timeline: Timeline, offset?: number): void;
+    collectAudio(_out: AudioDescriptor[], _baseTime: number): void;
+    /**
+     * 2.5D hook. Runs once per rendered frame, after the timeline seek and the
+     * per-frame media sync, before the render. Compositions override it to
+     * project their `threeD` layers; everything else has nothing to do.
+     */
+    updateSpace(_t: number, _host: SpaceHost): void;
+    destroy(): void;
+}
+
+export { type PathRouters as P, Sequence as S };

package/dist/Composition-BI5HZJFL.cjs

@@ -0,0 +1,13 @@
+'use strict';
+
+var chunk64IHCYYN_cjs = require('./chunk-64IHCYYN.cjs');
+require('./chunk-7OIWYXGV.cjs');
+
+
+
+Object.defineProperty(exports, "CompositionSequence", {
+  enumerable: true,
+  get: function () { return chunk64IHCYYN_cjs.CompositionSequence; }
+});
+//# sourceMappingURL=Composition-BI5HZJFL.cjs.map
+//# sourceMappingURL=Composition-BI5HZJFL.cjs.map

package/dist/Composition-BI5HZJFL.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-BI5HZJFL.cjs"}

package/dist/Composition-IO7ZN32J.js

@@ -0,0 +1,4 @@
+export { CompositionSequence } from './chunk-H55V3U56.js';
+import './chunk-VJCDG6YG.js';
+//# sourceMappingURL=Composition-IO7ZN32J.js.map
+//# sourceMappingURL=Composition-IO7ZN32J.js.map

package/dist/Composition-IO7ZN32J.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-IO7ZN32J.js"}

package/dist/Controller.d.cts

@@ -1,6 +1,7 @@
-import { M as Movie } from './Movie-Bp66rkaC.cjs';
+import { M as Movie } from './Movie-CcR6h2jO.cjs';
 import 'pixi.js';
 import 'gsap';
+import './types-CNBilhpz.cjs';
 
 declare function formatTime(seconds: number): string;
 declare function frameToPercent(frame: number, totalFrames: number): number;

package/dist/Controller.d.ts

@@ -1,6 +1,7 @@
-import { M as Movie } from './Movie-Bp66rkaC.js';
+import { M as Movie } from './Movie-D-n8glA6.js';
 import 'pixi.js';
 import 'gsap';
+import './types-CNBilhpz.js';
 
 declare function formatTime(seconds: number): string;
 declare function frameToPercent(frame: number, totalFrames: number): number;

package/dist/Movie-CcR6h2jO.d.cts

@@ -0,0 +1,82 @@
+import { Application } from 'pixi.js';
+import { gsap } from 'gsap';
+import { A as AssetSpec, g as CompositionSpec } from './types-CNBilhpz.cjs';
+
+interface MovieOptions {
+    width?: number;
+    height?: number;
+    duration?: number;
+    frameRate?: number;
+    background?: string;
+    canvas?: HTMLCanvasElement;
+    assets?: AssetSpec[];
+    composition?: CompositionSpec;
+}
+interface RenderOptions {
+    format?: 'mp4' | 'mov' | 'webm' | 'mkv';
+    video?: {
+        codec?: string;
+        bitrate?: 'very-low' | 'low' | 'medium' | 'high' | 'very-high';
+    };
+    audio?: {
+        codec?: string;
+        bitrate?: 'very-low' | 'low' | 'medium' | 'high' | 'very-high';
+    };
+}
+interface FrameEvent {
+    frame: number;
+    totalFrames: number;
+}
+interface ProgressEvent {
+    progress: number;
+    frame: number;
+    totalFrames: number;
+}
+type Listener = (...args: any[]) => void;
+declare class Movie {
+    private _events;
+    private _initState;
+    app: Application | null;
+    timeline: ReturnType<typeof gsap.timeline> | null;
+    audioBuffer: AudioBuffer | null;
+    audioSource: AudioBufferSourceNode | null;
+    gainNode: GainNode | null;
+    private _volume;
+    private _muted;
+    isPlaying: boolean;
+    currentFrame: number;
+    totalFrames: number;
+    width: number;
+    height: number;
+    duration: number;
+    frameRate: number;
+    background: string;
+    private _audioContext;
+    private _rootSequence;
+    private _rootContainer;
+    private _raf;
+    on(event: 'ready', fn: () => void): this;
+    on(event: 'frame', fn: (e: FrameEvent) => void): this;
+    on(event: 'progress', fn: (e: ProgressEvent) => void): this;
+    on(event: 'pause', fn: () => void): this;
+    off(event: string, fn: Listener): this;
+    emit(event: string, ...args: unknown[]): void;
+    get isReady(): boolean;
+    private _ensureAudioContext;
+    init(options?: MovieOptions): Promise<void>;
+    gotoFrame(frame: number, force?: boolean): Promise<void>;
+    private _awaitVideoFrames;
+    /** Projects every `threeD` layer for the current frame (see src/space). */
+    private _updateSpace;
+    play(): void;
+    pause(): void;
+    set volume(v: number);
+    get volume(): number;
+    set muted(v: boolean);
+    get muted(): boolean;
+    toggleMute(): boolean;
+    render(options?: RenderOptions): Promise<Blob>;
+    destroy(): Promise<void>;
+}
+
+export { type FrameEvent as F, Movie as M, type ProgressEvent as P, type RenderOptions as R, type MovieOptions as a };

package/dist/Movie-D-n8glA6.d.ts

@@ -0,0 +1,82 @@
+import { Application } from 'pixi.js';
+import { gsap } from 'gsap';
+import { A as AssetSpec, g as CompositionSpec } from './types-CNBilhpz.js';
+
+interface MovieOptions {
+    width?: number;
+    height?: number;
+    duration?: number;
+    frameRate?: number;
+    background?: string;
+    canvas?: HTMLCanvasElement;
+    assets?: AssetSpec[];
+    composition?: CompositionSpec;
+}
+interface RenderOptions {
+    format?: 'mp4' | 'mov' | 'webm' | 'mkv';
+    video?: {
+        codec?: string;
+        bitrate?: 'very-low' | 'low' | 'medium' | 'high' | 'very-high';
+    };
+    audio?: {
+        codec?: string;
+        bitrate?: 'very-low' | 'low' | 'medium' | 'high' | 'very-high';
+    };
+}
+interface FrameEvent {
+    frame: number;
+    totalFrames: number;
+}
+interface ProgressEvent {
+    progress: number;
+    frame: number;
+    totalFrames: number;
+}
+type Listener = (...args: any[]) => void;
+declare class Movie {
+    private _events;
+    private _initState;
+    app: Application | null;
+    timeline: ReturnType<typeof gsap.timeline> | null;
+    audioBuffer: AudioBuffer | null;
+    audioSource: AudioBufferSourceNode | null;
+    gainNode: GainNode | null;
+    private _volume;
+    private _muted;
+    isPlaying: boolean;
+    currentFrame: number;
+    totalFrames: number;
+    width: number;
+    height: number;
+    duration: number;
+    frameRate: number;
+    background: string;
+    private _audioContext;
+    private _rootSequence;
+    private _rootContainer;
+    private _raf;
+    on(event: 'ready', fn: () => void): this;
+    on(event: 'frame', fn: (e: FrameEvent) => void): this;
+    on(event: 'progress', fn: (e: ProgressEvent) => void): this;
+    on(event: 'pause', fn: () => void): this;
+    off(event: string, fn: Listener): this;
+    emit(event: string, ...args: unknown[]): void;
+    get isReady(): boolean;
+    private _ensureAudioContext;
+    init(options?: MovieOptions): Promise<void>;
+    gotoFrame(frame: number, force?: boolean): Promise<void>;
+    private _awaitVideoFrames;
+    /** Projects every `threeD` layer for the current frame (see src/space). */
+    private _updateSpace;
+    play(): void;
+    pause(): void;
+    set volume(v: number);
+    get volume(): number;
+    set muted(v: boolean);
+    get muted(): boolean;
+    toggleMute(): boolean;
+    render(options?: RenderOptions): Promise<Blob>;
+    destroy(): Promise<void>;
+}
+
+export { type FrameEvent as F, Movie as M, type ProgressEvent as P, type RenderOptions as R, type MovieOptions as a };