TVideo — 実際のWebアプリを使ったチュートリアル動画
あなたは、エンドユーザーにWebアプリで1つのタスクを実行する方法を教える短い動画を制作しています。視聴者は技術者ではありません。すべてのフレームは落ち着いて、読みやすく、現実的でなければなりません。パイプラインは2つの半分に分かれており、3つのファイルで合流します。
recorder (Playwright) ──► video.webm + timeline.json + clicks.json ──► editor (Hyperframes) ──► MP4
- Recorder (
templates/recorder/) は実際のアプリを操作し、可視カーソルを描画し、各ステップの開始/終了とクリックの発生時刻を記録します。 - Editor (
templates/editor/build.mjs) は映像をブランドキャンバスに配置し、視聴者が読む時間を必要とする場所で静止画を保持し、押すべきコントロールをズーム&リングで強調し、クリックごとにクリック音を追加し、レンダリングします。
編集はそれらのファイルから生成されるため、UI変更後の再録音は、録画 → インポート → ビルド → レンダリングだけで完了します。その状態を維持してください。index.html を手動編集せず、plan.json / tvideo.config.json を変更して再ビルドしてください。
フェーズ0 — 事前確認
各セッションの開始時(最初の返信と同時に、簡単な質問をしている場合はユーザーを待たせないように)に以下のチェックを実行し、録画前に不足を修正してください。録画中にツールが見つからないとテイクが無駄になります。
| 必要項目 | 確認方法 | 修正方法 |
|---|---|---|
| Node ≥ 20 | node -v | Nodeをインストール |
| ffmpeg / ffprobe | ffmpeg -version | brew install ffmpeg / apt |
| Hyperframes CLI + スキル | npx hyperframes --version | npx hyperframes skills update general-video (media-use, hyperframes-audioもインストールされます) |
| Playwright用Chromium | レコーダーディレクトリ内: npx playwright install chromium | — |
このセッションでHyperframesをまだ使用したことがない場合は、references/hyperframes-notes.md を一度お読みください(ビルドスクリプトが既に従っている構成ルールとその理由について)。
フェーズ1 — ブリーフィング(質問し、推測しない)
短い1ラウンドで、作業内容を変更するものを収集します。
- アプリのURLと環境。ステージング/UAT/デモ環境を推奨します。録画はアプリを実際に操作します。フォームは送信され、レコードが作成され、メールが送信されます。これを明確に伝え、共有環境に対して録画する前に承諾を得てください。
- ログイン: 専用のデモアカウント(ユーザー名/パスワードは環境変数を介して — チャットに貼り付けたりファイルに書き込んだりしないでください)。ログインにOTP/2FAが必要な場合は、実行中にユーザーがコードを貼り付ける計画を立ててください(
references/recording.mdを参照)。 - フロー: タスクごとに1つの動画。「システムの使い方」をそれぞれ30~120秒のクリップに分割します(サインイン、Xの作成、Xの編集/キャンセル、Yのダウンロード…)。視聴者が視聴する順番を尋ねてください。
- UIとキャプションの言語 (
TV_LOCALE,lang)。 - ブランド: ロゴファイル、1~2色、必要に応じてフォント(バンドルされているIBM Plex Sans Thaiはタイ語とラテン文字をカバー)。デフォルトはニュートラルなネイビー/グリーンです。
- オーディオ: キャプション+クリックSEFがデフォルトです。音楽: バンドルされているCC BYトラック、またはなし。ナレーションはオプションで、TTSクォータを消費します —
references/narration.mdを参照してください。
安全に関する決定(ブリーフィングで、録画前に確定する)
これらの動画は配布され、録画は実際のアクションを実行します。トレードオフを説明し、安全なオプションを推奨し、ユーザーに決定させてから従ってください。
- 画面上のデータの帰属先。視聴者が見てはいけないもの: 他の顧客の名前、実際の注文、個人のメールアドレス/住所/電話番号、内部テストラベル。架空のデモアカウントを推奨します。ユーザーが個人アカウントや実アカウントを主張する場合は、正確に何が表示されるかを伝え、明示的な承諾を得て、すべての個人値に対して
maskを計画してください(スナップショットで確認)。値が本物かどうか不明な場合は、質問してください。 - 元に戻せない、または金銭的なステップ(支払い、送金、実際の第三者への送信、削除、公開)。実際の支払いやその他の元に戻せないアクションを撮影のために完了させないでください。サンドボックス/テストモード(テストカード、ステージングゲートウェイ)を推奨します。ない場合は、最終確認画面まで録画し、そこで停止し、最後のキャプションで最終クリックを説明します。ブリーフィングでこれを伝えてください。
- 本番環境 vs ステージング。本番サイトでの録画は、作成するもの(注文、メール、在庫変更)とそのクリーンアップ方法を列挙した後、明示的な承諾が必要です。そこでは読み取り専用または元に戻せるフローを推奨します。
- 認証情報。パスワードとOTPは環境変数/ユーザーが管理するローカルファイルに保存し、チャットや作成したファイルには絶対に入力しないでください。ユーザーが既に入力したユーザー名/メールは秘密ではありませんが、
TV_USERNAMEを超えてファイルに繰り返さないでください。 - サードパーティーサインイン(Google、Microsoft、SSO、キャプチャ)。そこでの自動ログインは通常、ボットチェックや2FAに引っかかります。ユーザーに一度、ヘッド付きブラウザで手動サインインしてもらい (
npx playwright codegen --save-storage=.auth/state.json <login URL>)、その保存されたセッションで録画し、TV_USERNAMEは設定しないでください。 - 公開。納品前に、個人データがないか再確認し、アウトロに音楽クレジットを残してください(CC BYは帰属表示が必要です)。公開ページは内部トレーニングよりも厳格な視聴者です — プライバシールールを厳格に適用してください。
フェーズ2 — 調査とリハーサル
- プロジェクトごとに作業フォルダを作成します(例:
tvideo-work/<app>/)。その後、templates/recorder/をrecorder/にコピーし、そこでnpm iを実行します。 - 調査: フローの各ページを開き(Playwright MCP / ブラウザツール、または使い捨てスクリプト)、安定したセレクターを選択します — CSSクラスよりもロール/ラベル/test-idを優先します。撮影に適さないものに注意してください(recording.mdを参照: ネイティブの
<select>ポップアップ、日付ピッカー、瞬時のスクロールジャンプ、予約ウィンドウ)。 recorder/clips/NN-name.spec.tsにクリップごとに1つのスペックを書き、clips/01-example.spec.tsに従ってください: 最初にcreateTimeline; 視聴者に見える各ステップはtl.step('<キャプションテキスト>', …)でexpectで終了; クリックはtap()/typeInto()を介して; フォールドより下にあるものの前にはglideTo(); 重要な瞬間の後にはhold(); 最後にawait tl.save()。ユーザーが行うように値を選択してください — コードを入力するのではなく、ドロップダウン/カレンダーから選択してください。- リハーサル:
TV_REHEARSE=1 npx playwright test— 動画なし、ポーズなし。ここで全ての失敗を修正してください。テイクを台無しにするよりも、数秒で済みます。
フェーズ3 — 録画
npx playwright test (または1つのクリップ: npx playwright test clips/02-)。各クリップは test-results/<clip>/ 以下に video.webm, timeline.json, clicks.json を書き込みます。すぐにコピーしてください(次のステップで行います)— Playwrightは次の実行時に test-results/ を消去します。
ステップが失敗した場合、アプリが予期しない動作をしたことを意味します(バリデーション、ビジネスルール、遅い読み込み)。失敗のスクリーンショットを読み、スペックまたはデータを修正し、そのクリップを再実行してください。テイクを得るためだけにアサーションを緩めないでください。壊れたフローの合格テイクは、ユーザーに間違ったことを教えます。
フェーズ4 — 編集のセットアップ
クリップごとに1つのHyperframesプロジェクトを、レコーダーの隣に作成します(例: tvideo-work/<app>/clip-02/)。hyperframes init は独自のスターターファイルを書き込みます。その上にテンプレートをコピーすることは意図されています(build.mjs は index.html を再生成します)。作業フォルダから実行:
npx hyperframes init clip-02 --non-interactive --example=blank
cp -R <skill>/templates/editor/. clip-02/
cp clip-02/tvideo.config.example.json clip-02/tvideo.config.json # ブランド、フォント、ロゴ、音楽、言語
cp clip-02/plan.example.json clip-02/plan.json # タイトル、アウトロ、tl.stepごとに1ステップ
ls recorder/test-results/ # クリップのフォルダ名は長い — ここで見つけてください
bash <skill>/scripts/import.sh recorder/test-results/<that-folder> clip-02
bash <skill>/scripts/sfx.sh clip-02 # クリック-ソフト、ウーッシュ-ショート、チャイム、スパークル
tvideo.config.json で: lang と readingCharsPerSec (英語なら約15、タイ語なら約12 — スクリプトが遅いと読み取りも遅い)、ブランドカラー、logo (パス、またはテキストのみのカードの場合は null) を設定します。music.credit は維持してください — バンドルトラックはCC BYです。
plan.json のステップは、レコーダーの tl.step に 1:1、順序通り マッピングされます(ビルドは不一致を拒否します)。plan.json のキャプションは視聴者が読むものです — 短い指示(「「保存」をクリック」)にし、ナレーションにしないでください。通常、tl.step のラベルは既に良いキャプションです。それらをコピーしてください。
フェーズ5 — 測定、ビルド、確認
- 座標を見つけるためにフレームを取得:
bash <skill>/scripts/frames.sh assets/footage.mp4 frames <t1> <t2> …。 良いタイミング:clicks.jsonの各クリックから約0.3秒前(カーソルは既にコントロール上にあります — それがその位置です)、および各ステップのendMsから0.3秒前(確定した結果)。フルサイズのPNGを読んでください。座標は録画のピクセル単位です(例: 1280×800)。 - 必要に応じてステップごとに追加(詳細は
references/editing.mdを参照):- 押すコントロールに
zoom {scale,at}+ring {x,y,w,h}— ズームはリングを中心にします(ズームの固定点はコントロール上にある必要があります。そうしないとコントロールが端に滑ってクリップされます); - クリックするとコントロールが消える場合(移動するボタン)は
holdFirst: true— クリック前のフレームを最初に表示します; - 出荷してはいけない値を隠すための
mask {x,y,w,h,text,after}; - 成功の瞬間のための
chimeAfter: <s>。
- 押すコントロールに
node build.mjsを実行し、続けてnpx hyperframes checkを実行します。すべてのエラーを修正します。キャプションのフェードイン中のコントラスト警告は予想され、無害です。- 自分の目で確認:
build.mjsは各ステップがOUTPUTタイムラインのどこに着地するかを出力します(出力時間 ≠ 録画時間 — イントロとホールドによってシフトします)。それらのウィンドウ内でスナップショットを取得します —npx hyperframes snapshot --at <t…> --no-end、リングがある各静止画、各マスク、各ステップの中間点で1枚ずつ — そしてコンタクトシートを読んでください。リングはコントロール上にあり、マスクは正確にカバーし、キャプションは画面上のものと一致している必要があります。
フェーズ6 — レビューとレンダリング
- プレビューを開く:
npx hyperframes render --quality draft -o renders/draft.mp4を実行し、openで開きます(Studioプレビューnpx hyperframes preview --backgroundも機能しますが、シークが長いクリップで途切れることがあります。レンダリングはそのようなことはありません)。 - フィードバックに基づいて、プラン/設定を編集して再ビルドするか、フッテージ自体が間違っている場合(ペーシング、ジャンプ、間違ったデータ)は再録画して繰り返します。フッテージの問題はオーバーレイではなく、ソースで修正してください。
- 最終:
npx hyperframes render --quality delivery -o renders/<clip-name>.mp4。 パス、時間、サイズを報告します。 - 環境が共有されている場合は、録画によってアプリ内に作成されたもの(デモ注文/予約)をクリーンアップし、クリーンアップした内容を伝えます。
何か問題が発生した場合
references/troubleshooting.md には、このパイプラインがこれまでに直面した障害とその実際の原因(フッテージ/タイムラインのずれ、ネイティブセレクト、予約ウィンドウ、上書きされたtest-results、SFX重複リント、プレビューの途切れ)がリストされています。ゼロからデバッグする前に確認してください。
このスキルのファイル
templates/recorder/— Playwrightプロジェクト:cursor.ts,timeline.ts,auth.setup.ts,playwright.config.ts,clips/01-example.spec.ts(プラグインリポジトリのexamples/demo-app向けに記述、plan.example.jsonとペア)templates/editor/—build.mjs,plan.example.json,tvideo.config.example.json,assets/fonts(OFL),assets/music(CC BY)scripts/—import.sh,frames.sh,sfx.sh,voice.mjs(オプションのTTS)references/—recording.md,editing.md,narration.md,hyperframes-notes.md,troubleshooting.md