syklayou-glitch/video-shotcraft

video-shotcraft：映画感あふれる製品ビデオ制作

自己完結型の制作機能ライブラリ：152 枚のショットレシピカード（デモ実装ソースコードと動的サンプルギャラリー付き）、検証済みの完全プロモーションテンプレート、再利用可能なコンポーネントとオーディオアセット、6 段階のワークフロー。現在の焦点は Web/デスクトップ製品プロモーションビデオですが、ショットカード自体は汎用的なモーション語彙です。任意のビデオ内の個々のショットとしてカードを単独で抽出することもできます。

呼び出し時のモード判断

完全なプロモーションビデオには、相互に排他的な 3 つのモードがあります。素材収集、ストーリーボード、または実装を開始する前に、ユーザーが明確に選択しているかどうかを判断してください。既に選択されている場合は、そのまま実行し、繰り返し質問したり、別のモードに変更したりしないでください。

1. テンプレートを直接使用：Ink Press の既存の置換フローを維持します。template/TEMPLATE.md を読み、既存のショット構造に従って、ターゲット製品のスクリーンショット、コピー、ブランド情報を置き換えます。
2. 自律的自由制作：references/pipeline.md を読みます。エージェントは、ユーザーの既存の要件とプロジェクト内容に基づいて、ビジュアル方向性、ショットマッピング、ストーリーボード、素材、オーディオを自律的に決定し、最終成果物まで連続して進めます。製品ブリーフ、スタイルフレーム、ショットマッピング、またはストーリーボードの段階でユーザーの確認を待つために一時停止しません。
3. 共同制作：references/guided-free-creation.md を読みます。エージェントはまず根拠のある判断と提案を行い、ユーザーが順番に製品ブリーフ、要件決定、ビジュアル方向性、ショットマッピング、最終ストーリーボードを確認します。ストーリーボードが承認された後、references/pipeline.md の最終素材収集と制作段階に進みます。

ユーザーがプロジェクトパス、URL、スクリーンレコード、またはページスクリーンショットを提供しているが、まだモードを選択していない場合は、最初に最小限の読み取り専用の製品チェックを実行します。製品のポジショニング、主要機能、ページビジュアル、表示可能な状態、および素材リスクを理解します。ビジネスプロジェクトを変更したり、機密データを収集したり、ビデオコードを作成したりしません。チェック後、3 つのモードを提示し、以下を説明します。

• Ink Press がその製品に適しているかどうか、適している/適していない具体的な理由。
• 自律的自由制作と共同制作がそれぞれ適しているかどうか、どの製品ビジュアルの手がかりが保持される見込みか。
• エージェントが推奨するモードとその根拠、およびトレードオフ。

次に、明確に質問します：「上記の製品チェックに基づいて、私は ×× モードの使用を推奨します。このモードで続行しますか？」 同時にユーザーに伝えます：https://vincentwei1021.github.io/video-shotcraft/ で動的サンプルを閲覧し、ビデオで使用したいモーションエフェクトショットを選択できます。

ユーザーがチェック可能なプロジェクトやページを提供していない場合は、3 つのモードを簡単に紹介してから質問します。Ink Press が既成のテンプレートだからといって、デフォルトで推奨しないでください。

• ユーザーがテンプレートを選択：template/TEMPLATE.md を完全に読み、元のテンプレートフローに従って実行します。
• ユーザーが自律的自由制作を選択：references/pipeline.md を完全に読み、エージェントが自律的に進め、段階ごとに確認を待ちません。
• ユーザーが共同制作を選択：references/guided-free-creation.md を完全に読み、その中の確認ノードに従って協力します。
• ユーザーが未決定：ここで選択を待ちます。ユーザーに代わってデフォルトで選択したり、制作を開始したりしないでください。

例外 1：ユーザーが Ink Press テンプレートを明示的に指定した場合、テンプレートモードが選択されたと見なします。 例：「Ink Press テンプレートを使って製品のプロモーションビデオを作って」。この場合、再度質問せず、template/TEMPLATE.md を完全に読んでテンプレートルートに従って実行します。

