The VS Code of video editing, built for agents.
TypeScript
Add export functionality to CLI with configurable settings
konstantin-paulusb06d72388e0a
diff --git a/apps/cli/src/cli-channels.ts b/apps/cli/src/cli-channels.tsindex efe25124..adecc9ca 100644--- a/apps/cli/src/cli-channels.ts+++ b/apps/cli/src/cli-channels.ts@@ -119,6 +119,56 @@ export type CheckResult = {issues: CheckIssue[];};+export type ExportFormat = "mp4" | "webm" | "ogg" | "mov";++// The settings shape mirrors the scene's `diffusion.export.<id>` entry in the+// project's package.json (see the web app's engine/project-config), spelled+// out here so the wire seam stays dependency-free. Codecs are strings on the+// wire; the app validates them against what the encoder accepts.+export type ExportVideoSettings = {+ enabled?: boolean;+ codec?: string;+ bitrate?: number;+ fps?: number;+ resolution?: number;+};++export type ExportAudioSettings = {+ enabled?: boolean;+ codec?: string;+ sampleRate?: number;+ bitrate?: number;+};++export type ExportSettings = {+ format?: ExportFormat;+ video?: ExportVideoSettings;+ audio?: ExportAudioSettings;+};++/**+ * `path` is the absolute output file, whose extension picks the container;+ * omitted, the app writes `exports/<id>.<format>` in the project folder.+ * Everything else — codecs, bitrates, resolution — is read from the scene's+ * export entry in the project's package.json.+ */+export type ExportRequest = { id: string; path?: string };++/**+ * `config` echoes the settings the export was made with — the package.json+ * entry (or the defaults), with the container the extension resolved to — so+ * a caller sees what its config edit actually did. `width`/`height` are the+ * encoded pixel size (0×0 for an audio-only export); `duration` is seconds.+ */+export type ExportResult = {+ path: string;+ width: number;+ height: number;+ duration: number;+ size: number;+ config: ExportSettings;+};+export type GeneratedAsset = { id: string; name: string; type: string };export type ModelsRequest = { type?: "image" | "video" | "audio" };diff --git a/apps/cli/src/cli-client.ts b/apps/cli/src/cli-client.tsindex 6e2d3f6d..fc125a02 100644--- a/apps/cli/src/cli-client.ts+++ b/apps/cli/src/cli-client.ts@@ -15,6 +15,7 @@ import type { AppRouter } from "../../web/src/context/dapi";const DEFAULT_TIMEOUT_MS = 60000;export const GENERATE_TIMEOUT_MS = 600000;+export const EXPORT_TIMEOUT_MS = 3600000;// Asks the app (via the unix socket) to have the renderer dial our WebSocket// server. Main replies once the connect info has been delivered, so adiff --git a/apps/cli/src/index.ts b/apps/cli/src/index.tsindex c869ab38..5a695a3e 100644--- a/apps/cli/src/index.ts+++ b/apps/cli/src/index.ts@@ -11,7 +11,7 @@ import { dirname, isAbsolute, join, resolve } from "node:path";import { Command } from "commander";import { version } from "../../../package.json";import { parseTime, TIME_FPS } from "@diffusionstudio/jsx";-import { editor, errnoCode, GENERATE_TIMEOUT_MS, waitForCliSocket } from "./cli-client";+import { editor, errnoCode, EXPORT_TIMEOUT_MS, GENERATE_TIMEOUT_MS, waitForCliSocket } from "./cli-client";import { listLocalFonts } from "./fonts";import { buildIssueBody, createIssue } from "./report";import { fetchVideo } from "./ytdlp";@@ -20,6 +20,7 @@ import type { AssetRef, FrameQuality, LogEntry, LogLevel, TimecodedImage } from// Long-running commands (renders, AI generation) override the default 60s.const GENERATE = { context: { timeoutMs: GENERATE_TIMEOUT_MS } };+const EXPORT = { context: { timeoutMs: EXPORT_TIMEOUT_MS } };const APP_NAME = "Diffusion Studio";@@ -302,6 +303,22 @@ async function captureNode(id: string, opts: CaptureOptions): Promise<void> {}}+async function exportScene(id: string, output: string | undefined): Promise<void> {+ // The app owns everything else: settings come from the project's+ // package.json, the extension check and the default output path need the+ // config and project folder, which live on its side of the socket.+ const path = output !== undefined ? resolve(process.cwd(), output) : undefined;+ const stop = startSpinner("Exporting scene");+ try {+ const result = await editor.export.mutate({ id, path }, EXPORT);+ stop();+ console.log(JSON.stringify(result));+ } catch (e) {+ stop();+ handleSocketError(e);+ }+}+async function checkNode(id: string): Promise<void> {try {const result = await editor.check.query({ id });@@ -624,6 +641,18 @@ program.option("-o, --output <dir>", "directory to write the PNGs into (default: a fresh dir in the system temp dir)").action((id: string, opts: CaptureOptions) => captureNode(id, opts));+program+ .command("export")+ .description(+ `Encode a scene to a video file — the full render the app's own export runs: the scene's workarea from start to end, video and audio, streamed to the output file as it encodes. Settings are read from the scene's entry in the project's package.json (\`diffusion.export.<id>\`: container format, video codec/bitrate/fps/resolution, audio codec/bitrate/sampleRate — the same entry the app's export panel writes), so an export is reproducible from the project alone; a scene without an entry exports with the defaults (1080p H.264 MP4 with AAC audio). The [output] extension picks the container (.mp4, .webm, .ogg audio-only, .mov), overriding the configured format. Prints one JSON object with the written path, encoded size, duration, byte size, and the settings used. Renders take a while (timeout: 60 minutes); progress shows in the app, where the export can also be canceled. One export runs at a time. Verify frames with \`capture\` and structure with \`check\` before spending the render time.`,+ )+ .argument("<id>", 'scene id to export or `file:id` when two files use the same id')+ .argument(+ "[output]",+ 'output file path, ffmpeg-style; its extension picks the container (default: "exports/<id>.<format>" in the project folder)',+ )+ .action((id: string, output: string | undefined) => exportScene(id, output));+program.command("check").description(diff --git a/apps/web/src/context/dapi/api.tsx b/apps/web/src/context/dapi/api.tsxindex 71a70e6b..1619cf04 100644--- a/apps/web/src/context/dapi/api.tsx+++ b/apps/web/src/context/dapi/api.tsx@@ -8,12 +8,14 @@ import { useWorld } from '@diffusionstudio/koota-solid';import { Project } from '@diffusionstudio/runtime';import { useProject } from '@/context/project';import { useAuth } from '@/context/auth';+import { useEngineContext } from '@/engine';import { t, q, q0, m } from "@/lib/cli-rpc";import { editorSession, requireEditorSession, setEditorSession } from "./session";import { handleContextGet } from "./context";import { createAssetResolver, handleMediaProbe, handleMediaFrame, handleMediaTranscribe, handleMediaFilmstrip, handleMediaWaveform, handleMediaListen } from "./media";import { handleCapture } from "./capture";import { handleCheck } from "./check";+import { handleExport } from "./export";import { handleLogs } from "./logs";import { handleModels } from "./models";import { handleVoices } from "./voices";@@ -76,11 +78,12 @@ export function EditorApiProvider(props: EditorApiProviderProps) {const project = useProject();const isFullscreen = useFullscreenState();const world = useWorld();+ const engine = useEngineContext();createEffect(() => {if (!window.desktop || project.id() !== world.get(Project)?.id) return;- setEditorSession({ world, project });+ setEditorSession({ world, project, engine });onCleanup(() => setEditorSession(null));});@@ -117,6 +120,7 @@ function createAppRouter({ navigate, getUser, requireAuth }: AppRouterDeps) {context: q0(handleContextGet(editorSession)),capture: q(handleCapture(requireEditorSession)),check: q(handleCheck(requireEditorSession)),+ export: m(handleExport(requireEditorSession)),models: q(handleModels()),logs: q(handleLogs()),screenshot: q0(handleWindowScreenshot()),diff --git a/apps/web/src/context/dapi/export.ts b/apps/web/src/context/dapi/export.tsnew file mode 100644index 00000000..a2a6536e--- /dev/null+++ b/apps/web/src/context/dapi/export.ts@@ -0,0 +1,141 @@+/* 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/. */++import { canEncodeVideo } from "mediabunny";+import { computeOutputSize } from "@diffusionstudio/encoder";+import { Computed, FrameRate, getParentNode, isScene, Source, Workarea } from "@diffusionstudio/runtime";++import { renderOverlay, renderScene } from "@/context/render";+import { ElectronWritableFileHandle } from "@/lib/electron-file-writable";+import { ProjectConfig as ProjectConfigTrait } from "@/engine/traits";+import { sceneConfigKey } from "@/engine/project-config";+import {+ getDefaultExportTemplate,+ VIDEO_FORMAT_OPTIONS,+} from "@/components/sidebar-right/inspector/export-templates";+import { mainBridge } from "@/lib/ipc";+import { MAIN_CHANNELS } from "@desktop/main-channels";+import { resolveNode } from "./nodes";++import type { ExportRequest, ExportResult, ExportSettings } from "@diffusionstudio/cli/channels";+import type { ContainerFormat, ExportConfig } from "@/engine/project-config";+import type { EditorSession } from "./session";++/**+ * The container the export writes: the output extension when a path was+ * given (ffmpeg's rule — the file must be what its name says), the config's+ * format otherwise, mp4 when neither says. A given path settles it entirely,+ * so a bad config format only fails an export that would actually use it.+ */+function resolveFormat(path: string | undefined, config: ExportConfig): ContainerFormat {+ const supported = VIDEO_FORMAT_OPTIONS.map((format) => `.${format}`).join(", ");+ if (path !== undefined) {+ const extension = /\.([a-z0-9]+)$/i.exec(path)?.[1]?.toLowerCase();+ if (!extension || !VIDEO_FORMAT_OPTIONS.includes(extension as ContainerFormat)) {+ throw new Error(`The output path must end in a container extension: ${supported}.`);+ }+ return extension as ContainerFormat;+ }+ const format = config.format ?? "mp4";+ if (!VIDEO_FORMAT_OPTIONS.includes(format)) {+ throw new Error(`The export entry names an unknown format "${format}" — use one of ${supported.replaceAll(".", "")}.`);+ }+ return format;+}++export function handleExport(session: () => EditorSession) {+ return async ({ id, path }: ExportRequest): Promise<ExportResult> => {+ const { world, project, engine } = session();++ const scene = resolveNode(world, id);+ if (!isScene(scene)) {+ let parent = getParentNode(scene);+ while (parent !== null && !isScene(parent)) parent = getParentNode(parent);+ const stamp = parent?.get(Source)?.value;+ throw new Error(+ stamp+ ? `"${id}" is not a scene — a scene is the unit an export renders. Export its scene "${stamp}" instead.`+ : `"${id}" is not a scene — a scene is the unit an export renders, so export takes a scene id.`,+ );+ }++ // The scene's entry in the project's package.json (`diffusion.export.<id>`)+ // — the same one the app's export panel writes — so a CLI export+ // reproduces the in-app one; a scene without an entry uses the default+ // template, the way ⌘E does. `template` is only the preset's label.+ const base = world.get(ProjectConfigTrait)?.exportOf(scene) ?? getDefaultExportTemplate();+ const settings: ExportConfig = { format: base.format, video: base.video, audio: base.audio };++ const format = resolveFormat(path, settings);+ const key = sceneConfigKey(scene) ?? id;+ const target = path ?? `${project.dir()}/exports/${key.replace(/[^\w.-]+/g, "-")}.${format}`;++ // Fail before the render machinery spins up: an unencodable configuration+ // is known right away (same precheck the UI export runs).+ const videoEnabled = format !== "ogg" && settings.video?.enabled !== false;+ const computed = scene.get(Computed);+ const { width, height } = computeOutputSize(+ computed?.width || 1920,+ computed?.height || 1080,+ settings.video?.resolution ?? 1080,+ );+ if (videoEnabled) {+ const codec = settings.video?.codec ?? "avc";+ const encodable = await canEncodeVideo(codec, {+ width,+ height,+ bitrate: settings.video?.bitrate ?? 10e6,+ });+ if (!encodable) {+ throw new Error(+ `Cannot encode ${codec.toUpperCase()} at ${width}×${height}. ` ++ "Set a lower resolution, a lower bitrate, or another codec in the scene's export entry.",+ );+ }+ }++ const workarea = scene.get(Workarea);+ const frames = workarea ? workarea.end - workarea.start : computed?.duration ?? 0;+ const duration = frames / (world.get(FrameRate)?.value || 30);++ // renderScene owns the one render slot (it stops the live engine and+ // raises the progress overlay), so refuse a second export rather than+ // interleave. No await sits between this check and renderScene claiming+ // the overlay, so two racing requests cannot both pass.+ if (renderOverlay()) {+ throw new Error("An export is already running — wait for it to finish, or cancel it in the app.");+ }++ const handle = new ElectronWritableFileHandle(target);+ try {+ const result = await renderScene(engine, {+ scene,+ target: handle,+ config: { ...settings, format },+ dir: project.dir(),+ });+ if (result.type === "canceled") throw new Error("Export canceled in the app");+ if (result.type === "error") throw result.error;+ } catch (error) {+ // Close the fd and drop the partial file; a failed export leaves nothing.+ await handle.dispose().catch(() => {});+ throw error;+ }++ const stat = await mainBridge.call(MAIN_CHANNELS.PROJECTS_FS_STAT, {+ dir: project.dir(),+ source: target,+ });++ const config: ExportSettings = { format, video: settings.video, audio: settings.audio };+ return {+ path: target,+ width: videoEnabled ? width : 0,+ height: videoEnabled ? height : 0,+ duration,+ size: stat?.size ?? 0,+ config,+ };+ };+}diff --git a/apps/web/src/context/dapi/session.ts b/apps/web/src/context/dapi/session.tsindex 55b67460..4b4d1429 100644--- a/apps/web/src/context/dapi/session.ts+++ b/apps/web/src/context/dapi/session.ts@@ -12,6 +12,7 @@ import { assert } from "@/utils/common";import type { Accessor } from "solid-js";import type { World } from "koota";+import type { Engine } from "@/engine";/*** The open project, as the editor knows it. Structural on purpose: this is@@ -22,8 +23,8 @@ export type OpenProject = {dir: () => string;};-/** What only an open project can offer: the world drawing it, and which project that is. */-export type EditorSession = { world: World; project: OpenProject };+/** What only an open project can offer: the world drawing it, the engine running it, and which project that is. */+export type EditorSession = { world: World; project: OpenProject; engine: Engine };const [session, setSession] = createSignal<EditorSession | null>(null);diff --git a/reference/README.md b/reference/README.mdindex 71fd8f9e..9bf1420a 100644--- a/reference/README.md+++ b/reference/README.md@@ -8,7 +8,7 @@ A project is a folder of that JSX, and **the source is the document**: the app c## Groups-**Top-level:** [`whoami`](./whoami.md), [`logs`](./logs.md), [`screenshot`](./screenshot.md), [`report`](./report.md), [`context`](./context.md) (alias `ctx`), [`capture`](./capture.md), [`check`](./check.md), [`models`](./models.md), [`voices`](./voices.md), [`fonts`](./fonts.md), [`fetch`](./fetch.md).+**Top-level:** [`whoami`](./whoami.md), [`logs`](./logs.md), [`screenshot`](./screenshot.md), [`report`](./report.md), [`context`](./context.md) (alias `ctx`), [`capture`](./capture.md), [`check`](./check.md), [`export`](./export.md), [`models`](./models.md), [`voices`](./voices.md), [`fonts`](./fonts.md), [`fetch`](./fetch.md).| Group | Alias | Scope || ----- | ----- | ----- |@@ -34,6 +34,7 @@ How the surface is divided:- [`dapi context`](./context.md): which project the app has open, where its playhead sits, its registered fonts, and where its generations stand- [`dapi capture`](./capture.md): render frames of a scene, as an export would, to a labelled contact sheet or one PNG per position- [`dapi check`](./check.md): check a node's subtree for structural mistakes (black-frame gaps, never-visible nodes, failed sources) and report subtree stats+- [`dapi export`](./export.md): encode a scene to a video file, with the settings saved in the project's `package.json`### Mediadiff --git a/reference/export.md b/reference/export.mdnew file mode 100644index 00000000..f3823172--- /dev/null+++ b/reference/export.md@@ -0,0 +1,68 @@+# `dapi export <id> [output]`++Encodes a scene to a video file — the full render the app's own export runs: the scene re-rendered from a fresh mount at its own size, the workarea from start to end, video and audio, streamed to the output file as it encodes. What [`capture`](./capture.md) shows one frame of, `export` writes all of.++**The settings live in the project, not on the command.** The export is made with the scene's entry in the project's `package.json` — the same entry the app's export panel writes — so a CLI export reproduces the in-app one exactly, and the settings version with the project. The command decides only what to export and where to put it; a hand edit to `package.json` is picked up by the running app immediately, no reload needed.++Renders take as long as the scene demands (the CLI waits up to 60 minutes). The app shows the export's progress overlay while it runs, with a working Cancel button; one export runs at a time. Verify frames with [`capture`](./capture.md) and structure with [`check`](./check.md) before spending the render time.++## Input++- `<id>`: scene id to export (required) — the scene's `id` attribute in the project's JSX, or `file:id` when two files use the same id. Scenes only: a scene is the unit an export renders, and the error names the scene to export when the id is some other node's.+- `[output]`: output file path, ffmpeg-style (optional; relative paths resolve against the working directory). Its extension picks the container — `.mp4`, `.webm`, `.ogg` (audio only), `.mov` — overriding the configured format, so the file is always what its name says. A path without one of those extensions is an error. Omitted, the file lands at `exports/<id>.<format>` in the project folder (parent directories are created); an existing file is overwritten.++## Settings++The scene's entry under `diffusion.export.<id>` in the project's `package.json`:++```jsonc+{+ "diffusion": {+ "export": {+ "intro": {+ "format": "mp4", // mp4 | webm | ogg | mov+ "video": {+ "enabled": true, // false encodes audio only+ "codec": "avc", // avc | hevc | vp9 | av1 | vp8+ "bitrate": 12000000, // bits per second+ "fps": 30, // capture rate; default: the project's+ "resolution": 1080 // shorter-side "p" number: 720 | 1080 | 1440 | 2160+ },+ "audio": {+ "enabled": true,+ "codec": "aac", // aac | opus+ "sampleRate": 48000,+ "bitrate": 128000+ }+ }+ }+ }+}+```++Every field is optional; the encoder fills what the entry leaves out. A scene without an entry exports with the defaults — 1080p H.264 MP4 with AAC audio, the app's default template. `resolution` scales the scene uniformly until its shorter side reaches the number, so a portrait 1080×1920 scene at `2160` encodes as 2160×3840.++## Output++One JSON object once the file is written:++```ts+{+ path: string; // absolute path of the written file+ width: number; // encoded pixel size (0×0 for an audio-only export)+ height: number;+ duration: number; // seconds encoded (the workarea's length)+ size: number; // bytes written+ config: { // the settings the export was made with — the package.json+ format: string; // entry (or the defaults), with the container the+ video?: {...}; // extension resolved to. Fields the entry left out are+ audio?: {...}; // absent; the encoder used its defaults for them.+ }+}+```++The echoed `config` is the confirmation of what a `package.json` edit actually did: fields of the wrong type are dropped when the entry is read, so a typoed key shows up here as the default it fell back to.++## Errors++Exits non-zero if no project is open (`No project open` — run `dapi open <dir>` first), the id is unknown or ambiguous (pass `file:id`), the id names a node that is not a scene (the error names the scene to export instead), the output path lacks a container extension, the entry's format is unknown, the configuration is unencodable on this machine (codec × resolution × bitrate — the error says what to lower), another export is already running, or the export is canceled in the app. A failed or canceled export deletes the partial file.