デモから販促リールへ：Screen Studio 風 Web アプリデモ

webapp-screencast

あなたがテイクをスクリプトし、webapp-screencastがそれを録画・編集します。出力: OUT/<名前>.mp4 (1920×1080、60 fps) とポスター画像 .jpg。 すべてはあなたが記述するファイル (scenario.py、plan.py) と1つのCLIで構成されます。 CLIは常に --json をサブコマンドの前につけて呼び出してください。標準出力は1つのJSONオブジェクト (ok、error、パス、時間、警告) です。進行状況は標準エラー出力に出力されます。終了コード0 成功、1 ステップ失敗、2 不正な入力。

APIとプランのキー: reference.md。scenario.py / plan.py を記述する前に必ず読んでください。

0. セットアップ (マシンごとに1回)

webapp-screencast --json doctor

webapp-screencast が存在しない場合: pip install git+https://github.com/dr-osmanovich/webapp-screencast.git (プロジェクトにvenvがあればそれを使用)、その後 python -m playwright install chromium。 doctor は失敗したチェックごとにその修正方法を一覧表示します。レンダリングには Node 22+ と ffmpeg が必要です。

1. アプリを理解する (録画前)

• ローカルでの実行方法 (README、package.jsonのscripts、Makefile、docker-compose) とそのURLを見つけてください。 プレーンな静的フォルダは webapp-screencast 自体で提供できます (make --serve DIR)。
• リポジトリ内のデモ/シードデータとテストアカウントを見つけてください (fixtures、seed scripts、.env.example)。 本番環境、実際の顧客や患者データ、実際の認証情報を決して録画しないでください。安全なデモデータが存在しない場合は、処理を停止してユーザーに問い合わせてください。
• 状態をリセットする方法を見つけてください (シード/リセットスクリプト、localStorageのクリア)。すべてのテイクはクリーンな状態から開始されます。
• 価値を示す3～5ビートを選んでください: フック → アクション → 結果 → 1つの詳細 → 終了。15～30秒の映像。
• 実際のコンポーネントを読んで安定したセレクター (ID、data-testid、ロール) を入手してください。推測はしないでください。

2. スキャフォールドとスクリプト作成

webapp-screencast --json init video/ --base-url http://127.0.0.1:3000 --title "製品名"

video/scenario.py を記述: CONFIG、オプションの login(page, cfg) と prepare(page, cfg)、そして run(take, page)。リテイクを減らすルール:

• 各ビートで take.mark("名前"); カメラやコールアウトがフレームに入れるすべてのものに対して take.box("名前", セレクター) (または click(..., name=)) を使用。必ず最初に hook をマークし、最後に end をマークしてください。
• アクション後は page.wait_for_selector(...) でアプリを待ち、その後 take.hold(0.3–0.8) を実行。
• テキストを入力する前にポインタをテキストから離してください (take.type(...))。タイピング速度は cps 25～35。
• prepare() ではトースト、Cookieバナー、開発者オーバーレイを非表示にし、サイドパネルを閉じてください。
• ネイティブの title= ツールチップはヘッドレスモードではレンダリングされません。代わりにプランの callout を使用してください。

3. 録画と確認

webapp-screencast --json record video/scenario.py --out video/out/footage [--base-url URL]
webapp-screencast --json inspect video/out/footage

忙しいビートで peak_fps ≥ 50 を確認してください (macOSでは低くなることがあります → GPUフラグの課題、reference.md参照)。計画したすべてのマークが存在することを確認してください。セレクターの失敗はPlaywrightエラーとしてstderrに出力されます: シナリオを修正して再度録画してください。フッテージは安価です (≈ テイク時間 + 10秒)。

4. 計画、合成、確認

video/plan.py を記述。inspect が出力したマークとボックスを使用してください (秒数をハードコードしない): アクションに追従するカメラセグメント (ビートではズーム1.4～1.7、シーン間では1.0に戻す)、ビートごとに1つの短い字幕 (単語あたり0.3秒以上、重複なし)、イントロ/アウトロカード。

webapp-screencast --json compose video/plan.py --footage video/out/footage --out video/out/composition
webapp-screencast --json snapshot video/out/composition --at 1,5,9,14 --out video/out/stills

すべての warnings エントリを修正してください。スチルを確認 (PNG / コンタクトシートを読む): テキストが読める、カメラがアクションに合っている、クリップされていない、説明対象を字幕が隠していない。compose + snapshot のみで plan.py を反復してください。録画の必要はありません。

5. レンダリングと納品

レンダリングはM1で20秒あたり約4～5分かかります。ログファイルを指定してバックグラウンドで実行してください。

webapp-screencast --json render video/out/composition --out video/out/video.mp4
webapp-screencast --json poster video/out/video.mp4 --at 9.0

JSONで fps: 60 と期待される時間を確認してください。mp4とポスターのパスを引き渡してください。 .gitignore ファイルに out/ ディレクトリを追加し、scenario.py + plan.py をコミットしてUI変更後に動画を再作成できるようにしてください。

シナリオとプランがすでに良い場合はワンショット: webapp-screencast --json make video/scenario.py video/plan.py --out video/out --base-url URL --poster-at 9 (--serve DIR は静的サイト用、--skip-render でチェック後に停止)。

/brag (または他の起動動画スキル) と連携

Bragがストーリーを決定し、webapp-screencastが実際の映像を提供します。

1. Brag自身の計画を実行: コンセプト、トーン、ビート、タイトル、コピー。スクリーンショットシーンを構築する前に停止。
2. Bragのビートを scenario.py のマークに変換 (1ビート=1マーク) して録画。
3. Bragのセリフを plan.py に入れる: フック → intro.title、ビートのキャプション → subtitles、 クロージングライン / CTA → outro; Bragのトーンを look にマッピング (洗練された → graphite/ocean、 遊び心 → sunset/violet、アクセント = アプリのブランドカラーをCSSから取得)。
4. 上記と同様に合成、スナップショット、レンダリングをBragの出力フォルダに実行。その後、Bragに共有コピーを書かせてください。 現在はランドスケープ16:9のみ。Bragが縦向きを要求した場合はその旨を伝え、ランドスケープでレンダリングしてください。