Skip to content

The VS Code of video editing, built for agents.

TypeScript
3.9 KB
Raw Blame
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

// Building blocks several tools share. A tool file composes these; nothing
// here is a tool on its own.

import { z } from "zod";
import { NonNegativeTime, TIME_FORMS } from "./time";

export const NodeId = z
  .string()
  .min(1)
  .describe("node id from the project's JSX, or `file:id` (`intro.tsx:hero`) when two files use the same id");

export const SceneId = z
  .string()
  .min(1)
  .describe("scene id from the project's JSX, or `file:id` (`intro.tsx:main`) when two files use the same id");

export const AssetPath = z
  .string()
  .min(1)
  .describe(
    "absolute file path or URL (works with or without an open project), or a library path like `b-roll/clip.mp4` (needs an open project)",
  );

/** Beyond this the cells get too small to be worth the tokens; use `filmstrip`. */
export const MAX_FRAMES_PER_SHEET = 12;

/**
 * Raw bytes as a handler produces them. How they travel is the transport's
 * business: base64 on a JSON wire, structured clone over IPC, a file on disk.
 */
export const Bytes = z.custom<Uint8Array>((value) => value instanceof Uint8Array, "expected bytes (a Uint8Array)");

/**
 * One rendered image as a handler returns it: a single frame stamped with its
 * timecode, or a contact sheet stamped with the span it covers (`0f-08s10f`).
 */
export const TimecodedImage = z.object({
  timecode: z.string(),
  png: Bytes,
});

/** The same image once the server has written it to disk. */
export const ImageRef = z.object({
  timecode: z.string(),
  path: z.string().describe("absolute path of the PNG"),
});

export const outputDirField = z
  .string()
  .optional()
  .describe("absolute directory to write the PNGs into (default: a fresh directory under the system temp dir)");

/**
 * How frames are laid out: merged into contact sheets (the default) or one
 * image each. `perSheet` only means something for sheets; `checkSheetOptions`
 * rejects it otherwise, so add it to any object that spreads these fields.
 */
export const sheetFields = {
  separate: z
    .boolean()
    .optional()
    .describe("write one image per position instead of merging them into contact sheets of up to 12 cells, each labelled with its timecode"),
  perSheet: z
    .int()
    .min(1)
    .max(MAX_FRAMES_PER_SHEET)
    .optional()
    .describe("positions per contact sheet, 1-12; fewer means a larger cell each (default: as many as fit)"),
};

export function checkSheetOptions(
  value: { separate?: boolean | undefined; perSheet?: number | undefined },
  ctx: z.RefinementCtx,
): void {
  if (value.perSheet !== undefined && value.separate) {
    ctx.addIssue({
      code: "custom",
      path: ["perSheet"],
      message: "perSheet lays out contact sheets; it cannot be combined with separate: true",
    });
  }
}

/** A `[start, end)` window in seconds; both optional, and start must precede end. */
export const windowFields = {
  start: NonNegativeTime.optional().describe(`start of the window — ${TIME_FORMS} (default: 0)`),
  end: NonNegativeTime.optional().describe(`end of the window — ${TIME_FORMS} (default: asset duration)`),
};

export function checkWindow(
  value: { start?: number | undefined; end?: number | undefined },
  ctx: z.RefinementCtx,
): void {
  if (value.start !== undefined && value.end !== undefined && value.start >= value.end) {
    ctx.addIssue({
      code: "custom",
      path: ["end"],
      message: `start (${value.start}s) must be less than end (${value.end}s)`,
    });
  }
}

export const LogLevel = z.enum(["debug", "info", "warning", "error"]);

export const LogEntry = z.object({
  ts: z.number().describe("unix time, milliseconds"),
  level: LogLevel,
  message: z.string(),
  source: z.string().describe("file:line the entry came from, or empty"),
});