@aicut/core 0.4.3 → 0.6.0

package/dist/types-BbZjOQLz.d.ts

@@ -0,0 +1,108 @@
+import { P as Project, M as Ms } from './types-CmS-UIEr.js';
+
+/**
+ * Construction context the Editor hands to a playback engine. The
+ * engine mounts itself into `host` (typically the editor's preview
+ * element) and owns whatever DOM / canvas / video elements it needs.
+ */
+interface PlaybackEngineOptions {
+    /** Mount point. Engine appends its preview surface here. */
+    host: HTMLElement;
+    /** Initial project — engine pre-warms sources, etc. */
+    project: Project;
+}
+/**
+ * The contract every preview engine satisfies. Editor talks ONLY
+ * through this surface — implementations are interchangeable.
+ *
+ * Built-in implementations:
+ *   - `HtmlVideoEngine`  default; one HTMLVideoElement per source,
+ *                        swap on clip boundaries. Zero deps,
+ *                        GPU-accelerated decode by the browser, but
+ *                        seek snaps to keyframes (browser controls
+ *                        the decode pipeline).
+ *   - `WebCodecsEngine`  opt-in (v0.6+); manual VideoDecoder loop +
+ *                        canvas blit. Frame-accurate seek; will
+ *                        underpin multi-track compositing, transitions,
+ *                        and shaders in later versions.
+ *
+ * Hosts can ship their own implementation (e.g., a WebGL compositor,
+ * a WebRTC stream consumer, a desktop-wrapper IPC bridge) and inject
+ * it via `Editor.create({ playbackEngine: myFactory })`.
+ */
+interface PlaybackEngine {
+    /** Replace the project. Engine re-warms sources + re-resolves the
+     *  active clip for the current playhead. Idempotent. */
+    setProject(next: Project): void;
+    play(): void;
+    pause(): void;
+    isPlaying(): boolean;
+    /** Current playhead (ms from project start). */
+    getTime(): Ms;
+    /** Move the playhead. Engine clamps to [0, totalDuration]. */
+    seek(timeMs: Ms): void;
+    /** Free all resources (DOM nodes, decoders, AudioContexts, rAF). */
+    destroy(): void;
+    /**
+     * Optional. The **output frame rect** — the fixed bounds anything
+     * the engine renders is clipped to. The user's keyframe X / Y /
+     * scale move the content WITHIN this frame (think picture-in-
+     * picture, pan, zoom); anything outside is hidden by the engine.
+     *
+     * This rect does NOT change with the active transform — it's
+     * the stage. The overlay's dashed border is drawn here. Coords
+     * relative to `opts.host`. Returns null when no clip is active.
+     */
+    getOutputFrameRect?(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    /**
+     * Optional. Return the screen-space CSS-pixel rectangle of the
+     * actually-rendered content (the video frame after the active
+     * keyframe transform is applied). May extend outside the output
+     * frame — the engine clips to the output frame at paint time, but
+     * the overlay still wants the geometric rect to position scale
+     * handles on the visible content corners.
+     *
+     * Returns null when no clip is active. Engines that don't expose
+     * this leave keyframe handles attached to the output frame instead.
+     */
+    getFrameRect?(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    /** Fired on each rAF / decoded frame with the current playhead. */
+    onTimeUpdate?: (ms: Ms) => void;
+    /** Fired once when the project's end is reached during playback. */
+    onEnded?: () => void;
+    /** Decode / network / capability failures. */
+    onError?: (err: Error) => void;
+    /**
+     * Fired the first time a fresh playback target is "ready to play"
+     * — analogue of HTMLMediaElement's `loadedmetadata`. Editor uses
+     * it to gate scaling / auto-fit work.
+     */
+    onReady?: () => void;
+    /**
+     * Fired when an individual source's duration becomes known. Editor
+     * folds this into the project model so the timeline can size clips
+     * correctly even when the host didn't ship a `duration` upfront.
+     */
+    onSourceMetadata?: (sourceId: string, durationMs: Ms) => void;
+}
+/**
+ * A factory that builds an engine for a given mount/project. Hosts
+ * pass one of these to `Editor.create({ playbackEngine })` to swap
+ * implementations. The factory shape — rather than a class reference
+ * — keeps Editor decoupled from constructor signatures and lets
+ * factories close over host-side configuration (auth tokens, render
+ * backend URL, custom shaders, etc.) without polluting the interface.
+ */
+type PlaybackEngineFactory = (opts: PlaybackEngineOptions) => PlaybackEngine;
+
+export type { PlaybackEngine as P, PlaybackEngineOptions as a, PlaybackEngineFactory as b };

package/dist/types-CjvRUPtZ.d.cts

@@ -0,0 +1,108 @@
+import { P as Project, M as Ms } from './types-CmS-UIEr.cjs';
+
+/**
+ * Construction context the Editor hands to a playback engine. The
+ * engine mounts itself into `host` (typically the editor's preview
+ * element) and owns whatever DOM / canvas / video elements it needs.
+ */
+interface PlaybackEngineOptions {
+    /** Mount point. Engine appends its preview surface here. */
+    host: HTMLElement;
+    /** Initial project — engine pre-warms sources, etc. */
+    project: Project;
+}
+/**
+ * The contract every preview engine satisfies. Editor talks ONLY
+ * through this surface — implementations are interchangeable.
+ *
+ * Built-in implementations:
+ *   - `HtmlVideoEngine`  default; one HTMLVideoElement per source,
+ *                        swap on clip boundaries. Zero deps,
+ *                        GPU-accelerated decode by the browser, but
+ *                        seek snaps to keyframes (browser controls
+ *                        the decode pipeline).
+ *   - `WebCodecsEngine`  opt-in (v0.6+); manual VideoDecoder loop +
+ *                        canvas blit. Frame-accurate seek; will
+ *                        underpin multi-track compositing, transitions,
+ *                        and shaders in later versions.
+ *
+ * Hosts can ship their own implementation (e.g., a WebGL compositor,
+ * a WebRTC stream consumer, a desktop-wrapper IPC bridge) and inject
+ * it via `Editor.create({ playbackEngine: myFactory })`.
+ */
+interface PlaybackEngine {
+    /** Replace the project. Engine re-warms sources + re-resolves the
+     *  active clip for the current playhead. Idempotent. */
+    setProject(next: Project): void;
+    play(): void;
+    pause(): void;
+    isPlaying(): boolean;
+    /** Current playhead (ms from project start). */
+    getTime(): Ms;
+    /** Move the playhead. Engine clamps to [0, totalDuration]. */
+    seek(timeMs: Ms): void;
+    /** Free all resources (DOM nodes, decoders, AudioContexts, rAF). */
+    destroy(): void;
+    /**
+     * Optional. The **output frame rect** — the fixed bounds anything
+     * the engine renders is clipped to. The user's keyframe X / Y /
+     * scale move the content WITHIN this frame (think picture-in-
+     * picture, pan, zoom); anything outside is hidden by the engine.
+     *
+     * This rect does NOT change with the active transform — it's
+     * the stage. The overlay's dashed border is drawn here. Coords
+     * relative to `opts.host`. Returns null when no clip is active.
+     */
+    getOutputFrameRect?(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    /**
+     * Optional. Return the screen-space CSS-pixel rectangle of the
+     * actually-rendered content (the video frame after the active
+     * keyframe transform is applied). May extend outside the output
+     * frame — the engine clips to the output frame at paint time, but
+     * the overlay still wants the geometric rect to position scale
+     * handles on the visible content corners.
+     *
+     * Returns null when no clip is active. Engines that don't expose
+     * this leave keyframe handles attached to the output frame instead.
+     */
+    getFrameRect?(): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    /** Fired on each rAF / decoded frame with the current playhead. */
+    onTimeUpdate?: (ms: Ms) => void;
+    /** Fired once when the project's end is reached during playback. */
+    onEnded?: () => void;
+    /** Decode / network / capability failures. */
+    onError?: (err: Error) => void;
+    /**
+     * Fired the first time a fresh playback target is "ready to play"
+     * — analogue of HTMLMediaElement's `loadedmetadata`. Editor uses
+     * it to gate scaling / auto-fit work.
+     */
+    onReady?: () => void;
+    /**
+     * Fired when an individual source's duration becomes known. Editor
+     * folds this into the project model so the timeline can size clips
+     * correctly even when the host didn't ship a `duration` upfront.
+     */
+    onSourceMetadata?: (sourceId: string, durationMs: Ms) => void;
+}
+/**
+ * A factory that builds an engine for a given mount/project. Hosts
+ * pass one of these to `Editor.create({ playbackEngine })` to swap
+ * implementations. The factory shape — rather than a class reference
+ * — keeps Editor decoupled from constructor signatures and lets
+ * factories close over host-side configuration (auth tokens, render
+ * backend URL, custom shaders, etc.) without polluting the interface.
+ */
+type PlaybackEngineFactory = (opts: PlaybackEngineOptions) => PlaybackEngine;
+
+export type { PlaybackEngine as P, PlaybackEngineOptions as a, PlaybackEngineFactory as b };

package/dist/types-CmS-UIEr.d.cts

@@ -0,0 +1,137 @@
+/**
+ * Milliseconds. All timing in the project is expressed as integer ms to
+ * keep JSON serialization unambiguous (no frame-rate coupling in the
+ * data model — the renderer can present time as frames if it wants).
+ */
+type Ms = number;
+interface MediaSource {
+    id: string;
+    url: string;
+    kind: "video" | "audio";
+    /** Optional — probed lazily from the <video> element if absent. */
+    duration?: Ms;
+    name?: string;
+}
+interface Clip {
+    id: string;
+    sourceId: string;
+    /** Window into the source — `in` inclusive, `out` exclusive. */
+    in: Ms;
+    out: Ms;
+    /** Position on the timeline. */
+    start: Ms;
+    /**
+     * Playback rate. 1 = normal, 2 = 2× speed. Default 1.
+     * Persisted in the project JSON so a host can restore exactly.
+     */
+    speed?: number;
+    /**
+     * Static base values for the content transform, used when the clip
+     * has no keyframes for that property. Pan slides the video inside
+     * the FIXED output frame (the dashed border the user sees); scale
+     * grows / shrinks the content around the frame center. Anything
+     * pushed outside the output frame is clipped — that's how
+     * picture-in-picture, pan, and zoom work.
+     *
+     * `panX`, `panY` are CSS pixels relative to the output frame center.
+     * Defaults: panX = 0, panY = 0, scale = 1 (content fills frame).
+     */
+    panX?: number;
+    panY?: number;
+    scale?: number;
+    /**
+     * Per-property keyframe animation. Each keyframe targets one prop
+     * (`panX`, `panY`, or `scale`) so the user can animate one axis
+     * independently of the others (the standard NLE / CapCut model).
+     *
+     * Times are clip-local (0 = clip's `in`), so trim and move ops
+     * carry keyframes with the clip. Empty array / undefined = use the
+     * static base values above. `normalizeProject` keeps it sorted by
+     * (prop, time).
+     */
+    keyframes?: Keyframe[];
+}
+/** Properties on a Clip that can be animated by keyframes. */
+type KeyframeProp = "panX" | "panY" | "scale";
+/**
+ * Easing curve that shapes the segment LEAVING this keyframe — i.e.
+ * the curve from this keyframe to the next one in time. Matches the
+ * "outgoing" easing model in After Effects / Premiere / CapCut so a
+ * single dropdown per keyframe is enough.
+ *
+ *   - `linear`     — constant rate (default)
+ *   - `easeIn`     — start slow, finish fast (cubic)
+ *   - `easeOut`    — start fast, finish slow (cubic)
+ *   - `easeInOut`  — slow on both ends, fast in the middle (cubic)
+ */
+type EasingKind = "linear" | "easeIn" | "easeOut" | "easeInOut";
+/**
+ * One pinned value for one property at one moment in clip-local time.
+ * Properties without keyframes fall back to the clip's static base
+ * value (`Clip.panX` / `panY` / `scale`).
+ */
+interface Keyframe {
+    id: string;
+    /** Which property this keyframe controls. */
+    prop: KeyframeProp;
+    /** Clip-local time in ms. 0 = clip's `in`. Bounds: [0, clip.out - clip.in]. */
+    time: Ms;
+    /** The value the property holds at this moment. Same units as the
+     *  matching static field (CSS px for pan, multiplier for scale). */
+    value: number;
+    /** Easing curve for the segment leaving THIS keyframe toward the
+     *  next one. Optional — omitted / undefined = "linear" (back-compat
+     *  with projects authored before the easing field existed). */
+    easing?: EasingKind;
+}
+interface Track {
+    id: string;
+    kind: "video" | "audio";
+    /** Clips on this track. Must be kept sorted by `start` and non-overlapping. */
+    clips: Clip[];
+}
+interface Project {
+    /** Schema version — bump when breaking the JSON shape. */
+    version: 1;
+    sources: MediaSource[];
+    tracks: Track[];
+    /**
+     * Project frame rate. Drives keyboard frame-stepping (← / →), the
+     * future timecode display, and ffmpeg compilation of keyframe
+     * animations. Optional for back-compat — projects without `fps`
+     * default to 30, matching consumer NLE convention (CapCut /
+     * Premiere project defaults). `normalizeProject` does NOT fill
+     * this in, so a missing field stays missing through round-trips.
+     */
+    fps?: number;
+}
+/**
+ * Subset of CSS variables the editor honors. Pass any custom values
+ * via `Editor` options; everything is forwarded as `--aicut-*` on the
+ * editor's root container, so a host can also override via plain CSS.
+ */
+interface Theme {
+    brand?: string;
+    secondary?: string;
+    surface?: string;
+    dark?: string;
+    muted?: string;
+    card?: string;
+    success?: string;
+    warning?: string;
+    info?: string;
+    error?: string;
+    /** Toolbar / ruler chrome. Background of the editor frame. */
+    controlsBg?: string;
+    controlsBorder?: string;
+    controlsText?: string;
+    controlsHover?: string;
+    controlsActive?: string;
+    /** Letterbox color around the preview video. Defaults to black. */
+    previewBg?: string;
+    radiusSm?: string;
+    radiusMd?: string;
+    radiusLg?: string;
+}
+
+export type { Clip as C, EasingKind as E, KeyframeProp as K, Ms as M, Project as P, Track as T, MediaSource as a, Theme as b, Keyframe as c };

package/dist/types-CmS-UIEr.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Milliseconds. All timing in the project is expressed as integer ms to
+ * keep JSON serialization unambiguous (no frame-rate coupling in the
+ * data model — the renderer can present time as frames if it wants).
+ */
+type Ms = number;
+interface MediaSource {
+    id: string;
+    url: string;
+    kind: "video" | "audio";
+    /** Optional — probed lazily from the <video> element if absent. */
+    duration?: Ms;
+    name?: string;
+}
+interface Clip {
+    id: string;
+    sourceId: string;
+    /** Window into the source — `in` inclusive, `out` exclusive. */
+    in: Ms;
+    out: Ms;
+    /** Position on the timeline. */
+    start: Ms;
+    /**
+     * Playback rate. 1 = normal, 2 = 2× speed. Default 1.
+     * Persisted in the project JSON so a host can restore exactly.
+     */
+    speed?: number;
+    /**
+     * Static base values for the content transform, used when the clip
+     * has no keyframes for that property. Pan slides the video inside
+     * the FIXED output frame (the dashed border the user sees); scale
+     * grows / shrinks the content around the frame center. Anything
+     * pushed outside the output frame is clipped — that's how
+     * picture-in-picture, pan, and zoom work.
+     *
+     * `panX`, `panY` are CSS pixels relative to the output frame center.
+     * Defaults: panX = 0, panY = 0, scale = 1 (content fills frame).
+     */
+    panX?: number;
+    panY?: number;
+    scale?: number;
+    /**
+     * Per-property keyframe animation. Each keyframe targets one prop
+     * (`panX`, `panY`, or `scale`) so the user can animate one axis
+     * independently of the others (the standard NLE / CapCut model).
+     *
+     * Times are clip-local (0 = clip's `in`), so trim and move ops
+     * carry keyframes with the clip. Empty array / undefined = use the
+     * static base values above. `normalizeProject` keeps it sorted by
+     * (prop, time).
+     */
+    keyframes?: Keyframe[];
+}
+/** Properties on a Clip that can be animated by keyframes. */
+type KeyframeProp = "panX" | "panY" | "scale";
+/**
+ * Easing curve that shapes the segment LEAVING this keyframe — i.e.
+ * the curve from this keyframe to the next one in time. Matches the
+ * "outgoing" easing model in After Effects / Premiere / CapCut so a
+ * single dropdown per keyframe is enough.
+ *
+ *   - `linear`     — constant rate (default)
+ *   - `easeIn`     — start slow, finish fast (cubic)
+ *   - `easeOut`    — start fast, finish slow (cubic)
+ *   - `easeInOut`  — slow on both ends, fast in the middle (cubic)
+ */
+type EasingKind = "linear" | "easeIn" | "easeOut" | "easeInOut";
+/**
+ * One pinned value for one property at one moment in clip-local time.
+ * Properties without keyframes fall back to the clip's static base
+ * value (`Clip.panX` / `panY` / `scale`).
+ */
+interface Keyframe {
+    id: string;
+    /** Which property this keyframe controls. */
+    prop: KeyframeProp;
+    /** Clip-local time in ms. 0 = clip's `in`. Bounds: [0, clip.out - clip.in]. */
+    time: Ms;
+    /** The value the property holds at this moment. Same units as the
+     *  matching static field (CSS px for pan, multiplier for scale). */
+    value: number;
+    /** Easing curve for the segment leaving THIS keyframe toward the
+     *  next one. Optional — omitted / undefined = "linear" (back-compat
+     *  with projects authored before the easing field existed). */
+    easing?: EasingKind;
+}
+interface Track {
+    id: string;
+    kind: "video" | "audio";
+    /** Clips on this track. Must be kept sorted by `start` and non-overlapping. */
+    clips: Clip[];
+}
+interface Project {
+    /** Schema version — bump when breaking the JSON shape. */
+    version: 1;
+    sources: MediaSource[];
+    tracks: Track[];
+    /**
+     * Project frame rate. Drives keyboard frame-stepping (← / →), the
+     * future timecode display, and ffmpeg compilation of keyframe
+     * animations. Optional for back-compat — projects without `fps`
+     * default to 30, matching consumer NLE convention (CapCut /
+     * Premiere project defaults). `normalizeProject` does NOT fill
+     * this in, so a missing field stays missing through round-trips.
+     */
+    fps?: number;
+}
+/**
+ * Subset of CSS variables the editor honors. Pass any custom values
+ * via `Editor` options; everything is forwarded as `--aicut-*` on the
+ * editor's root container, so a host can also override via plain CSS.
+ */
+interface Theme {
+    brand?: string;
+    secondary?: string;
+    surface?: string;
+    dark?: string;
+    muted?: string;
+    card?: string;
+    success?: string;
+    warning?: string;
+    info?: string;
+    error?: string;
+    /** Toolbar / ruler chrome. Background of the editor frame. */
+    controlsBg?: string;
+    controlsBorder?: string;
+    controlsText?: string;
+    controlsHover?: string;
+    controlsActive?: string;
+    /** Letterbox color around the preview video. Defaults to black. */
+    previewBg?: string;
+    radiusSm?: string;
+    radiusMd?: string;
+    radiusLg?: string;
+}
+
+export type { Clip as C, EasingKind as E, KeyframeProp as K, Ms as M, Project as P, Track as T, MediaSource as a, Theme as b, Keyframe as c };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aicut/core",
-  "version": "0.4.3",
-  "description": "Framework-agnostic core for the AiCut video editor — canvas timeline, data model, HTML5 playback engine, plus an opt-in 3D lighting picker.",
+  "version": "0.6.0",
+  "description": "Framework-agnostic core for the AiCut video editor — canvas timeline, data model, pluggable PlaybackEngine (HTML5 / Canvas / WebCodecs), plus opt-in 3D lighting picker.",
   "license": "MIT",
   "author": "ziqiang <ziqiangytu@gmail.com>",
   "homepage": "https://github.com/ziqiangai/AiCut#readme",
@@ -57,6 +57,11 @@
       "import": "./dist/lighting/index.js",
       "require": "./dist/lighting/index.cjs"
     },
+    "./webcodecs": {
+      "types": "./dist/playback/webcodecs/index.d.ts",
+      "import": "./dist/playback/webcodecs/index.js",
+      "require": "./dist/playback/webcodecs/index.cjs"
+    },
     "./styles.css": "./styles/theme.css"
   },
   "files": [
@@ -65,12 +70,16 @@
     "README.md"
   ],
   "dependencies": {
+    "mp4box": "^2.4.1",
     "three": "^0.159.0"
   },
   "devDependencies": {
     "@types/three": "^0.159.0",
+    "@vitest/coverage-v8": "^4.1.9",
+    "happy-dom": "^20.10.6",
     "tsup": "^8.3.5",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.9"
   },
   "publishConfig": {
     "access": "public"
@@ -78,6 +87,8 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }