@pixerate/editor 0.234.0 → 0.235.0

package/dist/effects/index.js

@@ -12,10 +12,14 @@ import {
   effectLayerInput,
   effectLayerOffered,
   effectLayerRole,
+  effectLayerSpan,
   effectSequenceEffects,
   effectSequenceSlots,
+  effectSequenceTiming,
   effectSubjectKind,
   effectSubjectProblem,
+  effectTemplateTools,
+  fillEffectTemplate,
   isSubjectTemplateSlot,
   searchTemplateSummaries,
   templateDefaultValues,
@@ -24,7 +28,7 @@ import {
   templateSlotTakes,
   templateValueProblem,
   templateValuesSchema
-} from "../chunk-I277KJLQ.js";
+} from "../chunk-G3RUKJ5C.js";
 import {
   EffectRendererPool
 } from "../chunk-EHLOCVWB.js";
@@ -1574,16 +1578,20 @@ export {
   effectLayerInput,
   effectLayerOffered,
   effectLayerRole,
+  effectLayerSpan,
   effectOffered,
   effectParameterFields,
   effectSampleInputs,
   effectSamplePicture,
   effectSequenceEffects,
   effectSequenceSlots,
+  effectSequenceTiming,
   effectSubjectKind,
   effectSubjectProblem,
+  effectTemplateTools,
   effectValueErrors,
   encodeEffectFloat,
+  fillEffectTemplate,
   groupEffectsByCategory,
   hasEffectTags,
   isCameraView,

package/dist/effects/template-tools.d.cts

@@ -0,0 +1,25 @@
+/**
+ * Agent tools for the provider's sequence templates, shared by the editors that can load an
+ * `EffectSequence`: `list_templates`, `describe_template` and `fill_template`. An editor gives
+ * them to its effect tool provider (`extraTools`) with an `EffectTemplateToolHost` that says what
+ * filling makes there and does it as one undo step.
+ */
+import type { AgentTool } from '../tools/registry.cjs';
+import type { JsonSchema } from '../tools/schema.cjs';
+import type { EffectToolContext } from './tools.cjs';
+import type { EffectProvider } from './types.cjs';
+export interface EffectTemplateToolHost {
+    /** The current provider, or `null`. */
+    provider(): EffectProvider | null;
+    /** Added to `fill_template`'s description: what filling makes in this editor and what it returns. */
+    fillDetails: string;
+    /** Arguments `fill_template` takes in this editor besides `template`, `values` and `name`. */
+    fillOptions?: Record<string, JsonSchema>;
+    /** Fills the template and loads it as one undo step; returns what it made. Throws a sentence when it cannot. */
+    fill(template: string, values: Record<string, unknown>, options: {
+        name?: string;
+        [option: string]: unknown;
+    }): Promise<Record<string, unknown>>;
+}
+/** The template tools (see the module comment). */
+export declare function effectTemplateTools(host: EffectTemplateToolHost, ctx: EffectToolContext): AgentTool[];

package/dist/effects/template-tools.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Agent tools for the provider's sequence templates, shared by the editors that can load an
+ * `EffectSequence`: `list_templates`, `describe_template` and `fill_template`. An editor gives
+ * them to its effect tool provider (`extraTools`) with an `EffectTemplateToolHost` that says what
+ * filling makes there and does it as one undo step.
+ */
+import type { AgentTool } from '../tools/registry.js';
+import type { JsonSchema } from '../tools/schema.js';
+import type { EffectToolContext } from './tools.js';
+import type { EffectProvider } from './types.js';
+export interface EffectTemplateToolHost {
+    /** The current provider, or `null`. */
+    provider(): EffectProvider | null;
+    /** Added to `fill_template`'s description: what filling makes in this editor and what it returns. */
+    fillDetails: string;
+    /** Arguments `fill_template` takes in this editor besides `template`, `values` and `name`. */
+    fillOptions?: Record<string, JsonSchema>;
+    /** Fills the template and loads it as one undo step; returns what it made. Throws a sentence when it cannot. */
+    fill(template: string, values: Record<string, unknown>, options: {
+        name?: string;
+        [option: string]: unknown;
+    }): Promise<Record<string, unknown>>;
+}
+/** The template tools (see the module comment). */
+export declare function effectTemplateTools(host: EffectTemplateToolHost, ctx: EffectToolContext): AgentTool[];

package/dist/effects/templates.d.cts

@@ -4,7 +4,7 @@
  * a sequence before loading it, and which input a layer's subject feeds. Dependency-free.
  */
 import type { JsonSchema } from '../tools/schema.cjs';
-import { type EffectDescription, type EffectLayer, type EffectLayerRole, type EffectSequence, type EffectSubjectKind, type EffectSummary, type EffectTemplateSearchOptions, type EffectTemplateSlot, type EffectTemplateSummary } from './types.cjs';
+import { type EffectDescription, type EffectProvider, type EffectTemplateDescription, type EffectTemplateOptions, type EffectLayer, type EffectLayerRole, type EffectSequence, type EffectSubjectKind, type EffectSummary, type EffectTemplateSearchOptions, type EffectTemplateSlot, type EffectTemplateSummary } from './types.cjs';
 export declare const EFFECT_SEQUENCE_NAME: RegExp;
 /** True for a subject slot (`image`, `video`, `svg`). */
 export declare const isSubjectTemplateSlot: (slot: Pick<EffectTemplateSlot, "type">) => boolean;
@@ -54,3 +54,32 @@ export declare function checkEffectSequence(sequence: unknown, catalog?: readonl
 export declare function effectSequenceEffects(sequence: EffectSequence): string[];
 /** Subject slots a sequence leaves for the host (`{ slot }` subjects), each once. */
 export declare function effectSequenceSlots(sequence: EffectSequence): string[];
+/** A filled template, checked and ready for an editor to load. */
+export interface FilledEffectTemplate {
+    template: EffectTemplateDescription;
+    sequence: EffectSequence;
+    openSlots: string[];
+    notes: string[];
+}
+/**
+ * Fills a provider template for an editor: checks the provider has templates, checks `values`
+ * against the slots first (every problem at once, as sentences), fills it, and checks the
+ * sequence against the provider's catalog before anything is loaded. Throws an `Error` whose
+ * message says what is wrong and what to call instead; never returns a sequence that names
+ * effects the provider does not list.
+ */
+export declare function fillEffectTemplate(provider: EffectProvider | null | undefined, id: string, values?: unknown, options?: EffectTemplateOptions): Promise<FilledEffectTemplate>;
+/** Where a layer of a sequence shows, in ms from the sequence's start, given each shot's start and the total length. */
+export declare function effectLayerSpan(layer: Pick<EffectLayer, 'from' | 'until'>, shotIndex: number, shotStarts: readonly number[], total: number): {
+    start: number;
+    end: number;
+};
+/**
+ * When each shot of a sequence starts and how long it all lasts (ms): a shot plays its lead-in (the
+ * longer of its transition and its camera move in, when the move says its `ms`) and then holds.
+ */
+export declare function effectSequenceTiming(sequence: EffectSequence): {
+    starts: number[];
+    leadIns: number[];
+    total: number;
+};

package/dist/effects/templates.d.ts

@@ -4,7 +4,7 @@
  * a sequence before loading it, and which input a layer's subject feeds. Dependency-free.
  */
 import type { JsonSchema } from '../tools/schema.js';
-import { type EffectDescription, type EffectLayer, type EffectLayerRole, type EffectSequence, type EffectSubjectKind, type EffectSummary, type EffectTemplateSearchOptions, type EffectTemplateSlot, type EffectTemplateSummary } from './types.js';
+import { type EffectDescription, type EffectProvider, type EffectTemplateDescription, type EffectTemplateOptions, type EffectLayer, type EffectLayerRole, type EffectSequence, type EffectSubjectKind, type EffectSummary, type EffectTemplateSearchOptions, type EffectTemplateSlot, type EffectTemplateSummary } from './types.js';
 export declare const EFFECT_SEQUENCE_NAME: RegExp;
 /** True for a subject slot (`image`, `video`, `svg`). */
 export declare const isSubjectTemplateSlot: (slot: Pick<EffectTemplateSlot, "type">) => boolean;
@@ -54,3 +54,32 @@ export declare function checkEffectSequence(sequence: unknown, catalog?: readonl
 export declare function effectSequenceEffects(sequence: EffectSequence): string[];
 /** Subject slots a sequence leaves for the host (`{ slot }` subjects), each once. */
 export declare function effectSequenceSlots(sequence: EffectSequence): string[];
+/** A filled template, checked and ready for an editor to load. */
+export interface FilledEffectTemplate {
+    template: EffectTemplateDescription;
+    sequence: EffectSequence;
+    openSlots: string[];
+    notes: string[];
+}
+/**
+ * Fills a provider template for an editor: checks the provider has templates, checks `values`
+ * against the slots first (every problem at once, as sentences), fills it, and checks the
+ * sequence against the provider's catalog before anything is loaded. Throws an `Error` whose
+ * message says what is wrong and what to call instead; never returns a sequence that names
+ * effects the provider does not list.
+ */
+export declare function fillEffectTemplate(provider: EffectProvider | null | undefined, id: string, values?: unknown, options?: EffectTemplateOptions): Promise<FilledEffectTemplate>;
+/** Where a layer of a sequence shows, in ms from the sequence's start, given each shot's start and the total length. */
+export declare function effectLayerSpan(layer: Pick<EffectLayer, 'from' | 'until'>, shotIndex: number, shotStarts: readonly number[], total: number): {
+    start: number;
+    end: number;
+};
+/**
+ * When each shot of a sequence starts and how long it all lasts (ms): a shot plays its lead-in (the
+ * longer of its transition and its camera move in, when the move says its `ms`) and then holds.
+ */
+export declare function effectSequenceTiming(sequence: EffectSequence): {
+    starts: number[];
+    leadIns: number[];
+    total: number;
+};

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

@@ -52,6 +52,22 @@ export interface VideoEditorOptions {
 }
 /** What `applyClipEffect` and the other effect edits return: the edit result plus what they made or changed. */
 /** What setting or clearing a clip's camera move did: its camera now, the keys baked per property, any cuts and when each move plays (clip ms). */
+/** What filling a template did (see `fillTemplate`). */
+export type VideoTemplateResult = {
+    ok: true;
+    template: string;
+    tracks: string[];
+    clips: string[];
+    assets: string[];
+    start: number;
+    end: number;
+    placeholders: Record<string, string[]>;
+    openSlots: string[];
+    notes: string[];
+} | {
+    ok: false;
+    error: string;
+};
 export type VideoCameraMoveResult = {
     ok: true;
     clip: string;
@@ -257,6 +273,16 @@ export declare class VideoEditorController {
     useEffects(provider: EffectProvider): () => void;
     /** The provider's description of an effect, checked for `place` (rejects without a provider or for an unknown id). */
     describeEffect(effect: string, place?: VideoEffectPlace): Promise<EffectDescription>;
+    /**
+     * 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.
+     */
+    fillTemplate(template: string, values?: Record<string, unknown>, options?: {
+        name?: string;
+        at?: number;
+    }): Promise<VideoTemplateResult>;
     private refused;
     private effectEdit;
     private clipOrThrow;

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

@@ -52,6 +52,22 @@ export interface VideoEditorOptions {
 }
 /** What `applyClipEffect` and the other effect edits return: the edit result plus what they made or changed. */
 /** What setting or clearing a clip's camera move did: its camera now, the keys baked per property, any cuts and when each move plays (clip ms). */
+/** What filling a template did (see `fillTemplate`). */
+export type VideoTemplateResult = {
+    ok: true;
+    template: string;
+    tracks: string[];
+    clips: string[];
+    assets: string[];
+    start: number;
+    end: number;
+    placeholders: Record<string, string[]>;
+    openSlots: string[];
+    notes: string[];
+} | {
+    ok: false;
+    error: string;
+};
 export type VideoCameraMoveResult = {
     ok: true;
     clip: string;
@@ -257,6 +273,16 @@ export declare class VideoEditorController {
     useEffects(provider: EffectProvider): () => void;
     /** The provider's description of an effect, checked for `place` (rejects without a provider or for an unknown id). */
     describeEffect(effect: string, place?: VideoEffectPlace): Promise<EffectDescription>;
+    /**
+     * 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.
+     */
+    fillTemplate(template: string, values?: Record<string, unknown>, options?: {
+        name?: string;
+        at?: number;
+    }): Promise<VideoTemplateResult>;
     private refused;
     private effectEdit;
     private clipOrThrow;