例外 2：ユーザーが特定のショットカードの使用または参照を明確に指定した場合、ショットの制約は既に選択されています。 例：「deck-deal-flyin と row-embed を使ってこのビデオを作る」または「spotlight-hero-card のエフェクトを参考にする」。この場合、テンプレートを紹介したり、テンプレートの使用を質問したりしないでください。ギャラリー名解決ルールに従って指定されたショットを確認し、各カードを完全に読み、カードの「参考実装」に従って正確なデモソースコードを特定します。単一ショットはターゲット素材が明確になった後に実行できます。完全なプロモーションビデオで、まだ自律的自由制作と共同制作のどちらを使用するか説明されていない場合は、これら 2 つのモードのみを質問します。指定されたショットはその後の制作の制約として扱われ、自動的に共同制作と見なされるわけではありません。

4 つの使用方法

1. 完全なプロモーションビデオ（テンプレートルート）：テンプレートビデオと非常に似た効果を希望 → template/TEMPLATE.md を読み、「製品置換ガイド」に従って素材をショットごとに適応させます。
2. 完全なプロモーションビデオ（自律的自由制作）：新しいスタイルを希望し、エージェントに自律的な決定を許可 → references/pipeline.md を読み、製品理解から最終チェックまで連続して進め、途中で段階ごとに確認を待ちません。
3. 完全なプロモーションビデオ（共同制作）：重要な決定に参加したい → references/guided-free-creation.md を読み、製品ブリーフ、要件決定、ビジュアル方向性、ショットマッピング、最終ストーリーボードを確認します。承認後、パイプラインの最終素材収集から続行します。
4. 単一ショット/単一モーション：references/shots/ からカードを選択（またはユーザーに gallery/ ギャラリーで選択させる）、カード全文を読み、「参考実装」に従って正確なデモソースコードを特定し、ターゲット素材に適応させます。

自律的自由制作と共同制作の境界

自律的自由制作は、クリエイティブおよびエンジニアリングの決定をエージェントに委ねます。エージェントはプロジェクトコンテンツから製品の重点、ビジュアル方向性、ショットマッピング、ストーリーボード、素材処理、オーディオ計画を動的に導き出し、重要な判断を記録した後、直接実行します。安全に推論できない必須入力を除き、質問したり、段階ごとに一時停止したり、中間成果物の確認を求めたりしません。ユーザーの既存の明確な要求は常に制約であり、エージェントのデフォルトの選択によって上書きされることはありません。

共同制作でのみ段階ごとの確認が使用されます。デフォルトで references/guided-free-creation.md を読み、各ラウンドで手戻りを最も減らせる 1～3 個の質問のみを行い、製品ブリーフ、要件決定、ビジュアル方向性、ショットマッピング、最終ストーリーボードで一時停止し、ユーザーの確認を待ちます。ユーザーはビジネスとクリエイティブの方向性を確認します。エージェントは、収集方法、実装パラメータ、SFX フレーム固定、Remotion プロジェクト、レンダリング、テクニカル QA を自律的に完了します。

共同制作において、ユーザーが明確に「あなたに全権を委ねる」または「確認をスキップして直接実行して」と言った場合、自律的自由制作に切り替え、この選択を記録します。自律的に進めると主張しながら、引き続き段階ごとの確認を要求しないでください。

機能からショットへのマッピングは、単に「どのモーション構文を使用するか」であり、完全なストーリーボードではありません。共同制作でマッピングを確認した後、エージェントはショットの順序、長さ、具体的な画面、ページ状態、素材ソース、字幕、トランジション、SFX を提示しなければなりません。完全なストーリーボードが確認された後にのみ、最終素材収集に進みます。ユーザーがギャラリーからショット名をコピーする場合、カード名または「カード名 · スタイル名」を提供するだけでよく、エージェントがローカルのレシピカードとデモソースコードを読み取ります。

核心理念

1. 既存ページの複製には実際のスクリーンショットを使用する必要があります。手書き UI は非複製シナリオに限定され、品質と表現の明確さが厳格な要件です。 製品の実際のページを表現する場合、最初のステップでローカルの dev サーバーを起動し、ヘッドレスブラウザを使用して全ページ 2x テクスチャ + 要素レベルカットアウト + layout.json 座標テーブルをキャプチャします。非複製シナリオ（抽象的なオープニング/ブランドセクション/独立した表示コンポーネント）では手書き UI が許可されますが、出版品質に達していないか、視聴者が何を表現しているかを理解できない場合は、スクリーンショットルートに戻ります。ページデータはリスクに応じて処理します。公開デモデータは、製品ブリーフで明確に確認された場合にのみ保持できます。顧客、個人、内部、キー、リアルタイム、またはその他の機密データは、架空または匿名化されたコンテンツを使用する必要があり、収集前にフリーズします。

