motionrender 0.0.0-stage → 0.2.0

package/dist/types/packages/ai/src/assets.d.ts

@@ -0,0 +1,26 @@
+import { type Composition } from '../../core/src/index.js';
+/**
+ * assets: the supplied assets, id to src. srcs: other sources that are fine as they are (used when changing an existing composition).
+ * relativeInside: also allow relative paths that cannot leave the project folder (for pasted JSON, where nothing is supplied).
+ */
+export type AssetPolicy = {
+    assets: Map<string, string>;
+    srcs?: Set<string>;
+    relativeInside?: boolean;
+};
+/** Problems with the assets a composition declares or uses, in the wording used to ask the model to fix them. */
+export declare function assetProblems(composition: Composition, policy: AssetPolicy): string[];
+/**
+ * The policy for changing a composition that already exists: what it already declares and uses stays allowed (read both as written
+ * and with its templates expanded), plus anything newly supplied; anything else is new and refused.
+ */
+export declare function refinePolicy(current: unknown, supplied?: {
+    id: string;
+    src: string;
+}[]): AssetPolicy;
+/** A declared asset that is one of the supplied ones gets the supplied src, however the model spelled it. */
+export declare function restoreSuppliedSources(raw: any, supplied?: {
+    id: string;
+    type?: string;
+    src: string;
+}[]): void;

package/dist/types/packages/ai/src/batch.d.ts

@@ -0,0 +1,19 @@
+import { type Composition, type RenderMediaOptions } from '../../core/src/index.js';
+export type BatchSettings = Pick<RenderMediaOptions, 'preset' | 'crf' | 'bitrate' | 'audioBitrate' | 'scale' | 'loudness' | 'format' | 'codec' | 'transparent' | 'concurrency' | 'motionBlur' | 'frameRange'>;
+export type BatchJob = {
+    row: number;
+    values: Record<string, unknown>;
+    composition: Composition;
+    output: string;
+};
+export type BatchPlan = {
+    jobs: BatchJob[];
+};
+export declare function planBatch(composition: Composition, rows: Record<string, unknown>[], pattern: string, baseDir: string): Promise<BatchPlan>;
+export declare function renderBatch(plan: BatchPlan, baseDir: string, settings: BatchSettings, options?: {
+    limit?: number;
+    signal?: AbortSignal;
+    onProgress?: (message: string) => void;
+}): Promise<{
+    outputs: string[];
+}>;

package/dist/types/packages/ai/src/compose.d.ts

@@ -0,0 +1,34 @@
+import { type Composition, type ReviewIssue } from '../../core/src/index.js';
+import type { AiProvider } from './providers.js';
+import { type PromptOptions } from './prompt.js';
+export type ComposeOptions = PromptOptions & {
+    brief: string;
+    maxAttempts?: number;
+    /** Run `ove review`-style checks between attempts and feed design errors back. Slow; off by default. */
+    review?: boolean;
+    baseDir?: string;
+    signal?: AbortSignal;
+    onProgress?: (message: string) => void;
+};
+export type ComposeResult = {
+    composition: Composition;
+    attempts: number;
+    issues: ReviewIssue[];
+    warnings: string[];
+};
+export declare function composeVideo(provider: AiProvider, options: ComposeOptions): Promise<ComposeResult>;
+export type RefineOptions = {
+    instruction: string;
+    maxAttempts?: number;
+    /** Run `ove review`-style checks between attempts and feed design errors back. */
+    review?: boolean;
+    /** Pictures, clips and sounds newly made available; what the composition already uses stays allowed. */
+    assets?: {
+        id: string;
+        src: string;
+    }[];
+    baseDir?: string;
+    signal?: AbortSignal;
+    onProgress?: (message: string) => void;
+};
+export declare function refineVideo(provider: AiProvider, currentComposition: Composition | any, options: RefineOptions): Promise<ComposeResult>;

package/dist/types/packages/ai/src/history.d.ts

