framevideo-cli

FrameVideo CLI

When To Use

Use this skill for:

• Project scaffolding — init to create new projects
• Validation — lint to check structure, inspect for visual QA
• Preview — preview to test compositions in browser
• Rendering — render to export final video
• Troubleshooting — doctor, browser, info for environment issues
• Upgrading — upgrade to update FrameVideo CLI

Do NOT Use

Avoid this skill for:

• Asset preprocessing — use framevideo-media (tts, transcribe, remove-background)
• Writing composition HTML — use framevideo
• Chanjing integration — use chanjing-digital-human
• Visual QA methodology — use framevideo-visual-qa (this skill only runs commands)

---

Quick Start

Complete dev workflow:

# 1. Create project
npx framevideo init my-video

# 2. Edit composition (see `framevideo` skill)
# Edit index.html...

# 3. Validate
npx framevideo lint        # Check structure
npx framevideo inspect     # Visual QA

# 4. Preview
npx framevideo preview     # Test in browser

# 5. Render
npx framevideo render . --output video.mp4

Common options:

• --example <name> — use template (blank, warm-grain, product-promo, etc.)
• --tailwind — include Tailwind v4 browser runtime
• --video <file> — include video file
• --audio <file> — include audio file (auto-transcribes)

---

Workflow

1. Scaffold — npx framevideo init my-video
2. Write — author HTML composition (see the framevideo skill)
3. Lint — npx framevideo lint
4. Visual inspect — npx framevideo inspect
5. Preview — npx framevideo preview
6. Render — npx framevideo render

Lint and inspect before preview. lint catches missing data-composition-id, overlapping tracks, and unregistered timelines. inspect opens the rendered composition in headless Chrome, seeks through the timeline, and reports text spilling out of bubbles/containers or off the canvas.

Scaffolding

npx framevideo init my-video                        # interactive wizard
npx framevideo init my-video --example warm-grain   # pick an example
npx framevideo init my-video --video clip.mp4        # with video file
npx framevideo init my-video --audio track.mp3       # with audio file
npx framevideo init my-video --example blank --tailwind # with Tailwind v4 browser runtime
npx framevideo init my-video --non-interactive       # skip prompts (CI/agents)

Templates: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.

init creates the right file structure, copies media, transcribes audio with Whisper, and installs AI coding skills. Use it instead of creating files by hand.

When using --tailwind, invoke the tailwind skill before editing classes or theme tokens. The scaffold uses Tailwind v4.2 via the browser runtime, not Studio's Tailwind v3 setup.

Linting

npx framevideo lint                  # current directory
npx framevideo lint ./my-project     # specific project
npx framevideo lint --verbose        # info-level findings
npx framevideo lint --json           # machine-readable

Lints index.html and all files in compositions/. Reports errors (must fix), warnings (should fix), and info (with --verbose).

Visual Inspect

npx framevideo inspect                 # inspect rendered layout over the timeline
npx framevideo inspect ./my-project    # specific project
npx framevideo inspect --json          # agent-readable findings
npx framevideo inspect --samples 15    # denser timeline sweep
npx framevideo inspect --at 1.5,4,7.25 # explicit hero-frame timestamps

Use this after lint and validate, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports:

• Text extending outside the nearest visual container or bubble
• Text clipped by its own fixed-width/fixed-height box
• Text extending outside the composition canvas
• Children escaping clipping containers

Errors should be fixed before rendering. Warnings are surfaced for agent review; add --strict to fail on warnings too. Repeated static issues are collapsed by default so JSON output stays compact for LLM context windows. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with data-layout-allow-overflow. If a decorative element should never be audited, mark it with data-layout-ignore.

npx framevideo layout remains available as a compatibility alias for the same visual inspection pass.

Previewing

npx framevideo preview                   # serve current directory
npx framevideo preview --port 4567       # custom port (default 3002)

Hot-reloads on file changes. Opens the studio in your browser automatically.

If a video workflow needs Chanjing OAuth login and auth is missing, use preview as the preferred setup surface:

1. Run npx framevideo preview in the project.
2. Open the Studio project URL in the Codex in-app browser.
3. Navigate to the Voice, Digital Human, or account area that requires Chanjing access.
4. Click the login control so the OAuth login dialog is visible and the browser authorization flow starts.
5. Let the user complete the authorization page, then re-run the auth/status check before continuing.

Only fall back to command-line OAuth login guidance when preview is unavailable or the user explicitly asks not to use the browser UI. Never log tokens or credential-store contents.

When handing a project back to the user, use the Studio project URL, not the source index.html path:

http://localhost:<port>/#project/<project-name>

Use the actual port from the preview output and the project directory name. For example, after npx framevideo preview --port 3017 in codex-openai-video, report http://localhost:3017/#project/codex-openai-video.

Treat index.html as source-code context only. It is fine to link it as an implementation file, but do not label it as the project or preview surface.

Rendering

npx framevideo render                                # standard MP4
npx framevideo render --output final.mp4             # named output
npx framevideo render --quality draft                # fast iteration
npx framevideo render --fps 60 --quality high        # final delivery
npx framevideo render --format webm                  # transparent WebM
npx framevideo render --docker                       # byte-identical

Flag	Options	Default	Notes
--output	path	renders/name_timestamp.mp4	Output path
--fps	24, 30, 60	30	60fps doubles render time
--quality	draft, standard, high	standard	draft for iterating
--format	mp4, webm	mp4	WebM supports transparency
--workers	1-8 or auto	auto	Each spawns Chrome
--docker	flag	off	Reproducible output
--gpu	flag	off	GPU-accelerated encoding
--strict	flag	off	Fail on lint errors
--strict-all	flag	off	Fail on errors AND warnings
--variables	JSON object	—	Override variable values declared in data-composition-variables
--variables-file	path	—	JSON file with variable values (alternative to --variables)
--strict-variables	flag	off	Fail render on undeclared keys or type mismatches in --variables

Quality guidance: draft while iterating, standard for review, high for final delivery.

Parametrized renders: the composition declares its variables on the <html> root with data-composition-variables — a JSON array of declarations ({id, type, label, default} per entry) that defines the schema. Scripts inside read the resolved values via window.__framevideo.getVariables(). The CLI --variables '{"title":"Q4 Report"}' is a JSON object keyed by id that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. (Sub-comp hosts can also override per-instance with data-variable-values — same object shape, scoped to one mount of the sub-composition. See the framevideo skill for the full pattern.)

Asset Preprocessing

npx framevideo tts, transcribe, and remove-background produce assets (narration audio, word-level transcripts, transparent video) that get dropped into a composition. Each downloads its own model on first run. For voice selection, whisper model rules (the .en-translates-non-English gotcha), output format choice (VP9 alpha WebM vs ProRes), and the TTS → transcribe → captions chain, invoke the framevideo-media skill.

Troubleshooting

npx framevideo doctor       # check environment (Chrome, FFmpeg, Node, memory)
npx framevideo browser      # manage bundled Chrome
npx framevideo info         # version and environment details
npx framevideo upgrade      # upgrade CLI and refresh FrameVideo skills

Run doctor first if rendering fails. Common issues: missing FFmpeg, missing Chrome, low memory.

Upgrade Workflow

When the user asks to upgrade FrameVideo from Codex, Claude Code, Cursor, or another agent tool, handle it as an implementation task, not just advice:

1. Check the available version with npx framevideo upgrade --check or framevideo upgrade --json.
2. Briefly tell the user the upgrade plan: update the CLI package, refresh FrameVideo skills, then verify the installed command.
3. Run framevideo upgrade --yes.
4. If the command did not refresh skills automatically, run npx skills add chanjing-ai/framevideo --all.
5. Verify with framevideo --version and framevideo --help.

If any step fails, stop and report the failed step plus the manual command to retry. Do not claim the upgrade completed until the CLI version and skills refresh have both succeeded or the user explicitly accepts a partial upgrade.

Other

npx framevideo compositions   # list compositions in project
npx framevideo docs           # open documentation
npx framevideo benchmark .    # benchmark render performance