filmidi

CLI for creating, previewing, and rendering HTML video compositions — the FilMIDI framework's agent-friendly video toolchain (a fork of FilMIDI, Apache 2.0).

Install

npm install -g filmidi

Or use directly with npx:

npx filmidi <command>

Requirements: Node.js >= 22, FFmpeg

Commands

init

Scaffold a new composition project from a template:

npx filmidi init my-video
cd my-video

preview

Start the live preview studio in your browser:

npx filmidi preview
# Studio: http://localhost:3002/#project/my-video
# Server: http://localhost:3002

npx filmidi preview --port 4567

In an interactive terminal, the preview stays attached until you press Ctrl+C. In a non-interactive shell such as a coding-agent session, the same command starts a managed preview that survives after the command returns. Use --background or --foreground to choose explicitly, and manage persistent previews with --status, --stop, --list, and --kill-all. Add --json to managed lifecycle commands for machine-readable output. --foreground --json prints the ready-session envelope once, then remains attached until stopped.

normalize-audio

Measure two local authored audio clips with integrated LUFS and match the target to the unchanged reference. The command is a dry run unless --write is passed:

npx filmidi normalize-audio --reference target-audio --target user-audio
npx filmidi normalize-audio --reference target-audio --target user-audio --write

It updates only the target element's data-volume and refuses unsafe boosts that exceed Studio's +12 dB ceiling or would clip.

render

Render a composition to MP4. Run from the project directory; the positional argument is the project directory (not a file), so render the project's index.html directly, or point at a specific composition file with -c:

npx filmidi render -o output.mp4
npx filmidi render -c ./my-composition.html -o output.mp4

publish

Upload a project directory and get a hosted URL that keeps working after the CLI exits. Published projects are private by default:

npx filmidi publish
npx filmidi publish ./my-video
npx filmidi publish --public
npx filmidi publish --yes

Signed-out publishing returns an authentication-required claim URL; opening it lets someone sign in and claim the project. Sign in first with npx filmidi auth login to publish an owned project you can update. Use --public to make the claimed project visible to anyone. --yes only skips the confirmation prompt and does not change visibility.

Signed-in publishers can use --update <url-or-id> to target an existing project or --space <space-id> to publish into a shared team space. If the requested project is missing or inaccessible, publishing can create a new project instead; check the printed URL and status.

lint

Validate your composition HTML:

npx filmidi lint ./my-composition
npx filmidi lint ./my-composition --json      # JSON output for CI/tooling
npx filmidi lint ./my-composition --verbose   # Include info-level findings

By default only errors and warnings are shown. Use --verbose to also display informational findings (e.g., external script dependency notices). Use --json for machine-readable output with errorCount, warningCount, infoCount, and a findings array.

compositions

List compositions found in the current project:

npx filmidi compositions

benchmark

Run rendering benchmarks:

npx filmidi benchmark ./my-composition.html

doctor

Check your environment for required dependencies (Chrome, FFmpeg, Node.js):

npx filmidi doctor

browser

Manage the bundled Chrome/Chromium installation:

npx filmidi browser

info

Print version and environment info:

npx filmidi info

docs

Open the documentation in your browser:

npx filmidi docs

upgrade

Check for updates and show upgrade instructions:

npx filmidi upgrade
npx filmidi upgrade --check --json  # machine-readable for agents

Documentation

Underlying engine documentation (upstream FilMIDI): filmidi.pro/packages/cli

Related packages

• @filmidi/core — types, parsers, frame adapters
• @filmidi/engine — rendering engine
• @filmidi/producer — render pipeline
• @filmidi/studio — composition editor UI