Server (Node)

@miraiclip/server-export exports a project document from Node. It launches headless Chrome, loads the document into a page, and runs the same exportProject the browser uses.

npm install @miraiclip/server-export

import { exportProjectFile } from "@miraiclip/server-export";
import { readFile } from "node:fs/promises";

const doc = JSON.parse(await readFile("project.json", "utf8"));

const { filePath, bytesWritten } = await exportProjectFile(doc, {
  format: "mp4",
  quality: "high",
  out: "render/final.mp4",
  assets: { interview: "./media/interview.mp4" },
  onProgress: (p) => console.log(p.phase, p.framesDone, "/", p.totalFrames),
});

The document is what project.toJSON() returns. Server export renders built-in clip kinds only: custom clip kinds need their factories, which can't cross into the page.

OptionsCopy Anchor Link

ResultCopy Anchor Link

Use out for anything long. Without it, the file crosses from the page to Node in one piece, which briefly costs about twice its size in memory. A failed streamed export deletes the partial file.

bytesWritten in progress events is only set with out. Output is written in chunks of about 16 MiB, so short exports may report 0 until the end. Use framesDone / totalFrames for completion.

CancelCopy Anchor Link

import { ServerExportAbortedError, exportProjectFile } from "@miraiclip/server-export";
import type { ProjectDocument } from "@miraiclip/core";

declare const doc: ProjectDocument;

const controller = new AbortController();
process.on("SIGINT", () => controller.abort());

try {
  await exportProjectFile(doc, { format: "webm", out: "out.webm", signal: controller.signal });
} catch (error) {
  if (!(error instanceof ServerExportAbortedError)) throw error;
}

AssetsCopy Anchor Link

Each asset's media must be readable on the server. Per asset, in order:

A local file that doesn't exist fails the export before the browser starts.

The browserCopy Anchor Link

The package depends on playwright-core and downloads no browser. It launches the first of:

1. browser.executablePath
2. The MIRAICLIP_BROWSER environment variable
3. The installed Google Chrome

On a server without Chrome, npx playwright install chrome installs it.

Warm sessionsCopy Anchor Link

exportProjectFile launches a browser on every call. createExportSession keeps one browser open, so each export skips the launch. Calls on one session run one at a time, in order. A failed call doesn't break the session.

import { createExportSession } from "@miraiclip/server-export";
import type { ProjectDocument } from "@miraiclip/core";

declare const docA: ProjectDocument;
declare const docB: ProjectDocument;

const session = await createExportSession({ assetsDir: "./media" });
try {
  await session.exportFile(docA, { format: "mp4", out: "out/a.mp4" });
  await session.exportFile(docB, { format: "mp4", out: "out/b.mp4" });
} finally {
  await session.close();
}

For many videos from one template, Batch rendering runs rows through export sessions for you.

CLICopy Anchor Link

npx miraiclip-export project.json --out final.mp4 --quality high --asset interview=./media/interview.mp4

It prints progress to stderr and <file> (<MB> MB, <seconds>s) to stdout. Ctrl-C cancels the export.

The CLI has no --help flag. An unknown flag exits with unknown flag ….