@@ -0,0 +1,37 @@
+export type RevisionKind = 'baseline' | 'compose' | 'refine' | 'edit' | 'import' | 'restore';
+export type Revision = {
+    n: number;
+    /** File name inside the history folder. */
+    file: string;
+    at: string;
+    kind: RevisionKind;
+    /** The brief or instruction, or a note such as "Before AI changes". */
+    label: string;
+    provider?: string;
+    model?: string;
+    template?: string;
+    attempts?: number;
+    frames: number;
+    scenes: number;
+    /** What differs from the previous revision, in a few short phrases. */
+    changes: string[];
+    restoredFrom?: number;
+};
+export type RevisionMeta = {
+    kind: RevisionKind;
+    label: string;
+    provider?: string;
+    model?: string;
+    template?: string;
+    attempts?: number;
+    restoredFrom?: number;
+};
+export declare function listRevisions(compositionFile: string): Promise<Revision[]>;
+/** A few short phrases about what changed between two compositions. */
+export declare function summarizeChange(previous: any, next: any): string[];
+/** Keeps the composition file as it is now as the next revision. */
+export declare function saveRevision(compositionFile: string, meta: RevisionMeta): Promise<Revision>;
+/** Before an AI change replaces a composition that has no history yet, keeps what is there as revision 1. */
+export declare function ensureBaseline(compositionFile: string): Promise<Revision | undefined>;
+/** Makes revision n the current composition (and records that as a new revision, so nothing is lost). */
+export declare function restoreRevision(compositionFile: string, n: number): Promise<Revision>;

package/dist/types/packages/ai/src/image.d.ts

@@ -0,0 +1,19 @@
+import type { Composition } from '../../core/src/index.js';
+import type { AiProvider } from './providers.js';
+export type GenerateImageOptions = {
+    out: string;
+    prompt: string;
+    size?: string;
+    composition?: Composition;
+    compositionPath?: string;
+    id?: string;
+    signal?: AbortSignal;
+};
+export type GenerateImageResult = {
+    file: string;
+    id: string;
+    composition?: Composition;
+};
+export declare function imageSize(size?: string): string;
+/** Generates one picture, writes it, and optionally registers it as an asset in a composition. */
+export declare function generateImage(provider: AiProvider, options: GenerateImageOptions): Promise<GenerateImageResult>;

package/dist/types/packages/ai/src/index.d.ts

@@ -0,0 +1,13 @@
+export * from './providers.js';
+export * from './compose.js';
+export * from './assets.js';
+export * from './history.js';
+export * from './template.js';
+export { applyFixes, isFixReply, type Fix } from './patch.js';
+export * from './narrate.js';
+export * from './voiceover.js';
+export * from './image.js';
+export * from './batch.js';
+export * from './project.js';
+export { extractJson, sanitizeCompositionJson } from './json.js';
+export { systemPrompt, userPrompt, refineUserPrompt, refineOutlinePrompt, compositionOutline, refineOutlineChars, ratioName, type PromptOptions } from './prompt.js';

package/dist/types/packages/ai/src/json.d.ts

@@ -0,0 +1,2 @@
+export declare function extractJson(text: string): unknown;
+export declare function sanitizeCompositionJson(input: unknown): unknown;

package/dist/types/packages/ai/src/narrate.d.ts

@@ -0,0 +1,63 @@
+import type { Composition } from '../../core/src/index.js';
+import type { AiProvider, Transcript } from './providers.js';
+export type NarrateOptions = {
+    text?: string;
+    brief?: string;
+    outDir: string;
+    voice?: string;
+    language?: string;
+    /** Target length for a generated script, in seconds. */
+    durationSeconds?: number;
+    composition?: Composition;
+    compositionPath?: string;
+    tailSeconds?: number;
+    captions?: boolean;
+    signal?: AbortSignal;
+    onProgress?: (message: string) => void;
+};
+export type NarrateResult = {
+    audio: string;
+    captions?: string;
+    durationSeconds: number;
+    words: number;
+    composition?: Composition;
+    text: string;
+};
+export declare function cleanScript(text: string): string;
+export declare function writeNarrationScript(provider: AiProvider, brief: string, options?: {
+    durationSeconds?: number;
+    language?: string;
+    signal?: AbortSignal;
+}): Promise<string>;
+export type SceneOptions = {
+    audioSrc?: string;
+    captionsSrc?: string;
+    sceneId?: string;
+    captionStartFrame?: number;
+    durationSeconds: number;
+    tailSeconds?: number;
+};
+export declare function narrationScene(composition: Composition, options: SceneOptions): Composition;
+export declare function narrate(provider: AiProvider, options: NarrateOptions): Promise<NarrateResult>;
+export type CaptionOptions = {
+    audio: string;
+    outDir?: string;
+    language?: string;
+    composition?: Composition;
+    compositionPath?: string;
+    /** Seconds into the video where the audio starts, so the captions line up. */
+    startSeconds?: number;
+    tailSeconds?: number;
+    signal?: AbortSignal;
+    onProgress?: (message: string) => void;
+};
+export type CaptionResult = {
+    captions: string;
+    durationSeconds: number;
+    words: number;
+    cues: number;
+    composition?: Composition;
+    transcript: Transcript;
+};
+/** Captions for audio that already exists (a recorded voiceover or a video's own sound). */
+export declare function captionAudio(provider: AiProvider, options: CaptionOptions): Promise<CaptionResult>;

