@pixerate/editor 0.234.0 → 0.235.0

package/dist/video-editor/index.js

@@ -153,6 +153,13 @@ import {
 import {
   namedWithSuggestion
 } from "../chunk-EUKY4KFX.js";
+import {
+  effectLayerRole,
+  effectLayerSpan,
+  effectSequenceTiming,
+  effectTemplateTools,
+  fillEffectTemplate
+} from "../chunk-G3RUKJ5C.js";
 import "../chunk-EHLOCVWB.js";
 import {
   CAMERA_MOVE_MAX_MS,
@@ -3454,6 +3461,106 @@ var VideoPreviewEngine = class {
   }
 };
 
+// src/video-editor/sequence.ts
+var svgUrl = (svg) => svg.trimStart().startsWith("<") ? `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}` : svg;
+var GROUPS = ["base", "background", "subject", "overlay", "text"];
+function videoEditsFromSequence(project, sequence, options = {}) {
+  const at = options.at ?? videoProjectDuration(project);
+  const W = project.width;
+  const H = project.height;
+  const sx = W / sequence.stage.width;
+  const sy = H / sequence.stage.height;
+  const timing = effectSequenceTiming(sequence);
+  const provider = options.provider ? { provider: options.provider } : {};
+  const notes = [];
+  const usedClips = new Set(allVideoClipIds(project));
+  const usedTracks = new Set(project.tracks.map((t) => t.id));
+  const usedAssets = new Set(project.assets.map((a) => a.id));
+  const fresh = (used, base) => {
+    for (let i = 1; ; i++) if (!used.has(`${base}${i}`)) return used.add(`${base}${i}`), `${base}${i}`;
+  };
+  const edits = [];
+  const assets = [];
+  const placeholders = {};
+  const items = [];
+  const placement = (r) => {
+    if (!r) return {};
+    const x = (r.x + r.width / 2) * sx - W / 2;
+    const y = (r.y + r.height / 2) * sy - H / 2;
+    const scale = Math.min(r.width * sx / W, r.height * sy / H);
+    return { transform: { x: Math.round(x * 100) / 100, y: Math.round(y * 100) / 100, scale: Math.round(scale * 1e3) / 1e3 } };
+  };
+  const clipOf = (layer, start, duration, shot) => {
+    const id = fresh(usedClips, "tpl-c");
+    const common = { id, start, duration, ...layer.opacity !== void 0 && layer.opacity < 1 ? { opacity: layer.opacity } : {}, ...layer.fade ? { fadeIn: layer.fade, fadeOut: layer.fade } : {}, ...placement(layer.rect) };
+    const effects = layer.effect ? { effects: [{ id: "fx1", effect: layer.effect, ...provider, ...layer.values ? { values: layer.values } : {} }] } : {};
+    const s = layer.subject;
+    if (!s) return { ...common, type: "effect", effect: layer.effect, ...provider, ...layer.values ? { values: layer.values } : {} };
+    if ("slot" in s) {
+      (placeholders[s.slot] ??= []).push(id);
+      if (layer.effect) notes.push(`Shot ${shot + 1}: the "${s.slot}" slot is a grey placeholder; when you swap in the picture, apply ${layer.effect} to it again (apply_effect).`);
+      return { ...common, type: "color", color: "#475569", name: `Slot "${s.slot}"` };
+    }
+    if ("text" in s) return { ...common, type: "text", text: s.text, ...s.font ? { fontFamily: s.font } : {}, ...typeof s.weight === "number" ? { fontWeight: s.weight } : {}, ...effects };
+    const asset = fresh(usedAssets, "tpl-a");
+    assets.push(asset);
+    if ("video" in s) {
+      notes.push(`Shot ${shot + 1}: a video's length is not known here, so its asset is given the clip's length (${Math.round(duration)} ms); correct it with update_video_asset if it is longer.`);
+      edits.push({ op: "add_asset", asset: { id: asset, kind: "video", src: s.video, duration } });
+    } else edits.push({ op: "add_asset", asset: { id: asset, kind: "image", src: "image" in s ? s.image : svgUrl(s.svg) } });
+    return { ...common, type: "media", asset, fit: "contain", ...effects };
+  };
+  sequence.shots.forEach((shot, i) => {
+    const shotStart = timing.starts[i];
+    const shotEnd = timing.starts[i + 1] ?? timing.total;
+    let base;
+    shot.layers.forEach((layer, j) => {
+      const span = effectLayerSpan(layer, i, timing.starts, timing.total);
+      if (span.end - span.start <= 0) return void notes.push(`Shot ${i + 1}, layer ${j + 1} lasts no time, so it was left out.`);
+      const clip = clipOf(layer, at + span.start, span.end - span.start, i);
+      const isBase = j === 0 && !base && span.start === shotStart && span.end === shotEnd && effectLayerRole(layer) === "background" && !layer.rect;
+      const item = { group: isBase ? "base" : effectLayerRole(layer), clip };
+      if (isBase) base = item;
+      items.push(item);
+    });
+    if (!base) {
+      base = { group: "base", clip: { id: fresh(usedClips, "tpl-c"), type: "color", color: "#000000", name: `Shot ${i + 1}`, start: at + shotStart, duration: shotEnd - shotStart } };
+      items.push(base);
+    }
+    if (i > 0 && shot.transition) {
+      base.clip.transition = { type: "effect", duration: shot.transition.ms ?? 800, effect: { effect: shot.transition.effect, ...provider, ...shot.transition.values ? { values: shot.transition.values } : {} } };
+      if (shot.layers.length > 1) notes.push(`Shot ${i + 1}: its transition blends the clips on the base track; the layers above it cut.`);
+    }
+    const words = (text, y, size, name) => items.push({ group: "text", clip: { id: fresh(usedClips, "tpl-c"), type: "text", text, name, fontSize: Math.round(size), start: at + shotStart, duration: shotEnd - shotStart, transform: { x: 0, y: Math.round(y) } } });
+    if (shot.title) words(shot.title, 0, H * 0.09, "Title");
+    if (shot.caption) words(shot.caption, H * 0.35, H * 0.045, "Caption");
+    if (shot.camera?.in !== void 0 || shot.camera?.during !== void 0 || shot.camera?.framing) notes.push(`Shot ${i + 1}: its camera framing and moves were not carried over; set them with set_clip_camera_move on its clips.`);
+  });
+  const lanes = [];
+  for (const group of GROUPS) {
+    const mine = [];
+    for (const item of items.filter((x) => x.group === group).sort((a, b) => a.clip.start - b.clip.start)) {
+      let lane = group === "base" ? mine[0] : mine.find((l) => l.ends.every((e) => e <= item.clip.start + 1e-6));
+      if (!lane) mine.push(lane = { group, id: fresh(usedTracks, "tpl-v"), ends: [], clips: [] });
+      lane.ends.push(item.clip.start + item.clip.duration);
+      lane.clips.push(item);
+    }
+    lanes.push(...mine);
+  }
+  for (const lane of lanes) edits.push({ op: "add_track", track: { id: lane.id, kind: "video", name: `Template ${lane.group}` }, at: 0 });
+  for (const lane of lanes) for (const item of lane.clips) edits.push({ op: "add_clip", track: lane.id, clip: item.clip });
+  return {
+    edits,
+    clips: lanes.flatMap((l) => l.clips.map((c) => c.clip.id)),
+    tracks: lanes.map((l) => l.id).reverse(),
+    assets,
+    start: at,
+    end: at + timing.total,
+    placeholders,
+    notes
+  };
+}
+
 // src/video-editor/controller.ts
 var VideoEditorController = class _VideoEditorController {
   history;
@@ -3818,6 +3925,29 @@ var VideoEditorController = class _VideoEditorController {
     if (place) checkVideoEffectPlace(d, place);
     return d;
   }
+  /**
+   * Fills a provider sequence template and puts it on the timeline at `at` (default the end), on
+   * new tracks above the others (see `videoEditsFromSequence`). Values are checked first and every
+   * problem is refused at once. One undo step. Returns the new tracks, clips and assets, where it
+   * starts and ends, the placeholder clips standing in for open slots, and notes.
+   */
+  async fillTemplate(template, values = {}, options = {}) {
+    const reason = this.readOnlyReason();
+    if (reason) return this.refused(reason);
+    if (options.at !== void 0 && !(Number.isFinite(options.at) && options.at >= 0)) return this.refused(`"at" is a time in ms, 0 or more (got ${options.at}).`);
+    let filled;
+    try {
+      filled = await fillEffectTemplate(this.effects.provider, template, values, options.name ? { name: options.name } : {});
+    } catch (error) {
+      if (isEffectError(error) || error instanceof Error) return this.refused(error.message);
+      throw error;
+    }
+    const made = videoEditsFromSequence(this.getState().project, filled.sequence, { at: options.at, provider: this.effects.provider.id });
+    const r = this.apply(made.edits, `Template ${filled.template.name}`);
+    if (!r.ok) return r;
+    const { edits: _edits, notes, ...rest } = made;
+    return { ok: true, template, ...rest, openSlots: filled.openSlots, notes: [...filled.notes, ...notes] };
+  }
   refused(message) {
     return this.refuse(message);
   }
@@ -5923,6 +6053,20 @@ function createVideoEffectsToolProvider(controller, options = {}) {
     subscribe: (notify) => controller.subscribe(() => notify()),
     extraTools: (ctx) => [
       ...videoCameraMoveTools(controller, ctx),
+      ...effectTemplateTools(
+        {
+          provider: () => controller.effectsProvider,
+          fillDetails: `It goes on the timeline at "at" (default the end of the project), on new tracks above the others: each shot's bottom layer on a base track (with the shot's transition), other layers as effect, picture and text clips on tracks by role, titles and captions as text clips; an open subject slot becomes a grey placeholder clip named after it. Camera moves are not carried over. Returns { template, tracks, clips, assets, start, end (ms), placeholders (clip ids by open slot), openSlots, notes }. To fill an open slot, add the picture with add_video_asset and put it on the placeholder's track at its start with add_video_clip in overwrite mode.`,
+          fillOptions: { at: { type: "number", minimum: 0, description: "Where on the timeline it starts, ms (default the end of the project)." } },
+          fill: async (template, values, options2) => {
+            const r = await controller.fillTemplate(template, values, { name: options2.name, at: options2.at });
+            if (!r.ok) throw new Error(r.error);
+            const { ok: _ok, ...rest } = r;
+            return rest;
+          }
+        },
+        ctx
+      ),
       {
         name: "add_video_effect_clip",
         title: "Add an effect clip",
@@ -6684,6 +6828,7 @@ export {
   videoEaseBezier,
   videoEaseProgress,
   videoEaseToAnimationEasing,
+  videoEditsFromSequence,
   videoEffectFrameTime,
   videoEffectLayerKey,
   videoEffectValuesAt,

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

@@ -0,0 +1,38 @@
+/**
+ * An effects provider's `EffectSequence` (what a sequence template fills to) as video edits, so a
+ * template lands on the timeline as one undo step:
+ *
+ * - Each shot's bottom layer, when it lasts exactly the shot, goes on a base track; otherwise the
+ *   shot gets a black colour clip there. A shot's transition goes on its base clip (a provider
+ *   `effect` transition from the base clip before), so it blends the base pictures.
+ * - Other layers go on tracks above by role (background, subject, overlay), packed so clips of a
+ *   track never overlap: an effect with no subject is an effect clip; a picture or SVG is a media
+ *   clip on a new image asset, carrying the layer's effect as a clip effect; words are a text clip;
+ *   an open slot is a grey placeholder colour clip named after it.
+ * - A layer's `rect` becomes the clip's placement; `opacity` and `fade` carry over.
+ * - Titles and captions are text clips on the top track.
+ *
+ * Camera moves are not carried over (notes say so); set them with `set_clip_camera_move`.
+ */
+import type { EffectSequence } from '../effects/types.cjs';
+import type { VideoEdit } from './edit.cjs';
+import type { VideoProject } from './types.cjs';
+export interface VideoSequenceEdits {
+    edits: VideoEdit[];
+    /** The new clips' ids, base clips first. */
+    clips: string[];
+    /** The new tracks' ids, top to bottom. */
+    tracks: string[];
+    assets: string[];
+    /** Where the sequence starts and ends on the timeline (ms). */
+    start: number;
+    end: number;
+    /** Placeholder clips standing in for open subject slots, by slot. */
+    placeholders: Record<string, string[]>;
+    notes: string[];
+}
+/** The edits that put a sequence on a project's timeline at `at` (default its end), on new tracks above the others. */
+export declare function videoEditsFromSequence(project: VideoProject, sequence: EffectSequence, options?: {
+    at?: number;
+    provider?: string;
+}): VideoSequenceEdits;

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

@@ -0,0 +1,38 @@
+/**
+ * An effects provider's `EffectSequence` (what a sequence template fills to) as video edits, so a
+ * template lands on the timeline as one undo step:
+ *
+ * - Each shot's bottom layer, when it lasts exactly the shot, goes on a base track; otherwise the
+ *   shot gets a black colour clip there. A shot's transition goes on its base clip (a provider
+ *   `effect` transition from the base clip before), so it blends the base pictures.
+ * - Other layers go on tracks above by role (background, subject, overlay), packed so clips of a
+ *   track never overlap: an effect with no subject is an effect clip; a picture or SVG is a media
+ *   clip on a new image asset, carrying the layer's effect as a clip effect; words are a text clip;
+ *   an open slot is a grey placeholder colour clip named after it.
+ * - A layer's `rect` becomes the clip's placement; `opacity` and `fade` carry over.
+ * - Titles and captions are text clips on the top track.
+ *
+ * Camera moves are not carried over (notes say so); set them with `set_clip_camera_move`.
+ */
+import type { EffectSequence } from '../effects/types.js';
+import type { VideoEdit } from './edit.js';
+import type { VideoProject } from './types.js';
+export interface VideoSequenceEdits {
+    edits: VideoEdit[];
+    /** The new clips' ids, base clips first. */
+    clips: string[];
+    /** The new tracks' ids, top to bottom. */
+    tracks: string[];
+    assets: string[];
+    /** Where the sequence starts and ends on the timeline (ms). */
+    start: number;
+    end: number;
+    /** Placeholder clips standing in for open subject slots, by slot. */
+    placeholders: Record<string, string[]>;
+    notes: string[];
+}
+/** The edits that put a sequence on a project's timeline at `at` (default its end), on new tracks above the others. */
+export declare function videoEditsFromSequence(project: VideoProject, sequence: EffectSequence, options?: {
+    at?: number;
+    provider?: string;
+}): VideoSequenceEdits;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.234.0",
+  "version": "0.235.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",