Skip to content

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.ts
index 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.ts
index 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 a
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index 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.tsx
index 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.ts
new file mode 100644
index 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.ts
index 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.md
index 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`
### Media
diff --git a/reference/export.md b/reference/export.md
new file mode 100644
index 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.