package/dist/types/packages/ai/src/patch.d.ts

@@ -0,0 +1,15 @@
+export type Fix = {
+    path?: string;
+    value?: unknown;
+    remove?: boolean;
+    layer?: string;
+    set?: Record<string, unknown>;
+};
+/** A reply that holds fixes and not a composition of its own. */
+export declare const isFixReply: (reply: any) => reply is {
+    fixes: Fix[];
+};
+/** Applies the fixes to a copy of the composition. A fix that cannot be placed is an error the model gets to read. */
+export declare function applyFixes(previous: any, fixes: Fix[]): any;
+/** What the model is told after a failed attempt, once there is a composition it can patch. */
+export declare const patchFeedback: (intro: string) => string;

package/dist/types/packages/ai/src/project.d.ts

@@ -0,0 +1,27 @@
+import { type Composition } from '../../core/src/index.js';
+export declare const colorValue: RegExp;
+export type FieldSpec = {
+    name: string;
+    type: string;
+    description?: string;
+    example?: unknown;
+};
+/** Variables inferred from a batch file, so a generated template can be used with `ove render --batch` unchanged. */
+export declare function fieldsFromRows(rows: Record<string, unknown>[]): FieldSpec[];
+/** Writes a ready-to-use project: composition.json, the schema for editors, and an assets folder. */
+export declare function writeCompositionProject(dir: string, composition: Composition, options?: {
+    force?: boolean; /** Written instead of the resolved composition: a template that is still a template (variables, components). */
+    source?: unknown;
+}): Promise<{
+    dir: string;
+    composition: string;
+    schema: string;
+}>;
+/** A composition-relative path in the form OVE accepts (`./assets/x.png`, or `../shared/x.png`). */
+export declare function compositionRelative(baseDir: string, file: string): string;
+export declare const assetIdFromPath: (file: string) => string;
+export declare const baseDirOf: (file: string) => string;
+/** Values for a template's required variables, so a raw file can be checked without knowing real inputs. */
+export declare function sampleValues(raw: any): Record<string, unknown>;
+/** Validates a composition that may still contain template variables, without resolving them in the file. */
+export declare function validateTemplate(raw: any): void;

package/dist/types/packages/ai/src/prompt.d.ts

@@ -0,0 +1,30 @@
+export type PromptOptions = {
+    width: number;
+    height: number;
+    fps: number;
+    durationSeconds: number;
+    kind?: string;
+    fields?: {
+        name: string;
+        type: string;
+        description?: string;
+        example?: unknown;
+    }[];
+    assets?: {
+        id: string;
+        type: string;
+        src: string;
+    }[];
+    includeSchema?: boolean;
+    narration?: boolean;
+};
+export declare function systemPrompt(options?: Partial<PromptOptions>): string;
+export declare function userPrompt(brief: string, options: PromptOptions): string;
+export declare function refineUserPrompt(composition: any, instruction: string): string;
+/** Compositions longer than this many characters are shown to the model as an outline, not in full (about 4000 tokens). */
+export declare const refineOutlineChars = 16000;
+/** One line per layer, with the path to it, so changes can be addressed exactly without sending animation and component bodies. */
+export declare function compositionOutline(composition: any, maxLines?: number): string;
+/** For a large composition: the outline, and a request for fixes by path instead of the whole composition back. */
+export declare function refineOutlinePrompt(composition: any, instruction: string): string;
+export declare function ratioName(width: number, height: number): string;

