kinetograph-studio

Studio で作業する

npx kinetograph studio <entry> を実行するとローカル Studio が起動します（サウンドを再生するプレビュー、範囲をドラッグして選択できるタイムライン、props とプリセット、プラグインカード、シーンツリー、エクスポートダイアログ、レンダーキュー、コーディングエージェントとのチャットを備えています）。http://127.0.0.1:3000 でブラウザーが開きます。entry はプロジェクトファイル、.json シーン、または HyperFrames ページです。ファイルが変更されると再ビルドし、停止するまで実行されます。これは画面の前にいる人向けのものであり、MCP ツールではありません。

オプション：--port N（0 を指定すると空きポートが選ばれます）、--host、--no-open（自分で Studio を起動するときに使用）、--agent <command>（チャットで使うコーディングエージェント。デフォルトはインストールされているもののうち Claude Code、Codex、Gemini CLI のいずれか）、--allow-remote-agent、--props <json>、--offline。ほかのコンピューターから Studio にアクセスできるように --host を設定すると、--allow-remote-agent を指定しない限りエージェントは無効になります。

利用者が使える機能

• プレビューとタイムライン。 レイヤーをクリックして選択します。タイムラインのルーラーまたはクリップ上をドラッグして、時間範囲を選択します。受信する各メッセージには、プロジェクトファイル、コンポジション、フレームまたは範囲、そして各レイヤーの名前、種類、ソースファイルと行、位置、サイズ、見た目、プラグインが含まれます。範囲を選択すると、そこに重なるシーケンスと、最大 8 フレームのコンタクトシートも取得できます。
• Props タブ。 コンポジションの Zod schema からフォームが生成され、編集するとプレビューが再レンダーされます。プリセットでは props が entry の隣の presets/<composition id>/<name>.json に保存され、--props を使うとコマンドラインから読み込んでレンダーできます。
• マークアップモード（M）：利用者はスポットにピンを立て、領域を四角で囲み、描画し、範囲に印を付けることができ、それぞれにコメントを追加できます。
• エクスポート（上部バー）：範囲、.mp4 または .mov のパス、Draft を指定すると、レンダーキューに追加されます。

ツール

MCP 経由で利用する場合、Studio を開いた状態で（kinetograph mcp --studio <address> を実行し、トークンを KINETOGRAPH_STUDIO_TOKEN に設定します。Studio 独自のチャットエージェントでは、これらをすでに利用できます）：

• studio_get_props はプレビューに表示されている props を読み取ります。studio_set_props はそれらを変更し、利用者はプレビューの変化を確認できます。この方法で値を試してから、選んだ値をコードまたはプリセットに書き込みます。
• studio_open_panel と studio_panel_result は、パネルで利用者に選択を求めます（以下を参照）。

チャットエージェントは、すべての kinetograph コマンドと、プロジェクトのプラグインのツール（<plugin>_<tool>）も利用できます。

マークアップのメモ

Markup notes on <comp> で始まるメッセージは、プレビュー上に描かれた利用者のメモです。時間順の番号付きリスト（フレーム、時間、コンポジションのピクセル座標でのマーク、その下にあるレイヤー、コメント）で構成され、フレームごとに、マークが描かれた画像が添付されます（public/refs/markup-<stamp>-<n>.png。パスはメッセージ内にあります）。メモを順番に修正し、最後に、対応した項目と対応しなかった項目、その理由を番号付きリストで示します。上限を超えたフレームには画像が付かないため、フレーム番号と座標を使ってください。利用者が添付した画像も public/refs/ に保存されます。staticFile('refs/name.png') を使ってください。

新しい動画のためのパネル

アニメーションを作成する前に、studio_open_panel を使って順番に決定事項を固めます。まず ブリーフ（チャットで把握している内容をあらかじめ入力します）、次にスクリプトまたはトラック、その次に ストーリーボード、最後にルック（styleframes）です。アニマティックを作成し、アニメーション化する前に レビュー を依頼します。まずフックとリビールをアニメーション化し、もう一度レビューを依頼します。作業に合わない段階は省略してください（キャプションの修正にブリーフは不要です）。承認されていないストーリーボードに基づいてアニメーション化する場合は、必ずそのことを伝えてください。

• studio_open_panel({ panel, data, message?, placement? }) は、brief、script、storyboard、styleframes、review、または custom を開き、すぐに { id, status: 'open' } を返します。data はパネルの初期値で、部分的な Brief、Storyboard（comp と shots）、または ReviewRequest（comp、range?、ask?）を指定します。message はパネル上部に表示される1行のメッセージです。同じ種類のパネルを2つ目に開くと、最初のパネルが置き換えられます。
• studio_panel_result({ id }) は { status: 'open' | 'submitted' | 'dismissed', answer? } を返します。相手がターミナル上で回答したと伝えてきた場合にのみ使用してください。

パネルを開いたら、何を待っているかを1行で伝えてターンを終了してください。次の段階に進んだり、確認のためにツールを再度呼び出したりしないでください。回答は [panel <kind> <id> submitted] で始まるメッセージとして届きます。相手がパネルを閉じた場合は dismissed で届きます。パネルの内容に基づいて作業を進める前に、plan/<panel>.json を読んでください。

組み込みパネルが用途に合わない単発の質問には、panel: 'custom' を使用してください。ブロックの種類と回答の形式は references/panels.md に記載されています。