2. ビデオ全体のビジュアル言語は製品自体から成長する必要があり、無関係な「プロモーションビデオスキン」を別途作成してはいけません。 スタイルフレームを作成する前に、製品/ウェブサイトのデザインシステム、ソースコード、または計算されたスタイルからデザインスペックを抽出して記述します。フォントファミリーとウェイト、フォントサイズ階層、行高/文字間隔、グリッド、間隔、配置、情報密度と角丸、および背景/サーフェス/本文/強調/状態色、グラデーションとマテリアル。ビデオ内のすべてのタイトル、字幕、数字、テキストカード、タイポグラフィ、トランジション、パーティクル、光エフェクト、その他のモーションエフェクトの配色は、このトークンセットを再利用するか、控えめに拡張する必要があり、同時に製品のトーン、センス、質感に一致する必要があります。テンプレートまたはショットカードルートを使用する場合、そのショット構造、モーション構文、リズム、調整済みパラメータのみを継承します。フォント、タイポグラフィ、配色、マテリアルは、ターゲット製品に合わせて再スキニングする必要があります。ナラティブ上の理由で製品ビジュアルから逸脱する必要がある場合、共同制作では最初に理由を説明し、ユーザーに確認を求めます。自律的自由制作では、理由とトレードオフをデザインスペックに記述して続行します。

3. 映画感はカメラワーク、光と影、リズム、音の協調から生まれ、派手なアニメーションからは生まれません。 繰り返し承認されているのは、単一主役の完全なアクションアーク（スポットライト → ズームイン → フロート → 元の位置）、物理的メタファーによって駆動される加速度（カードディール）、サイドチルトのオービットショット、ライザー → インパクト → スパークルのサウンドフレーズです。バルク要素のエントランスはモーション自体に依存し、個々のグローには依存しません。装飾的なグリント/グローの大量発光は安っぽく見えますが、単一の高品質なライトエフェクトは許容されます。

4. 各ショットは 1 つのモーションのみを伝えます。重要な情報が着地した後は、呼吸するための時間が必要です。 1 つのアニメーション手法（フライイン/スタック/ページめくり）は、ビデオ全体を通じて 1 回のみ主役として登場します。繰り返しのショットやタグラインはすべて削除します。リズムの好みは一方向です。過去のフィードバックはすべて「遅く/停止」を指向しており、「遅すぎる」という指摘は一度もありません。ブランドのロゴタイプの着地は ≥1 秒ホールド、バルクモーションの終了後は 0.5 秒の静止、オープニングの主役アクションは 3 秒を確保します。タイムラインを作成する際は、ホールド/レストのフレームバジェットを事前に割り当てます。

5. 強力なリズムの BGM を持つビデオでは、すべてのトランジションとモーションエフェクトはビートに同期する必要があります。 ユーザーが音楽を選択済み → 作業開始前にリズム分析を実行（librosa グリッドフィッティングで実際の BPM/フェーズ + kick/snare/hihat 3 クラスのドラムヒット位置特定）、グリッドのトランジェントカバレッジが検証を通過した後にのみストーリーボードを作成。タイムラインは拍数 beatF(n) で記述し、スパースなアクセントはグリッド補間点ではなく実際のトランジェントに固定します。レンダリング後、完成ビデオからオーディオトラックを抽出してカットポイント誤差 ≤3f を確認します。ビート同期はタイミングに関係し、振幅には関係しません。フル画面/カメラレイヤーに作用するビートインパクトは大きなスラムと見なされ、ビデオ全体で ≤3 箇所（美的ルール R4）、残りのビートポイントのモーションは要素レイヤーにのみ作用します。方法論は references/music-beat-sync.md を参照。BGM を適用したビデオの最終レンダリングでは、デフォルトで 2 つのバージョンを提供します。BGM ありバージョンと BGM なしバージョン（SFX は保持）、bgm inputProp を使用して同じタイムラインからレンダリングし、ユーザーが後で独自の音楽を適用できるようにします。

