clip-builder

クリップビルダー

3つの部分から短いビデオを構築します：画像をレンダリングするHTMLページ（シーン）、clip.json内のスクリプトラインのリスト（キュー）、およびページをフレームごとにキャプチャしてMP4にエンコードするコマンドラインツール。

シーンページはdraw(s)を定義します。これは、sだけから計算された、秒sにおけるページの状態を設定します。キャプチャは各フレーム（秒0、次に1/30、以下同様）に対してそれを呼び出し、スクリーンショットを撮ります。その結果、出力はマシンの速度に依存せず、任意のフレームを個別にレビュー用にレンダリングでき、クリップの一部を--fromおよび--toで再キャプチャできます。

CLIは、このスキルのディレクトリ内のscripts/clip.mjsです。このドキュメントでは、clipはnode "<skill dir>/scripts/clip.mjs"を意味します。ここで<skill dir>は、このファイルを含むディレクトリの絶対パスです。（Claude Codeはここでそのパス${CLAUDE_SKILL_DIR}を置き換えます。他のエージェントでは、このファイルが読み取られたディレクトリを使用します。）clip.jsonを含むクリップのプロジェクトディレクトリからコマンドを実行します。clip helpですべてのコマンドとオプションを一覧表示します。

必要条件

Node 20以降、ffmpeg、およびChromiumを使用したPlaywright。clip doctorでそれらをチェックし、欠けているもののインストールコマンドを表示します。Playwrightは、クリップが構築されるディレクトリにインストールします（npm install --save-dev playwright、次にnpx playwright install chromium）。このスキルのディレクトリにはインストールしないでください。ナレーションと生成音楽はオプションです。これらは、費用がかかるか、APIキーが必要な唯一のステップです。

サンドボックス化されたコマンド（Codexのデフォルト）：clip stills、clip capture、clip serveは127.0.0.1でHTTPサーバーを起動し、最初の2つはChromiumも起動します。コマンドサンドボックスは両方をブロックします。コマンドはステータス1で終了し、サンドボックスを特定するメッセージを表示します。これらの3つのコマンドをサンドボックスの外で実行する承認を求め、理由を述べてください。他のキャプチャ方法に代用しないでください。他のコマンドはサーバーもブラウザも必要とせず、サンドボックス内で実行されます。tts --generateとmusic --generateもネットワークアクセスを必要とします。

概要

開始する前に以下を確定します。不足しているものだけを尋ねてください。ユーザーが指定していないものについては、デフォルトを使用し、それを1行で述べてください。

• 目的と対象者：プロモーション、プロダクトデモ、スタッフのハウツー、レッスン。これがペースを決定します。プロモーションクリップは速く動きます。トレーニングクリップは各ステップに従う時間を残します。
• 長さ。デフォルト：プロモーションまたはデモの場合は20〜45秒、トレーニングの場合は60〜120秒。
• 出力先。これがフレームを決定します。デフォルト：wide 1920×1080、ソーシャルフィード用のtall 1080×1350。references/delivery.mdを参照してください。
• ビジュアルアプローチ：新しいグラフィックまたはアプリ画面。アプリの場合：どの画面か、そのソースコードまたはデザインシステムが色、タイポグラフィ、スペーシングのソースとして利用可能かどうか。
• サウンド。デフォルト：キャプション付きの無音。これは無料で、ほとんどのフィードビデオはミュートで再生されます。ナレーションと音楽はそれぞれオプトインです。
• スクリプト。ユーザーが持っている場合はユーザーのスクリプトを使用します。それ以外の場合は、下書きを作成し、シーンを構築する前に承認を得てください。

ワークフロー

