framevideo-cli

FrameVideo CLI

适用场景

在以下场景使用此技能：

• 项目脚手架 — 使用 init 创建新项目
• 验证 — 使用 lint 检查结构，使用 inspect 进行视觉质量检查
• 预览 — 使用 preview 在浏览器中测试构图
• 渲染 — 使用 render 导出最终视频
• 故障排查 — 使用 doctor、browser、info 排查环境问题
• 升级 — 使用 upgrade 更新 FrameVideo CLI

不要使用

在以下场景避免使用此技能：

• 素材预处理 — 使用 framevideo-media（tts、transcribe、remove-background）
• 编写构图 HTML — 使用 framevideo
• Chanjing 集成 — 使用 chanjing-digital-human
• 视觉质量检查方法 — 使用 framevideo-visual-qa（此技能仅运行命令）

---

快速开始

完整的开发工作流：

# 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

常用选项：

• --example <name> — 使用模板（blank、warm-grain、product-promo 等）
• --tailwind — 包含 Tailwind v4 浏览器运行时
• --video <file> — 包含视频文件
• --audio <file> — 包含音频文件（自动转录）

---

工作流

1. 搭建脚手架 — npx framevideo init my-video
2. 编写 — 编写 HTML 构图（参见 framevideo 技能）
3. Lint 检查 — npx framevideo lint
4. 视觉检查 — npx framevideo inspect
5. 预览 — npx framevideo preview
6. 渲染 — npx framevideo render

先运行 lint 和 inspect，再进行预览。lint 会检测缺失的 data-composition-id、轨道重叠和未注册的时间轴。inspect 会在无头 Chrome 中打开渲染后的构图，沿时间轴逐段检查，并报告文字溢出气泡或容器、超出画布等问题。

搭建脚手架

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)

模板：blank、warm-grain、play-mode、swiss-grid、vignelli、decision-tree、kinetic-type、product-promo、nyt-graph。

init 会创建合适的文件结构、复制媒体、使用 Whisper 转录音频，并安装 AI 编码技能。请使用此命令，而不要手动创建文件。

使用 --tailwind 时，在编辑类或主题令牌之前先调用 tailwind 技能。脚手架使用浏览器运行时中的 Tailwind v4.2，而非 Studio 的 Tailwind v3 配置。

Lint 检查

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

对 index.html 和 compositions/ 中的所有文件运行 lint 检查。报告错误（必须修复）、警告（应该修复）和信息（使用 --verbose 时显示）。

视觉检查

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

在 lint 和 validate 之后使用此命令，尤其适用于包含对话气泡、卡片、字幕或紧凑排版的构图。它会报告：

• 文字超出最近的视觉容器或气泡
• 文字被自身固定宽度或固定高度的方框裁切
• 文字超出构图画布
• 子元素逃逸出裁切容器

渲染前应修复错误。警告会显示出来供 Agent 审查；添加 --strict 也可让警告导致失败。默认会合并重复的静态问题，让 JSON 输出在大模型上下文窗口中保持精简。如果动画的入场或退场效果需要故意溢出，请在元素或祖先元素上添加 data-layout-allow-overflow。如果某个装饰元素不应接受审查，请为其添加 data-layout-ignore。

npx framevideo layout 仍可作为兼容别名，用于执行相同的视觉检查流程。

预览

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

文件更改时会热重载，并自动在浏览器中打开 Studio。

如果视频工作流需要 Chanjing OAuth 登录，但缺少身份验证信息，请优先使用预览来完成设置：

1. 在项目中运行 npx framevideo preview。
2. 在 Codex 应用内浏览器中打开 Studio 项目 URL。
3. 前往需要访问 Chanjing 的 Voice、Digital Human 或账户区域。
4. 点击登录控件，显示 OAuth 登录对话框并启动浏览器授权流程。
5. 让用户完成授权页面操作，然后重新运行身份验证/状态检查，再继续操作。

只有在预览不可用，或用户明确要求不使用浏览器界面时，才改用命令行 OAuth 登录说明。切勿记录令牌或凭据存储内容。

将项目交还给用户时，请使用 Studio 项目 URL，而不是 源文件 index.html 路径：

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

请使用预览输出中的实际端口和项目目录名称。例如，在 codex-openai-video 中运行 npx framevideo preview --port 3017 后， 请提供 http://localhost:3017/#project/codex-openai-video。

请仅将 index.html 视为源代码上下文。可以将其链接为实现文件，但不要将其标记为项目或预览入口。

渲染

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

标志	选项	默认值	说明
--output	路径	renders/name_timestamp.mp4	输出路径
--fps	24, 30, 60	30	60fps 会使渲染时间加倍
--quality	draft, standard, high	standard	迭代时使用 draft
--format	mp4, webm	mp4	WebM 支持透明度
--workers	1-8 or auto	auto	每个工作进程都会启动一个 Chrome
--docker	flag	off	确保输出可复现
--gpu	flag	off	使用 GPU 加速编码
--strict	flag	off	遇到 lint 错误时失败
--strict-all	flag	off	遇到错误和警告时均失败
--variables	JSON 对象	—	覆盖 data-composition-variables 中声明的变量值
--variables-file	路径	—	包含变量值的 JSON 文件（--variables 的替代选项）
--strict-variables	flag	off	--variables 中包含未声明的键或类型不匹配时，渲染失败

**质量建议：**迭代时使用 draft，审核时使用 standard，最终交付时使用 high。

**参数化渲染：**组合在 <html> 根元素上通过 data-composition-variables 声明变量——这是一个 JSON 声明数组（每个条目包含 {id, type, label, default}），用于定义架构。内部脚本通过 window.__framevideo.getVariables() 读取解析后的值。CLI 参数 --variables '{"title":"Q4 Report"}' 是一个按 id 为键的 JSON 对象，可在单次渲染时覆盖这些声明的默认值；未提供的键会使用默认值，因此同一组合在开发预览和生产环境中均可原样运行。（子组合宿主也可以通过 data-variable-values 按实例覆盖——对象结构相同，作用范围仅限于子组合的一次挂载。完整模式请参阅 framevideo 技能。）

资源预处理

npx framevideo tts、transcribe 和 remove-background 会生成可放入组合中的资源（旁白音频、逐词转录文本、透明视频）。首次运行时，每个命令都会下载自己的模型。关于语音选择、whisper 模型规则（.en 会翻译非英语内容这一易错点）、输出格式选择（VP9 alpha WebM 与 ProRes），以及 TTS → 转录 → 字幕流程，请调用 framevideo-media 技能。

故障排除

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

如果渲染失败，请先运行 doctor。常见问题包括：缺少 FFmpeg、缺少 Chrome、内存不足。

升级工作流

当用户要求通过 Codex、Claude Code、Cursor 或其他 Agent 工具升级 FrameVideo 时，请将其视为实现任务，而不只是提供建议：

1. 使用 npx framevideo upgrade --check 或 framevideo upgrade --json 检查可用版本。
2. 简要告知用户升级计划：更新 CLI 软件包、刷新 FrameVideo 技能，然后验证已安装的命令。
3. 运行 framevideo upgrade --yes。
4. 如果该命令未自动刷新技能，请运行 npx skills add chanjing-ai/framevideo --all。
5. 使用 framevideo --version 和 framevideo --help 进行验证。

如果任何步骤失败，请停止并报告失败的步骤以及可用于重试的手动命令。在 CLI 版本和技能刷新均成功之前，或用户明确接受部分升级之前，不要声称升级已完成。

其他

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