package/dist/types/packages/ai/src/providers.d.ts

@@ -0,0 +1,109 @@
+export type ChatRole = 'system' | 'user' | 'assistant';
+export type ChatMessage = {
+    role: ChatRole;
+    content: string;
+};
+export type ChatOptions = {
+    json?: boolean;
+    temperature?: number;
+    maxTokens?: number;
+    signal?: AbortSignal;
+};
+export type ImageOptions = {
+    size?: string;
+    signal?: AbortSignal;
+};
+export type ImageResult = {
+    data: Uint8Array;
+    extension: string;
+};
+export type SpeakOptions = {
+    voice?: string;
+    signal?: AbortSignal;
+};
+export type AudioResult = {
+    data: Uint8Array;
+    extension: string;
+};
+export type TranscriptWord = {
+    text: string;
+    start: number;
+    end: number;
+};
+export type TranscriptCue = {
+    text: string;
+    start: number;
+    end: number;
+};
+export type Transcript = {
+    text: string;
+    words: TranscriptWord[];
+    cues: TranscriptCue[];
+};
+/** A video model: chat is required; image, speech and transcription are optional capabilities. */
+export type AiProvider = {
+    id: string;
+    model: string;
+    baseUrl: string;
+    chat(messages: ChatMessage[], options?: ChatOptions): Promise<string>;
+    image?(prompt: string, options?: ImageOptions): Promise<ImageResult>;
+    speak?(text: string, options?: SpeakOptions): Promise<AudioResult>;
+    transcribe?(audio: Uint8Array, filename: string, options?: {
+        language?: string;
+        signal?: AbortSignal;
+    }): Promise<Transcript>;
+};
+export type ProviderId = 'groq' | 'mock';
+export type ProviderConfig = {
+    provider?: string;
+    model?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    /** The model used for images, speech and transcription; chat uses `model`. */
+    imageModel?: string;
+    speechModel?: string;
+    transcriptionModel?: string;
+};
+export declare const providerCapabilities: (provider: AiProvider) => {
+    chat: boolean;
+    image: boolean;
+    speech: boolean;
+    transcription: boolean;
+};
+export declare const requestTimeoutMs = 180000;
+/** Aborts when the caller's signal does or when the timeout passes, whichever comes first (a caller's signal does not remove the timeout). */
+export declare const timeoutSignal: (signal?: AbortSignal | null, ms?: number) => AbortSignal;
+/** The longest wait before a retry, whatever Retry-After or the error text asks for. */
+export declare const maxRetryDelayMs = 30000;
+export declare function request(url: string, init: RequestInit, what: string): Promise<Response>;
+export declare function transcriptFrom(data: any): Transcript;
+/** Converts raw 16-bit mono/stereo PCM to a standard WAV container. */
+export declare function pcmToWav(pcmData: Uint8Array, sampleRate?: number, numChannels?: number, bitsPerSample?: number): Uint8Array;
+export declare function splitSpeech(text: string, limit?: number): string[];
+/** Joins WAV files that share one format (sample rate, channels, bit depth). */
+export declare function concatWav(parts: Uint8Array[]): Uint8Array;
+export declare class GroqProvider implements AiProvider {
+    id: string;
+    model: string;
+    baseUrl: string;
+    apiKey: string;
+    speechModel: string;
+    transcriptionModel: string;
+    constructor(config?: ProviderConfig);
+    private headers;
+    chat(messages: ChatMessage[], options?: ChatOptions): Promise<string>;
+    speak(text: string, options?: SpeakOptions): Promise<AudioResult>;
+    transcribe(audio: Uint8Array, filename: string, options?: {
+        language?: string;
+        signal?: AbortSignal;
+    }): Promise<Transcript>;
+}
+export declare class MockProvider implements AiProvider {
+    id: string;
+    model: string;
+    baseUrl: string;
+    chat(messages: ChatMessage[]): Promise<string>;
+    image(): Promise<ImageResult>;
+}
+export declare function createProvider(config?: ProviderConfig): AiProvider;
+export declare function describeProvider(provider: AiProvider): string;