1. ツールをチェック：clip doctor。
2. プロジェクトを作成：clip init <dir> --template graphicsまたは--template app-ui。これにより、clip.json、実用的な例を含むscene/ディレクトリ、およびaudio/が作成されます。両方のテンプレートは変更なしでレンダリングされます。
3. clip.jsonにキューを記述します。1ビートにつき1つです。ビートは、1行と1つのビジュアル状態を持つクリップのセグメントです。最初にスクリプトを記述します。シーンはそれにタイミングを合わせられ、録音後のすべての文言変更は別の有料リクエストになります。references/narration.mdでは、音声用の作成について説明しています。
4. シーンを構築：scene/index.htmlとscene/scene.jsを編集します。最初にreferences/scenes.mdを読んでください。シーンを決定論的に保つ制約（Math.random()なし、クロックやタイマーなし、CSSアニメーションなし、すべての状態がsから計算されること）がリストされています。アプリ画面の場合は、references/app-ui.mdも読んでください。
5. 静止画をレビュー：clip stillsは、選択された秒のフレームとコンタクトシートをout/review/に書き込みます。コンタクトシートを画像として開き、検査します。テキストが読みやすいこと、何も重なっていないこと、各ビートがそのキャプションが表示されている間は画面に表示されていることを確認します。すべてのフレームサイズ（--frame tall）に対して繰り返します。ほとんどの反復はこのステップで行います。静止画は高速で、費用はかかりません。clip serveは、ユーザーにライブプレビューを提供します。
6. ドラフトをキャプチャ：clip capture --draftは、モーションとペーシングをチェックするために3分の2のサイズでレンダリングします。ユーザーにファイルパスを渡し、視聴を依頼します。
7. 要求された場合、サウンドを追加。ナレーション：references/narration.md。音楽とミックス：references/sound.md。最初にclip ttsをフラグなしで実行します。計画されたリクエストと文字数をリストします。ユーザーの承認を得てから、clip tts --generateを実行します。新しい録音の後は、clip timingを実行します。これにより、キューとキャプションのタイミングが配置され、設定されていればシーンがナレーションに合わせて引き伸ばされます。その後、再度静止画をレビューします。
8. 最終版をキャプチャ：各フレームに対してclip capture --finalを実行し、サウンドがある場合はclip mix、アップロード用の小さなコピーとしてclip web <ファイル>を実行します。
9. 確認して報告：最終版の静止画をレビューし、ミックスレポートのラウドネスを読み、clip scan outを実行します。何が生成されたか、ファイルパス、何がチェックされ、何がチェックされなかったかを報告します。

無音のクリップはステップ7をスキップします。キャプションは各キューのatおよびuntil値から取得され、clip timingがそれらをページに書き込みます。

安全ルール

クリップジョブには、ユーザーの資金、APIキー、および公開されたアイデンティティが含まれます。

• 有料リクエストには明示的なユーザー承認が必要です。プロバイダーはナレーションと音楽に課金します。CLIは--generateなしでは何も送信しません。そのフラグは、ユーザーが特定のテイクを承認した後にのみ渡してください。1つのテイクの承認は次のテイクをカバーしません。リクエスト時にドライラン出力（行数と文字数）を表示します。リクエストが中断された場合、そのレシートはattemptedのままです。ユーザーがプロバイダーの使用履歴を確認するまで再試行しないでください。リクエストが課金されている可能性があるためです。
• APIキーは環境からのみ取得します。CLIはELEVENLABS_API_KEYまたはOPENAI_API_KEYを読み取り、他のソースは読み取りません。ユーザーのシークレットストアから、単一コマンド用にキーをインラインで渡します（references/keys-and-paid-calls.mdにコマンドがあります）。ユーザーにキーを会話に貼り付けるように頼んだり、キーを印刷したり（echo、env、cat）、ファイルに書き込んだりしないでください。キーが設定されていることを確認するには、その長さを確認します。clip doctorがこれを行います。
• ファイルを配信し、公開しないでください。クリップの投稿またはアップロードは、ユーザーがその特定のアクションを要求しない限り、ユーザーのアクションです。
• ユーザーが使用する権利を持つ素材のみを使用してください。音楽、フォント、ロゴ、映像には、ライセンスまたはユーザーの所有権が必要です。ユーザーが所有するか、表示する許可を持つアプリのみを表示し、モックアップを他社の製品としてスタイル設定しないでください。両方のプロバイダーの利用規約は、商用利用と生成音声の開示をカバーしています。ナレーション付きクリップが公開される前に、ユーザーにそれらを参照させてください。
• 画像とファイルにプライベートデータを残さないでください。アプリ画面には架空の名前と番号を使用してください。実際のものとして提示される数字と引用は実際のものでなければならず、例は例として識別可能でなければなりません。共有する前に、clip scanを実行してください。APIキー、ローカルユーザー名とパス、メールアドレス、ユーザーのプライベート用語リスト、メディアファイルに埋め込まれたメタデータをチェックします。

編集ガイドライン

• クリップごとに1つのトピックをカバーします。2つをカバーするスクリプトは分割します。
• 最初の数秒以内にナレーションまたは最初のキャプションを開始します。
• ビートごとに1つのキューを使用し、ビートのビジュアルを、その行が話されている間は画面に表示したままにします。
• 常にキャプションを含めます。ほとんどのフィードビデオはミュートで再生されます。
• 縦長フレームは電話サイズでレビューします。このため、シーンユニットは縦長フレームで大きくなります。
• モーションを使用して状態の変化をマークするか、注意を向けます。連続的な動きは避けてください。
• 終了カードは少なくとも2.5秒間保持します。
• トレーニングの場合：アクションとその結果を、視聴者が実行しながら追跡できるペースで表示します。画面上のステップに番号を付け、最初に視聴者が何をできるようになるかを述べます。

