framevideo-cli

FrameVideo CLI

使用する場面

以下の場合にこのスキルを使用します。

• プロジェクトのスキャフォールディング — init で新しいプロジェクトを作成します
• 検証 — lint で構造を確認し、inspect でビジュアル QA を実施します
• プレビュー — preview でブラウザー上のコンポジションをテストします
• レンダリング — render で最終動画を書き出します
• トラブルシューティング — 環境の問題には doctor、browser、info を使用します
• アップグレード — upgrade で FrameVideo CLI を更新します

使用しない場面

以下の場合、このスキルの使用は避けてください。

• アセットの前処理 — framevideo-media を使用します（tts、transcribe、remove-background）
• コンポジション HTML の作成 — framevideo を使用します
• Chanjing との連携 — chanjing-digital-human を使用します
• ビジュアル QA の手法 — 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 スキルを呼び出してください。スキャフォールドでは Studio の Tailwind v3 セットアップではなく、ブラウザーランタイム経由で Tailwind v4.2 を使用します。

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 の後に使用してください。特に、吹き出し、カード、キャプション、または文字組みが詰まったコンポジションで有効です。次の項目を報告します。

• テキストが最も近いビジュアルコンテナーまたは吹き出しの外にはみ出している
• テキストが自身の固定幅／固定高さのボックスでクリップされている
• テキストがコンポジションのキャンバスの外にはみ出している
• 子要素がクリッピングコンテナーからはみ出している

レンダリングの前にエラーを修正してください。警告はエージェントによる確認用に表示されます。警告でも失敗させるには --strict を追加してください。LLM のコンテキストウィンドウで 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. ユーザーが認証ページでの操作を完了するのを待ってから、続行する前に認証／ステータスチェックを再実行します。

プレビューを利用できない場合、またはユーザーがブラウザー UI を使用しないよう明示的に求めた場合に限り、コマンドラインでの OAuth ログイン方法を案内してください。トークンや認証情報ストアの内容は決してログに記録しないでください。

プロジェクトをユーザーに引き渡す際は、ソースの index.html のパスではなく、Studio のプロジェクト URL を使用してください。

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ではレンダリング時間が2倍になります
--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 object	—	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"}'は、1回のレンダリングで宣言済みのデフォルト値を上書きする、idをキーとするJSONオブジェクトです。指定されていないキーはデフォルト値が適用されるため、同じコンポジションを開発プレビューと本番環境で変更せずに実行できます。（サブコンポジションのホストは、data-variable-values**を使ってインスタンスごとに上書きすることもできます。形式は同じオブジェクトで、サブコンポジションの1つのマウントにスコープされます。パターンの詳細はframevideoスキルを参照してください。）

アセットの前処理

npx framevideo tts、transcribe、remove-backgroundは、コンポジションに追加するアセット（ナレーション音声、単語単位の文字起こし、透過動画）を生成します。各コマンドは初回実行時に独自のモデルをダウンロードします。音声の選択、Whisperモデルのルール（.enが非英語を英語に翻訳する落とし穴）、出力形式の選択（VP9アルファ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、または別のエージェントツールで 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