framejam

FrameJam：スタイル、プレイブック、ワンクリックで動画やストーリーボードをレビュー

スキルのバージョン：5

FrameJam は http://localhost:2400 でチャットの横に表示されます。チャットが苦手とする次の3つを提供します。 スタイルの選択（見た目を説明する構造化された style.json とサンプル動画）、プレイブックに沿った進行 （ある種類の動画を作るための一連の手順。ユーザーが用意するもの、手順、ツール、品質基準をまとめたもの）、そして正確な フィードバック（レンダリングのフレーム画像付きで、タイムスタンプを指定して固定できるコメント）です。

FrameJam は、動画の作成に使うものを問いません。ユーザーがレビューするのはレンダリング済みの動画（videoPath）なので、ユーザーが見るのは、レンダリングしたものそのものです。プロジェクト独自のツールでも、普段使っているツールでも、用途に合うものを使ってください（Hyperframes、Remotion、Motion Canvas、ffmpeg など）。

FrameJam はツールキットであり、決まった手順ではありません。適切なデフォルトを使ってユーザーの依頼に対応し、役立つ場合にこれらのツールを使ってください。ユーザーが求めていない手順や質問、承認を追加しないでください。

ユーザーとの会話で使う言葉： FrameJam では、レビュー1件をプロジェクトと呼びます（開始ページは「Projects」です）。「FrameJam でプロジェクトを開きました」と言い、「レビューを開きました」とは言わないでください。ツール名やフィールド名（open_review、reviewId）はそのままにしてください。

0. 組み込みブラウザーで FrameJam を開く（必ず最初に行う）

このスキルを使ったら、ユーザーに確認せず、ユーザーに見える状態で FrameJam を開いてください。

• Cursor： 組み込みブラウザーツール（cursor-ide-browser → browser_navigate）を使い、 position: "side" を指定してチャットの横に開きます。
• その他のハーネス： ブラウザーまたはプレビュー用ツールがあれば、それを使います。なければ、ユーザーにリンクを伝えます。
• 開くページ： プロジェクトに url があればそのページ、ピッカーページを開いた場合はそのページ、それ以外は http://localhost:2400（Projects）です。
• ページが読み込まれない場合、UI をホストしているものがありません。npx -y framejam start を実行します（バックグラウンドで UI を起動するか、起動中のものを再利用し、URL を出力します）。その後、その URL を開きます。ユーザーに起動を依頼しないでください。
• framejam ツール自体を利用できない場合は、実行中のアプリ（cursor、claude、codex）を指定して npx -y framejam install <app> を実行します。MCP サーバーとスキルを追加（またはインストール済みであることを確認）し、UI を起動します。出力されたリンクを開き、最後に表示される手順（ツールを読み込むためにアプリを一度再起動すること）をユーザーに伝えます。

1. ユーザーの依頼に対応する

適切なデフォルト（長さ、形式、ツール、見た目）を使って、すぐに依頼に取りかかります。編集する映像素材など、推測できないことがある場合に限って質問してください。依頼が短い場合に役立つショートカット：

• /framejam playbook または /framejam style： 該当するものだけのピッカーを開きます（open_picker({ kinds: ["playbook"] }) または ["style"]）。ループのステップ0を参照してください。
• 続きの作業： このチャットで動画を作成中なら、同じプロジェクトに次のバージョンをレンダリングします （reviewId を指定して add_version を使うか、同じ title を指定して open_review を使います）。
• フィードバックが届いている場合： list_reviews() にはすべてのプロジェクトが表示されます。いずれかが sent_not_delivered または user_commenting の場合は、get_feedback({ reviewId }) を呼び出して反映します。awaiting_user の場合は、その url を開いて wait_for_feedback を実行します。
• このフォルダーに動画がすでにある場合（レンダリング済み動画、または Hyperframes、Remotion、Motion Canvas のプロジェクト）に、ユーザーがレビューを希望した場合：最新のレンダリング済み動画をプロジェクトとして開きます。
• /framejam だけで手がかりがない場合： 動画のテーマを一行で尋ねます。

ループ

