@pixerate/editor 0.241.0 → 0.242.0

package/dist/video-editor/controller.d.cts

@@ -15,7 +15,7 @@ import { type VideoSvgOptions } from './render.cjs';
 import type { VideoCameraFraming, VideoClipCamera, VideoClipEffect, VideoEffectValues, VideoPlacementMode, VideoProject } from './types.cjs';
 import { EffectsSlot } from '../effects/helpers.cjs';
 import { type VideoCameraBake } from './camera.cjs';
-import type { CameraMoveRole, CameraMoveSpec, EffectDescription, EffectProvider, EffectSummary, EffectValue } from '../effects/types.cjs';
+import type { CameraMoveRole, CameraMoveSpec, EffectDescription, EffectPathValue, EffectProvider, EffectSummary, EffectValue } from '../effects/types.cjs';
 import { VideoEffectsEngine, type VideoEffectPlace } from './effects.cjs';
 import { type VideoAnimatable, type VideoKey } from './keyframes.cjs';
 import { type VideoEditPlan, type VideoEditPlanInput } from './plan.cjs';
@@ -80,6 +80,26 @@ export type VideoCameraMoveResult = {
     ok: false;
     error: string;
 };
+/** The effect a path is drawn for on the preview: a clip, its effect instance ("generator" for an effect clip) and optionally the path control. */
+export interface VideoPathDrawingTarget {
+    clip: string;
+    instance: string;
+    control?: string;
+}
+/** A path for an effect that draws along one (`setEffectPath`). */
+export type VideoEffectPathInput = {
+    points: number[];
+} | {
+    d: string;
+} | {
+    mask: {
+        clip: string;
+    };
+} | {
+    text: string;
+    font?: string;
+    align?: 'start' | 'middle' | 'end';
+};
 export type VideoEffectEditResult = (VideoEditResult & {
     ok: true;
     clip: string;
@@ -116,6 +136,8 @@ export interface VideoEditorState {
     effectsProvider: EffectProvider | null;
     /** Proposed edit plans waiting for review, oldest first (see `proposePlan`). Not part of the project or its undo history. */
     plans: readonly VideoEditPlan[];
+    /** The effect a path is being drawn for on the preview (`startPathDrawing`), or `null`. Editor state. */
+    pathDrawing: VideoPathDrawingTarget | null;
     /** Bumped on every change. */
     revision: number;
 }
@@ -365,6 +387,32 @@ export declare class VideoEditorController {
     updateEffectValues(clip: string, part: 'generator' | 'transition', values: VideoEffectValues, options?: {
         merge?: string;
     }): Promise<VideoEffectEditResult>;
+    /**
+     * Gives an effect that draws along a path (see `pathControlsOf`) its path: on an effect clip
+     * (`instance` "generator") or a clip effect (its id). The path is frame points (`points`
+     * `[x0, y0, …]`, mapped into the pixels of the picture the effect renders: the project frame for
+     * an effect clip, the clip's own picture for a clip effect), SVG path data (`d`, which the effect
+     * fits as its control says; `""` clears it), the outline of a clip's mask (`mask`), or words the
+     * provider writes as a single-stroke path (`text`). `control` picks the path control when there
+     * are several. Checked before anything changes; one undo step. Returns the edit, the control and
+     * the value it took.
+     */
+    setEffectPath(clip: string, instance: string, path: VideoEffectPathInput, options?: {
+        control?: string;
+    }): Promise<VideoEffectEditResult & {
+        control?: string;
+        value?: EffectPathValue;
+    }>;
+    private pathDrawing;
+    /**
+     * Starts drawing a path on the preview for an effect that draws along one (the preview then
+     * takes the pointer; `finishPathDrawing` with the frame points applies it). Editor state.
+     */
+    startPathDrawing(target: VideoPathDrawingTarget): void;
+    /** Stops drawing a path without changing anything. */
+    cancelPathDrawing(): void;
+    /** Applies the drawn path (frame points) to the effect being drawn for, and stops drawing. One undo step. */
+    finishPathDrawing(points: number[]): Promise<VideoEffectEditResult>;
     /** Keys for one numeric control of a clip effect (clip-relative ms), or `null` to stop animating it (keeping its value at the clip's start). */
     setClipEffectKeyframes(clip: string, instance: string, control: string, keys: VideoKey[] | null): Promise<VideoEffectEditResult>;
     /** What plays at `time` (default: the playhead). */

package/dist/video-editor/controller.d.ts

@@ -15,7 +15,7 @@ import { type VideoSvgOptions } from './render.js';
 import type { VideoCameraFraming, VideoClipCamera, VideoClipEffect, VideoEffectValues, VideoPlacementMode, VideoProject } from './types.js';
 import { EffectsSlot } from '../effects/helpers.js';
 import { type VideoCameraBake } from './camera.js';
-import type { CameraMoveRole, CameraMoveSpec, EffectDescription, EffectProvider, EffectSummary, EffectValue } from '../effects/types.js';
+import type { CameraMoveRole, CameraMoveSpec, EffectDescription, EffectPathValue, EffectProvider, EffectSummary, EffectValue } from '../effects/types.js';
 import { VideoEffectsEngine, type VideoEffectPlace } from './effects.js';
 import { type VideoAnimatable, type VideoKey } from './keyframes.js';
 import { type VideoEditPlan, type VideoEditPlanInput } from './plan.js';
@@ -80,6 +80,26 @@ export type VideoCameraMoveResult = {
     ok: false;
     error: string;
 };
+/** The effect a path is drawn for on the preview: a clip, its effect instance ("generator" for an effect clip) and optionally the path control. */
+export interface VideoPathDrawingTarget {
+    clip: string;
+    instance: string;
+    control?: string;
+}
+/** A path for an effect that draws along one (`setEffectPath`). */
+export type VideoEffectPathInput = {
+    points: number[];
+} | {
+    d: string;
+} | {
+    mask: {
+        clip: string;
+    };
+} | {
+    text: string;
+    font?: string;
+    align?: 'start' | 'middle' | 'end';
+};
 export type VideoEffectEditResult = (VideoEditResult & {
     ok: true;
     clip: string;
@@ -116,6 +136,8 @@ export interface VideoEditorState {
     effectsProvider: EffectProvider | null;
     /** Proposed edit plans waiting for review, oldest first (see `proposePlan`). Not part of the project or its undo history. */
     plans: readonly VideoEditPlan[];
+    /** The effect a path is being drawn for on the preview (`startPathDrawing`), or `null`. Editor state. */
+    pathDrawing: VideoPathDrawingTarget | null;
     /** Bumped on every change. */
     revision: number;
 }
@@ -365,6 +387,32 @@ export declare class VideoEditorController {
     updateEffectValues(clip: string, part: 'generator' | 'transition', values: VideoEffectValues, options?: {
         merge?: string;
     }): Promise<VideoEffectEditResult>;
+    /**
+     * Gives an effect that draws along a path (see `pathControlsOf`) its path: on an effect clip
+     * (`instance` "generator") or a clip effect (its id). The path is frame points (`points`
+     * `[x0, y0, …]`, mapped into the pixels of the picture the effect renders: the project frame for
+     * an effect clip, the clip's own picture for a clip effect), SVG path data (`d`, which the effect
+     * fits as its control says; `""` clears it), the outline of a clip's mask (`mask`), or words the
+     * provider writes as a single-stroke path (`text`). `control` picks the path control when there
+     * are several. Checked before anything changes; one undo step. Returns the edit, the control and
+     * the value it took.
+     */
+    setEffectPath(clip: string, instance: string, path: VideoEffectPathInput, options?: {
+        control?: string;
+    }): Promise<VideoEffectEditResult & {
+        control?: string;
+        value?: EffectPathValue;
+    }>;
+    private pathDrawing;
+    /**
+     * Starts drawing a path on the preview for an effect that draws along one (the preview then
+     * takes the pointer; `finishPathDrawing` with the frame points applies it). Editor state.
+     */
+    startPathDrawing(target: VideoPathDrawingTarget): void;
+    /** Stops drawing a path without changing anything. */
+    cancelPathDrawing(): void;
+    /** Applies the drawn path (frame points) to the effect being drawn for, and stops drawing. One undo step. */
+    finishPathDrawing(points: number[]): Promise<VideoEffectEditResult>;
     /** Keys for one numeric control of a clip effect (clip-relative ms), or `null` to stop animating it (keeping its value at the clip's start). */
     setClipEffectKeyframes(clip: string, instance: string, control: string, keys: VideoKey[] | null): Promise<VideoEffectEditResult>;
     /** What plays at `time` (default: the playhead). */

package/dist/video-editor/effect-path.d.cts

@@ -0,0 +1,66 @@
+/**
+ * Paths for effects that draw along one (`pathControlsOf`): where a clip's picture is in the frame,
+ * so a path drawn on the frame can be handed to an effect in the pixels of the picture it renders.
+ *
+ * An effect clip renders at the project frame and is placed over it (filled, unless moved or
+ * scaled); a clip effect renders over the clip's picture as it comes from the source (a media
+ * clip's own size), before placement. Either way a frame point maps into the picture by undoing
+ * the clip's placement and rotation at its first frame.
+ */
+import type { VideoClip, VideoProject } from './types.cjs';
+/** A clip's picture: its size in pixels, where it is placed in the frame, and its rotation (degrees). */
+export interface VideoClipPicture {
+    size: {
+        width: number;
+        height: number;
+    };
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    rotation: number;
+}
+/** Where a clip's picture lies in the frame at its first frame. */
+export declare function videoClipPicture(project: VideoProject, clip: VideoClip): VideoClipPicture;
+/** Frame points `[x0, y0, x1, y1, …]` in the pixels of a clip's picture (rounded to 0.01 px). */
+export declare function framePointsToPicture(points: readonly number[], picture: VideoClipPicture): number[];
+/** A clip's mask outline as frame points `[x0, y0, …]` (its rotation applied), closed; `null` without a mask. */
+export declare function videoClipMaskOutline(project: VideoProject, clip: VideoClip): number[] | null;
+/**
+ * Collects a path drawn on the preview with a pointer, in frame pixels: `down` and `move` take the
+ * pointer's position over the preview element (`box`, its on-screen rect) and keep a point every
+ * `spacing` frame pixels. Framework-free, for the bindings.
+ */
+export declare class VideoPathGesture {
+    private readonly frame;
+    private readonly spacing;
+    points: number[];
+    private drawing;
+    constructor(frame: {
+        width: number;
+        height: number;
+    }, spacing?: number);
+    private at;
+    down(e: {
+        clientX: number;
+        clientY: number;
+    }, box: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }): void;
+    move(e: {
+        clientX: number;
+        clientY: number;
+    }, box: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }): boolean;
+    /** Ends the stroke; returns its points, or `null` for a tap (fewer than two points). */
+    up(): number[] | null;
+}

package/dist/video-editor/effect-path.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Paths for effects that draw along one (`pathControlsOf`): where a clip's picture is in the frame,
+ * so a path drawn on the frame can be handed to an effect in the pixels of the picture it renders.
+ *
+ * An effect clip renders at the project frame and is placed over it (filled, unless moved or
+ * scaled); a clip effect renders over the clip's picture as it comes from the source (a media
+ * clip's own size), before placement. Either way a frame point maps into the picture by undoing
+ * the clip's placement and rotation at its first frame.
+ */
+import type { VideoClip, VideoProject } from './types.js';
+/** A clip's picture: its size in pixels, where it is placed in the frame, and its rotation (degrees). */
+export interface VideoClipPicture {
+    size: {
+        width: number;
+        height: number;
+    };
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    rotation: number;
+}
+/** Where a clip's picture lies in the frame at its first frame. */
+export declare function videoClipPicture(project: VideoProject, clip: VideoClip): VideoClipPicture;
+/** Frame points `[x0, y0, x1, y1, …]` in the pixels of a clip's picture (rounded to 0.01 px). */
+export declare function framePointsToPicture(points: readonly number[], picture: VideoClipPicture): number[];
+/** A clip's mask outline as frame points `[x0, y0, …]` (its rotation applied), closed; `null` without a mask. */
+export declare function videoClipMaskOutline(project: VideoProject, clip: VideoClip): number[] | null;
+/**
+ * Collects a path drawn on the preview with a pointer, in frame pixels: `down` and `move` take the
+ * pointer's position over the preview element (`box`, its on-screen rect) and keep a point every
+ * `spacing` frame pixels. Framework-free, for the bindings.
+ */
+export declare class VideoPathGesture {
+    private readonly frame;
+    private readonly spacing;
+    points: number[];
+    private drawing;
+    constructor(frame: {
+        width: number;
+        height: number;
+    }, spacing?: number);
+    private at;
+    down(e: {
+        clientX: number;
+        clientY: number;
+    }, box: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }): void;
+    move(e: {
+        clientX: number;
+        clientY: number;
+    }, box: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }): boolean;
+    /** Ends the stroke; returns its points, or `null` for a tap (fewer than two points). */
+    up(): number[] | null;
+}