6. ショットカードモーションを使用するには、まずギャラリーインデックスを解析し、正確なデモ実装コードを読み取る必要があります。 まず gallery/api/library.json を使用してカード名と style-key を検証し、次にカードドキュメントの「参考実装」に従って特定の TSX を特定します。レシピカードはセマンティクスとパラメータテーブルを提供します。正確なデモソースコードは、調整済みパラメータの真実（イージング、持続時間配分、マスク解除のタイミング、既知の落とし穴の回避方法）です。適応的な変更は許可されますが、カードの「既知の落とし穴/クリティカルポイント」としてマークされたパラメータをダウングレードしてはいけません。品質基準は引き上げるのみで、引き下げてはいけません。カード名と理解に基づいて新しく作成することは、すべての調整の蓄積を放棄することを意味します。

7. 共同制作では安価な確認を先行させ、自律的自由制作では同じ判断を実行記録として残します。 製品ブリーフ → 要件から実行決定テーブル → テキスト方向性 → スタイルフレーム → ショットマッピング → ストーリーボードの順序は変わりません。共同制作では段階ごとにユーザーに確認を求め、自律的自由制作ではエージェントが自律的に選択し連続して進めます。どちらのモードでも、方向性が定まっていない状態でショットごとの実装に入ってはいけません。

8. 検証は全行程を通じて + 納品前の独立したレビュー。 フェーズ 5 以降、各ショットは npx remotion still を使用して静止フレームを出力し自己チェック、各修正ラウンド後はフルビデオをレンダリングし ffmpeg でフレーム抽出して確認。納品前には、クリーンなコンテキストを持つサブエージェントを割り当て、独立した最終レビューを実行する必要があります。レビュー入力には、完成ビデオ、キーフレーム、製品ブリーフ、要件から実行決定テーブル、現在のモードで確認または記録されたビジュアル方向性/スタイルフレーム、機能からショットへのマッピング、ギャラリーカード名/バリアント、正確なデモ TSX、ギャラリー参照サンプル/フレーム抽出、最終ストーリーボード、選択されたショットカード、美的基準が含まれます。references/final-review.md に従って、スキームの一貫性、機能の完全性、ショットの忠実度、ビジュアル/オーディオの技術品質、データセキュリティを同時にチェックし、フレーム番号付きの証拠を含むレポートを項目ごとに作成します。制作者自身の成果物には確証バイアスが存在するため、最初のレビューは決してユーザーに委ねてはいけません。

9. 決定論的レンダリング：Date.now()/Math.random() は禁止。すべての疑似乱数は固定シード（mulberry32/ハッシュ、シードはインデックスから派生）を使用し、フレームごとに再現可能である必要があります。

ワークフロー

自律的自由制作は references/pipeline.md に従い、フェーズ 0 から連続して実行し、段階ごとにユーザーの確認を待ちません。共同制作は最初に references/guided-free-creation.md に従ってフェーズ 0～3（製品理解、ビジュアル方向性、ショットマッピング、ストーリーボード確認）を完了し、パイプラインのフェーズ 4（最終素材収集）から続行します。質問を繰り返したり、再設計したりしてはいけません。フェーズ 2～3 では references/shots/ の各カードのフロントマターをスキャンし、エネルギーカーブに従ってショットを選択します。フェーズ 5～7 では継続的に references/aesthetic-rules.md と照合して自己チェックします。フェーズ 6 では references/sound-design.md を読みます。ビート同期ビデオでは全行程で references/music-beat-sync.md を参照します。

すべてのモードで完成ビデオを納品した後、デフォルトでユーザーに一度、剪映プロジェクトファイルの同時エクスポートが必要かどうかを尋ねます（剪映で字幕の内容/フォントサイズ/色の変更、ショットの速度変更/並べ替え、オーディオの調整または置換が可能）。ユーザーが必要とするか、またはエクスポートを明示的に指定した場合、references/jianying-export.md を読んで実行します。

各ファイルを読むタイミング

