dyachkovp/product-motion

Product Motion

機能の動作を紹介する短い動画：インターフェースを画面に表示し、カーソルがクリックし、テキストが入力され、入力フィールドの下にラベルが表示され、カードがカスケード表示され、カメラが視線を誘導し、ナレーションが進行を説明します。このアプローチは複数のプロダクトの動画で実証済みであり、特定のブランドから独立しています。

原則

1. フレームは時間の関数である。 動画はHTMLページであり、render(t) が時間に基づいてフレームの状態を計算し、scripts/render.py がフレームを1つずつキャプチャしてffmpegに渡します。CSSアニメーション、タイマー、画面録画は使用しません。カクつきや同期ズレがなく、任意の瞬間を個別のフレームで確認できます。エンジンは templates/engine.js（references/engine.md）です。
2. プロダクトに実際に存在するものだけを表示する。 画面、ラベル、状態は、現在のプロジェクトのコード、プロトタイプ、docs/、またはスクリーンショットから取得します。存在しない機能を動画に含めることはありません。データは架空の短い名前を使用します。シーンのために考案した内容（応答、状態テキスト）は、ユーザーに確認のために提示します。
3. スタイルはプロダクトのものであり、スキルのものではない。 色、アクセントカラー、フォント、ロゴは、プロジェクトのコードから収集されたブランドプロファイル（motion/brand/、references/brand.md）から取得します。スキルの中立プロファイルは、ドラフト版のみに使用します。
4. ナレーションは自分で合成しない。 ローカルのTTSはロボットのように聞こえます。ユーザーは、Gemini TTS用のテキストとプロンプトを別途受け取り（または自分でナレーションを録音し）、ファイルを送信します。align_vo.py がそれを単語ごとに配置します。それまでは、動画は字幕と音楽で構成されます。
5. まず目で確認し、その後レンダリングする。 選択したフォーマットのキーフレームのコンタクトシートと verify_scene.py を、フルレンダリングの前に実行します。フレーム上で構成の誤りを発見するのが最も効率的です。
6. ユーザーの決定を推測しない。 言語、フォーマット、速度、音楽、公開方法は、ブリーフィングまたは質問に基づきます。以下のデフォルト値は、ユーザーが特に指定しなかった場合にのみ使用されます。

プロセス

0. 環境セットアップ（マシンごとに1回）

python3 <skill>/scripts/check_env.py

必要要件：Python 3.9+、ffmpeg/ffprobe、pip install playwright numpy scipy pillow（+ ナレーション用 faster-whisper）、python -m playwright install chromium；高速版の場合は rubberband 対応の ffmpeg。プロジェクトのvenv内かその近くが望ましい；依存関係はユーザーの同意なしにインストールしないこと。コマンドを提案すること。

1. ブリーフィング

機能；長さ（指定がない場合：1機能あたり30～35秒、セクションあたり60～75秒）；対象者と目的（チュートリアル、プロモーション、投資家、ランディング）；言語；フォーマット（指定がない場合：16:9、縦型9:16を提案）。一度に2つ以上の質問はしない；残りは妥当なデフォルト値として回答に記載する。詳細は references/brief.md。

2. 機能に関する事実 – 現在のプロジェクトから

機能のコード、プロトタイプ、docs/、スクリーンショットを読む：画面、正確なラベル、プレースホルダー、ボタン、状態、存在するものとしないもの。メインアクションの後にユーザーが何を目にするか不明な場合は、質問する。

3. ブランドプロファイル – プロジェクトごとに1回

プロジェクトに motion/brand/ が存在しない場合、references/brand.md に従って収集する：brand.css（CSS変数、テーマ、Tailwind設定からのトークン）、ライセンスが確認されたローカルフォント、ロゴ。最初の動画の前に、サンプルフレームをユーザーに表示する。以降の動画は、既存のプロファイルを使用する。

4. 脚本

「タイムコード · 画面内容 · カメラ/アニメーション · セリフ」の表（references/storyboard.md：長さに応じた骨組み、テキスト密度は1秒あたり1.3～1.6語、シーンのアーキタイプ）。動画が30秒を超える場合、またはブリーフィングが不完全な場合は、表を表示して「OK」を待つ；短くてブリーフィングが明確な場合は、すぐに組み立てを開始し、最初のフレームとともに表を表示してもよい。

5. 動画プロジェクト

プロジェクト内に動画用の場所がすでにある場合（promo/、design/motion/ など）はそこに配置する；それ以外の場合は motion/<slug>/ に作成する。

python3 <skill>/scripts/new_project.py motion/<slug> --brand motion/brand --lang ru --title "機能 · プロダクト"