package/dist/types/packages/ai/src/template.d.ts

@@ -0,0 +1,80 @@
+import { type Composition } from '../../core/src/index.js';
+import type { AiProvider } from './providers.js';
+export type TemplateVariableInfo = {
+    name: string;
+    type: string;
+    default?: unknown;
+    description?: string;
+    items?: Record<string, {
+        type: string;
+        default?: unknown;
+        description?: string;
+    }>;
+};
+export type ThemeChoice = {
+    id: string;
+    name: string;
+    description: string;
+    variables: Record<string, string | number>;
+};
+/** `themed` templates read colour variables (bg, text, accent…) that a theme can set. */
+export type TemplateChoice = {
+    themed?: boolean;
+    id: string;
+    name: string;
+    description: string;
+    width: number;
+    height: number;
+    durationSeconds: number;
+    variables: TemplateVariableInfo[];
+    composition: Record<string, unknown>;
+};
+export type TemplateOptions = {
+    brief: string;
+    width: number;
+    height: number;
+    /** Pictures the user supplied; picture variables (image, photo…) may name one of them. */
+    assets?: {
+        id: string;
+        type: string;
+        src: string;
+    }[];
+    /** Themes the model may choose for a themed template. */
+    themes?: ThemeChoice[];
+    maxAttempts?: number;
+    signal?: AbortSignal;
+    onProgress?: (message: string) => void;
+};
+export type TemplateResult = {
+    source: Record<string, unknown>;
+    composition: Composition;
+    attempts: number;
+    template: string;
+    theme?: string;
+    values: Record<string, unknown>;
+    warnings: string[];
+};
+/** Variables that hold a picture (an asset id or nothing): image, image2, photo, heroImage… */
+export declare const isPictureVariable: (name: string) => boolean;
+/** The templates whose shape matches the wanted video, so a vertical reel is never filled into a landscape layout. */
+export declare const templatesFor: (templates: TemplateChoice[], size: {
+    width: number;
+    height: number;
+}) => TemplateChoice[];
+/** The template with the given values as the variables' defaults, checked and resolved like any composition. */
+export declare function fillTemplate(template: TemplateChoice, values: Record<string, unknown>, theme?: ThemeChoice, assets?: {
+    id: string;
+    type: string;
+    src: string;
+}[]): Composition;
+/** The template with the values and theme written in, still a template (variables, components): what is saved so it stays editable. */
+export declare function fillTemplateSource(template: TemplateChoice, values: Record<string, unknown>, theme?: ThemeChoice, assets?: {
+    id: string;
+    type: string;
+    src: string;
+}[]): any;
+/**
+ * Asks the model for a template and its values. Returns undefined when no template has the wanted shape or the model says
+ * none suits the brief, so the caller can fall back to writing a whole composition.
+ */
+export declare function composeFromTemplate(provider: AiProvider, templates: TemplateChoice[], options: TemplateOptions): Promise<TemplateResult | undefined>;

package/dist/types/packages/ai/src/voiceover.d.ts

@@ -0,0 +1,49 @@
+import type { Composition } from '../../core/src/index.js';
+import type { AiProvider } from './providers.js';
+export type VoiceoverOptions = {
+    brief: string;
+    outDir: string;
+    compositionPath?: string;
+    voice?: string;
+    language?: string;
+    /** Frames of picture before a line starts, and of pause after it. */
+    leadFrames?: number;
+    padFrames?: number;
+    tailFrames?: number;
+    signal?: AbortSignal;
+    onProgress?: (message: string) => void;
+};
+export type VoiceoverResult = {
+    composition: Composition;
+    audio: string;
+    captions?: string;
+    durationSeconds: number;
+    words: number;
+    lines: string[];
+    text: string;
+};
+/**
+ * Carries a narration (scene timings, the narration scene, its assets and the new length) from the resolved composition back into the
+ * template source it came from, so the video stays editable. Undefined when the scenes do not line up (then save the resolved one).
+ */
+export declare function mergeNarration(source: Record<string, any>, resolved: Composition): Record<string, any> | undefined;
+/** Format of a canonical PCM WAV: channels, sample rate, bits, and the length of its audio in seconds. */
+export declare function wavInfo(data: Uint8Array): {
+    channels: number;
+    sampleRate: number;
+    bits: number;
+    seconds: number;
+};
+/** One spoken line per scene, written from what the scene shows. */
+export declare function writeSceneLines(provider: AiProvider, brief: string, scenes: {
+    texts: string[];
+    seconds: number;
+}[], options?: {
+    language?: string;
+    signal?: AbortSignal;
+}): Promise<string[]>;
+/**
+ * Speaks one line per scene and resizes the scenes to fit, then adds the narration scene (audio and captions). The composition
+ * must have its scenes laid out one after another with their transitions (as the template videos are).
+ */
+export declare function narrateScenes(provider: AiProvider, composition: Composition, options: VoiceoverOptions): Promise<VoiceoverResult>;