タイミング	読むファイル
プロジェクト起動時、モード未確定	最小限の読み取り専用チェック、その後 3 つの完全プロモーションモードを提示し推奨
自律的自由制作	pipeline.md（エージェントがフェーズ 0～7 を自律的に完了、段階ごとに確認を待たない）
共同制作	guided-free-creation.md（フェーズ 0～3 を確認）、その後 pipeline.md のフェーズ 4 から続行
ユーザーが BGM を選択済み	music-beat-sync.md（最初に分析、次にストーリーボード）
テンプレートルート	template/TEMPLATE.md 全文
ストーリーボード設計	sequences/ ブリッジテンプレート（最初に全体の骨格を埋める）；shots/ の全フロントマター；選択したカードは全文を読む
ショットごとの実装	該当ショットカード全文 + 「参考実装」に従って正確なデモソースコード全文 + assets/lib/ の対応コンポーネント
サウンドデザイン	sound-design.md + assets/audio/
検収	final-review.md + aesthetic-rules.md 全文でチェックリストを実行（独立サブエージェントが実行）
完成ビデオ納品後（剪映プロジェクトエクスポート）	jianying-export.md + jianying-export/ プラットフォームモジュール

アセットの使用方法

• assets/lib/ コンポーネントは 新しいプロジェクトにコピー した後、自由に変更可能（このライブラリを import しない）。 リスト：PageCam（2.5D ページカメラ – すべての「実際のページ」ショットの基盤）、ClipCard（外部ビデオ素材 mp4 を、ショットカードのカメラワーク骨格によって駆動される「カード主役」としてラップ、OffthreadVideo クロスフェードループを含む – 素材がショットより短い場合にシームレスに継続再生）、DigitRoll、FlashCut、Caption、FlatPanel、VerticalTicker（3D 無限スクロールウォール）、helpers(rand/shake/camera/motion)。FlatPanel と helpers/camera には three + @react-three/fiber + @remotion/three の依存関係が必要です。その他は remotion のみ必要です。
• assets/scripts/capture-template.mjs はコピー後、上部の CONFIG（BASE/ルート/セレクター）を変更します。
• assets/audio/ のサウンドエフェクトは直接コピーして使用可能（無料商用ライセンス、audio/ATTRIBUTION.md を参照）： audio/bgm/ はリズム感の強い BGM オプション。audio/sfx/<カテゴリ>/ 149 個のサウンドエフェクトは 16 カテゴリに分類（transition impact riser camera ui text paper film light data scifi mech glass fluid crowd counter）。サウンドを探す際は、まずカテゴリディレクトリを確認。リストは sound-design.md を参照。 用語のスパークルのディレクトリ名は light/（sparkle/ はなし）。S1 は音色を禁止するが、アクションは禁止しない – 画面上で実際にクリックやスイッチがある場合は擬音を配置する必要があるが、ui/ 内の半分は合成フィードバック音（tone/bleep/notification）のため、個別に試聴する必要があり、ディレクトリ全体を許可してはいけない（リストは sound-design 3.3 を参照）。長いサンプルと軽量サウンド素材にはそれぞれ特別な処理が必要なリストがある（sound-design 4.1）。
• demos/ 各カードの実装ソースコード：ほとんどは自己完結型のグレースケールデモ（一部は demos/_fixtures/Fixtures.tsx の偽 UI シーンコンポーネントを import、一部は demos/_textures/ の実際のページテクスチャを import）。Remotion プロジェクトにコピーして実行可能。一部のデモは @remotion/motion-blur（CameraMotionBlur）を使用しており、npm i @remotion/motion-blur が必要。リストは demos/README.md を参照。
• template/ 完全なレンダリング可能なプロジェクト：npm install && npx remotion render src/index.ts AiflPromo out/promo.mp4。
• jianying-export/ 剪映プロジェクトエクスポートモジュール：mac_draft.py（Mac 剪映 11.2 でテスト済み）、windows_draft.py（上流のサポートパスに従って実装、実機未検証）、smoke_test.py（新しい環境で最初に実行する最小限のスモークテスト）。フロー、タイムライン抽出、トラック構築方法は references/jianying-export.md を参照。venv + pip install pyJianYingDraft が必要。
• gallery/ 静的ギャラリー：可能な限り、ユーザーにオンラインバージョン https://vincentwei1021.github.io/video-shotcraft/library.html を優先して提供。ローカルで実行する場合は、最初に gallery/fetch-media.sh を実行してサンプルビデオを取得（mp4 は git に含まれていません）。次に cd gallery && python3 -m http.server 4178 を実行。152 カード、209 の動的サンプルビデオを閲覧/検索/複数選択してカード名をコピー可能 – ユーザーがサンプルを見ながらショットを選ぶのに適しています。