内部構成：video.html、plan.js、cues.js、tmap.js、engine.js、processing.js、base.css、brand/、build/、out/、README.md。build/ と大きな out/*.mp4 は、ユーザーが特に指定しない限り、プロジェクトの .gitignore に追加する。プロジェクトに docs/ がある場合、動画とそのREADMEへの短いリンクを追加する。

6. plan.js とシーン

plan.js が唯一の情報源となる：duration、fps、canvas、language、product、audience、hold、ナレーション vo[]（id、at、text、tts、subs）、pronounce、emphasis、music。window.PLAN = の後に厳密なJSON形式で記述する。

video.html では、テンプレートのデモコンテンツを機能の画面に置き換える：build（繰り返し要素）、setup（E.measureAt + E.rect による測定、両フォーマットのカメラキー、カーソル、クリック）、scene(t)。画面上のイベントは、セリフの単語に同期させる（E.sync('p3:слово', 代替)）。暗い画面やモーダルは、E.dim() と #app2 を使用する。シーンのレシピは references/scenes.md、動きとカメラのルールは references/motion.md。スライダー付きプレビュー：動画フォルダから python3 -m http.server を実行し、video.html?preview=1 でアクセス。

7. フレームによる確認

python3 <skill>/scripts/verify_scene.py video.html --fmt both
python3 <skill>/scripts/render.py video.html stills --fmt both --times 1,6,9,12,15,19,23,27,31,34 --sheet

build/stills/sheet_h.jpg と sheet_v.jpg を開く：カメラがアクションを捉えているか；ラベルが対応する断片の下にあるか；テキストが改行や切り詰められていないか；アクセントカラーが適切な場所のみにあるか；「処理 → 結果」の切り替わりで白いフラッシュがないか；9:16ではテキストが大きく、字幕が下部パネルの上にあるか。キーフレームが問題なくなるまで修正する。最初のレンダリングの前に references/pitfalls.md を確認する。

8. ナレーション

python3 <skill>/scripts/vo_pack.py plan.js            # --model 3.8 で Gemini 3.8 Flash TTS、--voice female

out/voiceover/tts_text.txt と tts_prompt.txt を2つの別々のコードブロックとして提供する（テキストはテキストフィールド用、プロンプトはスタイルフィールド用）。声（ロシア語男性の場合、最初に Schedar）、全体を1テイクで録音するよう依頼し、timing.md からのタイミング表を添付する。ユーザーが同じテキストで自分で録音したものを使用することもできる。ルールは references/voiceover.md。

9. ナレーション到着 → 配置

python3 <skill>/scripts/align_vo.py plan.js voice.wav        # build/vo_aligned.wav、cues.js、out/subtitles.srt、レポート

build/align_report.md を読む：「耳で確認する必要がある」単語をタイムコードとともにユーザーに伝える；ずれたナレーションは plan.js で修正するのが望ましい。音声が最終フレーム（hold）にかかる場合、スクリプトは停止する。

速度変更は提案のみ。 動画が「間延びしている」場合、retime.py を提案する（読み上げ速度+4.5%、ポーズ短縮、動画、音声、音楽、字幕のための単一のタイムマップ）。メインの作業はユーザーの同意を得てから行うこと。

10. 音楽、ミキシング、レンダリング、アセンブル

python3 <skill>/scripts/music.py plan.js --out build/music.wav                         # musicセクションに基づくドラフト合成
python3 <skill>/scripts/prepare_music.py plan.js track.mp3 --end-align --out build/music.wav   # またはユーザーのトラック
python3 <skill>/scripts/mix.py build/music.wav build/vo_aligned.wav --out build/mix.wav
python3 <skill>/scripts/render.py video.html video --fmt h --out build/h_subs.mp4
python3 <skill>/scripts/render.py video.html video --fmt h --qs subs=0 --out build/h.mp4
python3 <skill>/scripts/assemble.py --video build/h.mp4 --audio build/mix.wav --out out/<slug>_16x9.mp4
python3 <skill>/scripts/assemble.py --video build/h_subs.mp4 --audio build/mix.wav --out out/<slug>_16x9_subs.mp4
#   … 縦型がブリーフィングにある場合、--fmt v でも同様（_9x16、_9x16_subs）
python3 <skill>/scripts/verify_media.py plan.js out/*.mp4 --sheet

レンダリング時間は、1分の動画あたり約2～5分（フォーマットによる）。バックグラウンドまたは分割して実行する（--start/--end、assemble.py --video part1 part2 … で結合）。合成音楽は一時的なもの；公開用動画にはライセンスされたトラックを提案する。詳細は references/audio.md。必要に応じて export_web.py（クリーンなMP4、WebVTT、ポスター画像、最終フレーム）をウェブサイトのプレーヤー用に提供する；ユーザーの個別の決定なしに公開は実行しない。

ユーザーに提供するもの

• 選択されたフォーマットのファイル：<slug>_16x9.mp4、<slug>_16x9_subs.mp4（+ _9x16）、SRT、ナレーションパッケージ（録音前）、コンタクトシート。ファイルパス；ファイル送信ツールがあれば、それを使用して送信する。
• 簡潔に：長さ、各シーンに何が含まれるか；考案された内容でプロダクトとの確認が必要なもの；音楽が一時的なもの；未確認のもの（例：耳で確認していないもの）。
• 動画フォルダのREADMEを更新する：ステータス、ブリーフィングの決定、再ビルド方法。
• プロセスの説明や「革新的なAI」の宣伝は不要。

スキルファイル

templates/engine.js	フレームエンジン：カメラ、カーソル、クリック、暗転とオーバーレイ #app2、字幕（subs=0）、タイムマップ tmap.js、プレビュー preview=1、測定、markup/grad/plural
templates/base.css	ブランドトークンを使用したコンポーネント：ヘッダー、入力フィールド、ラベル、ツールチップ、ダーク処理、結果表示、ポップオーバー、チャット、評価、エンディング
templates/brand/	ニュートラルなブランドプロファイル：brand.css、Manrope（OFL）、プレースホルダーロゴ
templates/processing.js	ニュートラルな処理アニメーション（リング、アクセントグレア、飛び込むカード）
templates/starter.html、plan.js	架空のプロダクト「Demo」における「スマート検索」の約36秒の実用的なデモ動画：フック → ラベル付き入力 → サジェスト → 処理 → 「理由」付き結果表示 → 保存 → 評価 → エンディング
scripts/	check_env、new_project、verify_scene、render、vo_pack、align_vo、retime、music、prepare_music、mix、assemble、verify_media、export_web
references/	brief.md · brand.md · storyboard.md · scenes.md · motion.md · engine.md · voiceover.md · audio.md · pitfalls.md