package/dist/types/packages/animation/src/index.d.ts

@@ -0,0 +1,27 @@
+import type { Animation } from '../../schema/src/index.js';
+export declare const easingNames: readonly ["linear", "easeIn", "easeOut", "easeInOut", "easeInCubic", "easeOutCubic", "easeInOutCubic", "easeInQuart", "easeOutQuart", "easeInOutQuart", "easeInExpo", "easeOutExpo", "easeInOutExpo", "easeInBack", "easeOutBack", "spring", "hold", "land", "snap", "glide", "pop", "move", "exit", "drift"];
+export type Easing = typeof easingNames[number] | readonly [number, number, number, number];
+export declare function cubicBezier(x1: number, y1: number, x2: number, y2: number, t: number): number;
+export declare function ease(t: number, kind?: Easing): number;
+export declare function parseColor(value: string): [number, number, number, number];
+export declare function mixColors(from: string, to: string, t: number): string;
+export declare function interpolate(frame: number, input: readonly number[], output: readonly number[], easing?: Easing): number;
+export declare function animationSegment(animation: {
+    keyframes: readonly {
+        frame: number;
+        value: unknown;
+        easing?: Easing;
+    }[];
+    repeat?: number;
+    reverse?: boolean;
+}, frame: number): {
+    from: unknown;
+    to: unknown;
+    t: number;
+};
+export declare function evaluateAnimation(animation: Animation, frame: number): number | string;
+export declare function spring(frame: number, fps: number, config?: {
+    damping?: number;
+    stiffness?: number;
+    mass?: number;
+}): number;

package/dist/types/packages/assets/src/cache.d.ts

@@ -0,0 +1,26 @@
+export declare const cacheKinds: readonly ["media", "video", "sfx"];
+export type CacheKind = typeof cacheKinds[number];
+export declare const cacheRoot: () => string;
+export declare const cacheDir: (kind: CacheKind) => string;
+/** Marks an entry as used now (its modification time), for cleaning by age. Missing entries are ignored. */
+export declare const touchCacheEntry: (path: string) => Promise<void>;
+type Listed = CacheKind | 'other';
+export type CacheUsage = {
+    root: string;
+    kinds: {
+        kind: Listed;
+        entries: number;
+        bytes: number;
+    }[];
+    bytes: number;
+};
+export declare function cacheUsage(): Promise<CacheUsage>;
+/** Removes cache entries last used before `olderThanMs` ago (all of them when not given). Returns what was freed. */
+export declare function cleanCache(options?: {
+    olderThanMs?: number;
+    kinds?: readonly Listed[];
+}): Promise<{
+    entries: number;
+    bytes: number;
+}>;
+export {};

package/dist/types/packages/assets/src/index.d.ts

@@ -0,0 +1,8 @@
+import type { Composition } from '../../schema/src/index.js';
+export declare const supportedAssetTypes: readonly ["png", "jpeg", "webp", "svg", "mp4", "webm", "mp3", "wav", "woff", "woff2"];
+export declare function validateAssetPath(src: string): void;
+export declare const isUrl: (src: string) => boolean;
+export declare function resolveAssetSource(composition: Composition, src: string, baseDir: string): string;
+export declare function toDataUrl(source: string): Promise<string>;
+export declare function resolveAudio(composition: Composition, baseDir: string): string | undefined;
+export * from './cache.js';