コマンド

コマンド	機能
clip doctor	Node、ffmpeg、Playwrightをチェックし、設定されているキーを報告します（長さのみ）
clip init <dir> --template graphics|app-ui	実用的な例からプロジェクトを作成します
clip serve	ライブプレビューを提供します。URLの?t=5で5秒で保持します
clip stills [--at 2,5,9] [--frame tall] [--final]	レビュー用の静止画とコンタクトシートをレンダリングします
clip capture [--frame wide] [--draft] [--final] [--from s --to s] [--web]	すべてのフレームをレンダリングし、MP4にエンコードします
clip capture --mode clock --url … --seconds N [--actions file.mjs]	実行中のアプリをキャプチャします（実験的。references/app-ui.mdを参照）
clip tts [--generate]	まだ録音されていないナレーションをリストします。--generateで録音します（有料）
clip music [--generate]	生成されたスコアについても同様です（有料）
clip timing	キューとキャプションの時間を計算し、scene/timing.jsonと.srtを書き込みます
clip mix	標準ラウドネスでサウンドトラックを構築し、キャプチャされた各ビデオにマルチプレックスします
clip web <video>	アップロード用の小さなコピーを書き込みます
clip scan <dir> [--terms-file words.txt]	ファイルが共有される前にプライベートデータを報告します
clip strip <media file>	埋め込まれたすべてのメタデータを削除したコピーを書き込みます

出力はout/に、<name>-<take>-<frame>.mp4という名前で、該当する場合-draft、-part（--from/--toでキャプチャされた範囲）、-sound、-webの接尾辞が追加されます。古いバージョンを新しいバージョンの隣に保持するには、clip.jsonの"take"をインクリメントします（a、b、c、…）。

参考ファイル

現在のステップで必要なファイルを読んでください。

ファイル	いつ読むか
references/scenes.md	シーンの作成または変更時：ページ契約、ヘルパーライブラリ、ユニット、縦長フレーム、フォント、およびキャプチャを決定論的に保つ制約
references/app-ui.md	クリップがアプリ画面を表示する場合：デザイントークンからの再構築、ポインター、タイピング、カメラ移動、実行中のアプリのキャプチャ
references/narration.md	行の作成、プロバイダーと音声の選択、発音、1行の再録音、シーンをナレーションに合わせる、キャプション
references/sound.md	音楽とミックス：レベル、ダッキング、トラックをクリップに合わせる、ラウドネス、ミックスの修正
references/keys-and-paid-calls.md	有料リクエストの前：キーを安全に渡す方法、送信されるもの、レシート、中断されたリクエスト
references/project-file.md	clip.jsonの任意のフィールド
references/delivery.md	フレームサイズ、最終レンダリング、配信前のチェック、報告する内容
references/cookbook.md	リクエストが一般的なジョブと一致する場合。12の実用的なレシピ：無音クリップ、デザイントークンからのアプリ画面、複数のアスペクト比、ステップバイステップのトレーニングクリップ、JSONからの棒グラフ、各プロバイダーを使用したナレーション、1行の再録音、バックグラウンドミュージック、カスタムフォントとロゴ、実行中のアプリ、最終チェック。draw()スニペットも含む

トラブルシューティング

症状	考えられる原因
「これはコマンドサンドボックスのように見えます」、listen EPERM、またはブラウザの起動に失敗する	エージェントのサンドボックスがHTTPサーバーまたはブラウザをブロックしています。ユーザーの承認を得て、stills、capture、serveをサンドボックスの外で実行してください
「ページがwindow.readyを設定しませんでした」	シーンのスクリプトエラー（メッセージにページのエラーがリストされます）、またはページがキットのclip()を呼び出していません
同じシーンの2つのキャプチャが異なる	シーン内の一部の状態がsから計算されていません：Math.random()、Date、CSSアニメーションまたはトランジション、<video>、タイマー
テキストが別のマシンで異なるフォントでレンダリングされる	シーンがシステムフォントを使用しています。フォントファイルをシーンディレクトリに配置してください（references/scenes.md）
画像がナレーションより先行または遅れている	新しい録音後にclip timingが実行されていないか、その前にビデオがキャプチャされました。clip mixは最初のケースでは実行を拒否し、2番目のケースでは警告します
ttsリストのattempted	以前のリクエストが完了しませんでした。--retry-attemptedを使用する前に、プロバイダーの使用履歴を確認してください
音楽レベルが単語の間で上下する	"mix": { "master": "limit" }を設定します（references/sound.md）