0. 選択（求められた場合のみ）。 ユーザーがプレイブックやスタイルを指定した場合は、それを使用します（get_playbook(id) / get_preset(id)）。 選択ページを開くのは、ユーザーが選択を求めた場合（/framejam playbook、/framejam style、「スタイルを選ばせて」など）、 または依頼の範囲が広すぎて作業を始められない場合のみです。それ以外は、そのまま制作します。
   • open_picker({ title, kinds }) を呼び出します（kinds のデフォルトは両方です）。返された url を組み込みブラウザーで開き、 チャットにクリック可能なリンクとして投稿してから、wait_for_pick({ pickId }) を呼び出します。pending が返されたら、もう一度呼び出します。 pending が6回連続で返された後は、代わりにチャットで尋ねます。
   • 選択結果が届いたら、何を使うかを1行で伝えます（「Clean Cut プレイブックを使用し、スタイルは使用しません」など）。それぞれのページへのリンクも付けます。
   • null のプレイブックまたはスタイルは、ユーザーが何も選ばなかったことを意味します。open_review に playbookId と styleId を渡し、後のバージョンにも引き継がれるようにします。既存のプロジェクトでは、get_feedback と wait_for_feedback がそれらを返します。
1. プレイブックとスタイルに従います。
   • プレイブック： skill はこの種の動画を作るためのレシピで、デフォルト設定はユーザーの依頼によって上書きされます。レンダリングのたびに、以下の手順を実行します。方法から指定された場合は playbookDir 内のファイルを読み込み、使用前にスクリプト、エンジン、テンプレートをプロジェクトにコピーします。playbookDir は決して編集しません。stylesSentence には、スタイルとプレイブックをどう組み合わせるかが記載されています。プレイブックによっては、そのために作られたスタイル（featuredStyles）が列挙されています。選択されたスタイルがその中にある場合は、get_playbook({ id, styleId }) を呼び出し、プレイブックのスキルで指定されている箇所に styleForThisPlaybook.settings を使用します。プレイブックの例の動画に合う設定だからです。
   • スタイルは見た目であり、動画の出発点ではありません。 まずユーザーの依頼に基づいて動画を計画します（ロケットの打ち上げなら、主題はロケットです）。次に、guide の説明に従い、スタイルのビジュアル表現でその主題を制作します。palette、テクスチャ、背景、fonts、easing、transitions、textAnimations、ペース配分を使います。スタイルは強力な出発点として扱いますが、厳格なルールではありません。主題やユーザーの依頼に合わせて柔軟に調整します。
   • example には、スタイルのプレビュー動画に何が映っているかが記載されています。ユーザーから求められない限り、その場面（主題、小道具、レイアウト、ストーリーなど。たとえば Cyanotype Mac のコンピューター）を再利用しないでください。
   • templateDir 内の構成例は参考資料であり、ひな型ではありません。コピーしてテキストだけ差し替えることはしないでください。templateFiles 内のファイルを開く（または get_preset({ id, includeTemplate: true }) を呼び出す）のは、テクスチャフィルターやタイトルの表示など、技法の実装方法を確認する場合に限ります。その技法を使って、独自の構成を作り直してください。
