@miraiclip/templates

npm install @miraiclip/templates

@miraiclip/templatesCopy Anchor Link

FunctionsCopy Anchor Link

defineTemplateCopy Anchor Link

Build a template from a document and its declared fields; throws on incoherence.

function defineTemplate(input: Omit<Template, "version">): Template

Guides: Defining templates, Ad variants, Catalog to product video, Personalized video

describeTemplateCopy Anchor Link

A compact, deterministic template summary for prompts.

function describeTemplate(template: Template): string

Guides: CLI, Data & validation, Defining templates

extractFieldsCopy Anchor Link

Authoring aid: scan a document and propose its field list — one text field per distinct placeholder (refine types by hand: numbers, colors, enums), plus nothing for assets, which are declared intentionally.

function extractFields(doc: ProjectDocument): TemplateField[]

Guides: Defining templates

fitClipsToMediaCopy Anchor Link

Shorten video / audio clips that would play past the end of their media — e.g. after a media slot was filled with a clip shorter than the placeholder — and fit transitions to the footage their clips now have around each cut (shortened, or dropped when there's none). Later clips on the track don't move; returns a new document.

function fitClipsToMedia(doc: ProjectDocument): ProjectDocument

Guides: Roadmap, Data & validation, Catalog to product video

hydrateCopy Anchor Link

Hydrate: validate the payload, then return a NEW document with every blank filled. The template is never mutated. Throws TemplateValidationError on a bad payload; tryHydrate is the non-throwing variant.

function hydrate(template: Template, data: TemplateData): ProjectDocument

Guides: Data & validation, Defining templates, Ad variants, Catalog to product video

insertCommandsCopy Anchor Link

The commands that add source (e.g. hydrate(template, data)) to target. Pure: nothing is dispatched. Tracks without clips aren't added. The target's settings are left alone; compare source.settings yourself if the frame size matters.

function insertCommands(target: ProjectDocument, source: ProjectDocument, options?: InsertOptions): InsertPlan

Guides: Data & validation

insertDocumentCopy Anchor Link

Insert source into project as one undo step; returns the plan (ids, time range).

function insertDocument(project: Project, source: ProjectDocument, options?: InsertOptions): InsertPlan

Guides: Roadmap, Data & validation

parseTemplateCopy Anchor Link

Parse and validate untrusted template JSON (a parsed file, an API body).

function parseTemplate(json: unknown): Template

Guides: Batch rendering, CLI, Defining templates, Ad variants

rowsFromCsvCopy Anchor Link

CSV rows against a template: cells are strings, so values coerce to each field's declared type (numbers, booleans); an empty cell means "not provided" and the field's default applies.

function rowsFromCsv(template: Template, text: string): TemplateData[]

Guides: Batch rendering, Data & validation, Personalized video

rowsFromNdjsonCopy Anchor Link

One JSON object per non-empty line.

function rowsFromNdjson(text: string): TemplateData[]

Guides: Data & validation

scanPlaceholdersCopy Anchor Link

Every placeholder site in the document, in a stable order.

function scanPlaceholders(doc: ProjectDocument): PlaceholderSite[]

Guides: Defining templates

suggestTemplateFieldsCopy Anchor Link

Every place in the document that could be a field, in timeline order: text clips, string params of html clips (designed text, backgrounds; params starting with "_" are bookkeeping and skipped), and video / image / audio assets used by clips (media slots). Names are unique and stable for the same document.

function suggestTemplateFields(doc: ProjectDocument): TemplateCandidate[]

Guides: Defining templates

templateFromDocumentCopy Anchor Link

Make a template from a document: each chosen candidate becomes an optional field defaulting to its current value (a {{name}} placeholder in the text or param; asset fields swap the asset's src). The document is not modified. Hydrating the result with {} gives back the original content.

function templateFromDocument(doc: ProjectDocument, options: TemplateFromDocumentOptions): Template

Guides: Defining templates

toFieldToolDefinitionCopy Anchor Link

The template's fields as one ready-to-send tool definition — the payload an agent produces is exactly what hydrate takes.

function toFieldToolDefinition(template: Template, options?: ToFieldToolDefinitionOptions): unknown

Guides: Tools from the command catalog, Data & validation, Ad variants

tryHydrateCopy Anchor Link

Hydrate with machine-readable failures (the tryDispatch of templates).

function tryHydrate(template: Template, data: TemplateData): HydrateResult

Guides: Batch rendering, Data & validation, Ad variants, Catalog to product video

validateDataCopy Anchor Link

Validate a payload against the template's fields; returns resolved values with defaults applied.

function validateData(template: Template, data: TemplateData): {
    resolved: Resolved;
    issues: TemplateIssue[];
}

Guides: Data & validation

ClassesCopy Anchor Link

TemplateValidationErrorCopy Anchor Link

Thrown by defineTemplate/parseTemplate/hydrate on invalid input.

Extends Error.

new TemplateValidationError(issues: TemplateIssue[])

Guides: Data & validation, Defining templates

InterfacesCopy Anchor Link

AssetFieldCopy Anchor Link

A media slot: the payload's value replaces the named asset's src (and optionally durationUs). Hydration never touches clip timing — swapped video/audio should match the placeholder's duration, or carry durationUs.

Extends FieldBase.

BooleanFieldCopy Anchor Link

Extends FieldBase.

ColorFieldCopy Anchor Link

A CSS color string ("#ff8c32", "rgb(...)", "tomato").

Extends FieldBase.

InsertOptionsCopy Anchor Link

Putting a (hydrated) template into a project that already has content: the document becomes a batch of ordinary commands — assets, tracks on top of the existing ones, clips shifted to the insert time, their keyframes, effects and transitions — with every id remapped so nothing collides. insertDocument dispatches the batch as one transaction (one undo step).

InsertPlanCopy Anchor Link

NumberFieldCopy Anchor Link

Extends FieldBase.

PlaceholderSiteCopy Anchor Link

Placeholder scanning: where {{field}} may appear in a document, and what a document's placeholders are. The binding surface is deliberately small and safe — sites whose values are CONTENT, never structure:

• text clip text
• caption word text
• html clip params STRING values

An html clip's template is NOT a site: its own {{param}} placeholders belong to the clip's params and are consumed by the rasterizer — template fields bind through the clip's params instead. Asset fields don't use placeholders at all; they name an asset id.

TemplateCopy Anchor Link

A template: an ordinary ProjectDocument plus the declared blanks. Plain JSON end to end — it serializes, crosses process boundaries, and needs no code to run, exactly like the documents it hydrates.

Guides: Defining templates

TemplateFromDocumentOptionsCopy Anchor Link

TemplateIssueCopy Anchor Link

One machine-readable problem with a template or a payload.

TextFieldCopy Anchor Link

Extends FieldBase.

ToFieldToolDefinitionOptionsCopy Anchor Link

The AI surface: a template's fields as an LLM tool, and a compact template summary for prompts — same philosophy as core's toToolDefinitions and describeProject. An agent designs the template once (via commands/MCP); from then on FILLING it is a plain tool call with a typed schema, and no LLM sits in the render loop.

TypesCopy Anchor Link

AssetValueCopy Anchor Link

An asset payload value: a source alone, or a source with its duration.

type AssetValue = string | {
    src: string;
    durationUs?: number;
};

HydrateResultCopy Anchor Link

tryHydrate's result: a hydrated document, or the issues an agent can self-correct from.

type HydrateResult = {
    ok: true;
    doc: ProjectDocument;
} | {
    ok: false;
    issues: TemplateIssue[];
};

TemplateCandidateCopy Anchor Link

Something in a document that can become a template field.

type TemplateCandidate = {
    kind: "text";
    name: string;
    label: string;
    clipId: string;
    value: string;
} | {
    kind: "param";
    name: string;
    label: string;
    clipId: string;
    param: string;
    value: string;
    color: boolean;
} | {
    kind: "asset";
    name: string;
    label: string;
    assetId: string;
    assetKind: "video" | "image" | "audio";
    value: string;
};

TemplateDataCopy Anchor Link

One data row: field name → value.

type TemplateData = Record<string, TemplateValue>;

TemplateFieldCopy Anchor Link

A template field: one declared blank in the document. The declaration is the whole API surface — it drives payload validation, UI form generation, and LLM tool schemas, the same one-source-of-truth pattern as the command catalog.

type TemplateField = TextField | NumberField | BooleanField | ColorField | AssetField;

TemplateValueCopy Anchor Link

A payload value for any field.

type TemplateValue = string | number | boolean | AssetValue;

@miraiclip/templates/render (Node)Copy Anchor Link

FunctionsCopy Anchor Link

renderTemplateBatchCopy Anchor Link

Render every row of rows through the template. Rows that fail (bad payload, missing media) are reported per row and never abort the others, unless stopOnError asks for that.

function renderTemplateBatch(template: Template, rows: TemplateData[], options: RenderTemplateBatchOptions): Promise<RenderTemplateBatchResult>

Guides: Batch rendering, CLI, Ad variants, Catalog to product video

InterfacesCopy Anchor Link

BatchProgressCopy Anchor Link

BatchRowCopy Anchor Link

Batch rendering (Node-only): hydrate a template once per data row and export each hydrated document through ONE (or a few) warm headless-Chrome export sessions — createExportSession keeps the browser alive across rows, so a row costs an export, not a browser launch.

Import path: @miraiclip/templates/render — kept out of the main entry so browser bundles never touch playwright.

Guides: Batch rendering

RenderTemplateBatchOptionsCopy Anchor Link

Extends Omit<ExportFileOptions, "out" \| "onProgress" \| "signal">, Pick<CreateExportSessionOptions, "assets" \| "assetsDir" \| "browser">.

RenderTemplateBatchResultCopy Anchor Link