2. 制作： プロジェクトのツールで動画を制作します（Hyperframes の詳細は以下、その他のツールについてはさらに下を参照）。
3. レンダリング： バージョンごとに新しいファイルへレンダリングします（例：renders/v1.mp4、renders/v2.mp4）。これにより、以前のバージョンと比較できます。 まず自分で確認します： レビューを開く前に、確認できる方法を使って、レンダリング結果が依頼（およびプレイブックに品質基準があればそれ）に沿っているか確認し、問題があれば修正します。
4. レビューを開く： open_review({ title, videoPath: "<abs>/renders/v1.mp4" })。絶対パスを使い、後のレンダリングがこのプロジェクトの新しいバージョンになるよう、毎回同じ title を使います。 動画に音声がありますか？ 単語のタイミング情報がすでにある場合（動画に焼き込んだ字幕、タイムスタンプ付きのナレーション、実行済みの文字起こしなど）は、transcriptPath（.srt、.vtt、または Whisper のような単語タイミングの JSON）を追加します。すると、ユーザーはタイムラインの下に表示される文字を追いながら、単語にコメントできます。タイミング情報がない場合でも、whisper.cpp がインストールされていれば FrameJam がレンダリング結果を文字起こしするため、このためだけに文字起こしを行う必要はありません。 返された url を組み込みブラウザーで開きます（手順0）。また、ユーザーがブラウザーに表示されていない場合でもチャットから開けるよう、必ずクリック可能な Markdown リンクとしてチャットに投稿します。 例：[FrameJamでv1を開く](http://localhost:2400/review/rev_…)。その後、次の内容を1行で伝えます。 「動画をクリックして指摘箇所を示すか、一時停止して入力し、レビューを終了を押してください。」
5. 同じターン内で待機します： レビューを開いた直後に wait_for_feedback({ reviewId }) を呼び出します。先にターンを終了してはいけません。レビュー画面で「Agent listening」と表示されるのは、このループの実行中のみです。
   • status: "pending" は、直近約50秒間に何も届かなかったことを意味します。ユーザーに尋ねず、すぐにもう一度呼び出します。
   • pending が12回連続で返されたら（約10分）、待機を終了します。 無期限に待ってはいけません。プロジェクトの url と「終わったらレビューを終了を押し、ページに表示された行を貼り付けるか、apply my FrameJam feedback と伝えてください。その後、対応します。」を短く伝えてターンを終了します。コメントは保存されるため、失われることはありません。ユーザーが戻ったら get_feedback を呼び出します。ユーザーがチャットで待機を止めるよう伝えた場合は、その時点で終了します。
   • status: "feedback" は、comments[]、Markdown の要約、フレーム画像を返します。
   • revised: true は、フィードバックを受け取った後にユーザーがレビューを再度開き、コメントを変更したことを意味します。新しいリストが以前のリストに置き換わります。新しいリストにない以前の変更指示は破棄します。
   • 完了ですか？ コメントが動画の完成、承認、または問題なしを伝えるだけで、変更点がない場合は、次のバージョンを作成しません。最終ファイルの場所とプロジェクトのリンクをユーザーに伝え、待機を終了します。
6. すべてのコメントに対応します。
   • at / time / endTime は動画内の位置です。position はフレーム内の位置です。
   • ピン留めコメントのフレーム画像にはピンが描かれています。ピンの下にあるものを確認し、その時点のソースから該当する要素を見つけます。
   • wholeVideo: true は、ペース配分、色、音楽など、動画全体に関する指摘を意味します。
   • 文字起こしがある場合、範囲に関するコメントの spoken にはその範囲の発話内容が、特定の時点に関するコメントの spokenAround にはその近辺の発話内容が記載されています。これらは文字起こしから取得されるため、名前や珍しい単語は聞き間違えられている場合があります。台本としてではなく、該当箇所を見つけるために使います。
7. 次のバージョンを納品します。 renders/v2.mp4 に再レンダリングしてから、add_version({ reviewId, videoPath, note }) を呼び出します（または同じ title で open_review を再度呼び出します）。発話のタイミングが変わった場合は、新しい transcriptPath も渡します。 note は変更内容を1行で要約したものです。新しいバージョンが届いたときと、バージョンメニューに表示されます。 チャットでバージョンの準備ができたことを伝え、返された url をクリック可能なリンクとして再度投稿します。例：[FrameJamでv2を開く](http://localhost:2400/review/rev_…)。同じ1行の要約も添えます。 各バージョンで1ラウンドとなります。ユーザーが「レビューを終了」すると前のバージョンが確定し、新しいバージョンにはコメントがない状態で始まります。コメントに対応できなかった場合は、その理由をチャットと note の両方で伝えます。 ラウンドを手早く進めます： 変更箇所だけ再レンダリングし、残りは再利用します。
8. 手順5に戻ります。

長時間実行するジョブ

• 1 分以上かかる処理は、コマンドの実行後も動作し続けるように開始してください（バックグラウンドジョブを使用し、シェルが終了すると停止するサブシェル内の & は使わないでください）。ファイルにログを記録し、30〜60 秒ごとに状況を確認してください。ポーリングできるジョブに対して、固定の長時間待機はしないでください。
• 重いジョブは一度に 1 つだけ実行してください。レンダリングを 2 つ同時に行ったり、レンダリングと文字起こしを同時に行ったりすると、どちらも遅くなります。
• 待機する前に、実行中の処理と所要時間の目安を 1 行でユーザーに伝えてください。

Hyperframes

• このマシンでの初回実行： npx hyperframes doctor を 1 回実行してください。レンダリングに必要な Node、ffmpeg、Chrome を確認します。何か不足している場合は、ビルドする前にインストール方法をユーザーに伝えてください。
• コンポジションをビルドします： ルート要素に data-composition-id と data-width／data-height を設定した index.html、data-start／data-duration／data-track-index を設定した .clip 要素、および window.__timelines["<id>"] に登録した一時停止状態の GSAP タイムラインを用意します。npx hyperframes lint を実行し、エラーを修正してください。
• レンダリング： npx hyperframes render -o renders/v1.mp4。
• 開く： 他のツールと同様に videoPath を渡します。ユーザーがレンダリング結果を確認します。

その他のツール（Remotion、Motion Canvas、ffmpeg、録画など）

• プロジェクト独自のツールとレンダリングコマンド（npx remotion render、Motion Canvas エクスポーター、ffmpeg スクリプト、画面録画など）をそのまま使ってください。プロジェクトを Hyperframes に変換しないでください。
• バージョンごとに新しい mp4／webm／mov ファイルにレンダリングし、open_review({ title, videoPath }) を呼び出してください。
• ユーザーの題材に合わせて、スタイルの見た目（guide、palette、fonts、easing、テンポ）を各ツール固有の方法で適用してください。

ストーリーボード（動画を作る前）

ユーザーが先にショットの内容を確認したい場合や、ストーリーボード、ショットリスト、「アニメーション化する前のフレーム」を求めている場合は、ストーリーボードレビューを使用してください。同じ手順で進めますが、各バージョンはレンダリング結果ではなく、静止画のパネル一式になります。

1. パネルを作成します。 各ショットにつき画像を 1 枚用意し（png、jpg、webp、gif、svg）、すべて最終動画と同じアスペクト比にして、1 つのフォルダーに順番どおりに並ぶ名前で保存します（storyboard/01.png、02.png、…）。推奨する画像ソースは、上から順に次のとおりです。
   • 粗く作成したコンポジションの Hyperframes スナップショット（npx hyperframes snapshot --at 0.5,2.5,4.5 -o storyboard）、またはプロジェクト独自のツールで作成した静止画。
   • ショットごとに生成した画像。
   • スクリーンショットを撮った簡単な HTML モックアップ。
2. 開きます： open_review({ title, panelsDir: "<abs>/storyboard", panels: [{ path: "01.png", title: "Cold open", caption: "Slow push in. VO: 'Every team ships faster now.' 2s" }, …] })。panels は省略可能です。省略すると、フォルダー内のすべての画像がファイル名順に使われます。タイトルとキャプションは各パネルの下に表示されるため、ショット名、動きまたはカメラワーク、ナレーションのセリフ、長さを記載してください。
3. 待機します： 動画の場合と同じように wait_for_feedback を使用します（先に組み込みブラウザーで URL を開き、pending が 12 回連続したら停止してください）。
4. パネルごとのコメントを確認します。 at は "panel 3 (Cold open)"、panel には番号、タイトル、キャプション、パネルの imagePath が含まれ、position はユーザーがパネル上でクリックした位置です。添付画像には、ピンが描かれたパネルが表示されます。wholeVideo: true は、ストーリーボード全体（順序、テンポ、ショットの追加または削除）を対象としていることを示します。
5. 次のバージョン： 画像を更新または再生成してから、add_version({ reviewId, note }) を呼び出します。メディアを指定しない場合は、同じ panelsDir が再度読み込まれ、引き続き存在するファイルのタイトルとキャプションが維持されます。順序、タイトル、キャプションを変更する場合は、panels を再度渡してください。以前のバージョンでは、それぞれ独自の画像のコピーが保持されます。
6. ユーザーがストーリーボードを承認したら、パネルとキャプションに沿ってショットごとに動画を作成し、通常の動画レビューとして開きます（レンダリング結果を videoPath に指定して、新しい open_review を呼び出します）。

ほかの方法

• ユーザーが「FrameJam のフィードバックを適用して」と言った場合（レビュー ID の有無は問いません）、get_feedback() を呼び出します。 reviewId が指定されていない場合は、コメントがまだ届いていないレビューが選択されます。ユーザーがコメントを入力したものの、レビューを完了するためのボタンを押していない場合は、ここで引き継がれます。list_reviews() を呼び出すと、すべてのプロジェクトと各プロジェクトの進捗状況を確認できます。
• MCP が接続されていない場合、ユーザーはレビューページのバージョンメニューにある コメントをテキストとしてコピー を使い、その内容をチャットに貼り付けることができます。

FrameJam の更新

ユーザーが FrameJam の更新を求めた場合、使用中のアプリ（cursor、claude、codex）を指定して npx -y framejam@latest install <app> を実行します。アプリを指定しない場合は、コンピューター上で見つかったすべてのアプリがセットアップされます。このコマンドで、スキル、MCP サーバーのエントリー、現在開いている FrameJam ページが更新されます。その後、ユーザーにアプリを一度再起動するよう伝えます。FrameJam のツールは、再起動後にのみ新しいバージョンを読み込みます。

ルール

• タイムスタンプをチャットで説明するよう、ユーザーに求めないでください。レビューページに案内してください。
• レンダリング結果を偽造しないでください。レンダリングに失敗した場合は、レビューを開く前に修正してください。
• レビュー URL は変更しないでください。動画ごとにプロジェクトを1つ作成し、レンダリングごとに新しいバージョンを作成します。
• ユーザーとの会話では「プロジェクト」と呼んでください。